MCP builder
Contract
| Field |
Bound contract |
| Trigger |
Creating an MCP server to integrate an API or service in Python or TypeScript. |
| Authority |
Reversible local: write only named project files; delete the project directory to roll back. |
| Side effect |
A new MCP server project with typed tools, tests, and a read-only evaluation suite. |
| Done |
Server builds, registers tools with correct Zod/Pydantic schemas and annotations, passes MCP inspector, and has 16 stable read-only evaluations with verified answers. |
Inputs
- API or service specification (required): endpoint list, auth method, request/response shapes, or OpenAPI/GraphQL schema describing the service to integrate.
- Language (required):
python or typescript.
- Project directory (required): target path for the new MCP server project.
- Tool design intent (optional): which operations to expose as MCP tools and any annotation hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).
Procedure
- Validate inputs: confirm the API specification is parseable, the language is
python or typescript, and the project directory does not already exist or is empty. Done when: all three validations pass or the run stops with the specific failure.
- Scaffold the project. TypeScript: initialize with
pnpm init, then run pnpm add @modelcontextprotocol/sdk zod; create src/index.ts as the server entry point. Python: initialize with uv init, install mcp and pydantic; create server.py as the server entry point. Done when: the project directory exists with the entry point file and dependencies installed.
- For each API operation to expose as a tool: define the tool with
server.tool() using a descriptive kebab-case name, a human-readable description, and input schema (TypeScript: Zod object; Python: Pydantic model). Set MCP annotations: readOnlyHint for GET-like operations, destructiveHint for delete/mutate operations, idempotentHint for safe retries, openWorldHint when the tool calls external services. Implement the handler: call the target API, validate the response against the expected shape, and return structured content (text or resource) with a type field. Done when: every tool is defined with schema, annotations, and a returning handler.
- Build and verify the server compiles. TypeScript: run
pnpm exec tsc --noEmit. Python: run python -c "import server" or pyright server.py. Done when: the build exits 0.
- Create the test suite with exactly 16 read-only evaluations. Each evaluation invokes one tool via the MCP inspector or a direct stdio client call with fixed input and has a pre-recorded verified expected output stored alongside the test. Cover: at least one happy-path call per tool, at least one error/edge case per tool, at least one schema-validation boundary test, and at least one annotation-correctness check. TypeScript: use vitest or jest. Python: use pytest. Done when: 16 evaluations exist with the required coverage and verified expected outputs.
- Run all 16 evaluations and confirm every one passes with the expected output. Done when: all 16 evaluations pass.
- Run the MCP inspector against the running server to confirm tool registration, schema correctness, and annotation presence. Done when: the inspector confirms every tool's registration, schema, and annotations.
Failure and recovery
| Failure class |
Detection |
Recovery |
| Build failure |
Compiler/type-checker exit code non-zero |
Fix the syntax or import error in the generated source; re-run the build step. |
| Schema mismatch |
MCP inspector rejects a tool registration or Zod/Pydantic validation fails at runtime |
Correct the input schema definition to match the API spec; re-register the tool. |
| Evaluation failure |
Any of the 16 evaluations returns output differing from the verified expected output |
Fix the tool handler logic; update the expected output only if the API behavior changed (not to force a pass). |
| MCP inspector failure |
Inspector reports protocol violation or missing annotations |
Fix the server entry point or annotation configuration; re-run inspector. |
Partial results rule: if the server builds but evaluations fail, keep the project directory and report which evaluations failed. Do not delete partial work.
Rollback: delete the project directory to fully reverse all side effects.
Blocked result: if the API specification is unparseable or the language is unsupported, stop and report the specific validation failure. Do not proceed with scaffolding.
Output
A complete MCP server project: server entry point with all tools registered, tool definitions with typed schemas and annotations, test suite with 16 read-only evaluations, and build/inspector/evaluation results — ordered by the procedure steps that produced them.
1---2name: mcp-builder3description: Use when asked to create an MCP server to integrate an API or service in Python or TypeScript. Produces a server with typed tools, tests, and a read-only evaluation suite. Don't use for remote, credential, publish, deploy, or irreversible changes.4---5
6# MCP builder
7
8## Contract
9
10| Field | Bound contract |
11|---|---|
12| Trigger | Creating an MCP server to integrate an API or service in Python or TypeScript. |
13| Authority | Reversible local: write only named project files; delete the project directory to roll back. |
14| Side effect | A new MCP server project with typed tools, tests, and a read-only evaluation suite. |
15| Done | Server builds, registers tools with correct Zod/Pydantic schemas and annotations, passes MCP inspector, and has 16 stable read-only evaluations with verified answers. |
16
17## Inputs
18
19- API or service specification (required): endpoint list, auth method, request/response shapes, or OpenAPI/GraphQL schema describing the service to integrate.
20- Language (required): `python` or `typescript`.
21- Project directory (required): target path for the new MCP server project.
22- Tool design intent (optional): which operations to expose as MCP tools and any annotation hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).
23
24## Procedure
25
261. Validate inputs: confirm the API specification is parseable, the language is `python` or `typescript`, and the project directory does not already exist or is empty. Done when: all three validations pass or the run stops with the specific failure.
272. Scaffold the project. TypeScript: initialize with `pnpm init`, then run `pnpm add @modelcontextprotocol/sdk zod`; create `src/index.ts` as the server entry point. Python: initialize with `uv init`, install `mcp` and `pydantic`; create `server.py` as the server entry point. Done when: the project directory exists with the entry point file and dependencies installed.
283. For each API operation to expose as a tool: define the tool with `server.tool()` using a descriptive kebab-case name, a human-readable description, and input schema (TypeScript: Zod object; Python: Pydantic model). Set MCP annotations: `readOnlyHint` for GET-like operations, `destructiveHint` for delete/mutate operations, `idempotentHint` for safe retries, `openWorldHint` when the tool calls external services. Implement the handler: call the target API, validate the response against the expected shape, and return structured content (text or resource) with a `type` field. Done when: every tool is defined with schema, annotations, and a returning handler.
294. Build and verify the server compiles. TypeScript: run `pnpm exec tsc --noEmit`. Python: run `python -c "import server"` or `pyright server.py`. Done when: the build exits 0.
305. Create the test suite with exactly 16 read-only evaluations. Each evaluation invokes one tool via the MCP inspector or a direct stdio client call with fixed input and has a pre-recorded verified expected output stored alongside the test. Cover: at least one happy-path call per tool, at least one error/edge case per tool, at least one schema-validation boundary test, and at least one annotation-correctness check. TypeScript: use vitest or jest. Python: use pytest. Done when: 16 evaluations exist with the required coverage and verified expected outputs.
316. Run all 16 evaluations and confirm every one passes with the expected output. Done when: all 16 evaluations pass.
327. Run the MCP inspector against the running server to confirm tool registration, schema correctness, and annotation presence. Done when: the inspector confirms every tool's registration, schema, and annotations.
33
34## Failure and recovery
35
36| Failure class | Detection | Recovery |
37|---|---|---|
38| Build failure | Compiler/type-checker exit code non-zero | Fix the syntax or import error in the generated source; re-run the build step. |
39| Schema mismatch | MCP inspector rejects a tool registration or Zod/Pydantic validation fails at runtime | Correct the input schema definition to match the API spec; re-register the tool. |
40| Evaluation failure | Any of the 16 evaluations returns output differing from the verified expected output | Fix the tool handler logic; update the expected output only if the API behavior changed (not to force a pass). |
41| MCP inspector failure | Inspector reports protocol violation or missing annotations | Fix the server entry point or annotation configuration; re-run inspector. |
42
43Partial results rule: if the server builds but evaluations fail, keep the project directory and report which evaluations failed. Do not delete partial work.
44
45Rollback: delete the project directory to fully reverse all side effects.
46
47Blocked result: if the API specification is unparseable or the language is unsupported, stop and report the specific validation failure. Do not proceed with scaffolding.
48
49## Output
50
51A complete MCP server project: server entry point with all tools registered, tool definitions with typed schemas and annotations, test suite with 16 read-only evaluations, and build/inspector/evaluation results — ordered by the procedure steps that produced them.
majiayu000