MCP Maker

MCP Maker — Enterprise MCP Server Builder

Turn a user request (“I need an MCP for X”) into a small, secure, tested MCP server on top of a real API. MCP does not replace APIs — it exposes discoverable tools with schemas so models can call them safely.

Core principles

1. Research before code — confirm API/SDK coverage; recommend if unsure.
2. Read-only v1 by default — writes/deletes only after explicit user ask.
3. TypeScript by default — switch language only when the ecosystem wins.
4. Narrow tool surface — few high-value tools beat a kitchen-sink catalog.
5. Secure by construction — secrets in mcp.json env, annotations, sanitized I/O.
6. Tested before done — handler tests + connection smoke + build.
7. QC before ship — mcp-maker qc + agent audit; never ship on FAIL.
8. Agent-shaped I/O — parameters agents can fill; md or compact json.
9. Reference architecture — clients/ + tools/ + thin index.ts.

Reference loading

Templates: assets/templates/.
Evals: evals/evals.json.

Install / CLI:

./install.sh
mcp-maker doctor
mcp-maker qc --project-dir /path/to/mcp-<service>

Quiet defaults (do not interrogate)

Proceed with defaults; state them in one short line. Exception: never add write/destructive tools without an explicit user request (or confirmation).

Ask when: auth model ambiguous, user wants writes/deletes, OAuth vs PAT trade-off, research finds no viable API, or remote HTTP transport is requested.

Default agent loop

Copy and track:

Task Progress:
- [ ] One-sentence agent job + quiet defaults stated
- [ ] Research API/SDK/existing MCP (research-and-recommend.md)
- [ ] Language + transport + auth model decided
- [ ] If uncertain → recommend (best vs easiest) and wait
- [ ] Write TOOL_SPEC.md (tool-spec-template.md) — required before tools code
- [ ] Scope v1 tools (read-only unless user asked writes)
- [ ] Annotations + output format per tool
- [ ] Scaffold package (gitignore, lockfile, clients, tools, tests, smoke)
- [ ] Implement: base client (timeout/sanitize) → reads → writes last
- [ ] Schema sync checklist; stderr tool logging
- [ ] npm test + npm run build (+ test:connections if env available)
- [ ] README: env, scopes, tools, annotations summary, risks
- [ ] mcp-maker qc --project-dir <repo>  (audit-pipeline.md)
- [ ] If FAIL → fix → re-qc until not FAIL
- [ ] Agent audit checklist (qc-checklist.md)
- [ ] Report qc verdict + qc-report.json; deferred v2 + residual risks
- [ ] mcp.json / install guidance ONLY if PASS (or WARN + user accepts)

Step 1 — Name the job

Rewrite as agent jobs, not API routes. One server = one domain (or one auth plane pair like Jira+Confluence). Prefer reuse existing MCP when it fits.

Step 2 — Research & recommend

Follow research-and-recommend.md and security.md. Map jobs → endpoints; note scopes, rate limits, injection surface. If confidence is low → recommendation gate, no code.

Step 3 — TOOL_SPEC.md (mandatory)

Copy tool-spec-template.md into the target repo. Fill tools, annotations, auth, non-goals. No src/tools until this exists.

Step 4 — Language & transport

TS default (language-choice.md).
stdio default (transports.md).
Check current MCP SDK docs for annotations support — do not blindly pin ancient versions.

Step 5 — Design tools

• Verbs: read_* / search_* / list_* / create_* / update_* / delete_*
• Every tool: annotations (tool-annotations.md)
• Params: URL/env fallbacks OK; caps; include flags default false
• Output: output-format.md
• Zod source of truth; sync inputSchema (schema-sync.md)

Step 6 — Scaffold & implement

mcp-<service>/
  TOOL_SPEC.md
  package.json  README.md  .gitignore  .env.example
  tsconfig.json  tsconfig.test.json
  src/index.ts
  src/types/
  src/clients/base-client.ts    # timeout, sanitize, headers
  src/clients/<domain>-client.ts
  src/tools/<domain>.ts         # zod + tool + annotations + handler
  src/scripts/test-connections.ts
  test/helpers/mock-fetch.ts
  test/*.test.ts
  .github/workflows/ci.yml      # when git repo

Use architecture-pattern.md, project-scaffold.md, resilience.md, testing.md, observability.md.

Templates under assets/templates/ when helpful.

Step 7 — Verify (tests/build)

• npm test + npm run build pass
• Smoke script present; secrets never printed
• README: env, scopes, tool table, risks (mcp.json draft OK)

Step 8 — Audit & QC (mandatory gate)

Follow audit-pipeline.md and qc-checklist.md:

mcp-maker qc --project-dir /path/to/mcp-<service>

Agent checklist covers TOOL_SPEC fidelity, annotation honesty, least privilege, output shaping, and residual risks. Never claim done on FAIL.

Mental model

[ LLM / Agent ]
       │  MCP (discover + call + annotations)
       ▼
[ MCP Server ]  ← thin, least-privilege capability surface
       │  HTTP/SDK (timeouts, sanitized errors)
       ▼
[ Real APIs / systems ]

Skills = how work is done. MCP = what tools exist. This skill builds the MCP layer — honest about the API, safe under agent control.

Anti-patterns (summary)

Full list: anti-patterns.md.

Success criteria

• Research + language + auth + transport stated
• Recommendation delivered when ambiguous
• TOOL_SPEC.md complete and matched by code
• Read-only v1 unless writes explicitly requested
• Annotations, timeouts, sanitized errors, schema sync
• Tests + build green; smoke script documented
• mcp-maker qc is PASS or accepted WARN (never ship on FAIL)
• Agent audit checklist completed (qc-checklist.md)
• User given qc-report.json path + residual risks
• mcp.json guidance only after QC gate
• No secrets in repo; no project .env / dotenv; auth via mcp.json env
• Deps verified/pinned