blindpay-mcp: Instructions file for Claude Code

BlindPay MCP - Agent Reference

Commands

npm run typecheck        # tsc --noEmit
npm run build            # tsc + chmod the entry point
npm run generate         # Raw openapi-mcp-generator dump to /tmp/mcp-generated (debugging only)
npm run sync              # Full deterministic pipeline: writes src/index.ts + package.json
npm run sync:check        # Same pipeline, but diffs against committed files instead of writing (exit 2 on diff)
npm run check-tool-names  # Static gate: fails if any committed tool name exceeds 52 chars
npm run check-plugin      # Static gate: fails if plugins/blindpay breaks a Claude directory rule
npm run check-openai-plugin  # Static gate: fails if plugins/openai breaks an OpenAI submission limit or leaves /mcp/readonly
npm run check-connector   # Live check: walks the OAuth sign-in of Claude, Claude Code, VS Code and ChatGPT against mcp.blindpay.com/mcp/readonly (not in CI)
npm test                  # Unit tests for scripts/lib (node:test via tsx)
npm run pack:openai       # ZIP for the ChatGPT/Codex plugin directory, in build-plugins/

How updates work

This repo is auto-synced with the BlindPay public API surface, the same set of routes shown on the public docs site (/doc). When that surface changes upstream, .github/workflows/api-sync.yml fires. There is no LLM anywhere in this path; every step is a plain script.

1. The blindpay-v2 mcp-sync.yml workflow generates apps/api/openapi.json (already filtered by applyPublicTagFilter to public-tagged routes) and pushes it to this repo's api-sync-data branch at .api-sync/openapi.json. Then it fires a repository_dispatch api-sync event.
2. api-sync.yml consumes the event and runs npm run sync (scripts/sync.mts), which:
   • runs openapi-mcp-generator against the spec,
   • extracts its toolDefinitionMap block,
   • deterministically shortens any tool name over 52 chars (see below),
   • rebuilds every tool's inputSchema from the spec the way the hosted server does (see "Parity with the hosted server"),
   • splices that map, plus the spec's webhook events, into src/index.template.ts to produce src/index.ts,
   • picks the version bump (see "Version bump") and writes that version into both package.json and SERVER_VERSION. Any spec shape the script can't map (missing map markers, a name it can't shorten under the limit, a duplicate name, a tool or parameter the generator and the hosted server's schema don't agree on) is a hard failure, not a best guess.
3. CI (ci.yml, required on main) typechecks, builds and re-checks the 52-char limit. The PR on the api-sync branch is opened/updated and gh pr merge --auto --squash is set on it, so it merges itself once CI is green, no human step.
4. publish.yml (unchanged) publishes to npm and tags a release on every push to main whose package.json version isn't already published.