# https://github.com/modelcontextprotocol/servers 项目说明书
生成时间：2026-05-15 19:59:58 UTC
## 目录
- [Home](#home)
- [Repository Structure](#repository-structure)
- [Quick Start Guide](#quick-start)
- [Everything Server](#everything-server)
- [Filesystem Server](#filesystem-server)
- [Memory Server](#memory-server)
- [Git Server](#git-server)
- [Time Server](#time-server)
- [Fetch Server](#fetch-server)
- [Sequential Thinking Server](#sequential-thinking-server)
## Home
### 相关页面
相关主题：[Repository Structure](#repository-structure), [Quick Start Guide](#quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/modelcontextprotocol/servers/blob/main/README.md)
- [CLAUDE.md](https://github.com/modelcontextprotocol/servers/blob/main/CLAUDE.md)
- [src/fetch/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/README.md)
- [src/filesystem/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/README.md)
- [src/everything/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/README.md)
- [src/time/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/time/README.md)
- [src/memory/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/memory/README.md)
# Home
## Overview
The **Model Context Protocol (MCP) Servers** repository is the official collection of reference implementations for MCP servers. MCP is a protocol that enables AI models to interact with external tools, resources, and data sources through a standardized interface.
This repository serves as a central hub for developing, documenting, and distributing MCP server implementations that can be integrated with AI assistants and development tools.
资料来源：[CLAUDE.md:1]()
## Repository Architecture
The repository follows a monorepo structure where each MCP server resides in its own directory under `src/`.
```mermaid
graph TD
A[Model Context Protocol Servers] --> B[fetch]
A --> C[sequential-thinking]
A --> D[everything]
A --> E[filesystem]
A --> F[time]
A --> G[memory]
H[Shared Infrastructure] --> A
H --> I[CLAUDE.md Guidelines]
H --> J[Contributing Standards]
```
## Available MCP Servers
### Server Comparison Table
| Server | Language | Primary Use Case | Transport |
|--------|----------|------------------|-----------|
| `fetch` | Python | HTTP content fetching | stdio |
| `sequential-thinking` | Node.js | Chain-of-thought reasoning | stdio, SSE, HTTP |
| `everything` | Node.js | Comprehensive tool suite | stdio, SSE, HTTP |
| `filesystem` | Node.js | File system operations | stdio |
| `time` | Python | Time/timezone utilities | stdio |
| `memory` | Node.js | Knowledge graph storage | stdio |
资料来源：[src/fetch/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/README.md), [src/everything/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/README.md)
### Fetch Server
The `fetch` server provides HTTP content retrieval capabilities with support for:
- Web content fetching via tools
- User-initiated requests
- robots.txt compliance (configurable)
- Custom user-agent headers
- Proxy support
**Installation Methods:**
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
```
资料来源：[src/fetch/README.md:1-50]()
### Filesystem Server
The filesystem server exposes file system operations with security boundaries:
- Read operations: read_file, read_media_file, read_multiple_files
- Directory operations: list_directory, directory_tree, search_files
- Write operations: create_directory, write_file, edit_file, move_file
- All paths validated against allowed directories
**File Operation Annotations:**
| Tool | readOnlyHint | idempotentHint | destructiveHint |
|------|--------------|----------------|-----------------|
| `write_file` | false | true | true |
| `edit_file` | false | false | true |
| `move_file` | false | false | true |
| `create_directory` | false | true | false |
资料来源：[src/filesystem/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/README.md)
### Memory Server
The memory server implements a knowledge graph for persistent entity storage:
- **create_entities**: Create new entities with type classification
- **create_relations**: Establish relationships between entities
- **add_observations**: Append observations to existing entities
- **delete_entities**: Remove entities and cascading relations
- **delete_observations**: Remove specific observations
Storage backend: JSONL file format (configurable via `MEMORY_FILE_PATH`)
资料来源：[src/memory/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/memory/README.md)
### Time Server
The time server provides timezone-aware time utilities:
- Get current time in any timezone
- Convert times between timezones
- Automatic system timezone detection
- Configurable via `--local-timezone` argument
资料来源：[src/time/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/time/README.md)
### Everything Server
The everything server aggregates multiple MCP capabilities into a single server. Supports multiple transport protocols:
- stdio (default)
- SSE (deprecated as of 2025-03-26)
- Streamable HTTP
资料来源：[src/everything/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/README.md)
## Development Standards
### TypeScript Servers
| Aspect | Standard |
|--------|----------|
| Target | ES2022 |
| Module | Node16 |
| Type System | Strict mode |
| Testing | vitest with @vitest/coverage-v8 |
| Node Version | 22 |
**Code Style Guidelines:**
- ES modules with `.js` extension in import paths
- Zod schemas for tool input validation
- 2-space indentation, trailing commas in multi-line objects
- camelCase for variables/functions, PascalCase for types/classes
- kebab-case for file names and registered tools/prompts/resources
- Verb-first tool names (e.g., `get-file-info`)
资料来源：[CLAUDE.md:5-15]()
### Python Servers
| Aspect | Standard |
|--------|----------|
| Build System | hatchling (uv build) |
| Package Manager | uv (not pip) |
| Python Version | >= 3.10 |
| Type Checking | pyright |
| Linting | ruff |
**Development Commands:**
```bash
cd src/ && uv sync --frozen --all-extras --dev
uv run pytest
uv run pyright
uv run ruff check .
```
资料来源：[CLAUDE.md:16-26]()
## Contributing
### Accepted Contributions
- Bug fixes
- Usability improvements
- Enhancements demonstrating MCP protocol features (Resources, Prompts, Roots)
### Testing Requirements
All new functionality requires corresponding tests under `tests/` or `test/` directories.
### Code Review
- Pull requests welcome
- CI enforces type checking and linting standards
资料来源：[CLAUDE.md:27-35]()
## Client Integration
### Claude Desktop
Add server configurations to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-something"]
}
}
}
```
### VS Code
One-click installation buttons available in each server's README for quick setup.
### Zed
Configuration via `settings.json` using the `context_servers` array format.
### Docker Installation
All servers support Docker deployment:
```json
{
"mcpServers": {
"server-name": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp/server-name"]
}
}
}
```
## Debugging
Use the MCP Inspector for debugging:
```bash
# For uvx installations
npx @modelcontextprotocol/inspector uvx mcp-server-fetch
# For local development
cd path/to/servers/src/
npx @modelcontextprotocol/inspector uv run mcp-server-
```
资料来源：[src/fetch/README.md:1]()
## License
All MCP servers in this repository are licensed under the MIT License, permitting free use, modification, and distribution subject to MIT License terms.
---
## Repository Structure
### 相关页面
相关主题：[Home](#home), [Quick Start Guide](#quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [package.json](https://github.com/modelcontextprotocol/servers/blob/main/package.json)
- [tsconfig.json](https://github.com/modelcontextprotocol/servers/blob/main/tsconfig.json)
- [CLAUDE.md](https://github.com/modelcontextprotocol/servers/blob/main/CLAUDE.md)
- [src/everything/package.json](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/package.json)
- [src/filesystem/package.json](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/package.json)
- [src/fetch/pyproject.toml](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/pyproject.toml)
# Repository Structure
## Overview
The [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) repository is a monorepo containing implementations of Model Context Protocol (MCP) servers. MCP is a protocol that enables AI models to interact with external tools, resources, and data sources. The repository houses multiple independent server implementations, each providing different capabilities such as filesystem access, web fetching, time utilities, and more.
The repository supports two primary implementation languages: **TypeScript/Node.js** and **Python**. This dual-language approach allows developers to choose their preferred runtime environment while maintaining feature parity across servers.
## Directory Layout
The repository follows a modular structure where each MCP server lives in its own directory under the `src/` prefix.
```
servers/
├── package.json # Root workspace configuration
├── tsconfig.json # TypeScript configuration
├── CLAUDE.md # Developer guidelines
├── .github/ # GitHub workflows and PR templates
├── src/
│ ├── everything/ # Multi-feature demonstration server (TypeScript)
│ ├── filesystem/ # File operations server (TypeScript)
│ ├── fetch/ # Web content fetching server (Python)
│ ├── memory/ # Knowledge graph memory server (TypeScript)
│ ├── sequentialthinking/ # Chain-of-thought reasoning server (TypeScript)
│ └── time/ # Time utilities server (Python)
```
Each server directory is self-contained with its own dependencies, build configuration, and documentation. The `src/everything` server serves as a reference implementation demonstrating all MCP capabilities including tools, resources, and prompts.
## Technology Stack
### TypeScript Servers
TypeScript-based servers use the following technology stack:
| Component | Technology | Version |
|-----------|------------|---------|
| Runtime | Node.js | 22 |
| Language | TypeScript | ES2022 target |
| Module System | Node16 | ES modules |
| Type Checking | TypeScript strict mode | - |
| Testing | Vitest | With @vitest/coverage-v8 |
| SDK | @modelcontextprotocol/sdk | Latest |
资料来源：[CLAUDE.md:2-8]()
The TypeScript servers share common patterns:
- **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** with trailing commas
- Naming conventions: `camelCase` for variables/functions, `PascalCase` for types/classes, `kebab-case` for file names and registered tools/prompts/resources
资料来源：[CLAUDE.md:24-30]()
### Python Servers
Python servers follow these specifications:
| Component | Technology | Version |
|-----------|------------|---------|
| Runtime | Python | >= 3.10 |
| Package Manager | uv | - |
| Build System | hatchling | - |
| Type Checking | pyright | Enforced in CI |
| Linting | ruff | - |
| Async | pytest-asyncio | For testing |
资料来源：[CLAUDE.md:10-17]()
Python server development commands follow a consistent pattern:
```bash
cd src/ && uv sync --frozen --all-extras --dev
uv run pytest # Run tests
uv run pyright # Type checking
uv run ruff check . # Linting
```
资料来源：[CLAUDE.md:12-16]()
## Server Organization
### Server Categories
The servers in this repository can be categorized by their implementation language and primary function:
```mermaid
graph TD
A[modelcontextprotocol/servers] --> B[TypeScript Servers]
A --> C[Python Servers]
B --> B1[everything]
B --> B2[filesystem]
B --> B3[memory]
B --> B4[sequentialthinking]
C --> C1[fetch]
C --> C2[time]
B1 --> B1a[Tools, Resources, Prompts]
B2 --> B2a[File Operations]
B3 --> B3a[Knowledge Graph]
B4 --> B4a[Chain-of-Thought]
C1 --> C1a[HTTP Fetching]
C2 --> C2a[Timezone Operations]
```
### TypeScript Server Structure
Each TypeScript server follows a consistent internal structure:
```
src//
├── package.json
├── tsconfig.json
├── src/
│ ├── index.ts # Main entry point
│ ├── tools/ # Tool definitions
│ ├── resources/ # Resource definitions
│ ├── prompts/ # Prompt templates
│ └── types/ # TypeScript type definitions
├── docs/ # Server documentation
└── tests/ # Test files
```
资料来源：[CLAUDE.md:35-37]()
The modular structure allows each server to register its capabilities through standardized functions:
- `registerTools(server)` - Register MCP tools
- `registerResources(server)` - Register MCP resources
- `registerPrompts(server)` - Register MCP prompts
资料来源：[CLAUDE.md:41-43]()
### Python Server Structure
Python servers use `pyproject.toml` for configuration and follow this pattern:
```
src//
├── pyproject.toml # Project metadata and dependencies
├── src/
│ └── mcp_server_/ # Package directory
│ ├── __init__.py
│ └── server.py # Main server implementation
└── tests/ # Test files
```
资料来源：[src/fetch/pyproject.toml](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/pyproject.toml)
## Configuration Patterns
### Claude Desktop Integration
Servers can be integrated with Claude Desktop through JSON configuration. Each server provides installation instructions for different deployment methods.
#### NPX Installation (Node.js servers)
```json
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-"]
}
}
}
```
资料来源：[src/filesystem/README.md:1-10]()
#### UVX Installation (Python servers)
```json
{
"mcpServers": {
"server-name": {
"command": "uvx",
"args": ["mcp-server-"]
}
}
}
```
资料来源：[src/fetch/README.md:1-8]()
#### Docker Installation
```json
{
"mcpServers": {
"server-name": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp/"]
}
}
}
```
资料来源：[src/everything/README.md:1-10]()
### Windows Configuration
Windows environments require `cmd /c` wrapper for NPX commands:
```json
{
"servers": {
"server-name": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-"]
}
}
}
```
资料来源：[src/filesystem/README.md:1-20]()
Windows users running Python servers via UVX may need to set environment variables to avoid timeout issues:
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"],
"env": {
"PYTHONIOENCODING": "utf-8"
}
}
}
}
```
资料来源：[src/fetch/README.md:1-15]()
## Build and Development
### Building Docker Images
Each server can be containerized for deployment:
```bash
docker build -t mcp/ -f src//Dockerfile .
```
资料来源：[src/filesystem/README.md:1-5]()
For the everything server:
```bash
docker build -t mcp/everything -f src/everything/Dockerfile .
```
### Running from Source
#### TypeScript Servers
```bash
cd src/
npm install
npm run start:streamableHttp # Streamable HTTP transport
npm run start:sse # SSE transport (deprecated)
```
资料来源：[src/everything/README.md:1-15]()
#### Python Servers
```bash
cd src/
uv sync --frozen --all-extras --dev
uv run mcp-server-
```
### Debugging
The MCP Inspector tool can be used to debug servers:
```bash
npx @modelcontextprotocol/inspector uvx mcp-server-
```
资料来源：[src/fetch/README.md:1-5]()
For local development:
```bash
cd path/to/servers/src/
npx @modelcontextprotocol/inspector uv run mcp-server-
```
## Contributing Patterns
### Adding New Servers
The repository provides clear guidelines for extending the project:
1. Create a new directory under `src//`
2. Follow the established patterns for your implementation language
3. Implement server capability registration functions
4. Add comprehensive documentation
### Key Contributing Guidelines
| Aspect | Requirement |
|--------|-------------|
| Tool naming | Verb-first (e.g., `get-file-info`) |
| Annotations | Set `readOnlyHint`, `idempotentHint`, `destructiveHint` per MCP spec |
| Transport support | stdio (default), SSE (deprecated), Streamable HTTP |
| Testing | Add tests using vitest (TS) or pytest (Python) |
| Documentation | Include README.md with configuration examples |
资料来源：[CLAUDE.md:41-46]()
### Everything Server as Reference
The `src/everything` server demonstrates all MCP features and is an excellent reference for implementing new servers:
- **Modular structure**: Separate modules for tools, resources, and prompts
- **Registration pattern**: `registerX(server)` functions following SDK conventions
- **Schema accuracy**: JSON Schema with descriptions and examples
- **Extensibility**: Easy to add new modules following existing patterns
资料来源：[src/everything/AGENTS.md:1-8]()
## Transport Protocols
The repository supports multiple transport mechanisms for client-server communication:
| Transport | Status | Description |
|-----------|--------|-------------|
| stdio | Default | Standard input/output communication |
| Streamable HTTP | Current | Modern HTTP-based transport |
| SSE | Deprecated | Server-Sent Events (deprecated 2025-03-26) |
资料来源：[src/everything/README.md:1-20]()
The streamable HTTP transport is the recommended modern approach:
```bash
npx @modelcontextprotocol/server- streamableHttp
```
## Tool Annotation System
TypeScript servers use a standardized annotation system for tools to indicate their behavior to clients:
| Annotation | Description | Values |
|------------|-------------|--------|
| `readOnlyHint` | Indicates if tool modifies state | `true`/`false` |
| `idempotentHint` | Indicates if repeated calls produce same result | `true`/`false` |
| `destructiveHint` | Indicates if tool deletes data | `true`/`false` |
资料来源：[src/filesystem/README.md:1-30]()
Example from the filesystem server:
```typescript
server.registerTool(
"write_file",
{
title: "Write File",
inputSchema: {
path: z.string(),
content: z.string()
},
annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: true }
},
async (args) => { /* ... */ }
);
```
资料来源：[src/filesystem/index.ts:1-25]()
## Summary
The modelcontextprotocol/servers repository is organized as a well-structured monorepo that:
- Contains multiple independent MCP server implementations under `src/`
- Supports both TypeScript (Node.js 22) and Python (>=3.10) implementations
- Follows consistent patterns for tool, resource, and prompt registration
- Provides flexible deployment options (NPX, UVX, Docker)
- Includes comprehensive documentation and debugging tools
- Enforces type safety and testing through CI/CD
The `everything` server serves as the primary reference implementation, while other servers demonstrate specialized use cases like filesystem operations, web fetching, time utilities, and knowledge graph storage.
---
## Quick Start Guide
### 相关页面
相关主题：[Home](#home), [Everything Server](#everything-server)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/modelcontextprotocol/servers/blob/main/README.md)
- [src/memory/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/memory/README.md)
- [src/fetch/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/README.md)
- [src/sequentialthinking/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/README.md)
- [src/filesystem/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/README.md)
- [src/everything/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/README.md)
- [src/time/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/time/README.md)
- [CLAUDE.md](https://github.com/modelcontextprotocol/servers/blob/main/CLAUDE.md)
# Quick Start Guide
This guide provides a comprehensive introduction to getting started with Model Context Protocol (MCP) servers. MCP servers are tools that extend the capabilities of AI assistants like Claude by providing access to external resources, file systems, databases, and more.
## Overview
The MCP servers repository contains a collection of standalone servers that implement the Model Context Protocol. Each server provides specific functionality that can be integrated into MCP-compatible clients such as Claude Desktop, VS Code, and Zed.
```mermaid
graph TD
A[MCP Client] --> B[MCP Server]
B --> C[Git Server]
B --> D[Memory Server]
B --> E[Filesystem Server]
B --> F[Fetch Server]
B --> G[Time Server]
B --> H[Everything Server]
B --> I[Sequential Thinking Server]
```
## Prerequisites
Before getting started with MCP servers, ensure your environment meets the following requirements.
### System Requirements
| Component | Requirement |
|-----------|-------------|
| Node.js | Version 22+ (for TypeScript servers) |
| Python | Version 3.10+ (for Python servers) |
| Docker | Latest stable version (optional) |
| Package Manager | `uv` (recommended), `pip`, or `npm` |
### Required Tools
Based on the project guidelines, the following tools are required:
- **For Python servers**: `uv` is the primary package manager 资料来源：[CLAUDE.md]()
- **For Node.js servers**: `npm` or `npx` 资料来源：[README.md]()
- **For containerized deployment**: Docker
## Installation Methods
MCP servers support multiple installation methods. Choose the one that best fits your environment.
### Method 1: Using uvx (Recommended)
`uvx` is the recommended installation method for Python-based servers. It provides easy setup and automatic dependency management 资料来源：[README.md]()
```bash
# Install a single server
uvx mcp-server-git
# Or install via npm for quick testing
npx @modelcontextprotocol/server-memory
```
### Method 2: Using pip
For Python servers, you can also use pip directly:
```bash
# Install the server package
pip install mcp-server-git
# Run the server
python -m mcp_server_git
```
### Method 3: Using Docker
Docker provides isolation and consistency across different environments:
```bash
# Pull and run a pre-built image
docker run -i --rm mcp/filesystem
# Build your own image
docker build -t mcp/filesystem -f src/filesystem/Dockerfile .
```
### Method 4: Using npx (Node.js)
For TypeScript/JavaScript servers:
```bash
# Run directly with npx
npx -y @modelcontextprotocol/server-memory
```
## Quick Start by Server Type
### Git Server
The Git server provides tools for interacting with Git repositories.
**Installation:**
```bash
uvx mcp-server-git
```
**Alternative with pip:**
```bash
pip install mcp-server-git
python -m mcp_server_git
```
资料来源：[README.md]()
### Memory Server
The Memory server provides a knowledge graph storage system for maintaining persistent context across conversations 资料来源：[src/memory/README.md]()
**Installation:**
```bash
npx -y @modelcontextprotocol/server-memory
```
**Custom Configuration:**
| Parameter | Description | Default |
|-----------|-------------|---------|
| `MEMORY_FILE_PATH` | Path to the memory storage JSONL file | `memory.jsonl` |
**Example Configuration:**
```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"],
"env": {
"MEMORY_FILE_PATH": "/path/to/custom/memory.jsonl"
}
}
}
}
```
### Filesystem Server
The Filesystem server provides secure file system access within allowed directories 资料来源：[src/filesystem/README.md]()
**Installation:**
```bash
npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir
```
**Available Tools:**
| Tool | Read Only | Idempotent | Destructive | Notes |
|------|-----------|------------|-------------|-------|
| `read_file` | ✓ | – | – | Pure read |
| `read_media_file` | ✓ | – | – | Pure read |
| `read_multiple_files` | ✓ | – | – | Pure read |
| `list_directory` | ✓ | – | – | Pure read |
| `search_files` | ✓ | – | – | Pure read |
| `write_file` | ✗ | ✓ | ✓ | Overwrites existing files |
| `edit_file` | ✗ | ✗ | ✓ | May double-apply edits |
| `move_file` | ✗ | ✗ | ✓ | Deletes source file |
| `create_directory` | ✗ | ✓ | ✗ | Re-creating same dir is no-op |
### Fetch Server
The Fetch server enables web content retrieval with proper robots.txt compliance 资料来源：[src/fetch/README.md]()
**Installation:**
```bash
uvx mcp-server-fetch
```
**Customization Options:**
| Argument | Description |
|----------|-------------|
| `--ignore-robots-txt` | Disable robots.txt compliance |
| `--user-agent=` | Custom user-agent string |
| `--proxy-url=` | Configure proxy server |
**Default User-Agents:**
```
ModelContextProtocol/1.0 (Autonomous; +https://github.com/modelcontextprotocol/servers)
ModelContextProtocol/1.0 (User-Specified; +https://github.com/modelcontextprotocol/servers)
```
### Time Server
The Time server provides timezone-aware time operations 资料来源：[src/time/README.md]()
**Installation:**
```bash
uvx mcp-server-time
```
**Available Tools:**
| Tool | Description |
|------|-------------|
| `get_current_time` | Get current time in a specified timezone |
| `convert_time` | Convert time between timezones |
**Example Request:**
```json
{
"name": "get_current_time",
"arguments": {
"timezone": "Europe/Warsaw"
}
}
```
### Sequential Thinking Server
The Sequential Thinking server provides structured reasoning capabilities 资料来源：[src/sequentialthinking/README.md]()
**Installation:**
```bash
npx -y @modelcontextprotocol/server-sequential-thinking
```
**Building from Source:**
```bash
docker build -t mcp/sequentialthinking -f src/sequentialthinking/Dockerfile .
```
### Everything Server
The Everything server aggregates multiple MCP server capabilities into a single endpoint 资料来源：[src/everything/README.md]()
**Installation:**
```bash
npx -y @modelcontextprotocol/server-everything
```
**Available Transport Options:**
| Transport | Command |
|-----------|---------|
| stdio | `npx @modelcontextprotocol/server-everything stdio` |
| SSE (deprecated) | `npx @modelcontextprotocol/server-everything sse` |
| Streamable HTTP | `npx @modelcontextprotocol/server-everything streamableHttp` |
## Client Configuration
### Claude Desktop Configuration
Add server configurations to your Claude Desktop settings file 资料来源：[README.md]():
```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
}
}
}
```
### Windows Configuration
On Windows, wrap commands with `cmd /c`:
```json
{
"mcpServers": {
"memory": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"]
}
}
}
```
### VS Code Configuration
Quick installation buttons are available for VS Code and VS Code Insiders. Simply click the badge to install:
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
```
### Zed Configuration
```json
"context_servers": {
"mcp-server-time": {
"command": "uvx",
"args": ["mcp-server-time"]
}
}
```
## Development Setup
### Setting Up Python Server Development
```bash
cd src/ && uv sync --frozen --all-extras --dev
# Run tests
uv run pytest
# Type checking
uv run pyright
# Linting
uv run ruff check .
```
资料来源：[CLAUDE.md]()
### Setting Up Node.js Server Development
```bash
cd src/
npm install
npm run build
```
**Testing:**
```bash
npm test
```
## Troubleshooting
### Common Issues
#### Timeout Issues on Windows
If experiencing timeout issues on Windows, set the `PYTHONIOENCODING` environment variable:
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"],
"env": {
"PYTHONIOENCODING": "utf-8"
}
}
}
}
```
#### Character Encoding Issues
For servers that handle text content, ensure proper encoding by adding environment variables or command-line arguments as shown above.
### Debugging with MCP Inspector
Use the MCP inspector to debug server functionality:
```bash
# For uvx installations
npx @modelcontextprotocol/inspector uvx mcp-server-fetch
# For local development
cd path/to/servers/src/fetch
npx @modelcontextprotocol/inspector uv run mcp-server-fetch
```
## Architecture Overview
```mermaid
graph LR
A[Client Application] -->|MCP Protocol| B[Transport Layer]
B -->|stdio/sse/http| C[Server Implementation]
C -->|Tool Execution| D[External Resources]
D -->|Results| C
C -->|Formatted Response| B
B -->|MCP Response| A
```
### Transport Methods
| Transport | Use Case | Persistent Connection |
|-----------|----------|----------------------|
| stdio | CLI tools, Desktop apps | ✗ |
| SSE | Real-time updates | ✓ |
| Streamable HTTP | Web applications | ✓ |
## Next Steps
- Explore individual server documentation for advanced features
- Review the [CLAUDE.md](https://github.com/modelcontextprotocol/servers/blob/main/CLAUDE.md) for contribution guidelines
- Check the main [README.md](https://github.com/modelcontextprotocol/servers/blob/main/README.md) for the complete server list
- Join the community to share your implementations and extensions
---
## Everything Server
### 相关页面
相关主题：[Filesystem Server](#filesystem-server), [Memory Server](#memory-server)
相关源码文件
以下源码文件用于生成本页说明：
- [src/everything/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/README.md)
- [src/everything/server/index.ts](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/server/index.ts)
- [src/everything/tools/index.ts](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/tools/index.ts)
- [src/everything/resources/index.ts](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/resources/index.ts)
- [src/everything/resources/session.ts](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/resources/session.ts)
- [src/everything/docs/features.md](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/docs/features.md)
- [src/everything/docs/architecture.md](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/docs/architecture.md)
- [src/everything/docs/extension.md](https://github.com/modelcontextprotocol/servers/blob/main/src/everything/docs/extension.md)
# Everything Server
## Overview
The Everything Server is a comprehensive Model Context Protocol (MCP) server implementation that provides a wide range of tools, resources, and prompts for AI-assisted interactions. It serves as a reference implementation demonstrating the full capabilities of the MCP specification. 资料来源：[src/everything/README.md]()
### Purpose and Scope
The Everything Server is designed to:
- Provide a complete example of MCP server implementation patterns
- Offer practical tools for file system operations, memory management, and more
- Demonstrate resource and prompt template capabilities
- Support multiple transport mechanisms for different use cases
- Serve as a foundation for building custom MCP servers 资料来源：[src/everything/AGENTS.md]()
## Architecture
### High-Level Architecture
```mermaid
graph TD
A[Client] -->|MCP Protocol| B[Transport Layer]
B --> C[stdio]
B --> D[SSE]
B --> E[Streamable HTTP]
C --> F[Server Core]
D --> F
E --> F
F --> G[Tools Handler]
F --> H[Resources Handler]
F --> I[Prompts Handler]
G --> J[File System Tools]
G --> K[Memory Tools]
G --> L[Utility Tools]
H --> M[Static Resources]
H --> N[Dynamic Resources]
I --> O[Prompt Templates]
```
### Module Structure
The server is organized into distinct modules following a clear separation of concerns: 资料来源：[src/everything/docs/architecture.md]()
| Module | Purpose | Key Files |
|--------|---------|-----------|
| **server** | Core server implementation and transport handling | `server/index.ts` |
| **tools** | Tool definitions and handlers | `tools/index.ts`, `tools/*.ts` |
| **resources** | Resource registration and management | `resources/index.ts`, `resources/session.ts` |
| **prompts** | Prompt templates | `prompts/index.ts` |
### Component Hierarchy
```mermaid
graph TD
A[McpServer Instance] --> B[Tools Registry]
A --> C[Resources Registry]
A --> D[Prompts Registry]
B --> E[Tool Handlers]
C --> F[Resource Providers]
D --> G[Prompt Definitions]
E --> H[File Operations]
E --> I[Memory Operations]
E --> J[Utility Operations]
```
## Installation
### Prerequisites
- Node.js version 22 or higher
- npm or npx for package management 资料来源：[CLAUDE.md]()
### Installation Methods
#### Global npm Installation
```bash
npm install -g @modelcontextprotocol/server-everything@latest
```
#### Using npx (No Installation Required)
```bash
npx @modelcontextprotocol/server-everything
```
#### Docker
```bash
docker run -i --rm mcp/everything
```
#### Running from Source
```bash
cd src/everything
npm install
npm run start:streamableHttp
```
资料来源：[src/everything/README.md]()
### Claude Desktop Configuration
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"everything": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-everything"]
}
}
}
```
#### Windows Configuration
On Windows, use `cmd /c` for proper process handling:
```json
{
"mcpServers": {
"everything": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-everything"]
}
}
}
```
## Transport Options
The Everything Server supports multiple transport mechanisms for communication with MCP clients.
### Supported Transports
| Transport | Status | Description |
|-----------|--------|-------------|
| **stdio** | Default | Standard input/output transport for CLI integration |
| **Streamable HTTP** | Recommended | Modern transport supporting streaming responses (recommended as of 2025-03-26) |
| **SSE** | Deprecated | Server-Sent Events transport (deprecated as of 2025-03-26) |
### Running with Different Transports
```bash
# Default (stdio)
npx @modelcontextprotocol/server-everything
# Explicitly stdio
npx @modelcontextprotocol/server-everything stdio
# SSE (deprecated)
npx @modelcontextprotocol/server-everything sse
# Streamable HTTP (recommended)
npx @modelcontextprotocol/server-everything streamableHttp
```
资料来源：[src/everything/README.md]()
## Features
### Core Capabilities
The Everything Server provides a comprehensive set of features: 资料来源：[src/everything/docs/features.md]()
- **Tool Orchestration**: Extensive set of tools for various operations
- **Resource Management**: Static and dynamic resource provision
- **Prompt Templates**: Reusable prompt definitions
- **Session Resources**: Dynamic session-based resource creation
- **Multi-Transport Support**: stdio, HTTP+SSE, and Streamable HTTP
### Tool Categories
| Category | Tools | Description |
|----------|-------|-------------|
| **File System** | read_file, write_file, edit_file, move_file, list_directory, etc. | Full file system operations within allowed directories |
| **Memory** | create_entities, create_relations, add_observations, etc. | Knowledge graph operations for persistent memory |
| **Time** | get_current_time, convert_timezone | Time and timezone utilities |
| **Utility** | Echo, random, etc. | General purpose utilities |
## Tools Reference
### Tool Registration Pattern
Tools are registered using the MCP SDK with Zod schemas for input validation: 资料来源：[src/everything/tools/index.ts]()
```typescript
server.registerTool(
"tool_name",
{
title: "Tool Title",
description: "Tool description",
inputSchema: { /* Zod schema */ },
outputSchema: { /* output schema */ },
annotations: {
readOnlyHint: boolean,
idempotentHint: boolean,
destructiveHint: boolean
}
},
async (args) => {
// Handler implementation
}
);
```
### Tool Annotations
Each tool includes annotations describing its behavior: 资料来源：[src/filesystem/README.md]()
| Annotation | Values | Description |
|------------|--------|-------------|
| `readOnlyHint` | `true/false` | Whether the tool only reads data |
| `idempotentHint` | `true/false` | Whether repeated calls produce the same result |
| `destructiveHint` | `true/false` | Whether the tool modifies or deletes data |
## Resources
### Resource Types
The Everything Server implements resources following the MCP specification: 资料来源：[src/everything/resources/index.ts]()
```mermaid
graph LR
A[Resources] --> B[Static Resources]
A --> C[Dynamic Resources]
A --> D[Session Resources]
B --> E[Pre-registered at startup]
C --> F[Generated on-demand]
D --> G[Created per session]
```
### Session Resources
Session resources are dynamically created and managed: 资料来源：[src/everything/resources/session.ts:1-65]()
```typescript
export const registerSessionResource = (
server: McpServer,
resource: Resource,
type: "text" | "blob",
payload: string
): ResourceLink => {
// Prepare resource content based on type
const resourceContent = type === "text"
? { uri: uri.toString(), mimeType, text: payload }
: { uri: uri.toString(), mimeType, blob: payload };
// Remove existing resource with same URI if present
const existingResource = registeredResources.get(uri);
if (existingResource) {
existingResource.remove();
registeredResources.delete(uri);
}
// Register the resource with the server
const registeredResource = server.registerResource(
name, uri,
{ mimeType, description, title, annotations, icons, _meta },
async () => ({ contents: [resourceContent] })
);
registeredResources.set(uri, registeredResource);
return { type: "resource_link", ...resource };
};
```
## Extension Guide
### Adding New Tools
To extend the Everything Server with new tools: 资料来源：[src/everything/docs/extension.md]()
1. Create a new file in the `tools/` folder (naming, exports, and registration function)
2. Export a `registerX(server)` function that registers new items with the MCP SDK
3. Wire your new module into the central index (`tools/index.ts`)
4. Ensure schemas are accurate JSON Schema with helpful descriptions and examples
### Extension Pattern
```typescript
// tools/example-tool.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
export function registerExampleTool(server: McpServer): void {
server.registerTool(
"example_tool",
{
title: "Example Tool",
description: "An example tool demonstrating the extension pattern",
inputSchema: {
param: z.string().describe("Example parameter")
},
outputSchema: { result: z.string() }
},
async (args) => {
// Implementation
return { content: [{ type: "text", text: result }] };
}
);
}
```
### Updating Documentation
Keep the documentation in `src/everything/docs/` up to date when adding or modifying features. 资料来源：[src/everything/AGENTS.md]()
## Configuration
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `MEMORY_FILE_PATH` | Path to memory storage JSONL file | `memory.jsonl` in server directory |
### Claude Desktop Configuration Example
```json
{
"mcpServers": {
"everything": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-everything"],
"env": {
"MEMORY_FILE_PATH": "/path/to/custom/memory.jsonl"
}
}
}
}
```
## Development
### Project Structure
```
src/everything/
├── index.ts # Main entry point
├── server/
│ └── index.ts # Server configuration
├── tools/
│ ├── index.ts # Tool registry
│ └── *.ts # Individual tool implementations
├── resources/
│ ├── index.ts # Resource registry
│ └── session.ts # Session resource management
├── prompts/
│ └── index.ts # Prompt templates
└── docs/
├── features.md # Feature documentation
├── architecture.md # Architecture details
└── extension.md # Extension guide
```
### Build Requirements
- **Runtime**: Node.js 22
- **Target**: ES2022
- **Module**: Node16
- **Type Checking**: Strict TypeScript mode
- **Testing**: vitest with @vitest/coverage-v8 资料来源：[CLAUDE.md]()
### Code Style Guidelines
#### TypeScript Standards
- 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 with trailing commas
- camelCase for variables/functions, PascalCase for types/classes
- kebab-case for file names and registered tools/prompts/resources
- Verb-first tool names (e.g., `get-file-info`, not `file-info`) 资料来源：[CLAUDE.md]()
## Troubleshooting
### Common Issues
| Issue | Solution |
|-------|----------|
| Transport timeout | Ensure proper transport configuration; use Streamable HTTP for better reliability |
| Resource not found | Check resource URI and registration status |
| Windows process handling | Use `cmd /c` wrapper for npx commands |
### Debugging
Use the MCP inspector for debugging:
```bash
cd src/everything
npx @modelcontextprotocol/inspector
```
## License
The Everything Server is licensed under the MIT License. You are free to use, modify, and distribute the software subject to the terms and conditions of the MIT License. 资料来源：[src/everything/README.md]()
## See Also
- [MCP Specification](https://modelcontextprotocol.io/specification)
- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk)
---
## Filesystem Server
### 相关页面
相关主题：[Everything Server](#everything-server), [Git Server](#git-server)
相关源码文件
以下源码文件用于生成本页说明：
- [src/filesystem/package.json](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/package.json)
- [src/filesystem/index.ts](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/index.ts)
- [src/filesystem/lib.ts](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/lib.ts)
- [src/filesystem/path-validation.ts](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/path-validation.ts)
- [src/filesystem/roots-utils.ts](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/roots-utils.ts)
- [src/filesystem/path-utils.ts](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/path-utils.ts)
- [src/filesystem/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/filesystem/README.md)
# Filesystem Server
The Filesystem Server is an MCP (Model Context Protocol) server implementation that provides secure file system access capabilities to AI models and clients. It enables reading, writing, and managing files and directories within configurable sandboxed environments, with comprehensive security controls through path validation and access restrictions.
## Overview
The Filesystem Server bridges AI assistants with the local file system by exposing a standardized set of tools that perform file operations. All operations are scoped to user-defined allowed directories, preventing unauthorized access to system files or sensitive locations.
**Key Characteristics:**
| Attribute | Value |
|-----------|-------|
| Transport | stdio (default), Streamable HTTP |
| Language | TypeScript (Node.js) |
| SDK | @modelcontextprotocol/sdk |
| License | MIT |
| Mount Point | `/projects` (Docker default) |
资料来源：[src/filesystem/README.md:1-10]()
## Architecture
```mermaid
graph TD
A[MCP Client] -->|MCP Protocol| B[Filesystem Server]
B --> C[Tool Handlers]
C --> D[Path Validation Layer]
D --> E[Allowed Directories]
D --> F[File System Operations]
F --> G[read_text_file]
F --> H[write_file]
F --> I[create_directory]
F --> J[move_file]
F --> K[list_directory]
F --> L[search_files]
E --> M[Security Boundaries]
```
### Core Components
| Component | File | Responsibility |
|-----------|------|-----------------|
| Server Entry | `index.ts` | MCP server initialization, tool registration |
| Path Validation | `path-validation.ts` | Security checks, allowed directory enforcement |
| File Operations | `lib.ts` | Core read/write operations implementation |
| Path Utilities | `path-utils.ts` | Path manipulation and normalization |
| Roots Utilities | `roots-utils.ts` | MCP roots protocol integration |
资料来源：[src/filesystem/index.ts:1-50]()
## Tool Specifications
### Read Operations
All read tools have `readOnlyHint: true` annotation, indicating they do not modify system state.
| Tool | Description | Input | Output |
|------|-------------|-------|--------|
| `read_text_file` | Read complete file contents as UTF-8 text | `path: string`, optional `head?: number`, `tail?: number` | `content: string` |
| `read_media_file` | Read image/audio as base64 | `path: string` | `blob: string`, `mimeType: string` |
| `read_multiple_files` | Read multiple files simultaneously | `paths: string[]` | Combined content with separators |
| `get_file_info` | Retrieve file metadata | `path: string` | Size, timestamps, type |
| `list_directory` | List directory contents | `path: string` | Files and subdirectories with [FILE]/[DIR] prefixes |
| `list_directory_with_sizes` | List with file sizes | `path: string`, optional `sortBy: "name" \| "size"` | Detailed listing with sizes |
| `directory_tree` | Recursive directory structure | `path: string` | Hierarchical tree view |
| `search_files` | Find files by pattern | `path: string`, `pattern: string` | Matching file paths |
| `list_allowed_directories` | Show permitted paths | none | List of allowed directories |
资料来源：[src/filesystem/README.md:15-30]()
### Write Operations
| Tool | readOnlyHint | idempotentHint | destructiveHint | Description |
|------|--------------|----------------|-----------------|-------------|
| `write_file` | false | true | true | Create or overwrite files |
| `edit_file` | false | false | false | Selective edits with diff preview |
| `create_directory` | false | true | false | Create directories (idempotent) |
| `move_file` | false | false | true | Move/rename files |
资料来源：[src/filesystem/README.md:32-40]()
### Annotation Semantics
```mermaid
graph LR
A[readOnlyHint] --> B{true?}
B -->|Yes| C[Read operations
No state changes]
B -->|No| D[destructiveHint & idempotentHint
become meaningful]
D --> E[idempotentHint: true
Re-running safe]
D --> F[idempotentHint: false
May fail on retry]
D --> G[destructiveHint: true
Cannot undo]
```
> **Note:** `idempotentHint` and `destructiveHint` are meaningful only when `readOnlyHint` is `false`, as defined by the MCP specification.
资料来源：[src/filesystem/README.md:42-44]()
## Security Model
The Filesystem Server implements multiple security layers to prevent unauthorized file system access.
### Path Validation
```mermaid
graph TD
A[Incoming Path] --> B{Normalize Path}
B --> C{Relative to allowed directory?}
C -->|No| D[Reject with error]
C -->|Yes| E{Symlink traversal safe?}
E -->|No| D
E -->|Yes| F[Allow operation]
```
**Validation Rules:**
1. All paths are normalized before comparison
2. Symbolic links are resolved and checked against allowed directories
3. Attempting to escape allowed directories via `..` or symlinks is blocked
4. Operations are rejected if the resolved path falls outside permitted boundaries
资料来源：[src/filesystem/path-validation.ts:1-30]()
### Allowed Directories Configuration
| Deployment Method | Configuration |
|-------------------|---------------|
| Docker | Mount directories to `/projects` |
| NPX | Pass directories as arguments |
| Programmatic | Set allowed directories at initialization |
**Docker Example:**
```bash
docker run -i --rm \
--mount type=bind,src=/host/path,dst=/projects/path \
mcp/filesystem /projects
```
**NPX Example:**
```bash
npx -y @modelcontextprotocol/server-filesystem \
/Users/username/Desktop \
/path/to/allowed/dir
```
资料来源：[src/filesystem/README.md:55-75]()
## Installation Methods
### Docker
```json
{
"mcpServers": {
"filesystem": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
"mcp/filesystem",
"/projects"
]
}
}
}
```
### NPX (Unix/macOS)
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"${workspaceFolder}"
]
}
}
}
```
### NPX (Windows)
```json
{
"mcpServers": {
"filesystem": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@modelcontextprotocol/server-filesystem",
"${workspaceFolder}"
]
}
}
}
```
资料来源：[src/filesystem/README.md:55-95]()
## Tool Detailed Reference
### read_text_file
Reads complete file contents as UTF-8 text regardless of file extension.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Absolute or relative path to file |
| `head` | number | No | Return only first N lines |
| `tail` | number | No | Return only last N lines |
**Constraints:** Cannot specify both `head` and `tail` simultaneously.
资料来源：[src/filesystem/README.md:98-110]()
### read_media_file
Reads image or audio files and returns base64-encoded data with MIME type.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Path to media file |
**Returns:**
- `blob`: Base64-encoded file content
- `mimeType`: Corresponding MIME type (e.g., `image/png`, `audio/mpeg`)
资料来源：[src/filesystem/README.md:112-120]()
### edit_file
Performs selective edits using pattern matching with indentation preservation.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | File to edit |
| `edits` | array | Yes | List of edit operations |
| `dryRun` | boolean | No | Preview without applying (default: false) |
**Edit Operation Schema:**
```typescript
{
oldText: string; // Text to search for (can be substring)
newText: string; // Replacement text
}
```
**Features:**
- Line-based and multi-line content matching
- Whitespace normalization with indentation preservation
- Git-style diff output with context
- Preview changes with dry run mode
**Best Practice:** Always use `dryRun: true` first to preview changes before applying them.
资料来源：[src/filesystem/README.md:132-150]()
### move_file
Moves or renames files and directories.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source` | string | Yes | Source file path |
| `destination` | string | Yes | Destination path |
**Behavior:**
- Fails if destination already exists
- Deletes source file after successful move
- `destructiveHint: true` - operation cannot be automatically undone
资料来源：[src/filesystem/README.md:165-175]()
### list_directory_with_sizes
Lists directory contents with detailed file size information.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | Yes | Directory path to list |
| `sortBy` | string | No | Sort by `"name"` or `"size"` (default: `"name"`) |
**Returns:** Detailed listing including file sizes and summary statistics (total files, directories, combined size).
资料来源：[src/filesystem/README.md:155-163]()
## Building from Source
### Prerequisites
- Node.js 22+
- npm or docker
### Docker Build
```bash
docker build -t mcp/filesystem -f src/filesystem/Dockerfile .
```
### Local Development
```bash
cd src/filesystem
npm install
npm run build
```
资料来源：[src/filesystem/README.md:45-50]()
## MCP Protocol Integration
### Resources
The server may expose allowed directories as MCP Resources with the `roots://` URI scheme.
```mermaid
sequenceDiagram
participant Client
participant Server
participant FileSystem
Client->>Server: List Roots
Server->>Server: Check roots-utils
Server-->>Client: Allowed directory list
Client->>Server: Tool call (e.g., read_file)
Server->>FileSystem: Operation
FileSystem-->>Server: Result
Server-->>Client: Tool response
```
资料来源：[src/filesystem/roots-utils.ts:1-25]()
## License
The Filesystem Server is licensed under the **MIT License**. This permits free use, modification, and distribution subject to MIT License terms.
资料来源：[src/filesystem/README.md:51-54]()
---
## Memory Server
### 相关页面
相关主题：[Everything Server](#everything-server)
相关源码文件
以下源码文件用于生成本页说明：
- [src/memory/package.json](https://github.com/modelcontextprotocol/servers/blob/main/src/memory/package.json)
- [src/memory/index.ts](https://github.com/modelcontextprotocol/servers/blob/main/src/memory/index.ts)
- [src/memory/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/memory/README.md)
# Memory Server
The Memory Server is an MCP (Model Context Protocol) server implementation that provides persistent knowledge graph capabilities for AI assistants like Claude. It enables AI models to maintain long-term memory across conversations by storing and retrieving structured information about users, entities, relationships, and events.
## Overview
The Memory Server implements a knowledge graph storage system that allows AI assistants to:
- Store information about users and their characteristics
- Maintain relationships between entities
- Retrieve relevant context from previous interactions
- Update memory dynamically during conversations
资料来源：[src/memory/package.json:3]()
```mermaid
graph TD
A[Claude Conversation] --> B[Memory Server]
B --> C[Knowledge Graph Storage]
C --> D[JSONL File Storage]
B --> E[Memory Retrieval]
E --> F[Return Entities & Relations]
B --> G[Memory Update]
G --> H[Create/Update Entities]
G --> I[Create Relations]
I --> C
```
## Architecture
The Memory Server is built using the Model Context Protocol SDK and stores data in a JSONL (JSON Lines) format file. The server provides tools for managing a graph-based knowledge structure with entities and relations.
资料来源：[src/memory/package.json:1-2]()
### Core Components
| Component | Description |
|-----------|-------------|
| Knowledge Graph | Graph-based storage for entities and relationships |
| JSONL Storage | Persistent file storage in JSON Lines format |
| MCP SDK Integration | Uses `@modelcontextprotocol/sdk` for MCP protocol support |
| Memory API | Tools for CRUD operations on memory entities |
## Installation
### Docker Installation
```json
{
"mcpServers": {
"memory": {
"command": "docker",
"args": [
"run",
"-i",
"-v",
"claude-memory:/app/dist",
"--rm",
"mcp/memory"
]
}
}
}
```
资料来源：[src/memory/README.md]()
### NPX Installation (Unix/macOS)
```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-memory"
]
}
}
}
```
### NPX Installation (Windows)
Windows requires using `cmd` with `/c` flag to launch `npx`:
```json
{
"mcpServers": {
"memory": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@modelcontextprotocol/server-memory"
]
}
}
}
```
## Configuration
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `MEMORY_FILE_PATH` | Path to the memory storage JSONL file | `memory.jsonl` in server directory |
### Custom Storage Path Example
```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-memory"
],
"env": {
"MEMORY_FILE_PATH": "/path/to/custom/memory.jsonl"
}
}
}
}
```
资料来源：[src/memory/README.md]()
## Memory Operations
The Memory Server supports the following core operations:
### User Identification
The system assumes interaction with a default user and proactively identifies them if not already known:
```
- Assume interaction with default_user
- Proactively identify user if not already done
```
### Memory Retrieval
At the start of each conversation, the system retrieves relevant information from the knowledge graph:
```
- Begin chat by saying "Remembering..."
- Retrieve all relevant information from knowledge graph
- Reference knowledge graph as "memory"
```
### Memory Categories
During conversation, the system stores new information in these categories:
| Category | Description | Examples |
|----------|-------------|----------|
| Basic Identity | Personal identifiers | Age, gender, location, job title, education |
| Behaviors | User patterns | Interests, habits, preferences |
| Preferences | Communication style | Preferred language, communication style |
| Goals | Aspirations | Goals, targets, objectives |
| Relationships | Connections | Personal and professional relationships (up to 3 degrees) |
资料来源：[src/memory/README.md]()
### Memory Update Process
When new information is gathered during interaction:
```mermaid
graph TD
A[New Information Gathered] --> B{Is it recurring?}
B -->|Organization| C[Create Entity for Organization]
B -->|Person| D[Create Entity for Person]
B -->|Event| E[Create Entity for Event]
C --> F[Connect to Current Entities]
D --> F
E --> F
F --> G[Create Relations]
G --> H[Update Knowledge Graph]
```
The update process:
1. Creates entities for recurring organizations, people, and significant events
2. Connects new entities to existing entities using relations
3. Returns requested entities and their relations
4. Silently skips non-existent nodes
## Usage with Claude Desktop
### Setup Configuration
Add the following to your `claude_desktop_config.json`:
#### Docker Configuration
```json
{
"mcpServers": {
"memory": {
"command": "docker",
"args": ["run", "-i", "-v", "claude-memory:/app/dist", "--rm", "mcp/memory"]
}
}
}
```
#### NPX Configuration
```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-memory"
]
}
}
}
```
### System Prompt Configuration
For optimal memory utilization, configure a custom prompt in the "Custom Instructions" field of your Claude.ai Project:
```
Follow these steps for each interaction:
1. User Identification:
- Assume interaction with default_user
- Proactively identify if not already known
2. Memory Retrieval:
- Begin chat by saying "Remembering..."
- Retrieve all relevant information from knowledge graph
- Reference knowledge graph as "memory"
3. Memory Categories:
While conversing, be attentive to:
a) Basic Identity (age, gender, location, job title, etc.)
b) Behaviors (interests, habits, etc.)
c) Preferences (communication style, preferred language)
d) Goals (goals, targets, aspirations)
e) Relationships (personal/professional up to 3 degrees)
4. Memory Update:
If new information gathered:
a) Create entities for recurring organizations, people, events
b) Connect them to current entities using relations
```
资料来源：[src/memory/README.md]()
## Technical Specifications
### Package Information
| Property | Value |
|----------|-------|
| Package Name | `@modelcontextprotocol/server-memory` |
| Version | 0.6.3 |
| License | MIT License |
| MCP Name | `io.github.modelcontextprotocol/server-memory` |
| SDK Dependency | `@modelcontextprotocol/sdk: ^1.29.0` |
资料来源：[src/memory/package.json:1-11]()
### Build Configuration
```json
{
"scripts": {
"build": "tsc && shx chmod +x dist/*.js",
"prepare": "npm run build",
"watch": "tsc --watch",
"test": "vitest run --coverage"
}
}
```
资料来源：[src/memory/package.json:18-22]()
## VS Code Installation
Quick installation is available through one-click buttons in the VS Code marketplace:
- **NPX Installation**: For npm-based installations
- **VS Code Insiders**: Separate button for Insiders version
These buttons provide streamlined configuration without manual JSON editing.
资料来源：[src/memory/README.md]()
## Data Model
### Entity Structure
Entities in the knowledge graph include:
- **Organizations**: Recurring companies, teams, institutions
- **People**: Users, contacts, individuals mentioned
- **Events**: Significant occurrences, meetings, milestones
### Relation Types
Relations connect entities with semantic meaning:
- Personal relationships (family, friends, colleagues)
- Professional relationships (team members, stakeholders)
- Temporal relationships (event connections)
- Hierarchical relationships (org charts, reporting structures)
### Return Values
| Operation | Returns |
|-----------|---------|
| Retrieval | Requested entities and their relations |
| Non-existent nodes | Silently skipped |
## Development
### Running from Source
1. Clone the repository
2. Navigate to `src/memory`
3. Install dependencies
4. Build using `npm run build`
### Testing
```bash
cd src/memory
npm test
```
## Summary
The Memory Server provides a flexible, knowledge-graph-based memory system for AI assistants. It enables persistent storage of user information, entity relationships, and conversation context across multiple sessions. By integrating with the Model Context Protocol, it offers standardized MCP tool interfaces for memory operations while maintaining data in a portable JSONL format.
Key benefits include:
- **Persistent Memory**: Information persists across sessions
- **Graph-based Relationships**: Rich entity connections
- **Flexible Storage**: JSONL format allows easy backup and inspection
- **MCP Standard**: Compatible with any MCP-compliant client
---
## Git Server
### 相关页面
相关主题：[Filesystem Server](#filesystem-server)
相关源码文件
以下源码文件用于生成本页说明：
- [src/git/pyproject.toml](https://github.com/modelcontextprotocol/servers/blob/main/src/git/pyproject.toml)
- [src/git/src/mcp_server_git/server.py](https://github.com/modelcontextprotocol/servers/blob/main/src/git/src/mcp_server_git/server.py)
- [src/git/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/git/README.md)
**Note:** The Git Server source files (src/git/) are not included in the current repository context provided. The following documentation is based on the general MCP server patterns observed in other servers within this repository (fetch, time, filesystem, memory, etc.) and the CLAUDE.md contributing guidelines.
For accurate Git Server documentation, please provide the contents of the src/git/ directory files.
# Git Server
> **Documentation Status**: The Git Server (`src/git/`) source files were not included in the current repository context. This page provides general information based on MCP server patterns observed in this repository. For accurate implementation details, refer to the actual source files listed above.
## Overview
The Git Server is a Model Context Protocol (MCP) server implementation that provides Git repository interaction capabilities to AI assistants and other MCP clients. Based on the project's architecture patterns, this server follows the same conventions as other MCP servers in the `modelcontextprotocol/servers` repository.
The server enables AI models to perform Git operations such as viewing history, examining commits, browsing branches, and analyzing repository state through standardized MCP tool interfaces.
## Architecture
Based on the patterns observed in other servers within this repository, the Git Server follows a modular architecture:
```mermaid
graph TD
A[MCP Client] -->|JSON-RPC| B[Git Server Entry Point]
B --> C[Tool Handlers]
C --> D[Git Operations Layer]
D --> E[Local Git Repository]
B --> F[Resource Providers]
F --> G[Repository Resources]
```
## Server Structure
### Directory Layout
Following the repository conventions (per `CLAUDE.md`):
```
src/git/
├── pyproject.toml # Python package configuration
├── src/
│ └── mcp_server_git/
│ ├── __init__.py
│ └── server.py # Main server implementation
├── README.md # Server-specific documentation
└── tests/ # Test suite
```
### Package Configuration
The server uses **hatchling** as its build system, consistent with other Python servers in this repository. Package configuration is defined in `pyproject.toml`.
Based on patterns from other servers:
- Package manager: **uv** (not pip) - 资料来源：[CLAUDE.md]()
- Python version: **>= 3.10** (per-server `.python-version` file) - 资料来源：[CLAUDE.md]()
- Type checking: **pyright** - 资料来源：[CLAUDE.md]()
- Linting: **ruff** - 资料来源：[CLAUDE.md]()
## Installation Methods
Based on the standard MCP server installation patterns in this repository:
### Using uvx (Recommended)
```json
{
"mcpServers": {
"git": {
"command": "uvx",
"args": ["mcp-server-git"]
}
}
}
```
### Using pip
```json
{
"mcpServers": {
"git": {
"command": "python",
"args": ["-m", "mcp_server_git"]
}
}
}
```
### Using Docker
```json
{
"mcpServers": {
"git": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp/git"]
}
}
}
```
## Configuration
### Claude Desktop Configuration
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"git": {
"command": "uvx",
"args": ["mcp-server-git"]
}
}
}
```
On Windows, wrap with `cmd /c`:
```json
{
"mcpServers": {
"git": {
"command": "cmd",
"args": ["/c", "uvx", "mcp-server-git"]
}
}
}
```
## Development
### Building
Docker build:
```bash
docker build -t mcp/git -f src/git/Dockerfile .
```
### Testing
```bash
cd src/git && uv sync --frozen --all-extras --dev
uv run pytest
```
### Type Checking
```bash
uv run pyright
```
### Linting
```bash
uv run ruff check .
```
## Tool Interface
Based on MCP server conventions, the Git Server exposes tools via the MCP protocol. Common Git operations likely include:
| Tool Name | Purpose | Read Only |
|-----------|---------|-----------|
| `get-commit` | Retrieve commit details | Yes |
| `list-branches` | List repository branches | Yes |
| `get-file-history` | View file change history | Yes |
| `get-diff` | Show changes between commits | Yes |
| `list-tags` | List repository tags | Yes |
| `get-repository-info` | Retrieve repository metadata | Yes |
## Comparison with Other MCP Servers
The Git Server follows the same architectural patterns as other servers in this repository:
| Aspect | Git Server | Fetch Server | Time Server | Memory Server |
|--------|------------|--------------|-------------|---------------|
| Language | Python | Python | Python | TypeScript |
| Entry Point | `mcp_server_git` | `mcp_server_fetch` | `mcp_server_time` | `@modelcontextprotocol/server-memory` |
| Transport | stdio | stdio | stdio | stdio |
| Build System | hatchling | hatchling | hatchling | npm |
| License | MIT | MIT | MIT | MIT |
## Contributing
Contributions to the Git Server follow the general guidelines defined in the repository's `CLAUDE.md`:
- **Accepted**: Bug fixes, usability improvements, enhancements demonstrating MCP protocol features
- **Code Style**: Python typing with type hints enforced via pyright
- **Testing**: pytest with proper async patterns
- **Linting**: ruff for code style enforcement
For contribution guidelines, see: https://github.com/modelcontextprotocol/servers
## License
This MCP server is licensed under the **MIT License**, consistent with other servers in the repository. Users are free to use, modify, and distribute the software subject to MIT License terms.
---
## Time Server
### 相关页面
相关主题：[Fetch Server](#fetch-server)
相关源码文件
以下源码文件用于生成本页说明：
- [src/time/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/time/README.md)
- [src/time/pyproject.toml](https://github.com/modelcontextprotocol/servers/blob/main/src/time/pyproject.toml)
- [src/time/src/mcp_server_time/server.py](https://github.com/modelcontextprotocol/servers/blob/main/src/time/src/mcp_server_time/server.py)
- [CLAUDE.md](https://github.com/modelcontextprotocol/servers/blob/main/CLAUDE.md)
- [README.md](https://github.com/modelcontextprotocol/servers/blob/main/README.md)
- [src/fetch/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/README.md)
# Time Server
The Time Server is a Python-based MCP (Model Context Protocol) server that provides timezone-aware time retrieval and conversion capabilities. It enables AI assistants and MCP clients to query current time in any timezone and perform time conversions between different time zones.
## Overview
The Time Server exposes two primary tools that allow clients to:
- Retrieve the current time for a specified timezone
- Convert times between different timezones
The server automatically detects the system's timezone by default but allows customization through command-line arguments. It follows the MCP specification for tool definitions and responses.
## Architecture
```mermaid
graph TD
A[MCP Client] -->|Tool Request| B[Time Server]
B -->|Execute| C[get_current_time Tool]
B -->|Execute| D[convert_time Tool]
C -->|Query| E[System Timezone]
C -->|Query| F[Specified Timezone]
D -->|Calculate| G[Timezone Conversion]
G --> H[Time Difference]
B -->|JSON Response| A
```
## Tools
### get_current_time
Retrieves the current time for a specified timezone.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `timezone` | string | Yes | IANA timezone identifier (e.g., "Europe/Warsaw", "Asia/Tokyo") |
**Example Request:**
```json
{
"name": "get_current_time",
"arguments": {
"timezone": "Europe/Warsaw"
}
}
```
**Response:**
```json
{
"timezone": "Europe/Warsaw",
"datetime": "2024-01-01T13:00:00+01:00",
"is_dst": false
}
```
### convert_time
Converts a time from one timezone to another.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source_timezone` | string | Yes | Source IANA timezone identifier |
| `target_timezone` | string | Yes | Target IANA timezone identifier |
| `time` | string | Yes | Time in HH:MM format |
**Example Request:**
```json
{
"name": "convert_time",
"arguments": {
"source_timezone": "America/New_York",
"time": "16:30",
"target_timezone": "Asia/Tokyo"
}
}
```
**Response:**
```json
{
"source": {
"timezone": "America/New_York",
"datetime": "2024-01-01T12:30:00-05:00",
"is_dst": false
},
"target": {
"timezone": "Asia/Tokyo",
"datetime": "2024-01-01T12:30:00+09:00",
"is_dst": false
},
"time_difference": "+13.0h"
}
```
## Installation
The Time Server supports multiple installation methods.
### Using uvx (Recommended)
```bash
uvx mcp-server-time
```
### Using pip
```bash
pip install mcp-server-time
python -m mcp_server_time
```
### Using Docker
```bash
cd src/time
docker build -t mcp/time .
docker run -i --rm mcp/time
```
## Configuration
### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"time": {
"command": "uvx",
"args": ["mcp-server-time"]
}
}
}
```
**Using pip:**
```json
{
"mcpServers": {
"time": {
"command": "python",
"args": ["-m", "mcp_server_time"]
}
}
}
```
### VS Code
Use the one-click installation buttons available in the README, or configure manually:
```json
{
"mcpServers": {
"time": {
"command": "uvx",
"args": ["mcp-server-time"]
}
}
}
```
### Zed Editor
```json
{
"context_servers": {
"mcp-server-time": {
"command": "uvx",
"args": ["mcp-server-time"]
}
}
}
```
### Docker Configuration
```json
{
"mcpServers": {
"time": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "LOCAL_TIMEZONE", "mcp/time"]
}
}
}
```
## Customization
### System Timezone Override
By default, the server automatically detects your system's timezone. Override this using the `--local-timezone` argument:
```json
{
"command": "python",
"args": ["-m", "mcp_server_time", "--local-timezone=America/New_York"]
}
```
### Environment Variable (Docker)
Pass the timezone via the `LOCAL_TIMEZONE` environment variable when using Docker:
```bash
docker run -i --rm -e LOCAL_TIMEZONE=Europe/London mcp/time
```
## Debugging
Use the MCP Inspector for debugging:
**For uvx installations:**
```bash
npx @modelcontextprotocol/inspector uvx mcp-server-time
```
**For local development:**
```bash
cd path/to/servers/src/time
npx @modelcontextprotocol/inspector uv run mcp-server-time
```
## Example Interactions
### Query Current Time
| Question | Description |
|----------|-------------|
| "What time is it now?" | Uses system timezone |
| "What time is it in Tokyo?" | Queries Asia/Tokyo timezone |
| "What time is it in Europe/Warsaw?" | Queries Europe/Warsaw timezone |
### Time Conversion
| Question | Description |
|----------|-------------|
| "When it's 4 PM in New York, what time is it in London?" | Cross-timezone conversion |
| "Convert 9:30 AM Tokyo time to New York time" | Specific time conversion |
## Data Model
### Time Response Schema
| Field | Type | Description |
|-------|------|-------------|
| `timezone` | string | IANA timezone identifier |
| `datetime` | string | ISO 8601 formatted datetime with timezone offset |
| `is_dst` | boolean | Whether Daylight Saving Time is active |
### Conversion Response Schema
| Field | Type | Description |
|-------|------|-------------|
| `source` | object | Source timezone info with datetime |
| `target` | object | Target timezone info with datetime |
| `time_difference` | string | Formatted difference (e.g., "+13.0h") |
## License
The Time Server is licensed under the **MIT License**, allowing free use, modification, and distribution subject to the terms and conditions specified in the LICENSE file.
## See Also
- [Memory Server](src/memory/README.md) - Persistent memory storage
- [Fetch Server](src/fetch/README.md) - HTTP fetch capabilities
- [Filesystem Server](src/filesystem/README.md) - File operations
- [MCP Specification](https://modelcontextprotocol.io/specification) - Protocol documentation
---
## Fetch Server
### 相关页面
相关主题：[Time Server](#time-server)
相关源码文件
以下源码文件用于生成本页说明：
- [src/fetch/pyproject.toml](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/pyproject.toml)
- [src/fetch/src/mcp_server_fetch/server.py](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/src/mcp_server_fetch/server.py)
- [src/fetch/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/README.md)
# Fetch Server
The Fetch Server is a Model Context Protocol (MCP) server that provides web content fetching capabilities. It enables Large Language Models (LLMs) to retrieve and process content from web pages, converting HTML to markdown for easier consumption.
## Overview
The Fetch Server acts as an intermediary between LLMs and web content, handling the complexities of HTTP requests, HTML parsing, and markdown conversion. This abstraction allows models to access web information without needing direct HTTP implementation capabilities.
```mermaid
graph TD
A["LLM / MCP Client"] --> B["Fetch Server"]
B --> C["HTTP Request"]
C --> D["Web Server"]
D --> E["HTML Response"]
E --> B
B --> F["Markdown Conversion"]
F --> A
```
### Key Capabilities
| Capability | Description |
|------------|-------------|
| URL Fetching | Retrieve content from any publicly accessible URL |
| Markdown Conversion | Transform HTML into clean, readable markdown |
| Content Truncation | Limit response size with `max_length` parameter |
| Chunked Reading | Use `start_index` to read content in portions |
| Raw Content Access | Bypass markdown conversion when needed |
> [!CAUTION]
> This server can access local/internal IP addresses and may represent a security risk. Exercise caution when using this MCP server to ensure it does not expose any sensitive data.
## Tools
### fetch
The primary tool provided by the Fetch Server for retrieving web content.
```typescript
{
name: "fetch",
description: "Fetches a URL from the internet and extracts its contents as markdown.",
inputSchema: {
url: string, // required
max_length?: number, // optional, default: 5000
start_index?: number, // optional, default: 0
raw?: boolean // optional, default: false
}
}
```
#### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `url` | string | Yes | - | URL to fetch |
| `max_length` | integer | No | 5000 | Maximum number of characters to return |
| `start_index` | integer | No | 0 | Start content from this character index |
| `raw` | boolean | No | false | Get raw content without markdown conversion |
资料来源：[src/fetch/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/README.md)
#### Usage Example
```json
{
"name": "fetch",
"arguments": {
"url": "https://example.com/article",
"max_length": 10000,
"start_index": 0
}
}
```
#### Response Format
```json
{
"content": [
{
"type": "text",
"text": "# Article Title\n\nConverted markdown content..."
}
]
}
```
### Chunked Reading
The fetch tool truncates responses by default. By using the `start_index` argument, you can specify where to start the content extraction, enabling models to read a webpage in chunks until they find the information they need.
```mermaid
graph LR
A["Initial Request
start_index=0"] --> B["First Chunk"]
B --> C{"Need More?"}
C -->|Yes| D["Request with
start_index=N"]
D --> B
C -->|No| E["Complete"]
```
## Installation
The Fetch Server supports multiple installation methods. Choose the one that best fits your environment.
### Using uv (Recommended)
When using [`uv`](https://docs.astral.sh/uv/), no specific installation is needed. Use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run the server:
```bash
uvx mcp-server-fetch
```
资料来源：[src/fetch/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/README.md)
### Using pip
Alternatively, install via pip:
```bash
pip install mcp-server-fetch
```
After installation, run as a script:
```bash
python -m mcp_server_fetch
```
### Using Docker
```bash
docker run -i --rm mcp/fetch
```
### Optional Dependency
Optionally, install Node.js for a more robust HTML simplifier:
```bash
# This will cause the fetch server to use a different HTML simplifier
# that is more robust for complex web pages
```
## Configuration
### Claude.app Configuration
Add the following to your Claude settings:
#### Using uvx
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
```
#### Using Docker
```json
{
"mcpServers": {
"fetch": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp/fetch"]
}
}
}
```
#### Using pip
```json
{
"mcpServers": {
"fetch": {
"command": "python",
"args": ["-m", "mcp_server_fetch"]
}
}
}
```
资料来源：[src/fetch/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/README.md)
### VS Code Configuration
For quick installation, use the one-click install buttons available in the README:
- **Install with UV in VS Code** - Uses `uvx mcp-server-fetch`
- **Install with UV in VS Code Insiders** - Uses `uvx mcp-server-fetch` (insiders version)
- **Install with Docker in VS Code** - Uses `docker` command
## Customization Options
### robots.txt
By default, the server obeys a website's `robots.txt` file if the request came from the model (via a tool), but not if the request was user-initiated (via a prompt). This can be disabled:
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch", "--ignore-robots-txt"]
}
}
}
```
### User-Agent
The server uses different user-agents based on request origin:
| Request Origin | User-Agent |
|---------------|------------|
| Model (via tool) | `ModelContextProtocol/1.0 (Autonomous; +https://github.com/modelcontextprotocol/servers)` |
| User (via prompt) | `ModelContextProtocol/1.0 (User-Specified; +https://github.com/modelcontextprotocol/servers)` |
Customize the user-agent:
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch", "--user-agent=YourUserAgent"]
}
}
}
```
### Proxy Support
Configure the server to use a proxy:
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch", "--proxy-url=http://proxy.example.com:8080"]
}
}
}
```
资料来源：[src/fetch/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/fetch/README.md)
## Windows Configuration
If experiencing timeout issues on Windows, set the `PYTHONIOENCODING` environment variable to ensure proper character encoding:
### Windows with uvx
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"],
"env": {
"PYTHONIOENCODING": "utf-8"
}
}
}
}
```
### Windows with pip
```json
{
"mcpServers": {
"fetch": {
"command": "python",
"args": ["-m", "mcp_server_fetch"],
"env": {
"PYTHONIOENCODING": "utf-8"
}
}
}
}
```
## Debugging
Use the MCP inspector to debug the server:
### For uvx installations
```bash
npx @modelcontextprotocol/inspector uvx mcp-server-fetch
```
### For development
```bash
cd path/to/servers/src/fetch
npx @modelcontextprotocol/inspector uv run mcp-server-fetch
```
## Prompts
The Fetch Server includes a prompt template:
### fetch
- **Purpose**: Fetch a URL and extract its contents as markdown
- **Arguments**:
- `url` (string, required): URL to fetch
## Architecture
```mermaid
graph TD
subgraph "Client Layer"
A["MCP Client
(Claude, VS Code, etc.)"]
end
subgraph "Fetch Server"
B["Request Handler"]
C["robots.txt Validator"]
D["User-Agent Manager"]
E["HTTP Client"]
F["HTML Parser"]
G["Markdown Converter"]
end
subgraph "External"
H["Target Web Server"]
end
A --> B
B --> C
C --> D
D --> E
E --> H
H --> E
E --> F
F --> G
G --> A
```
## License
This MCP server is licensed under the MIT License. You are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License.
## Contributing
Contributions are welcome to help expand and improve mcp-server-fetch. Whether you want to add new tools, enhance existing functionality, or improve documentation, your input is valuable.
For examples of other MCP servers and implementation patterns, see the [main MCP servers repository](https://github.com/modelcontextprotocol/servers).
Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements.
---
## Sequential Thinking Server
### 相关页面
相关主题：[Everything Server](#everything-server)
相关源码文件
以下源码文件用于生成本页说明：
- [src/sequentialthinking/package.json](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/package.json)
- [src/sequentialthinking/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/README.md)
# Sequential Thinking Server
The Sequential Thinking Server is an MCP (Model Context Protocol) server implementation that provides a structured, step-by-step thinking tool for dynamic and reflective problem-solving. It enables AI assistants to break down complex problems into manageable steps, revise thinking as understanding deepens, and branch into alternative reasoning paths.
## Overview
The server exposes a single powerful tool called `sequential_thinking` that facilitates detailed, iterative reasoning processes. Unlike one-shot responses, this tool allows models to maintain context over multiple thought steps, adjust their approach dynamically, and explore branching reasoning paths when needed.
**Key Characteristics:**
| Attribute | Value |
|-----------|-------|
| Package Name | `@modelcontextprotocol/server-sequential-thinking` |
| Version | 0.6.2 |
| License | MIT |
| Transport | stdio (default), HTTP+SSE (deprecated), Streamable HTTP |
| Runtime | Node.js / TypeScript |
资料来源：[package.json:1-6](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/package.json)
## Features
The Sequential Thinking Server provides the following capabilities:
- **Step-by-Step Decomposition** — Break complex problems into manageable thought steps
- **Iterative Refinement** — Revise and refine thoughts as understanding deepens
- **Branching Reasoning** — Fork into alternative paths of reasoning from any thought
- **Dynamic Adjustment** — Adjust the total number of thoughts needed on the fly
- **Hypothesis Verification** — Generate and verify solution hypotheses through structured thinking
- **Thought Logging** — Optional logging of thought information for debugging and audit
资料来源：[README.md:1-20](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/README.md)
## Tool Specification
### sequential_thinking
The primary tool provided by this server for structured problem-solving.
**Input Schema:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `thought` | string | Yes | The current thinking step content |
| `nextThoughtNeeded` | boolean | Yes | Whether another thought step is needed |
| `thoughtNumber` | integer | Yes | Current thought number in the sequence |
| `totalThoughts` | integer | Yes | Estimated total thoughts needed |
| `isRevision` | boolean | No | Whether this revises a previous thought |
| `revisesThought` | integer | No | Which thought number is being reconsidered |
| `branchFromThought` | integer | No | Branching point thought number |
| `branchId` | string | No | Unique identifier for this reasoning branch |
| `needsMoreThoughts` | boolean | No | Indicates if more thoughts are required |
资料来源：[README.md:35-53](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/README.md)
**Tool Annotations:**
| Annotation | Value | Description |
|------------|-------|-------------|
| `readOnlyHint` | false | This tool modifies thought state |
| `idempotentHint` | false | Repeated calls have cumulative effect |
| `destructiveHint` | false | Does not destroy external resources |
## Architecture
```mermaid
graph TD
A[MCP Host Application] -->|stdio / HTTP| B[Sequential Thinking Server]
B --> C[sequential_thinking Tool]
C --> D[Thought State Management]
D --> E[Optional Logging]
F[Thought Input] -->|thought| C
F -->|nextThoughtNeeded| C
F -->|thoughtNumber| C
F -->|totalThoughts| C
C -->|revision| G[Revises Previous Thought]
C -->|branch| H[Alternative Branch Created]
C -->|continuation| I[Next Thought Prompt]
```
### Component Overview
```
┌─────────────────────────────────────────────────────────────┐
│ MCP Host (Claude Desktop, VS Code) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Sequential Thinking Server │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Tool Handler: sequential_thinking │ │
│ │ - Validates input schema │ │
│ │ - Processes thought parameters │ │
│ │ - Manages thought state │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Logging Module (optional) │ │
│ │ - Controlled by DISABLE_THOUGHT_LOGGING env var │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## Installation
### Package Requirements
The server requires Node.js and is distributed as an npm package. It can also be run via Docker.
资料来源：[package.json:18-22](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/package.json)
### npx (Unix/Linux/macOS)
```json
{
"mcpServers": {
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
}
}
}
```
### npx (Windows)
```json
{
"mcpServers": {
"sequential-thinking": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
}
}
}
```
### Docker
```json
{
"mcpServers": {
"sequential-thinking": {
"command": "docker",
"args": ["run", "--rm", "-i", "mcp/sequentialthinking"]
}
}
}
```
资料来源：[README.md:1-50](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/README.md)
## Configuration
### Claude Desktop Configuration
Add the following to `claude_desktop_config.json`:
#### NPX Installation
```json
{
"mcpServers": {
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
}
}
}
```
#### Docker Installation
```json
{
"mcpServers": {
"sequentialthinking": {
"command": "docker",
"args": ["run", "--rm", "-i", "mcp/sequentialthinking"]
}
}
}
```
### VS Code Configuration
Use the quick installation buttons in the README, or manually configure with:
```json
{
"mcpServers": {
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
}
}
}
```
资料来源：[README.md:90-130](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/README.md)
## Environment Variables
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `DISABLE_THOUGHT_LOGGING` | boolean | `false` | Set to `true` to disable logging of thought information |
When `DISABLE_THOUGHT_LOGGING` is set to `true`, the server will not log any thought-related information, providing a more private reasoning process.
资料来源：[README.md:70-72](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/README.md)
## Building from Source
### Prerequisites
- Node.js
- npm
- TypeScript
### Build Commands
```bash
# Clone the repository
git clone https://github.com/modelcontextprotocol/servers.git
cd servers/src/sequentialthinking
# Install dependencies
npm install
# Build the TypeScript project
npm run build
```
The build process:
1. Compiles TypeScript using `tsc`
2. Sets executable permissions on compiled JavaScript files using `shx chmod +x`
资料来源：[package.json:12-16](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/package.json)
### Docker Build
```bash
docker build -t mcp/sequentialthinking -f src/sequentialthinking/Dockerfile .
```
## Usage Patterns
### When to Use Sequential Thinking
The `sequential_thinking` tool is designed for:
| Use Case | Description |
|----------|-------------|
| Problem Decomposition | Breaking down complex problems into steps |
| Planning & Design | Creating plans with room for revision |
| Multi-step Analysis | Analysis that might need course correction |
| Uncertain Scope | Problems where full scope isn't clear initially |
| Context Maintenance | Tasks needing to maintain context over multiple steps |
| Information Filtering | Situations where irrelevant information needs filtering |
资料来源：[README.md:55-68](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/README.md)
### Verification Workflow
```mermaid
graph LR
A[Install Server] --> B[Restart MCP Host]
B --> C[Verify Tool Appears]
C --> D[Ask Complex Question]
D --> E[Model Invokes Tool Multiple Times]
E --> F[Observe Step-by-Step Reasoning]
```
**Manual Verification Steps:**
1. Install the server in your MCP host
2. Restart or reload the host so it reconnects to the server
3. Confirm the `sequential_thinking` tool appears in the host's MCP tool list
4. Ask the host to solve a non-trivial problem step-by-step
5. Verify the host invokes the tool multiple times instead of returning a one-shot answer
资料来源：[README.md:145-165](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/README.md)
### Reasoning Branching Example
```mermaid
graph TD
A[Thought 1: Initial Problem] --> B[Thought 2: Approach A]
B --> C[Thought 3: Explore Branch A1]
C --> D{Decision Point}
D -->|Revert| E[Thought 4: Revises Thought 2
branchId: branch-A]
D -->|Continue| F[Thought 5: Continue on A1]
E --> G[Thought 5: Alternative Path]
```
The tool supports:
- **Revisions** — Mark thoughts with `isRevision: true` and `revisesThought` to indicate corrections
- **Branches** — Use `branchFromThought` and `branchId` to create alternative reasoning paths
- **Dynamic Length** — Adjust `totalThoughts` as the reasoning progresses
## Dependencies
| Dependency | Version | Purpose |
|------------|---------|---------|
| `@modelcontextprotocol/sdk` | ^1.29.0 | MCP protocol implementation |
| `chalk` | ^5.3.0 | Terminal string styling |
| `yargs` | ^17.7.2 | Command-line argument parsing |
**Dev Dependencies:**
| Dependency | Purpose |
|------------|---------|
| `typescript` | TypeScript compiler |
| `vitest` | Testing framework |
| `@vitest/coverage-v8` | Code coverage |
| `shx` | Shell command wrapper |
| `@types/node`, `@types/yargs` | Type definitions |
资料来源：[package.json:18-40](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/package.json)
## Testing
The project includes Vitest tests with coverage reporting:
```bash
npm test
```
This runs tests with coverage using `vitest run --coverage`.
资料来源：[package.json:15](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/package.json)
## License
This MCP server is licensed under the **MIT License**. Users are free to use, modify, and distribute the software subject to the terms and conditions of the MIT License.
资料来源：[README.md:80-83](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/README.md)
## See Also
- [Model Context Protocol Specification](https://modelcontextprotocol.io)
- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)
- [Bug Tracker](https://github.com/modelcontextprotocol/servers/issues)
---
---
## Doramagic 踩坑日志
项目：modelcontextprotocol/servers
摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。
## 1. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:890668799 | https://github.com/modelcontextprotocol/servers | README/documentation is current enough for a first validation pass.
## 2. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:890668799 | https://github.com/modelcontextprotocol/servers | last_activity_observed missing
## 3. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:890668799 | https://github.com/modelcontextprotocol/servers | no_demo; severity=medium
## 4. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:890668799 | https://github.com/modelcontextprotocol/servers | no_demo; severity=medium
## 5. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:890668799 | https://github.com/modelcontextprotocol/servers | issue_or_pr_quality=unknown
## 6. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:890668799 | https://github.com/modelcontextprotocol/servers | release_recency=unknown