mcp-server-builder · diff
git:20260512.a615139 to git:20260515.fc6f9ad
53 added, 38 removed. Audit A to A.
---
name: mcp-server-builder
description: Design high-quality MCP servers around workflows, narrow schemas, context-aware outputs, and actionable errors. Use when building or reviewing MCP tools for real agent tasks.
---
# MCP Server Builder
Use this skill when designing or implementing an MCP server.
## When to Use
-
- - Building a new MCP server
- - Refactoring a weak MCP tool surface
- - Reviewing whether a server exposes the right workflows
- - Designing evaluation cases for MCP usability
+ - Building a new MCP server from scratch.
+ - Refactoring a weak or over-thin MCP tool surface.
+ - Reviewing whether a server exposes the right workflows.
+ - Designing evaluation cases for MCP usability.
## Core Principles
-
- - Build workflow tools, not thin endpoint wrappers
- - Keep inputs schema-first and narrow
- - Return high-signal outputs sized for agent context limits
- - Make error messages corrective, not merely diagnostic
- - Prefer human-meaningful identifiers over opaque IDs when possible
- - Design evaluation cases before the server feels "done"
+ - Build **workflow tools**, not thin endpoint wrappers — one tool should complete a meaningful agent task, not expose a single API method.
+ - Keep input schemas **narrow and typed** — reject unknown fields; use enums over free strings where possible.
+ - Return **high-signal, size-bounded outputs** — default to concise; add `detail` or `verbose` flags when larger payloads are occasionally useful.
+ - Make error messages **corrective** — tell the agent what to do next, not just what went wrong.
+ - Prefer **human-meaningful identifiers** over opaque IDs when both are available.
+ - Design **evaluation cases** before declaring the server "done".
## Workflow
- 1. **Map the workflow**
- - Identify the real tasks the agent must complete.
- - Merge low-level API steps into meaningful tool operations where appropriate.
+ ### 1. Map the workflow
+ - Identify the real tasks an agent must complete, not the underlying API surface.
+ - Merge low-level steps into meaningful operations (e.g., one `create_and_publish` tool instead of separate `create`, `validate`, `publish`).
- 2. **Design the tool surface**
- - Stable tool names
- - Narrow, typed input schemas
- - Consistent output shapes
- - Clear failure modes
+ ### 2. Design the tool surface
+ ```
+ tool name: stable, verb-noun, describes the workflow step
+ input schema: typed, narrow, required fields only + optional detail flags
+ output shape: consistent structure across all tools in the server
+ failure modes: named error codes + correction hint
+ ```
- 3. **Design for context limits**
- - Default to concise responses
- - Add explicit detail flags when larger payloads are useful
- - Truncate or summarize large result sets deterministically
+ ### 3. Design for context limits
+ - Default response fits in ~500 tokens for list operations, ~1500 for detail operations.
+ - Add `limit`, `page`, or `summary` parameters for large result sets.
+ - Truncate deterministically (e.g., top N by recency) — never truncate randomly.
- 4. **Implement shared infrastructure first**
- - auth handling
- - retries and rate limits
- - pagination helpers
- - formatting helpers
+ ### 4. Design corrective errors
- 5. **Evaluate**
- - Write representative task scenarios
- - Check whether the current tools let an agent finish the workflow cleanly
- - Redesign weak tools before adding more tools
+ Bad error: `"Error: 404 Not Found"`
- ## Local References
+ Good error: `"Resource 'project-123' not found. Use list_projects to see available project IDs."`
+ Every error should tell the agent its next valid action.
+
+ ### 5. Implement shared infrastructure first
+ - Auth handling and token refresh.
+ - Retry logic with exponential backoff and rate-limit awareness.
+ - Pagination helpers.
+ - Output formatting helpers (consistent truncation, redaction of secrets).
+
+ ### 6. Evaluate before shipping
+ - Write representative task scenarios (not unit tests for individual tools).
+ - Check whether an agent can complete the full workflow using only the exposed tools.
+ - Redesign weak tools before adding more tools — more tools is not always better.
+
+ ## Server Readiness Checklist
+ - [ ] Every tool completes a meaningful workflow step.
+ - [ ] All inputs are typed and schema-validated.
+ - [ ] Output size is bounded by default.
+ - [ ] All error messages include a correction hint.
+ - [ ] Auth and retry are handled in shared infrastructure.
+ - [ ] At least one end-to-end task scenario has been tested.
+ - [ ] No secrets appear in tool outputs or error messages.
+
+ ## Local References
- `reference/mcp_best_practices.md`
- `reference/python_mcp_server.md`
- `reference/node_mcp_server.md`
- `reference/evaluation.md`
Use the Python and Node references only for the stack you are actually shipping.
## Bundled Scripts
-
- - `scripts/evaluation.py` for evaluation scaffolding
- - `scripts/connections.py` for connection-oriented examples
+ - `scripts/evaluation.py` — evaluation scaffolding
+ - `scripts/connections.py` — connection-oriented examples
- Use them as helpers, not as mandatory runtime requirements.
+ Use them as optional helpers, not mandatory runtime requirements.