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

安装

# 克隆仓库
git clone https://github.com/yourusername/claude-mcp.git
cd claude-mcp

# 安装依赖
bun install

运行服务器

# 开发模式（带热重载）
bun dev

# 生产模式
bun start

默认情况下，服务器运行在 http://localhost:3000。

部署选项

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

对于个人使用，只需在本地运行服务器，默认不应用身份验证或速率限制：

# 在开发模式下启动服务器
bun dev

2. 团队共享服务器

对于团队内的共享服务器，可能需要基本的身份验证：

# 创建包含基本设置的.env文件
echo "NODE_ENV=production\nAPI_KEY=your-secret-key" > .env

# 启动服务器
bun start

3. 公共部署

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

# 使用所有安全功能进行配置
echo "NODE_ENV=production\nAPI_KEY=strong-random-key\nRATE_LIMIT_ENABLED=true" > .env

# 启动服务器
b
bun start

4. Docker 部署

您还可以使用Docker运行MCP服务器：

# 使用Docker构建并运行
docker build -t claude-mcp .
docker run -p 3000:3000 -v ./docs:/app/docs claude-mcp

# 或使用Docker Compose
docker compose up

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

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

# 在端口3000上运行您的个人实例
bun dev

# 在您的.zshrc/.bashrc中设置两个来源：
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工具的访问：

# 为Claude Code安装MCP插件
curl -X POST http://localhost:3000/claude-code/install

# 源激活脚本（或添加到您的.bashrc/.zshrc）
source ~/.claude-code/plugins/claude-mcp/activate.sh

# 使用文档工具
claude fetch-docs langchain               # 获取并使用LangChain文档
claude list-versions fastapi              # 列出可用的FastAPI版本

# 列出所有可用工具
claude tools list                         # 查看所有可用工具
claude tools info docs-fetcher            # 获取特定工具的信息

# 直接使用任何工具
claude tool:docs-fetcher frameworks       # 列出支持的框架

当您使用claude fetch-docs获取框架的文档时，Claude Code将自动拥有这些文档的访问权限。随着您向MCP服务器添加更多工具，它们将自动通过Claude Code CLI可用。

HTTP API 集成

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

1. 检查最新版本

// Claude可以生成此代码以检查框架的最新版本
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(`最新版本: ${data.latestVersion}`);

2. 获取文档

// 将新框架添加到注册表
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'
  })
});

// 获取框架的文档
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     // 限制页面数量（测试更快）
  })
});
const data = await response.json();
console.log(`文档保存到: ${data.processedDocsLocation}`);

3. 文档状态检查

