使用说明

Claude MCP（主控制程序）

一个强大的基于服务器的工具系统，旨在通过访问最新文档和资源来扩展Claude的代码生成功能。

🌟 概述

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

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

个人模式：在您的计算机上本地运行，以增强您自己的Claude Code体验
共享模式：部署为可由多个用户或团队访问的服务

您可以添加自己的自定义工具或使用社区提供的工具。

🛠️ 工具

MCP系统旨在托管多种专用工具。目前实施：

1.文件提取器

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

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

支持的框架包括：

LangChain （Python和JavaScript）
快速 API
React、Vue、Angular、Svelte
Express、Next.js、Hono、Remix
而且可以很容易地添加更多。..

🚀 入门指南

先决条件

包子用于快速执行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代码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

🔧 扩展系统

在Docs Fetcher中添加新框架

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

# Run the documentation management tool
bun docadd add

# Follow the interactive prompts to add details about the framework

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

框架名称（例如，react、vue、fastapi）
框架类型（NPM包、Python包、GitHub存储库或自定义）
键入特定信息（包名、Python包或GitHub仓库）
主文档URL
框架是否有单独的API文档（以及URL（如果适用））
立即获取框架文档的选项

您还可以使用以下附加命令：

# 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

所有注册表更改都会自动保存到磁盘，并在服务器重新启动之间持续存在。

创建新工具

复制工具模板目录：

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

使用模板实现您的工具：

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;

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

import yourTool from '../tools/your-tool-name';

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

您的工具将通过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">)已过滤
检测并过滤非拉丁字符比例高的页面

可以通过修改scraper配置中的语言模式来定制此行为。

语义搜索配置

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

# 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也可以使用整体功能进行代码生成任务。

📄 许可证

麻省理工学院

🤝 贡献

欢迎投稿！请随时提交拉取请求。