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

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 fetched spec,
   • extracts its toolDefinitionMap block,
   • deterministically shortens any tool name over 52 chars (see below),
   • splices that map into src/index.template.ts to produce src/index.ts,
   • diffs the new tool-name set against the previously committed one to decide a minor (names added/removed) vs patch 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) 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.