AI导哈

文档爬取与搜索服务

一个完整的Python模板，用于构建具有文档爬取、向量搜索和灵活部署选项的MCP服务器。

  • by Qvakk
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Qvakk/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)

  2. 启动容器：

    docker-compose up -d

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

  3. 配置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/

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

    docker-compose --profile http up -d

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

  3. 测试服务器:

    # 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）

相关 MCP