unofficial-mcp-builder

Claude Code plugin for authoring and maintaining unofficial MCP servers — the ones you write yourself for a third-party API because the vendor hasn't shipped one.

Three skills covering the lifecycle: build it from the vendor's docs, keep it in sync as the API drifts, and prove it still works against real data.

Install

claude plugins install unofficial-mcp-builder@danielrosehill

Skills

Skill	Purpose
create-mcp-from-api-docs	Build a server from the vendor's API docs, verifying the real surface against a live key before any code is written. Produces a publishable npm package.
revalidate-api-surface	Periodic drift check — re-fetch the docs, diff against the recorded surface, update the server for what changed upstream. Safe to schedule.
smoke-test-mcp	Connect with the user's key and run real operations — reads unattended, writes with per-operation confirmation — then fix what breaks.

The idea

Documentation is a hypothesis. The API is the source of truth.

Every generated server carries an api-surface.yaml at its root recording what the API actually does, as distinct from what its docs claim — and, for each fact, how it was established (live / docs / inferred) and when. That file is the contract between the three skills:

• create-mcp-from-api-docs writes it, promoting entries to evidence: live as it verifies them and logging every place the API disagreed with its docs.
• revalidate-api-surface diffs the upstream against it — doc hashes, version signals, changelog — and classifies what moved as breaking, deprecation, additive, or docs-only.
• smoke-test-mcp annotates it with observed behaviour, and fixes whichever layer turned out to be wrong: the code, the map, or your assumptions.

Start from templates/api-surface.yaml.

Reference

• reference/server-conventions.md — the house style servers are generated against: TypeScript + official SDK, consolidated tool surface, error handling, naming.
• reference/probing-playbook.md — rules for making live calls against someone else's API with a real key: read-before-write, sequential, rate-limit discipline, secret handling, how to read status codes.
• reference/npm-publishing.md — package naming that doesn't squat a vendor's namespace, pre-publish checks, versioning, deprecating when the vendor ships an official server.

Working with a real API key

The key is used to verify that the server matches the API. Throughout:

• Read-only calls run unattended; anything that creates, modifies, or deletes data is confirmed per operation.
• Requests are sequential and stay within documented rate limits.
• The key is read from the environment, never logged, never committed, never passed on a command line.
• Fixtures are redacted at capture time.
• Sandbox or test-tier keys are preferred where the vendor offers them.

Scope

In scope: writing a new server for an API with no official MCP; keeping it current; testing it end-to-end; publishing it.

Not in scope: auditing an MCP server you didn't write (my-mcp-mgmt / longship cover that), installing or mounting servers (claude-vault, claude-rudder), or reverse-engineering an undocumented private API from browser traffic (browser-data-capture).

Licence

MIT. Servers generated by this plugin are unofficial and unaffiliated with the API vendors they wrap; that belongs in their READMEs, and the skills put it there.