mcp-builder

# MCP Server Builder

Build MCP servers that enable LLMs to accomplish real-world tasks through well-designed tools. Server quality is measured by how effectively agents can use the tools, not by API coverage alone.

## Before You Start

**Ask the user which programming language they want to use before doing anything else.** Use AskUserQuestion to prompt for their preferred language. Do not proceed until they answer. Then load the corresponding language-specific reference from `references/`:

- **TypeScript** → read `references/typescript.md`
- **Python** → read `references/python.md`
- **Other** → use the language-agnostic patterns in `references/guidelines.md` and adapt to the chosen language

Apply the language-specific conventions (naming, SDK, validation library, project structure, idioms) from the loaded reference throughout the entire build.

## Development Process

Follow four phases in order:

1. **Research & Plan** — Study the target API (endpoints, auth, data models, rate limits, pagination). Plan tool coverage. Prioritize comprehensive API coverage over workflow shortcuts when uncertain.
2. **Implement** — Build infrastructure first (API client, auth, errors, formatters), then tools incrementally.
3. **Review & Test** — Build, lint, test with MCP Inspector. Review for duplication, consistent errors, type coverage.
4. **Evaluate** — Create 10 complex realistic questions requiring multiple tool calls with stable verifiable answers.

## Architecture Decisions

Determine these upfront:

**Transport:**
- `stdio` — local/CLI tools, single user, simple setup
- `Streamable HTTP` — remote/cloud, multi-client, serverless. Avoid SSE (deprecated).

**State:**
- Stateless (recommended for remote) — fresh server per request, horizontal scaling, no session leaks
- Stateful — when session continuity is required

**Auth:**
- OAuth 2.1 — remote servers with user identity
- API key via env vars — simpler integrations
- None — local-only tools

**Language conventions (appli