MCP 服务器项目文档

安装指南

安装步骤

1. 克隆仓库到本地：

   git clone https://github.com/your-username/mcp-server.git
   cd mcp-server
   

2. 安装依赖项：

   npm install
   

3. 启动服务器：

   node server.js
   

项目结构

mcp-server/
├── server.js          # 主服务器文件
├── docs/             # 文档存储目录
│   └── doc.json      # 示例文档文件
├── crawl/            # 爬虫相关模块
│   ├── crawler.js    # 爬虫主逻辑
│   └── parsers/      # 数据解析模块
├── tools/            # MCP 工具实现
│   ├── search_docs.js  # 搜索文档工具
│   └── get_doc_detail.js  # 获取文档详情工具
└── test/             # 测试用例
    └── test_server.js     # 服务器测试用例

文档格式

文档结构

文档文件应为 JSON 格式，包含以下字段：

{
  "source": {
    "name": "taro",
    "url": "https://docs.taro.zone/docs"
  },
  "lastUpdated": "2024-03-27T12:00:00Z",
  "pages": {
    "https://docs.taro.zone/docs/components-desc": {
      "title": "组件库说明 | Taro 文档",
      "content": "页面内容..."
    },
    // 更多页面...
  }
}

加载流程

1. 服务器启动时会自动检测并加载 docs 目录下的 JSON 文件。
2. 如果项目目录下未找到文档，将尝试从当前工作目录加载。
3. 页面 ID 默认使用 URL 作为键，无需额外指定 url 字段。
4. 所有来源名称会自动转为小写以确保一致性。

爬虫功能

系统内置爬虫支持从各类框架官方文档站点抓取内容并转换为本地可用的文档格式。爬虫特性包括：

1. 多站点支持：支持任意框架和库的文档网站，完全可配置。
2. 选择性爬取：可以配置包含和排除模式，精确控制需要爬取的内容。
3. 智能内容提取：自动识别文档页面的标题、正文内容和结构。
4. 多线程爬取：支持高并发爬取，提高效率。
5. 自动转换：将爬取内容转换为标准的文档 JSON 格式。
6. 容错机制：提供超时处理和重试机制，增强稳定性。

MCP 工具

服务器提供以下 MCP 工具：

1. search_docs - 搜索文档

• 参数:
  • query: 搜索关键词 (字符串, 必须)
  • source: 文档源名称 (字符串, 可选)
  • limit: 最大结果数量 (数字, 可选, 默认为10)
• 特殊功能:
  • 当 query 为 "reload" 时，会触发重新加载文档。

2. get_doc_detail - 获取文档详情

• 参数:
  • id: 文档 ID (字符串, 必须)
  • source: 文档源名称 (字符串, 可选)

使用示例

// 搜索文档示例
{
  "command": "search_docs",
  "params": {
    "query": "组件开发指南",
    "source": "taro"
  }
}

// 获取文档详情示例
{
  "command": "get_doc_detail",
  "params": {
    "id": "https://docs.taro.zone/docs/components-desc"
  }
}

在 Cursor 中的配置

配置步骤

1. 将服务器启动后，获取其 IP 地址和端口号。
2. 在 Cursor 中配置远程服务器连接：

   {
     "name": "mcp-server",
     "type": "http",
     "url": "http://localhost:3000"
   }
   

3. 使用 MCP 工具进行文档管理和搜索。

测试方法

测试步骤

1. 启动服务器：

   node server.js
   

2. 运行测试用例：

   npm test
   

示例测试代码

test('search_docs should return results', async () => {
  const response = await fetch('/api/search_docs?query=test');
  expect(response.status).toBe(200);
});

test('get_doc_detail should return details', async () => {
  const response = await fetch('/api/get_doc_detail?id=document-id');
  expect(response.status).toBe(200);
});

常见问题

1. 如何处理爬虫的反爬机制？

• 使用请求间隔和随机 UA 模拟真实用户行为。
• 处理验证码和动态加载内容。

2. 如何提高搜索效率？

• 使用全文索引技术（如 Elasticsearch）。
• 优化查询逻辑和结果排序算法。

项目贡献

欢迎 fork 和提交 PR！

• 提交 issue 报告问题或提出建议。
• 贡献代码改进功能或修复 bug。