ayrshare-unofficial-mcp: Instructions file for Claude Code

CLAUDE.md

Project Overview

Unofficial MCP (Model Context Protocol) server for the Ayrshare social media API. This server executes real API calls, allowing AI agents to manage social media accounts directly.

Tech Stack

• TypeScript (ESM) — "type": "module" in package.json
• @modelcontextprotocol/sdk — MCP server framework
• Zod — Schema validation for tool parameters
• Native fetch — No axios/node-fetch (requires Node.js >= 18)
• StdioServerTransport — Communication via stdin/stdout

Commands

• npm run build — Compile TypeScript to build/
• npm run dev — Watch mode compilation
• npm start — Run the built server
• npx @modelcontextprotocol/inspector node build/index.js — Test tools interactively

Architecture

src/
├── index.ts         — Entry point: creates McpServer, registers all tools, starts stdio transport
├── client.ts        — AyrshareClient class: wraps all HTTP calls to https://api.ayrshare.com/api
├── types.ts         — Shared Zod schemas (platform enums, profileKey schema)
└── tools/
    ├── posts.ts          — create_post, get_post, get_post_history, delete_post
    ├── profiles.ts       — create_profile, list_profiles, update_profile (NO delete — too dangerous)
    ├── media.ts          — upload_media (accepts URL or base64)
    ├── comments.ts       — post_comment, get_comments, delete_comment
    ├── messages.ts       — send_message, get_messages
    ├── analytics.ts      — get_post_analytics, get_social_analytics
    └── auto-schedule.ts  — set_auto_schedule, list_auto_schedules, delete_auto_schedule

Key Patterns

Tool Registration Pattern

Each src/tools/*.ts file exports a register*Tools(server, client) function that registers tools using server.tool(name, description, zodSchema, handler). All handlers follow the same pattern:

• Try/catch wrapping the client call
• Return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] } on success
• Return { content: [...], isError: true } on error