Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 104 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
# 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

```bash
# 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

```bash
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](https://github.com/modelcontextprotocol/registry)), README server listing changes.

## CI/CD Pipeline

Both TypeScript and Python workflows use **dynamic package detection** (find + jq matrix strategy):

1. `detect-packages` -- finds all `package.json` / `pyproject.toml` under `src/`
2. `test` -- runs tests per package
3. `build` -- compiles and type-checks per package
4. `publish` -- 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](.github/pull_request_template.md) checklist -- ensure MCP docs are read, security best practices followed, and changes tested with an LLM client
2 changes: 1 addition & 1 deletion src/everything/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
- Watch mode: `npm run watch` - Watches for changes and rebuilds automatically
- Run STDIO server: `npm run start:stdio` - Starts the MCP server using stdio transport
- Run SSE server: `npm run start:sse` - Starts the MCP server with SSE transport
- Run StreamableHttp server: `npm run start:stremableHttp` - Starts the MCP server with StreamableHttp transport
- Run StreamableHttp server: `npm run start:streamableHttp` - Starts the MCP server with StreamableHttp transport
- Prepare release: `npm run prepare` - Builds the project for publishing

## Code Style Guidelines
Expand Down
Loading