使用说明

MCP文档--将任何文档站点转换为MCP服务器

一个Python包，它抓取文档站点，用嵌入对其进行索引，并将其作为MCP（模型上下文协议）服务器公开，用于LLM集成。

特性

网络爬虫：使用Playwright抓取JavaScript渲染的文档网站
语义搜索：使用嵌入对文档进行索引以进行语义搜索
多个嵌入提供程序：支持OpenAI和Azure OpenAI嵌入
向量存储：使用ChromaDB进行持久矢量存储
MCP服务器：为每个文档项目自动生成并运行MCP服务器
基于项目：将文档网站组织为单独的项目
CLI工具：用于管理项目的简单命令行界面

安装

来源

# Clone the repository
git clone https://github.com/yourorg/mcp-docs.git
cd mcp-docs

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows (PowerShell):
.\.venv\Scripts\Activate.ps1
# On macOS/Linux:
source .venv/bin/activate

# Install in editable mode
pip install -e ".[dev]"

# Install Playwright browsers
playwright install chromium

依赖项

该项目要求：

Python 3.8+
嵌入提供程序凭据：
- OpenAI API密钥，或
- Azure OpenAI（API密钥、终结点和部署ID）
剧作家（用于网页抓取）
ChromaDB（用于矢量存储）

快速开始

1.配置嵌入提供程序

设置您的嵌入提供商（OpenAI或Azure OpenAI）：

# Interactive configuration (will prompt for provider selection)
mcp-docs configure

或者通过命令行配置：

# Configure OpenAI
mcp-docs configure --provider openai --api-key sk-your-key-here

# Configure Azure OpenAI
mcp-docs configure --provider azure-openai --api-key your-key --endpoint https://your-resource.openai.azure.com --deployment-id text-embedding-ada-002

您还可以设置环境变量：

# For OpenAI
# Windows (PowerShell)
$env:OPENAI_API_KEY="sk-your-key-here"
# macOS/Linux
export OPENAI_API_KEY="sk-your-key-here"

# For Azure OpenAI
# Windows (PowerShell)
$env:AZURE_OPENAI_API_KEY="your-key"
$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
$env:AZURE_OPENAI_DEPLOYMENT_ID="text-embedding-ada-002"
# macOS/Linux
export AZURE_OPENAI_API_KEY="your-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
export AZURE_OPENAI_DEPLOYMENT_ID="text-embedding-ada-002"

2.添加文档项目

为文档站点创建新项目：

mcp-docs add-project my-docs https://docs.example.com

这将在以下位置创建一个项目目录 projects/my-docs/ 与：

project.json -项目配置
data/ -数据目录
logs/ -日志文件目录

3.为文件编制索引

报废并索引文件：

mcp-docs index my-docs --max-pages 200 --max-depth 5

这将：

从文档网站上抓取页面（最多 max-pages)
清理并分块内容
使用配置的提供程序（OpenAI或Azure OpenAI）生成嵌入
在ChromaDB中存储嵌入

4.启动MCP服务器

为您的项目启动MCP服务器：

mcp-docs start my-docs

服务器将运行并公开 search_docs MCP客户端可以使用的工具。

CLI命令

`add-project <name> <url>`

创建一个新的文档项目。

mcp-docs add-project react-docs https://react.dev

这将：

在以下位置创建项目目录 projects/<name>/
初始化ChromaDB集合
将项目配置保存到 project.json

`index <project_name> [options]`

为文档项目建立索引。

选项：

--max-pages <N>：要抓取的最大页数（默认值：200）
--max-depth <N>：最大爬行深度（默认值：5）

mcp-docs index react-docs --max-pages 100 --max-depth 3

`start <project_name> [options]`

启动项目的MCP服务器。

选项：

--port <PORT>：MCP服务器端口（可选，用于SSE传输）

mcp-docs start react-docs
mcp-docs start react-docs --port 8080

`list`

列出所有可用项目及其状态。

显示所有项目及其配置、索引状态和文档计数。

mcp-docs list

`configure [options]`

配置嵌入提供程序和凭据。

选项：

--provider <PROVIDER>：嵌入提供者（“penai”或“azure openai”）
--api-key <KEY>：API密钥（两个提供程序都需要）
--endpoint <URL>：Azure OpenAI端点URL（Azure OpenAI需要）
--deployment-id <ID>：Azure OpenAI部署ID（Azure OpenAI需要）
--api-version <VERSION>：Azure OpenAI API版本（可选，默认：2024-02-15-preview）
--project <NAME>：针对特定项目进行配置
--global：保存到全局配置（默认）
--show：显示当前配置
--unset：删除存储的配置

# Interactive configuration (prompts for provider selection)
mcp-docs configure

# Configure OpenAI
mcp-docs configure --provider openai --api-key sk-...

# Configure Azure OpenAI
mcp-docs configure --provider azure-openai --api-key your-key --endpoint https://your-resource.openai.azure.com --deployment-id text-embedding-ada-002

# Configure for specific project
mcp-docs configure --project my-docs --provider azure-openai --api-key ... --endpoint ... --deployment-id ...

