diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..ad30b915a8 --- /dev/null +++ b/CLAUDE.md @@ -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/ && 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/ && 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 diff --git a/README.md b/README.md index 39fae51c8f..874916cab3 100644 --- a/README.md +++ b/README.md @@ -187,6 +187,19 @@ However, running a server on its own isn't very useful, and should instead be co } ``` +On Windows, wrap `npx` with `cmd /c`: + +```json +{ + "mcpServers": { + "memory": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"] + } + } +} +``` + Additional examples of using the Claude Desktop as an MCP client might look like: ```json @@ -215,6 +228,8 @@ Additional examples of using the Claude Desktop as an MCP client might look like } ``` +On Windows, apply the same wrapper to each `npx`-based entry above by changing `"command"` to `"cmd"` and prepending `"/c", "npx"` to the existing `args`. Leave `uvx` entries unchanged. + ## 🛠️ Creating Your Own Server Interested in creating your own MCP server? Visit the official documentation at [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction) for comprehensive guides, best practices, and technical details on implementing MCP servers. diff --git a/src/everything/AGENTS.md b/src/everything/AGENTS.md index cfdcc506a0..c4a6df1348 100644 --- a/src/everything/AGENTS.md +++ b/src/everything/AGENTS.md @@ -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 diff --git a/src/everything/README.md b/src/everything/README.md index 8109e4449f..34a948a2fe 100644 --- a/src/everything/README.md +++ b/src/everything/README.md @@ -31,9 +31,27 @@ Add to your `claude_desktop_config.json`: } ``` +On Windows, use `cmd /c` to launch `npx`: + +```json +{ + "mcpServers": { + "everything": { + "command": "cmd", + "args": [ + "/c", + "npx", + "-y", + "@modelcontextprotocol/server-everything" + ] + } + } +} +``` + ## Usage with VS Code -For quick installation, use of of the one-click install buttons below... +For quick installation, use one of the one-click install buttons below... [![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-everything%22%5D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-everything%22%5D%7D&quality=insiders) @@ -62,6 +80,19 @@ Alternatively, you can add the configuration to a file called `.vscode/mcp.json` } ``` +On Windows, use: + +```json +{ + "servers": { + "everything": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-everything"] + } + } +} +``` + ## Running from source with [HTTP+SSE Transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) (deprecated as of [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports)) ```shell @@ -103,4 +134,3 @@ npx @modelcontextprotocol/server-everything sse ```shell npx @modelcontextprotocol/server-everything streamableHttp ``` - diff --git a/src/filesystem/README.md b/src/filesystem/README.md index bf087a2b25..c099da1e8c 100644 --- a/src/filesystem/README.md +++ b/src/filesystem/README.md @@ -250,6 +250,26 @@ Note: all directories must be mounted to `/projects` by default. } ``` +On Windows, use `cmd /c` to launch `npx`: + +```json +{ + "mcpServers": { + "filesystem": { + "command": "cmd", + "args": [ + "/c", + "npx", + "-y", + "@modelcontextprotocol/server-filesystem", + "/Users/username/Desktop", + "/path/to/other/allowed/dir" + ] + } + } +} +``` + ## Usage with VS Code For quick installation, click the installation buttons below... @@ -308,6 +328,25 @@ Note: all directories must be mounted to `/projects` by default. } ``` +On Windows, use: + +```json +{ + "servers": { + "filesystem": { + "command": "cmd", + "args": [ + "/c", + "npx", + "-y", + "@modelcontextprotocol/server-filesystem", + "${workspaceFolder}" + ] + } + } +} +``` + ## Build Docker build: diff --git a/src/git/README.md b/src/git/README.md index cdc77daa1b..c9ec3140be 100644 --- a/src/git/README.md +++ b/src/git/README.md @@ -139,7 +139,7 @@ Add this to your `claude_desktop_config.json`:
Using docker -* Note: replace '/Users/username' with the a path that you want to be accessible by this tool +* Note: replace '/Users/username' with a path that you want to be accessible by this tool ```json "mcpServers": { diff --git a/src/memory/README.md b/src/memory/README.md index dcc8116156..fdb8c4613e 100644 --- a/src/memory/README.md +++ b/src/memory/README.md @@ -159,6 +159,24 @@ Add this to your claude_desktop_config.json: } ``` +On Windows, use `cmd /c` to launch `npx`: + +```json +{ + "mcpServers": { + "memory": { + "command": "cmd", + "args": [ + "/c", + "npx", + "-y", + "@modelcontextprotocol/server-memory" + ] + } + } +} +``` + #### NPX with custom setting The server can be configured using the following environment variables: @@ -180,6 +198,27 @@ The server can be configured using the following environment variables: } ``` +On Windows, use: + +```json +{ + "mcpServers": { + "memory": { + "command": "cmd", + "args": [ + "/c", + "npx", + "-y", + "@modelcontextprotocol/server-memory" + ], + "env": { + "MEMORY_FILE_PATH": "/path/to/custom/memory.jsonl" + } + } + } +} +``` + - `MEMORY_FILE_PATH`: Path to the memory storage JSONL file (default: `memory.jsonl` in the server directory) # VS Code Installation Instructions @@ -216,6 +255,24 @@ Alternatively, you can add the configuration to a file called `.vscode/mcp.json` } ``` +On Windows, use: + +```json +{ + "servers": { + "memory": { + "command": "cmd", + "args": [ + "/c", + "npx", + "-y", + "@modelcontextprotocol/server-memory" + ] + } + } +} +``` + #### Docker ```json diff --git a/src/sequentialthinking/README.md b/src/sequentialthinking/README.md index 322ded2726..45d2c30f75 100644 --- a/src/sequentialthinking/README.md +++ b/src/sequentialthinking/README.md @@ -37,6 +37,36 @@ The Sequential Thinking tool is designed for: - Tasks that need to maintain context over multiple steps - Situations where irrelevant information needs to be filtered out +In practice, you do not call `sequential_thinking` directly by hand unless your client exposes raw tool calls. Instead, connect the server to an MCP-aware host and ask the model to think through a problem step by step. The host can then decide to call the tool one or more times while it works. + +### What it looks like in use + +Example prompts that typically benefit from this tool: + +- `Plan a database migration from PostgreSQL 14 to 16, list risks, and revise the plan if downtime exceeds 5 minutes.` +- `Debug why this deployment only fails in production and show your reasoning step by step.` +- `Compare three architecture options for a file sync engine and branch if one assumption turns out to be wrong.` + +### How to tell it is working + +If your host or inspector shows tool activity, you should see repeated calls to `sequential_thinking` with fields such as: + +- `thought` +- `thoughtNumber` +- `totalThoughts` +- `nextThoughtNeeded` + +When the reasoning changes course, you may also see revision or branching fields like `isRevision`, `revisesThought`, `branchFromThought`, or `branchId`. + +### Quick manual verification + +After installing the server in your MCP host: + +1. Restart or reload the host so it reconnects to the server. +2. Confirm the `sequential_thinking` tool appears in the host's MCP tool list or inspector. +3. Ask the host to solve a non-trivial problem in a step-by-step way. +4. Verify that the host invokes the tool multiple times instead of returning a one-shot answer. + ## Configuration ### Usage with Claude Desktop @@ -59,6 +89,24 @@ Add this to your `claude_desktop_config.json`: } ``` +On Windows, use `cmd /c` to launch `npx`: + +```json +{ + "mcpServers": { + "sequential-thinking": { + "command": "cmd", + "args": [ + "/c", + "npx", + "-y", + "@modelcontextprotocol/server-sequential-thinking" + ] + } + } +} +``` + #### docker ```json @@ -78,7 +126,6 @@ Add this to your `claude_desktop_config.json`: ``` To disable logging of thought information set env var: `DISABLE_THOUGHT_LOGGING` to `true`. -Comment ### Usage with VS Code @@ -114,6 +161,24 @@ For NPX installation: } ``` +On Windows, use: + +```json +{ + "servers": { + "sequential-thinking": { + "command": "cmd", + "args": [ + "/c", + "npx", + "-y", + "@modelcontextprotocol/server-sequential-thinking" + ] + } + } +} +``` + For Docker installation: ```json