Claude MCP (Master Control Program)

Claude MCP（主控程序）

一个强大的基于服务端的工具系统，旨在通过提供最新文档和资源，扩展 Claude 的代码生成能力。

🌟 概述

Claude MCP 是一个模块化服务，可托管工具，以增强 Claude 使用现代框架和库的能力。通过让 Claude 访问最新的文档和 API，确保生成的代码始终遵循最新的最佳实践，并使用最新的功能。

系统可以通过两种主要模式部署：

1. 个人模式：在本地计算机上运行，增强你使用 Claude Code 的体验
2. 共享模式：部署为服务，供多个用户或团队访问

你可以添加自己的自定义工具，也可以使用社区贡献的工具。

🛠️ 工具

MCP 系统旨在托管多个专用工具。目前已实现：

1. 文档获取器

发现、获取并处理框架和库的最新文档：

• 版本检测：自动从 npm、PyPI 或 GitHub 检测最新版本
• 文档抓取：使用无头浏览器抓取官方文档网站
• 内容处理：提取相关内容，并转换为结构化格式（JSON/Markdown）
• API 参考处理：单独处理 API 文档，以实现全面覆盖
• 速率限制感知：智能限速，遵守网站策略
• 智能爬取：优先抓取重要文档页面，并适应网站结构

支持的框架包括：

• LangChain（Python 和 JavaScript）
• FastAPI
• React、Vue、Angular、Svelte
• Express、Next.js、Hono、Remix
• 还可以轻松添加更多……

🚀 入门

前提条件

• Bun，用于快速执行 JavaScript/TypeScript

安装

# Clone the repository
git clone https://github.com/yourusername/claude-mcp.git
cd claude-mcp

# Install dependencies
bun install

运行服务

# Development mode (with hot reloading)
bun dev

# Production mode
bun start

服务默认运行在 http://localhost:3000。

部署选项

1. 个人/本地使用（推荐）

个人使用时，只需在本地运行服务。默认不启用身份验证或速率限制：

# Start the server in development mode
bun dev

2. 团队共享服务

如果要在团队内共享服务，可以启用基本身份验证：

# Create .env file with basic settings
echo "NODE_ENV=production\nAPI_KEY=your-secret-key" > .env

# Start the server
bun start

3. 公开部署

对于面向公众的服务，请启用所有安全功能：

# Configure with all security features
echo "NODE_ENV=production\nAPI_KEY=strong-random-key\nRATE_LIMIT_ENABLED=true" > .env

# Start the server
bun start

4. Docker 部署

你也可以使用 Docker 运行 MCP 服务：

# Build and run with Docker
docker build -t claude-mcp .
docker run -p 3000:3000 -v ./docs:/app/docs claude-mcp

# Or use Docker Compose
docker compose up

5. 双重部署（本地 + 共享）

你可以同时运行本地实例以使用个人工具，并连接到共享实例：

# Run your personal instance on port 3000
bun dev

# In your .zshrc/.bashrc, set up both sources:
export CLAUDE_CODE_PERSONAL_MCP="http://localhost:3000"
export CLAUDE_CODE_TEAM_MCP="https://team-mcp.example.com"

这样，你既可以开发和使用自己的工具，也可以访问团队共享的文档和工具。

🔌 与 Claude 集成

Claude Code CLI 集成

MCP 可以作为插件安装到 Claude Code CLI 工具中，从而访问所有 MCP 工具：

# Install the MCP plugin for Claude Code
curl -X POST http://localhost:3000/claude-code/install

# Source the activation script (or add to your .bashrc/.zshrc)
source ~/.claude-code/plugins/claude-mcp/activate.sh

# Use documentation tools
claude fetch-docs langchain               # Fetch and use LangChain documentation
claude list-versions fastapi              # List available FastAPI versions

# List all available tools
claude tools list                         # See all available tools
claude tools info docs-fetcher            # Get information about a specific tool

# Use any tool directly
claude tool:docs-fetcher frameworks       # List supported frameworks

使用 claude fetch-docs 获取某个框架的文档时，Claude Code 在编写代码时会自动访问这些文档。随着你向 MCP 服务添加更多工具，这些工具也会自动通过 Claude Code CLI 提供。

HTTP API 集成

Claude 也可以通过 HTTP 请求与 MCP 服务交互。以下是常见的集成模式：

1. 检查最新版本

// Claude can generate this code to check the latest version of a framework
const response = await fetch('http://localhost:3000/api/tools/docs-fetcher/latest-version', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ framework: 'langchain' })
});
const data = await response.json();
console.log(`Latest version: ${data.latestVersion}`);

2. 获取文档

// Add a new framework to the registry
const addResponse = await fetch('http://localhost:3000/api/tools/docs-fetcher/framework', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    name: 'new-framework',
    type: 'npm',
    packageName: 'new-framework',
    docsUrl: 'https://new-framework.dev/docs'
  })
});

// Fetch documentation for a framework
const response = await fetch('http://localhost:3000/api/tools/docs-fetcher/fetch', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    framework: 'fastapi',
    storageFormat: 'markdown',
    processContent: true,
    maxPages: 20     // Limit the number of pages (faster for testing)
  })
});
const data = await response.json();
console.log(`Documentation saved to: ${data.processedDocsLocation}`);

