Build Clean MCP Architecture

Apply Clean MCP Architecture

Architectural standard for TypeScript MCP servers built with mcp-use/server. Decides where files live, what each layer may import, what bootstrap wires, and how the discipline is enforced. Mechanical recipes (exact APIs, auth, transports, widgets) live in build-mcp-use-server.

When to use this skill

Trigger on phrases or contexts like:

• "where should this tool / gateway / presenter / port live?"
• "refactor this monolithic src/tools/*.ts into clean layers"
• "audit this MCP server's architecture" / "PR review for layering"
• "set up dependency-cruiser for an mcp-use server"
• "why is mcp-use imported from domain/ or application/?"
• "scaffold a greenfield mcp-use/server repo with proper folders"
• "process.env is being read all over the codebase — fix the seam"
• "design ports, adapters, and provider error classification"

Do NOT use this skill when:

• The question is a raw @modelcontextprotocol/sdk server mechanic — use build-mcp-server-sdk-v1, build-mcp-server-sdk-v2, or convert-mcp-sdk-v1-to-v2.
• The question is an mcp-use/server API recipe (tool helpers, auth, sessions, transports, widgets, CSP, Inspector, deploy) — use build-mcp-use-server.
• The work is on a client app or MCPAgent — use build-mcp-use-client or build-mcp-use-agent.
• The concern is general agentic usability, token cost, tool-description quality, or runtime UX rather than folder layout or layer boundaries — that is out of scope for this structural skill.

If the task is structural placement inside an mcp-use/server repo, this skill owns it. If it is a mechanical recipe outside of placement, route out.

Pinned Defaults

Mode Selection

Pick exactly one mode before editing. If evidence contradicts the picked mode, name the contradiction once and continue with the mode that matches the codebase.

Guardrails

These rules are absolute. When a hard external constraint blocks one, report the constraint and the smallest compensating boundary — do not silently weaken the rule.

1. Inner layers never import outer layers. domain/ imports nothing outside itself. application/ imports only domain/ and shared/.
2. No mcp-use or SDK types in domain/ or application/. SDK shape churn must not ripple into business logic.
3. One composition root. It constructs concrete gateways, instantiates MCPServer, registers tools/resources/prompts, and starts the server.
4. One config seam. runtime-config.ts is the only file that reads process.env; env validates with Zod there.
5. mcp-use imports stay at the protocol edge. Allowed: handlers/, resources/, prompts/, presenters/ (response helpers), and infrastructure/.
6. Zod at boundaries. Handler input schemas live at the handler boundary; root objects strict; no z.any()/z.unknown() at tool boundaries; use cases and domain do not revalidate.
7. Forbidden TypeScript stays forbidden. No bare any, as any, @ts-ignore, or unjustified @ts-expect-error.
8. Type-only imports use import type. verbatimModuleSyntax: true required.
9. Locked TS flags. strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, noImplicitOverride, noImplicitReturns, noFallthroughCasesInSwitch, verbatimModuleSyntax, NodeNext/Node16 module settings.
10. No stdout logging. console.* forbidden under src/; stdout is the JSON-RPC wire under stdio.
11. Provider errors classify at gateways. Raw provider errors become DomainError subclasses before crossing a port.
12. Domain events and next steps emit after durable commit. Never dispatch before the side effect succeeds.
13. Entity privacy is runtime-enforced. Prefer # private fields; private is acceptable only with equivalent lint and as any blocks.
14. One tool per file. Monolithic tool files are refactor targets.
15. No application barrels. Direct imports only; index.ts barrels inside src/ cause cycles and cold-start regressions.

Canonical Layout

src/
├── domain/          # pure entities, ports, errors, ToolResponse
├── application/     # use cases and pure transforms
├── handlers/        # tool schemas, defineTool(), handler factories
├── gateways/        # outbound adapter implementations and decorators
├── presenters/      # ToolResponse -> MCP CallToolResult
├── infrastructure/  # config, middleware, errors, auth, observability, bootstrap
├── resources/       # MCP resources, including server-side widget resources
├── prompts/         # MCP prompts
└── shared/          # structural types and cross-cutting helpers

Full naming rules, rationale, and per-folder AGENTS.md guidance: references/folder-layout.md.

Import Matrix

Enforce as a CI-blocking gate; copy-paste config in references/dependency-rules.md.

MCP Primitive Placement

Blended decisions split via references/coordinate-with-build-mcp-use-server.md.

Request Flow

MCP client
  -> mcp-use server registered in bootstrap
  -> handler parses schema and resolves request context
  -> use case receives validated command and ports
  -> gateway wraps external systems and classifies provider errors
  -> use case returns ToolResponse or throws DomainError
  -> presenter renders MCP response and sanitises output
  -> mcp-use response returns to client

The handler is thin: parse, derive command, delegate, render. The use case is framework-free. The gateway hides providers. The presenter shapes data and redacts; it does not make business decisions.

Audit Smells (sweep first)

Detect these before deep reading:

• mcp-use imported from domain/, application/, gateways/, or shared/.
• process.env outside infrastructure/config/runtime-config.ts.
• server.tool( outside the composition root.
• handler files over ~250 lines or monolithic src/tools/*.ts.
• new *Gateway(...) outside bootstrap.
• z.any() / z.unknown() in handler schemas.
• console.* under src/.
• index.ts barrels under application code.

After the sweep, look up concrete examples and fix paths in references/anti-patterns.md.

Validation

Minimum gates for structural work:

• python3 scripts/validate-skills.py when editing this skills pack.
• Project typecheck and lint for target MCP repos.
• dependency-cruiser import-boundary gate.
• Focused unit tests for changed handlers/use cases/gateways/presenters.
• End-to-end MCP call only when wiring, bootstrap, transport, auth/session, or response surfaces changed.

Bundled read-only audit helpers (run from the target MCP project root, or pass the project root as the first argument):

Claim only the verification rung actually reached.

Completion Output

Finish apply/review/refactor work with:

• selected mode
• changed layers and files
• guardrails checked
• scripts/tests run
• validation rung reached
• unresolved constraints or accepted deviations

For Review mode, lead with findings ordered by severity and include replayable evidence.

Reference Routing