mcp-builder

MCP builder

Contract

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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. Run all 16 evaluations and confirm every one passes with the expected output. Done when: all 16 evaluations pass.
7. 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.