mcp-typescript-template AGENTS.md

Repository Guidelines

TypeScript template for building Model Context Protocol (MCP) servers over HTTP.

Key Commands

# Development (hot reload via native Node.js type stripping)
npm run dev

# Build (Vite → ES modules in dist/)
npm run build

# Production
npm start

# Lint & format
npm run lint
npm run lint:fix
npm run format
npm run format:check

# Tests
npm run test       # interactive Vitest
npm run test:ci    # outputs test-results.json

Before Submitting

Always run these and fix any failures before opening a PR:

npm run lint && npm run format:check && npm run build && npm run test:ci

Project Structure

src/
  index.ts       # HTTP routing via createMcpHandler + toNodeHandler (stateless, per-request); calls registerTools() in getServer()
  tools.ts       # registerTools() wiring + per-tool logic functions
  tools.test.ts  # colocated integration tests (in-memory client/server)
  config.ts      # Env var validation via Zod
  logger.ts      # Pino structured logging (OpenTelemetry compatible)
  lib/
    utils.ts       # MCP response helpers (createTextResult, createErrorResult)
    utils.test.ts  # colocated unit tests
dist/            # compiled output (ES modules)

Config files (vite.config.ts, tsconfig.json, eslint.config.js, Dockerfile) live at the repo root.

Architecture

• HTTP transport via Express on PORT (default 3000) — not stdio
• Tools registered via registerTools(server) in src/tools.ts, the single source of truth for tool wiring — called from getServer() in src/index.ts and reused by the tests
• Tool responses use createTextResult / createErrorResult from src/lib/utils.ts: a text content block plus structuredContent (for clients that declare an outputSchema)
• Genuine execution failures return isError: true (via createErrorResult), not thrown; valid outcomes (e.g. a user declining an elicitation) are normal results
• Stateless per the MCP 2026-07-28 spec: no initialize/initialized handshake, no Mcp-Session-Id — createMcpHandler's factory runs getServer() fresh for every HTTP request. It also serves older (2025-era) clients automatically via a stateless fallback, so no separate legacy transport is needed.
• GET /health is a plain liveness endpoint (used by the Docker healthcheck) — GET /mcp itself is routed to the MCP handler and no longer doubles as one
• If a tool needs state across calls, mint an explicit handle and have the model pass it back as an argument on the next call — there is no transport-level session to hang state off anymore
• Graceful shutdown on SIGTERM/SIGINT (closes the handler, then exits)