mcp-builder

Files (5)

• SKILL.md
• evals.json · evals/
• trigger-evals.json · evals/
• quick-reference.md · references/
• scaffold.sh · scripts/

SKILL.md (first lines)

# MCP Server Development Guide

## Why this skill exists

Wrapping an external API in an MCP server sounds simple, but naive implementations fail in practice: tools return walls of JSON that exhaust context, list operations return unbounded results that time out, error messages say "400 Bad Request" without guidance, and tool names are so generic (`get`, `list`) that the model picks wrong ones. This guide enforces the patterns — pagination-first, structured output, actionable errors, consistent naming — that make the difference between a server a model can use reliably and one it struggles with.

**MCP is a protocol, not a Claude feature.** The server you build here is host-neutral: the
same stdio or HTTP server is consumed by Claude Code, Claude Desktop, Cursor, Codex CLI,
Gemini CLI, OpenCode and anything else speaking MCP. Nothing in the server implementation
may assume a particular host. What *does* differ per host is the **client config file** that
registers the server — that difference is confined to Phase 6, where it is generated and
validated per target, and it never leaks into the server code.

Throughout this guide, "the client" or "the host" means whichever agent runtime is calling
your tools. Where a passage says Claude, it is naming one client among several, not a
requirement.

## Supporting files

| File | When to use |
|------|-------------|
| `scripts/scaffold.sh` | Run at the start of Phase 2 to generate a project skeleton. Usage: `bash <skill-dir>/scripts/scaffold.sh <name> [ts\|py] [prefix]` (`$CLAUDE_SKILL_DIR` on Claude Code; substitute the skill directory on other hosts) |
| `references/quick-reference.md` | Read during Phase 1 and Phase 3 for SDK URLs, Zod patterns, annotation hints, return shapes, naming examples, and error message templates. |

At the start of **Phase 2**, run the scaffold script to bootstrap the project, then replace the placeholder tools in Phase 3.

---

## Internal skills

Pagination guardrails live in a companion skill — **do not duplicate or guess limits inline**:

```
Skill("mcp-pagination")
```

`mcp-pagination` is internal-only (`user-invocable: false`). Invoke it with the **Skill tool** whenever this workflow touches list/search operations. It owns limit defaults, cursor conventions, SQL `LIMIT` enforcement, and the pre-ship checklist.

**Invoke `mcp-pagination` when any of these apply:**

| Trigger | Phase |
|---------|-------|
| Planning tool inventory and any endpoint returns a collection | Phase 1 |
| Before writing each `list_*`, `search_*`, or array-returning tool | Phase 3 |
| Before adding or changing SQL-executing tools | Phase 3 |
| After implementing list/search tools — audit against checklist | Phase 4 |
| Eval questions require multi-page fetches — verify caller-driven pagination | Phase 5 |

Skip invocation only when the server has **zero** list, search, or bulk-read operations (e.g. a single `create_*` write tool).

---

## Language selection

| Criterion | TypeScript | Python |
|---|---|---|
| Recommended default | Yes | If team is Python-only |
| SDK maturity | High (first-party) | High (FastMCP) |
| Remote HTTP servers | `@modelcontextprotocol/sdk` | FastMCP |
| Local stdio servers | Same SDK | Same SDK |
| Type safety | Static (Zod + tsc) | Pydantic v2 |
| Compilation check | `npm run build` | `python -m py_compile` |

---

## Phase 1 — Research and planning

### 1.1 Load MCP specification and quick reference

Read the bundled quick reference first (URLs, patterns, naming cheat sheet):

```
Read("<skill-dir>/references/quick-reference.md")   # $CLAUDE_SKILL_DIR on Claude Code
```

Then fetch authoritative SDK docs with WebFetch:

```
WebFetch("https://modelcontextprotocol.io/specification/draft.md")
WebFetch("https://modelcontextprotocol.io/docs/concepts/tools.md")
```

**TypeScript SDK:**
```
WebFetch("https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md")
```

**Python (FastMCP):**
```
WebFetch("https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md")
```

### 1.2 Understand the target API

Review authentication method, rate limits, pagination strategy (cursor vs. offset), and which endpoints map to the most common user tasks. Deprioritize rarely-used admin endpoints.

Catalog every endpoint that returns a collection or supports search — these become list/search tools in Phase 3.

### 1.3 Apply pagination guardrails (mcp-pagination)

If the catalog from 1.2 includes **any** list, search, or bulk-read operation, invoke the internal skill **before** writing tool schemas:

```
Skill("mcp-pagination")
```

Pass the planned tool names and the target API's native pagination params. Apply its Step 1–3 output to your tool design (limit defaults, cursor/offset mapping, safe starting limits). Do not proceed to Phase 3 implementation until pagination strategy is set for every collection endpoint.

---

## Phase 2 — Project setup

### Use the scaffold script

The fastest way to start is the bundled scaffold:

```bash
# TypeScript
bash <skill-dir>/scripts/scaffold.sh my-mcp-server ts myservice

From Tamircohen28/tamirs-superpowers, MIT.

More from Tamircohen28/tamirs-superpowers