postfast-mcp: Instructions file for Claude Code

CLAUDE.md

Public stdio MCP server (npm: postfast-mcp) over PostFast's pf-api-key REST API — and the home of the shared tool catalog (src/core, exported as postfast-mcp/core). The deployed remote twin ../social-schedule-mcp (mcp.postfa.st) consumes the catalog too — its adapter landed 2026-08-05 (src/mcp/mcp.service.ts + gateway.adapter.ts import postfast-mcp/core), and a release here auto-bumps it (Release step 3).

Rules

• Source of truth is the backend: ../social-schedule-service — its docs/periphery.md holds the constellation map (repos, verify commands, release channels).
• Tool descriptions ARE the API — models discover fields only from descriptions/schemas, so wording changes are behavior changes. Keep them accurate against the BE REST responses.
• The catalog IS the single source: every tool (schema + description + title + annotations + outputSchema + binding) lives ONLY in src/core/tools/. Never author tool text anywhere else; both bindings render from it.
• stdio surface stability: scripts/parity-diff.mjs diffs a published version against the local build (initialize + tools/list over real stdio). Run it before any release that touches the catalog.
• One remote surface, always confirm-gated: every hosted session, whatever the client, gets the same catalogue. Posts are created held and publish only through approve_posts. Each comment operation is its own pair of tools, a read-only preview and the tool that carries it out with a token from that preview only, each after the user's yes: preview_comment_reply → reply_to_comment, preview_private_reply → send_private_reply, preview_comment_deletion → delete_comment. No remote tool picks between operations with a parameter. There is no ungated remote variant of any description, schema, annotation or server instruction: text that lets a model publish, approve, reply, delete, hide or email without the user's yes exists only on stdio, and test/confirm-gate.test.mjs checks the remote wording and the one-operation-per-tool rule. The host must pass confirmGate (without it the six comment tools are left out and a log line says so). test/remote-surface.test.mjs pins instructions + tools/list to test/snapshots/remote-surface.json; any change fails until UPDATE_SNAPSHOT=1 npm test, and the snapshot diff belongs in the PR, since it is what every hosted client and every directory reviewer sees.
• OAuth scopes (remote only): every remote tool declares scopes, exactly what the backend's MCP gateway checks for its call (../social-schedule-service/src/mcp-gateway/mcp-gateway.controller.ts, through the gateway command the host sends), and lists them as securitySchemes at the top level of tools/list and in _meta.securitySchemes. They are a hint for clients; the backend enforces scopes on every call. test/oauth-scopes.test.mjs pins the table, so a new tool or a backend scope change updates it. With RegisterToolsOptions.scopeChallenge, an InsufficientScopeError thrown by the port becomes an insufficient_scope challenge in the result's _meta["mcp/www_authenticate"], asking for the token's granted scopes (from the request's authInfo) plus the tool's.
• Calendar app (opt-in, remote only): src/core/app.ts, src/core/tools/app.ts and the view in view/ (vite single-file build to dist/view/index.html, read at runtime). A host turns it on with BuildToolsOptions.app (for every hosted session; its tools are app-only, hidden from the model); without it every surface stays byte-identical, and test/app.test.mjs checks that. @openai/mcp-extensions and @modelcontextprotocol/ext-apps are devDependencies only (type-only imports checked with satisfies, and bundled into the view). Never make them runtime dependencies: the host's pnpm release-age gate rejects fresh versions even as transitive dependencies, and the OpenAI package needs Node 22 and pins zod exactly. Tool icons (and every remote tool's top-level securitySchemes) reach tools/list by wrapping the SDK's tools/list handler, so re-check them on SDK bumps. scripts/app-preview.mjs serves the app with fixture data for ext-apps' basic-host (scenarios include several workspaces, a "many" one with 30 workspaces and 40 accounts, and a "single" one); appViewHtml() reads the view once, so restart the preview after npm run build.
• Directory plugin plugins/postfast/: skills plus a .mcp.json pointing at the hosted connector (https://mcp.postfa.st/mcp), listed in the Claude directory separately from the root plugin. Its skills are written for the remote surface, so a catalog change that renames or removes a tool, or changes a limit in the server instructions, updates the skills in the same PR; test/directory-plugin.test.mjs fails until it does. The skills name no client app (other clients' packages ship the same skills/ folder); the test enforces that too. Character limits live only in skills/schedule-posts/references/platform-rules.md. The folder is outside the npm package (files) and the .mcpb (.mcpbignore), so a plugin-only change needs no changeset or npm release. Its version is independent of the package version and not stamped: raise it by hand on every change to the folder. The directory reads only this folder, from the postfast-plugin-v* tag set as its tracked tag in the developer portal, so merging to main alone publishes nothing there (Release step 4).
• Cursor plugin .cursor-plugin/plugin.json: Cursor looks for .cursor-plugin/plugin.json, then .claude-plugin/plugin.json, then a root plugin.json, so this file decides what Cursor loads from the repository root. It launches the same pinned server as the Claude Code plugin, declares POSTFAST_API_KEY as a variable that Cursor asks for at install, and uses the root skills/ and assets/logo.png; test/cursor-plugin.test.mjs keeps it in step. A root Agent Plugins plugin.json would be shadowed by the Claude manifest in Cursor, and the Agent Plugins spec has no way to pass an API key to a stdio server.
• Workflow security: release.yml's dispatch authenticates as the release-bot GitHub App (RELEASE_BOT_APP_ID + RELEASE_BOT_PRIVATE_KEY; the private key is the critical credential) — it mints a short-lived token scoped to social-schedule-mcp only. Reference secrets ONLY on the step that uses them, never job/workflow level. This repo must NEVER gain a pull_request_target workflow that checks out PR code, and no secret-bearing workflow may interpolate PR-controlled strings (titles, branch names, bodies).
• Never commit with AI/Claude attribution or Co-authored-by.