3. 检查文档状态

// Claude can check if documentation is already available
const response = await fetch('http://localhost:3000/api/tools/docs-fetcher/status/langchain');
const data = await response.json();

if (data.available && data.upToDate) {
  console.log(`Using cached documentation at version ${data.latestVersion}`);
} else {
  console.log(`Need to fetch latest documentation (version ${data.latestVersion})`);
}

📚 API 参考

基础端点

• GET / - 服务状态和可用工具列表

文档抓取工具

• GET /api/tools/docs-fetcher/frameworks - 列出所有受支持的框架

  • 查询参数：
    • type：按类型筛选（all、npm、python、github、custom）

• POST /api/tools/docs-fetcher/framework - 向注册表添加新框架

  • 请求体：

    {
      "name": "new-framework",
      "type": "npm",
      "packageName": "new-framework",
      "docsUrl": "https://new-framework.dev/docs",
      "apiDocsUrl": "https://api.new-framework.dev"
    }
    

• DELETE /api/tools/docs-fetcher/framework/:name - 从注册表中移除框架

• POST /api/tools/docs-fetcher/latest-version - 获取框架的最新版本

  • 请求体：

    { "framework": "langchain" }
    

• POST /api/tools/docs-fetcher/fetch - 抓取并处理文档

  • 请求体：

    {
      "framework": "fastapi",
      "storageFormat": "json|markdown",
      "processContent": true|false,
      "maxPages": 20
    }
    

• GET /api/tools/docs-fetcher/status/:framework - 检查文档状态

• POST /api/tools/docs-fetcher/search - 搜索文档

  • 请求体：

    {
      "query": "state management",
      "framework": "react",
      "limit": 10
    }
    

🔍 搜索功能

文档工具包含强大的搜索系统，可帮助 Claude 快速查找相关信息：

# Search the documentation for a specific term
curl -X POST http://localhost:3000/api/tools/docs-fetcher/search \
  -H "Content-Type: application/json" \
  -d '{"query": "state management", "framework": "react", "mode": "hybrid"}'

搜索系统支持三种模式，并可自动回退：

• semantic：使用神经嵌入，根据含义查找内容（最适合概念性查询）
• keyword：传统文本搜索，查找完全匹配的词语（最适合 API 名称）
• hybrid：结合两种方式，提供全面的结果（默认）

如果语义搜索不可用，系统会自动回退到关键词搜索。

其他搜索选项：

{
  "query": "How to handle state in React components",
  "framework": "react",
  "version": "18.0.0",
  "mode": "hybrid",
  "hybridAlpha": 0.7,
  "limit": 20
}

系统还包含用于重建和优化搜索索引的工具：

# Rebuild search indexes
curl -X POST http://localhost:3000/api/tools/docs-fetcher/search/rebuild

# Check search stats
curl http://localhost:3000/api/tools/docs-fetcher/search/stats

搜索结果包含相关摘录和上下文，Claude 可在生成代码时使用这些信息，让文档更易于访问和使用。

✨ 使用示例

抓取 React 文档（小型示例）

# Get a small sample for testing (5 pages)
curl -X POST http://localhost:3000/api/tools/docs-fetcher/fetch \
  -H "Content-Type: application/json" \
  -d '{"framework": "react", "processContent": true, "maxPages": 5}'

抓取完整文档

# Get comprehensive documentation (may take several minutes)
curl -X POST http://localhost:3000/api/tools/docs-fetcher/fetch \
  -H "Content-Type: application/json" \
  -d '{"framework": "fastapi", "processContent": true, "maxPages": 100}'

检查 FastAPI 的最新版本

curl -X POST http://localhost:3000/api/tools/docs-fetcher/latest-version \
  -H "Content-Type: application/json" \
  -d '{"framework": "fastapi"}'

与 Claude Code CLI 配合使用

安装 Claude Code 插件后：

# Fetch latest documentation (small sample for testing)
claude fetch-docs langchain --maxpages 5

# Add a new framework interactively (via CLI)
bun docadd add

# Or fetch documentation for a new framework directly
bun docadd fetch fastapi --max-pages 20

# List available frameworks
claude tool:docs-fetcher frameworks

# Search documentation
claude tool:docs-fetcher search --query "agents" --framework langchain

🧩 架构

系统采用模块化架构：

• 核心服务：使用 Hono 和 Bun 构建，性能出色
• 工具注册表：用于管理和加载工具的中央注册表
• 独立工具：每个工具都有自己的路由器、服务和功能

目录结构

/
├── src/
│   ├── index.ts          # Main server entry point
│   ├── lib/
│   │   └── tool-registry.ts # Tool management
│   ├── types/
│   │   └── tool.ts       # Type definitions
│   └── tools/
│       └── docs-fetcher/ # Documentation fetcher tool
│           ├── index.ts     # Routes and endpoints 
│           ├── service.ts   # Core functionality
│           ├── registry.ts  # Framework registry
│           ├── scrapers.ts  # Website scrapers
│           └── processors.ts # Content processors
├── docs/                 # Stored documentation
├── package.json
└── tsconfig.json

