AI导哈

文档爬取与检索服务器

Python实现的文档爬取与检索服务器，包含爬取服务器（用于抓取文档网站并存储内容）和读取服务器（用于搜索和检索存储的文档），适用于开发文档管理和知识检索场景。

  • by sandeshghanta
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 sandeshghanta/docs-mcp-server

使用说明

Python文档MCP服务器

两个基于Python的MCP服务器，用于文档抓取和读取。复制深受启发 docs-mcp服务器.

概述

  • 刮刀服务器：抓取文档网站并将内容存储在SQLite中
  • 阅读器服务器：搜索和检索存储的文档

特性

刮刀服务器

  • 🕷️ 具有可配置深度和页面限制的网站爬行
  • 📄 HTML内容提取（标题、内容、元数据）
  • 💾 带FTS5全文搜索的SQLite存储
  • 🔧 用于Claude集成的MCP工具
  • 💻 CLI可直接使用

阅读器服务器

  • 🔍 在所有文档中搜索关键字
  • 📚 列出可用库和版本
  • 📖 按库浏览文档
  • 🎯 按URL检索特定文档
  • 🔧 用于Claude集成的5个MCP工具

安装

# Clone the repository
cd docs-mcp-server-python

# Install dependencies
uv sync --extra dev

Docker部署

使用Docker部署两台服务器进行生产或容器化开发。

快速开始

# Build images
cd docker && ./build.sh

# Deploy services
cd ../deploy && docker-compose up -d

两台服务器现在都在运行：

  • 刮刀MCP服务器: http://localhost:6281
  • 读取器MCP服务器: http://localhost:6282

主要特点

  • 🐳 容器化：隔离、可重复的环境
  • 🔒 网络隔离：阅读器服务器无法访问互联网（安全）
  • 💾 共享数据库：通过Docker卷的单个SQLite数据库
  • 🔄 自动重启：失败时重新启动服务
  • ⚙️ 可配置的：通过自定义 .env 文件

建筑

Scraper (6281)  ──┬──> Shared SQLite Database
                  │
Reader (6282)   ──┘    (Network Isolated)

文档

Docker命令

# Service management
docker-compose up -d              # Start all
docker-compose logs -f reader     # View logs
docker-compose restart scraper    # Restart service
docker-compose down               # Stop all

# Individual services
docker-compose up -d scraper      # Start scraper only
docker-compose stop reader        # Stop reader only

用法

刮刀服务器

通过CLI

# Scrape React documentation
uv run python scraper/cli.py scrape \
    --url https://react.dev \
    --library react \
    --version 19.0 \
    --max-depth 2 \
    --max-pages 50

# View all options
uv run python scraper/cli.py scrape --help

通过MCP服务器（本地开发）

添加到您的MCP客户端配置（例如，Claude Desktop）中，用于基于本地stdio的执行：

