companies-house-mcp: Instructions file for Claude Code

Companies House CLI and MCP

What this is

An unofficial CLI and MCP server for the UK Companies House public register. 18 tools covering company search, company records, officers, ownership, filings, filed documents and combined summaries. Every user brings their own free API key; there is no shared key, hosted backend or proxy.

Layout

packages/cli/      companies-house-cli — the API client, the tools, the CLI, and the MCP server
packages/mcp/      companies-house-mcp — a thin wrapper that starts the shared server over stdio
packages/worker/   optional single-user Cloudflare Worker (private, not published)
docs/              VitePress documentation site

All shared implementation lives in packages/cli/src:

• api/ — HTTP client, rate limiter, cache, pagination helper, endpoint functions
• api/endpoints/ — one file per API domain
• tools/ — MCP tool definitions, registered into a central registry by side-effect import
• server/ — the transport-neutral MCP factory, the Node stdio and HTTP runners, secret comparison
• cli/ — the ch entry point, its command table, and schema introspection
• formatters/ — shared markdown formatters
• types/ — types matching the Companies House API, in its own snake_case

Commands

pnpm build              # all packages
pnpm test:unit          # no API key needed
pnpm test:integration   # needs COMPANIES_HOUSE_API_KEY
pnpm test:package       # packaged stdio entry points, via the MCP client SDK
pnpm lint
pnpm typecheck
pnpm docs:dev

The Worker builds with wrangler deploy --dry-run, which is what catches bundling problems.

Conventions

• ESM throughout, Node 22 or newer.
• Types mirror the Companies House API and stay snake_case.
• Tools self-register by calling registerTool() at module level. tools/all.ts imports them for the side effect; the server and CLI import that.
• Every tool returns { content, structuredContent } — readable text plus a structured payload.
• Every tool declares a group, used by the CLI help and the generated docs.
• The rate limiter queues rather than throwing. A 429 is only waited out when Companies House says the window is about to reset.
• Native fetch. No Axios.
• Code shared with the Worker must stay runtime-neutral: web-standard APIs, no Buffer, no static node: imports. Node-only work belongs in server/index.ts, config.ts, or behind a dynamic import.