🔧 扩展系统

向文档抓取工具添加新框架

使用交互式 CLI 工具添加新框架：

# Run the documentation management tool
bun docadd add

# Follow the interactive prompts to add details about the framework

CLI 将引导你完成以下提示：

1. 框架名称（例如，react、vue、fastapi）
2. 框架类型（NPM 包、Python 包、GitHub 仓库或自定义）
3. 特定类型的信息（包名称、Python 包或 GitHub 仓库）
4. 主要文档 URL
5. 框架是否有单独的 API 文档（如果有，请提供 URL）
6. 立即抓取该框架文档的选项

你也可以使用以下其他命令：

# Fetch documentation for an existing framework
bun docadd fetch fastapi --max-pages 20

# List all registered frameworks
bun docadd list

# List frameworks of a specific type
bun docadd list --type npm

# Remove a framework from the registry
bun docadd remove vue

所有注册表更改都会自动保存到磁盘，并在服务器重启后保留。

创建新工具

1. 复制工具模板目录：

   cp -r src/tools/tool-template src/tools/your-tool-name
   

2. 使用模板实现你的工具：

import { z } from 'zod';
import { zValidator } from '@hono/zod-validator';
import { createToolTemplate } from '../../lib/tool-registry';

// Define validation schemas
const exampleSchema = z.object({
  parameter: z.string().min(1)
});

// Create your tool with the template
const yourTool = createToolTemplate({
  name: 'your-tool-name',
  description: 'What your tool does',
  version: '0.1.0',
  setupRoutes: (router) => {
    // Add your endpoints
    router.post(
      '/example',
      zValidator('json', exampleSchema),
      async (c) => {
        const { parameter } = c.req.valid('json');
        
        // Your implementation here
        
        return c.json({ success: true, result: 'Done!' });
      }
    );
    
    return router;
  }
});

export default yourTool;

3. 在 src/lib/tool-registry.ts 中注册该工具：

   import yourTool from '../tools/your-tool-name';
   
   const tools: Record<string, Tool> = {
     'docs-fetcher': docsFetcher,
     'your-tool-name': yourTool,
     // ...
   };
   

4. 你的工具将自动通过 Claude Code CLI 提供：

   claude tool:your-tool-name example
   

🔜 未来计划

• 向量数据库优化：改进向量搜索，提升语义理解能力
• 自动更新系统：定期检查是否有新的框架版本
• 代码示例提取：提取并索引代码示例
• 语义理解：增强对文档内容的语义解析
• 扩展语言支持：支持筛选和处理非英语文档
• 内存优化：减少大型文档集的内存占用
• 云端部署：支持云端部署和扩展

🔧 高级配置

速率限制和抓取选项

文档获取器包含高级配置选项，可用于控制抓取行为：

# Set delay between scraping requests (milliseconds)
SCRAPER_REQUEST_DELAY=2000

# Set maximum concurrent scraping operations
SCRAPER_MAX_CONCURRENT=1

# Control puppeteer browser timeout
PUPPETEER_TIMEOUT=60000

# Enable/disable headless mode for debugging
PUPPETEER_HEADLESS=true

# GitHub API token for higher rate limits
GITHUB_TOKEN=your_github_token

# Content language preferences (default is English-only)
CONTENT_LANGUAGE=en

# Minimum content quality threshold (0-1)
CONTENT_QUALITY_THRESHOLD=0.7

这些设置有助于确保文档质量，同时遵守网站的速率限制，并防止抓取文档时被屏蔽。

语言筛选

默认情况下，系统会优先处理英语文档，以获得更好的结果：

• 抓取过程中会自动跳过非英语 URL
• 会筛选带有明确非英语语言标签（<html lang="es">）的内容
• 会检测并筛选非拉丁字符占比较高的页面

可以通过修改抓取器配置中的语言模式自定义此行为。

语义搜索配置

基于向量的语义搜索系统可通过以下选项进行自定义：

# Search mode (semantic, keyword, hybrid)
SEARCH_DEFAULT_MODE=hybrid

# Default weight between vector and keyword search (0-1, higher = more semantic)
SEARCH_HYBRID_ALPHA=0.7

# Vector dimensions for embeddings (default: 384 for all-MiniLM-L6)
VECTOR_DIMENSIONS=384

# Maximum number of vectors to store
VECTOR_MAX_ELEMENTS=100000

也可以在查询时，在搜索请求中指定 mode 参数来选择不同的搜索模式。

错误处理和稳健性

系统采用多种策略来确保稳健性：

• 必要时可从语义搜索平稳回退到关键词搜索
• 抓取过程中发生网络错误时自动恢复并重试
• 检测速率限制并采用指数退避
• 详细记录所有操作，便于调试
• 管理大型文档集的内存

这样一来，即使系统部分组件遇到问题，Claude 仍可使用整体功能来完成代码生成任务。

📄 许可证

MIT

🤝 参与贡献

欢迎贡献！请随时提交 Pull Request。