{
  "mcpServers": {
    "docs-scraper": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/docs-mcp-server-python",
        "run",
        "python",
        "scraper/server.py"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

然后使用 scrape_documentation 克劳德的工具。

注： 有关Docker部署，请参阅 Docker容器的MCP配置 在......下面

阅读器服务器

通过MCP服务器（本地开发）

添加到您的MCP客户端配置中，用于基于本地stdio的执行：

{
  "mcpServers": {
    "docs-reader": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/docs-mcp-server-python",
        "run",
        "python",
        "reader/server.py"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

可用的MCP工具：

  • search_documentation -使用关键字搜索
  • list_libraries -列出所有可用库
  • list_versions -列出库的版本
  • get_document -按URL检索文档
  • browse_library -浏览库中的所有文档

Docker容器的MCP配置

服务器在Docker中使用HTTP传输运行，使其可以作为网络服务访问。

使用Claude CLI（推荐）

启动Docker容器后(docker-compose up -d)，添加服务器：

# Add scraper server
claude mcp add --transport http docs-scraper http://localhost:6281/mcp

# Add reader server
claude mcp add --transport http docs-reader http://localhost:6282/mcp

手动配置

或者，在MCP客户端配置中添加：

刮刀服务器（Docker）

{
  "mcpServers": {
    "docs-scraper": {
      "transport": "http",
      "url": "http://localhost:6281/mcp"
    }
  }
}

阅读器服务器（Docker）

{
  "mcpServers": {
    "docs-reader": {
      "transport": "http",
      "url": "http://localhost:6282/mcp"
    }
  }
}

要求：

  • Docker容器必须正在运行(docker-compose up -d)
  • 服务器使用HTTP传输进行远程访问
  • 数据库通过绑定挂载在容器之间共享 deploy/data/

注： 服务器自动检测传输模式。默认情况下，它们使用HTTP（适用于Docker），但您可以通过设置强制stdio模式 MCP_TRANSPORT=stdio 环境变量。

配置

环境变量（可选）：

# Database location (default: ~/.docs-mcp/documentation.db)
export DOCS_MCP_DB_PATH=/path/to/database.db

# Scraping settings
export DOCS_MCP_USER_AGENT="MyBot/1.0"
export DOCS_MCP_TIMEOUT=30
export DOCS_MCP_DELAY=0.5
export DOCS_MCP_MAX_DEPTH=3
export DOCS_MCP_MAX_PAGES=100

项目结构

docs-mcp-server-python/
├── scraper/              # Scraper server
│   ├── server.py         # MCP server
│   ├── cli.py            # CLI commands
│   ├── crawler.py        # Site crawler
│   ├── extractors/       # Content extractors
│   │   ├── base.py       # Base interface
│   │   └── html.py       # HTML extractor
│   └── strategies/       # Scraping strategies
│       ├── base.py       # Base interface
│       └── site_crawler.py # Site crawler strategy
├── reader/               # Reader server
│   ├── server.py         # MCP server
│   ├── search.py         # Search functionality
│   └── query.py          # Query builder
├── shared/               # Shared components
│   ├── database.py       # Database manager
│   ├── schema.py         # Database schema
│   ├── models.py         # Data models
│   └── config.py         # Configuration
├── docker/               # Docker image building
│   ├── Dockerfile.scraper    # Scraper image
│   ├── Dockerfile.reader     # Reader image
│   ├── build.sh              # Build script
│   ├── push.sh               # Push to registry
│   └── README.md             # Build documentation
├── deploy/               # Deployment configuration
│   ├── docker-compose.yml    # Service orchestration
│   ├── .env.example          # Configuration template
│   └── README.md             # Deployment guide
└── tests/                # Tests

数据库模式

使用FTS5全文搜索的简单模式：

documents (
    id, library, version, url, title, content,
    raw_html, metadata, scraped_at, updated_at
)
documents_fts (FTS5 virtual table for search)

发展

运行测试

# Run all tests
uv run pytest -v

# Run specific test file
uv run pytest tests/shared/test_database.py -v

类型检查

uv run mypy shared/ scraper/ reader/ --strict

代码检查

uv run ruff check .
uv run ruff format .

示例

示例1：报废和搜索

# 1. Scrape Python documentation
uv run python scraper/cli.py scrape \
    --url https://docs.python.org/3/ \
    --library python \
    --version 3.13

# 2. Start reader server and search
# (In Claude with reader MCP configured)
# Use: search_documentation("async generators")

示例2：浏览库

# Start reader MCP server
# (In Claude)
# Use: list_libraries()
# Use: browse_library("python", "3.13")

路线图

看 实施计划 用于：

  • 未来的增强功能（剧作家、语义搜索等）
  • 测试策略
  • 详细实施说明

MVP状态

✅ 完成 -所有核心功能均已实现：

  • 第一阶段：基础和共享组件
  • 第二阶段：刮刀服务器（MCP+CLI）
  • 第三阶段：阅读器服务器（MCP工具）

许可证

麻省理工学院

致谢

复制深受启发 docs-mcp服务器.

相关 MCP