# Show current config
mcp-docs configure --show

# Remove stored configuration
mcp-docs configure --unset

项目结构

mcp-docs/
├── projects/
│   ├── my-docs/
│   │   ├── project.json      # Project configuration
│   │   ├── server.py          # Auto-generated MCP server
│   │   ├── data/              # Data directory
│   │   └── logs/              # Log files
│   └── ...
├── indexes/                    # ChromaDB indexes
│   └── <collection-hash>/
└── src/                        # Source code
    ├── cli.py                  # CLI implementation
    ├── config.py               # Configuration management
    ├── indexer/                # Indexing pipeline
    │   ├── scrapper.py         # Web scraper
    │   ├── cleaner.py          # Text cleaning
    │   ├── chunker.py          # Text chunking
    │   ├── embedder.py         # Embedding generation
    │   └── db_writer.py        # Database writing
    ├── embeddings/             # Embedding providers
    │   ├── openai_provider.py  # OpenAI provider
    │   └── azure_openai_provider.py  # Azure OpenAI provider
    └── vectorstores/           # Vector store implementations
        └── chrome_store.py     # ChromaDB store

项目配置

每个项目都有一个 project.json 文件：

{
  "name": "my-docs",
  "url": "https://docs.example.com",
  "collection_name": "abc123...",
  "chroma_path": "/path/to/indexes/abc123...",
  "embedding_provider": "openai",
  "openai_api_key": "sk-..." 
}

对于Azure OpenAI项目：

{
  "name": "my-docs",
  "url": "https://docs.example.com",
  "collection_name": "abc123...",
  "chroma_path": "/path/to/indexes/abc123...",
  "embedding_provider": "azure-openai",
  "azure_openai_api_key": "...",
  "azure_openai_endpoint": "https://your-resource.openai.azure.com",
  "azure_openai_deployment_id": "text-embedding-ada-002"
}

嵌入提供程序配置

嵌入提供程序配置可以设置为多个级别（按优先级顺序）：

环境变量 （最高优先级）
- OpenAI： OPENAI_API_KEY
- Azure OpenAI： AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT_ID, AZURE_OPENAI_API_VERSION
项目特定：存储在 projects/<project>/project.json
全局配置: ~/.config/mcp-docs/config.json （Linux/macOS）或 %APPDATA%/mcp-docs/config.json （Windows）

支持的提供商

OpenAI：直接访问OpenAI API
- 需要：API密钥
- 默认型号： text-embedding-3-small
Azure OpenAI：Azure托管的OpenAI模型
- 需要：API密钥、端点URL、部署ID
- 可选：API版本（默认： 2024-02-15-preview)
- 非常适合拥有Azure订阅的组织

使用 mcp-docs configure 管理提供者配置。每个项目都可以使用不同的提供程序，也可以设置全局默认值。

运作原理

抓取：使用Playwright渲染JavaScript繁重的文档网站并提取内容
清洁：删除导航、标题和其他非内容元素
分块：将内容拆分为可管理的块以进行嵌入
嵌入：使用配置的提供程序（OpenAI或Azure OpenAI）生成嵌入
存储：将嵌入和元数据存储在ChromaDB中
MCP服务器：生成一个MCP服务器 search_docs 语义搜索工具

MCP服务器集成

生成的MCP服务器公开了 search_docs 该工具：

接受文本查询或预先计算的嵌入
返回前k个匹配的文档块及其元数据
提供对索引文档的语义搜索

服务器使用FastMCP并在SSE（服务器发送事件）模式下运行，以与MCP客户端（如VS Code的MCP扩展）兼容。

发展

运行测试

pytest

代码风格

该项目使用：

black 用于代码格式化
ruff 对于linting

black src/
ruff check src/

需求

Python 3.8+
嵌入提供程序凭据：
- OpenAI API密钥，或
- Azure OpenAI（API密钥、终结点、部署ID）
剧作家（使用Chromium浏览器）
色度数据库

看 pyproject.toml 获取完整的依赖关系列表。

局限性

使用ChromaDB作为唯一的矢量存储
需要JavaScript渲染（Playwright）进行抓取
无内置BM25/混合搜索（仅语义搜索）

贡献

欢迎投稿！拜托：

为功能请求或错误报告打开问题
提交带有测试的拉取请求
遵循代码风格（黑色+褶边）

许可证

MIT许可证——见 LICENSE 文件。

使用说明

MCP文档--将任何文档站点转换为MCP服务器

特性

安装

来源

依赖项

快速开始

1.配置嵌入提供程序

2.添加文档项目

3.为文件编制索引

4.启动MCP服务器

CLI命令

add-project <name> <url>

index <project_name> [options]

start <project_name> [options]

list

configure [options]

项目结构

项目配置

嵌入提供程序配置

支持的提供商

运作原理

MCP服务器集成

发展

运行测试

代码风格

需求

局限性

贡献

许可证

相关 MCP

PowerPoint操作服务器

AI持久记忆服务器

MySQL查询服务器

Markdown转换服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

`add-project <name> <url>`

`index <project_name> [options]`

`start <project_name> [options]`

`list`

`configure [options]`