Docs Scraper Shell For MCP

MCP文档抓取模板

一个用于构建的完整Python模板 模型上下文协议（MCP） 提供带有文档抓取、向量搜索和灵活部署选项的服务器。

特点/特性

• 🔍 双搜索模式语义搜索（基于机器学习）或关键词搜索（轻量级）
• 🤖 表示机器人。 多供应商嵌入HuggingFace（本地）、OpenAI 或 Azure OpenAI
• 📚 书籍的符号，常用于表示书籍或阅读相关内容。 网络数据抓取（或网页抓取）可配置的文档爬虫，具备深度控制功能
• 💾 代表“软盘”或“存储设备” 向量存储带有持久化存储的ChromaDB
• ⏰（时钟图标，无具体文字含义，可表示时间、提醒等） 自动更新计划中的文档更新
• 🔌（电源插头） 双运输stdio（本地MCP）或HTTP/SSE（远程访问）
• 🐳 这个表情符号代表“海豚”，所以可以翻译为“海豚”。 Docker 准备就绪使用配置文件的容器化部署
• ☸️（这个符号在中文中没有直接对应的翻译，它通常代表一个轮子或某种循环的象征，如佛教中的法轮，但在没有上下文的情况下，可以简单地描述为“一个轮子或循环的符号”。） Kubernetes 就绪带有自动扩展的生产部署

快速入门

选项1：stdio模式（本地MCP - 默认）

对于： 在您的本地机器上集成VS Code和Claude Desktop

1. 配置环境：

   cp .env.example .env
   # Edit .env and set your DOCS_URLS
   # Keep TRANSPORT=stdio (or leave it out, stdio is default)

1. 启动容器：

   docker-compose up -d

这开始了 mcp-server-template 容器（未暴露任何端口）。

1. 配置MCP客户端 （VS Code 或 Claude 桌面版）：

   {
     "mcpServers": {
       "docs-scraper": {
         "command": "docker",
         "args": ["exec", "-i", "mcp-server-template", "python", "-m", "mcp_server_template.server"]
       }
     }
   }

选项2：HTTP模式（远程访问）

对于： 测试API、远程访问或准备Kubernetes部署

1. 配置HTTP环境：

   cp .env.example .env
   # Edit .env and set:
   # TRANSPORT=http
   # DOCS_URLS=https://your-docs-site.com/

1. 启动带有HTTP配置文件的容器：

   docker-compose --profile http up -d

这开始了 mcp-server-template-http 在端口3003上的容器。

1. 测试服务器:

   # Check health
   curl http://localhost:3003/health

   # MCP clients connect to:
   # http://localhost:3003/sse

在模式之间切换

停止当前模式：

docker-compose down

启动标准输入输出模式：

docker-compose up -d

启动HTTP模式：

docker-compose --profile http up -d

查看日志：

# stdio mode
docker logs mcp-server-template -f

# HTTP mode
docker logs mcp-server-template-http -f

配置

关键环境变量（参见 .env.example （完整列表见下文）：

• TRANSPORT运输方式 - stdio （本地MCP）或 http （远程/Kubernetes）
• DOCS_URLS要抓取的文档URL（多个网站时用逗号分隔）

- 单曲： DOCS_URLS=https://docs.example.com/ - 多重的；多倍的 DOCS_URLS=https://docs.example.com/,https://api.example.com/docs/,https://guides.example.com/

• SWAGGER_URLSSwagger/OpenAPI JSON URL（逗号分隔，可选）
• USE_EMBEDDINGS启用语义搜索true) 或关键词搜索 (false）
• EMBEDDING_PROVIDER: huggingface， openai，或者 azure
• CRAWL_MAX_DEPTH最大抓取深度（0-3，建议设置为2）
• AUTO_UPDATE_ENABLED启用计划文档更新true/false)
• HTTP_PORTHTTP 模式的端口（默认：3000，在主机上映射为 3003）

运输方式

stdio 模式（本地 MCP）

最适合用于： 本地开发，VS Code，Claude 桌面版

这台服务器使用 stdio 传输 用于通过stdin/stdout管道进行直接的MCP客户端通信。

VS Code (settings.json):

{
  "mcp.servers": {
    "docs-scraper": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-server-template", "python", "-m", "mcp_server_template.server"]
    }
  }
}

Claude Desktop（可译为“Claude桌面版”） (claude_desktop_config.json)：

{
  "mcpServers": {
    "docs-scraper": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-server-template", "python", "-m", "mcp_server_template.server"]
    }
  }
}

HTTP 模式（远程访问）

最适合用于： 远程访问、多用户、Kubernetes部署

设定 TRANSPORT=http 在里面 .env 并使用HTTP配置文件：

docker-compose --profile http up -d

终点（或结局指标）：

• GET /health - 健康检查
• GET /sse - MCP 服务器发送事件（Server-Sent Events）端点

MCP客户端配置 （针对远程HTTP客户端）：

{
  "mcpServers": {
    "docs-scraper": {
      "url": "http://localhost:3003/sse",
      "transport": "sse"
    }
  }
}

Kubernetes 部署

看 k8s-deployment.yaml 用于生产环境的Kubernetes部署，包含：

• 水平Pod自动扩展
• ChromaDB的持久卷声明
• Ingress 配置
• 健康检查和就绪性探测

定制化

这是一个 模板 - 分支并为您的文档源进行定制：

1. 更新 DOCS_URLS 在 .env
2. 自定义抓取设置 src/mcp_server_template/documentation_scraper.py
3. 添加自定义工具到 src/mcp_server_template/server.py
4. 根据需要调整分块大小和搜索参数

要求

• Python 3.12及以上版本
• Docker & Docker Compose（推荐）
• 500MB+ 内存用于语义搜索（仅关键词搜索需50MB）