// Claude可以检查文档是否已经可用
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(`使用缓存的文档，版本 ${data.latestVersion}`);
} else {
  console.log(`需要获取最新文档（版本 ${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快速找到相关信息：

# 搜索文档中的特定术语
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": "如何在React组件中处理状态",
  "framework": "react",
  "version": "18.0.0",
  "mode": "hybrid",
  "hybridAlpha": 0.7,
  "limit": 20
}

系统包括重建和优化搜索索引的工具：

# 重建搜索索引
curl -X POST http://localhost:3000/api/tools/docs-fetcher/search/rebuild

# 检查搜索统计信息
curl http://localhost:3000/api/tools/docs-fetcher/search/stats

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

✨ 使用示例

获取React文档（小样本）

# 获取一个小样本用于测试（5页）
curl -X POST http://localhost:3000/api/tools/docs-fetcher/fetch \
  -H "Content-Type: application/json" \
  -d '{"framework": "react", "processContent": true, "maxPages": 5}'

获取完整文档

# 获取综合文档（可能需要几分钟）
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插件之后：

# 获取最新文档（小样本用于测试）
claude fetch-docs langchain --maxpages 5

# 通过CLI交互式地添加新框架
bun docadd add

# 或直接获取新框架的文档
bun docadd fetch fastapi --max-pages 20

# 列出可用框架
claude tool:docs-fetcher frameworks

# 搜索文档
claude tool:docs-fetcher search --query "agents" --framework langchain

🧩 架构

系统遵循模块化架构：

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

目录结构

/
├── src/
│   ├── index.ts          # 主服务器入口点
│   ├── lib/
│   │   └── tool-registry.ts # 工具管理
│   ├── types/
│   │   └── tool.ts       # 类型定义
│   └── tools/
│       └── docs-fetcher/ # 文档获取器工具
│           ├── index.ts     # 路由和端点 
│           ├── service.ts   # 核心功能
│           ├── registry.ts  # 框架注册表
│           ├── scrapers.ts  # 网站抓取器
│           └── processors.ts # 内容处理器
├── docs/                 # 存储的文档
├── package.json
└── tsconfig.json

🔧 扩展系统

向文档获取器添加新框架

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

# 运行文档管理工具
bun docadd add

# 按照交互式提示添加框架详情

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

1. 框架名称（例如，react, vue, fastapi）
2. 框架类型（NPM包，Python包，GitHub存储库，或自定义）
3. 类型特定信息（包名，Python包，或GitHub存储库）
4. 主文档网址
5. 框架是否有单独的API文档（如有，提供网址）
6. 是否立即获取该框架的文档

您还可以使用这些附加命令：

# 获取现有框架的文档
bun docadd fetch fastapi --max-pages 20

# 列出所有已注册的框架
bun docadd list

# 列出特定类型的框架
bun docadd list --type npm

# 从注册表中移除框架
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';

// 定义验证模式
const exampleSchema = z.object({
  parameter: z.string().min(1)
});

// 使用模板创建您的工具
const yourTool = createToolTemplate({
  name: 'your-tool-name',
  description: '您的工具做什么',
  version: '0.1.0',
  setupRoutes: (router) => {
    // 添加您的端点
    router.post(
      '/example',
      zValidator('json', exampleSchema),
      async (c) => {
        const { parameter } = c.req.valid('json');
        
        // 您的实现在这里
        
        return c.json({ success: true, result: '完成！' });
      }
    );
    
    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
   

🔜 未来计划

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

🔧 高级配置

速率限制和抓取选项

文档获取器包含高级配置选项以控制抓取行为：

# 设置抓取请求之间的延迟（毫秒）
SCRAPER_REQUEST_DELAY=2000

# 设置最大并发抓取操作数
SCRAPER_MAX_CONCURRENT=1

# 控制puppeteer浏览器超时
PUPPETEER_TIMEOUT=60000

# 启用/禁用调试用的无头模式
PUPPETEER_HEADLESS=true

# GitHub API令牌以提高速率限制
GITHUB_TOKEN=your_github_token

# 内容语言偏好（默认仅限英语）
CONTENT_LANGUAGE=en

# 最低内容质量阈值（0-1）
CONTENT_QUALITY_THRESHOLD=0.7

这些设置有助于确保高质量文档的同时尊重网站速率限制，并防止在获取文档时被阻止。

语言过滤

默认情况下，系统专注于英语文档以获得更好的质量结果：

• 自动跳过爬取过程中的非英语网址
• 过滤带有明确非英语语言标签（<html lang="es">）的内容
• 检测并过滤高比例非拉丁字符的页面

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

语义搜索配置

基于向量的语义搜索系统可以使用以下选项进行定制：

# 搜索模式（语义，关键词，混合）
SEARCH_DEFAULT_MODE=混合

# 默认权重在向量和关键词搜索之间（0-1，越高越语义）
SEARCH_HYBRID_ALPHA=0.7

# 嵌入的向量维度（默认：384，适用于all-MiniLM-L6）
VECTOR_DIMENSIONS=384

# 最大存储向量数
VECTOR_MAX_ELEMENTS=100000

您还可以在查询时通过指定搜索请求中的mode参数选择不同的搜索模式。

错误处理和健壮性

系统实现了几种策略以确保健壮性：

• 当需要时从语义搜索优雅地回退到关键词搜索
• 抓取过程中遇到网络错误时自动恢复和重试
• 速率限制检测和指数退避
• 所