CLAUDE.md
This file provides guidance to Claude Code when working with code in this repository.
Project Overview
Official MCP reference server implementations. This is an npm workspaces monorepo containing 7 servers (4 TypeScript, 3 Python) under src/. Each server is a standalone package published to npm or PyPI.
Monorepo Structure
src/
everything/ TS @modelcontextprotocol/server-everything (reference server, all MCP features)
filesystem/ TS @modelcontextprotocol/server-filesystem (file operations with Roots access control)
memory/ TS @modelcontextprotocol/server-memory (knowledge graph persistence)
sequentialthinking/ TS @modelcontextprotocol/server-sequential-thinking (step-by-step reasoning)
fetch/ Py mcp-server-fetch (web content fetching)
git/ Py mcp-server-git (git repository operations)
time/ Py mcp-server-time (timezone queries and conversion)
Build & Test Commands
TypeScript servers
# Single server
cd src/<server> && npm ci && npm run build && npm test
# All TS servers from root
npm install && npm run build
- Build:
tsc (target ES2022, module Node16, strict mode)
- Tests: vitest with
@vitest/coverage-v8 (required for new tests)
- Node version: 22
Python servers
cd src/<server> && uv sync --frozen --all-extras --dev
# Run tests (if tests/ or test/ directory exists)
uv run pytest
# Type checking
uv run pyright
# Linting
uv run ruff check .
- Build system: hatchling (
uv build)
- Package manager: uv (not pip)
- Python version: >= 3.10 (per-server
.python-version file)
- Type checking: pyright (enforced in CI)
- Linting: ruff
Code Style
TypeScript
- ES modules with
.js extension in import paths
- Strict TypeScript typing for all functions and variables
- Zod schemas for tool input validation
- 2-space indentation, trailing commas in multi-line objects
- camelCase for variables/functions, PascalCase for types/classes, UPPER_CASE for constants
- kebab-case for file names and registered tools/prompts/resources
- Verb-first tool names (e.g.,
get-file-info, not file-info)
- Imports grouped: external first, then internal
Python
- Type hints enforced via pyright
- Async/await patterns (especially in fetch server with pytest-asyncio)
- Follow existing module layout per server
Contributing Guidelines
Accepted: Bug fixes, usability improvements, enhancements demonstrating MCP protocol features (Resources, Prompts, Roots -- not just Tools).
Selective: New features outside a server's core purpose or highly opinionated additions.
Not accepted: New server implementations (use the MCP Server Registry), README server listing changes.
CI/CD Pipeline
Both TypeScript and Python workflows use dynamic package detection (find + jq matrix strategy):
detect-packages -- finds all package.json / pyproject.toml under src/test -- runs tests per packagebuild -- compiles and type-checks per packagepublish -- on release events only (npm for TS, PyPI trusted publishing for Python)
MCP Protocol Reference
The repo is configured with an MCP docs server (.mcp.json) pointing to https://modelcontextprotocol.io/mcp. For schema details, reference https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/schema which contains versioned schemas in JSON and TypeScript formats.
Key Patterns
- Each server registers capabilities via
registerTools(server), registerResources(server), registerPrompts(server) functions
- Tool annotations: set
readOnlyHint, idempotentHint, destructiveHint per MCP spec
- Transport support: stdio (default), SSE (deprecated), Streamable HTTP
- All PRs are reviewed against the PR template checklist -- ensure MCP docs are read, security best practices followed, and changes tested with an LLM client