全球通用文档 MCP 服务器

这是一个高性能的 MCP（模型上下文协议）服务器，可以将任何文档网站转换成一个可由AI访问的知识库。最初是为 GitBook 构建的，但也可以与Vercel 文档、Next.js 站点、Docusaurus 和许多其他文档平台一起使用。具有即时启动、智能缓存和自动域名检测等功能。

✨ 主要功能

• ⚡ 即时启动 - 使用 SQLite 存储实现亚秒级服务器初始化
• 🔍 高级搜索 - 使用 FTS5 全文搜索，支持模糊匹配和排名
• 🧠 智能自动检测 - 自动检测域名、关键词和品牌信息
• 📝 Markdown 完美支持 - 保留格式并高亮显示代码块
• 🔄 后台更新 - 非阻塞变更检测和缓存刷新
• 🌐 全面支持 - 支持 GitBook、Vercel 文档、Next.js 站点和其他许多文档平台
• 📡 双接口 - 提供 MCP 工具和 REST API 端点
• 🚀 生产就绪 - 包括速率限制、错误处理和强大的缓存机制

🚀 快速开始

💡 推荐：使用交互式创建器以获得最佳体验！

🎨 Web UI 管理仪表板

# 克隆此仓库（一次）
git clone https://github.com/tcsenpai/mcpbook/
cd mcpbook

# 构建 UI
npm run ui:build

# 启动 Web 界面
npm run ui

Web UI 提供：

• 🚀 视觉服务器创建 - 带实时 URL 验证的逐步向导
• 📊 服务器管理 - 实时状态下的启动/停止/删除服务器
• 📋 Claude Desktop 集成 - 一键复制配置或通过 CLI 添加
• 🖥️ 实时终端 - 实时反馈和命令执行
• ⚠️ 安全特性 - 确认对话框和取消功能

⭐ 一键设置

# 克隆此仓库（一次）
git clone https://github.com/tcsenpai/mcpbook/
cd mcpbook

# 即刻为任何文档站点创建 MCP 服务器
npm exec create-gitbook-mcp

就这样！ 🎉 交互式向导会：

• ✨ 引导您完成设置，带有智能默认值
• 🔍 自动检测域名/关键词来自您的文档站点
• 📦 安装在组织目录中 (~/.config/mcpbooks/servers/[name])
• 🌍 可选全局安装（可通过 your-server-name 命令访问）
• 🤖 自动配置 Claude Desktop（可选）
• 🚀 预缓存所有内容以便即时服务器启动

🛠️ 手动设置（高级用户）

1. 安装和配置

   npm install
   echo "GITBOOK_URL=https://docs.yoursite.com" > .env
   

2. 构建与自动检测

   npm run build  # 自动检测并配置您的域名
   

3. 启动服务器

   npm start  # 使用 SQLite 缓存即时启动
   

4. 使用 MCP 检查器测试

   npx @modelcontextprotocol/inspector node dist/index.js
   

📦 安装选项

选项 1：本地开发

git clone <repository>
cd mcpbook
npm install
npm run build
npm start

选项 2：全局安装

npm install -g .
# 然后使用 package.json 中的二进制名称
your-mcp-server-name

选项 3：Claude Desktop 集成

{
  "mcpServers": {
    "gitbook": {
      "command": "node",
      "args": ["/绝对路径/to/dist/index.js"],
      "env": {
        "GITBOOK_URL": "https://docs.yoursite.com"
      }
    }
  }
}

配置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json

选项 4：StreamableHTTP 运输

npm run start:http  # 在端口 3001 上运行 StreamableHTTP
node dist/index.js --streamable-http --port=3002  # 自定义端口

选项 5：REST API 服务器

npm run start:api  # 在端口 3000 上运行 HTTP 服务器
PORT=8080 npm run start:api  # 自定义端口

🌐 平台兼容性

虽然最初设计用于 GitBook，但这个 MCP 服务器已经证明与许多文档平台兼容：

✅ 保证工作

• GitBook（原始目标平台）
• 自定义 GitBook 实例

🎯 成功测试

• 托管在 Vercel 的文档 (docs.vercel.com, aptos.dev)
• Next.js 文档站点
• 静态站点生成器，具有一致的导航
• 大多数基于 HTML 的文档平台

🔧 如何工作

爬虫程序智能地：

• 发现导航 通过链接爬取
• 提取内容 从任何 HTML 结构中
• 适应不同的布局 自动
• 处理各种身份验证 和路由模式

💡 小贴士：如果站点具有一致的导航和可访问的内容，我们的爬虫很可能有效！自动检测功能会自动适应不同站点结构。

⚙️ 配置

自动检测（推荐）

GITBOOK_URL=https://docs.yoursite.com
AUTO_DETECT_DOMAIN=true
AUTO_DETECT_KEYWORDS=true

服务器将自动：

• 生成特定领域的工具名称（如 stripe_docs_search，api_docs_get_page）
• 从内容中提取相关关键词
• 创建上下文描述以更好地集成 AI

手动配置

# 目标 GitBook（必需）
GITBOOK_URL=https://docs.yoursite.com

# 自定义品牌（可选）
SERVER_NAME=my-api-docs
SERVER_DESCRIPTION=API 文档和指南
DOMAIN_KEYWORDS=api,rest,graphql,endpoints
TOOL_PREFIX=api_

# 性能调整
CACHE_TTL_HOURS=1
MAX_CONCURRENT_REQUESTS=5
SCRAPING_DELAY_MS=100

配置示例

API 文档：

GITBOOK_URL=https://api-docs.yourservice.com
TOOL_PREFIX=api_
DOMAIN_KEYWORDS=api,rest,endpoints,authentication

→ 结果为：api_search_content，api_get_page 等。

产品文档：

GITBOOK_URL=https://help.yourproduct.com  
TOOL_PREFIX=help_
DOMAIN_KEYWORDS=tutorial,guide,troubleshooting

→ 结果为：help_search_content，help_get_page 等。

🛠️ 可用工具

服务器暴露了 7 个 MCP 工具，并自动添加前缀：

核心工具

工具	描述	参数
{prefix}_search_content	带排名的高级搜索	query: 搜索词
{prefix}_get_page	获取特定页面内容	path: 页面路径（例如，“/api/auth”）
{prefix}_list_sections	获取目录	无
{prefix}_get_section_pages	获取章节中的所有页面	section: 章节名称
{prefix}_refresh_content	强制缓存刷新	无
{prefix}_get_code_blocks	提取带语法高亮的代码	path: 页面路径
{prefix}_get_markdown	获取格式化的 Markdown	path: 页面路径

MCP 提示

• explain_section - 生成综合教程
• summarize_page - 创建简洁摘要
• compare_sections - 对比文档章节
• api_reference - 格式化为 API 文档
• quick_start_guide - 生成快速入门指南

🌐 HTTP 接口

服务器支持 MCP StreamableHTTP 和传统的 REST API：

StreamableHTTP MCP 协议：

# 健康检查
curl http://localhost:3001/health

# MCP 请求（需要 MCP 客户端）
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

REST API（单独服务器）：

# 搜索内容
curl "http://localhost:3_000/api/search?q=authentication"

# 获取特定页面
curl "http://localhost:3_000/api/page/api/authentication"

# 获取页面作为 Markdown
curl "http://localhost:3_000/api/page/api/authentication/markdown"

# 获取代码块
curl "http://localhost:3_000/api/page/api/authentication/code"

# 列出章节
curl "http://localhost:3_000/api/sections"

# 获取章节页面
curl "http://localhost:3_000/api/sections/API/pages"

# 服务器状态
curl "http://localhost:3_000/api/status"

# 刷新缓存
curl -X POST "http://localhost:3_000/api/refresh"

🎯 使用示例

自动检测结果

• docs.stripe.com → stripe_search_content，stripe_get_page
• docs.react.dev → react_search_content，react_get_page
• api.yourcompany.com → api_search_content，api_get_page
• 通用站点 → docs_search_content，docs_get_page

MCP 工具使用

# 搜索认证文档
{"tool": "api_search_content", "arguments": {"query": "oauth 认证"}}

# 获取特定页面
{"tool": "api_get_page", "arguments": {"path": "/auth/oauth"}}

# 获取代码示例
{"tool": "api_get_code_blocks", "arguments": {"path": "/sdk/quickstart"}}

# 刷新内容
{"tool": "api_refresh_content", "arguments": {}}

🏗️ 架构

• SQLite 存储 - 使用 FTS5 全文搜索实现快速启动
• 后台更新 - 非阻塞变更检测
• 自动检测 - 域名和关键词提取
• 并行爬取 - 可配置并发
• 智能缓存 - 仅更新更改的内容

关键组件

• GitBookScraper - 网页爬取和内容提取
• SQLiteStore - 高性能存储，带 FTS5 搜索
• DomainDetector - 自动域名和关键词检测
• GitBookMCPServer - 带工具处理器的 MCP 服务器
• GitBookRestAPI - 用于 Web 集成的 HTTP 端点

🔧 开发

# 开发模式，自动重载
npm run dev

# 构建，自动检测
npm run build

# 手动自动检测
npm run auto-detect

# 清洁构建（无自动检测）
npm run build:clean

# 使用 MCP 检查器测试
npx @modelcontextprotocol/inspector node dist/index.js

🌍 全球通用 GitBook 支持

适用于任何公开的 GitBook，包括：

• API 文档 - Stripe，Twilio 等
• 框架文档 - React，Vue，Angular
• 产品指南 - 帮助中心和教程
• 开发者资源 - SDK 和参考
• 公司维基 - 内部文档

⚡ 性能

• 即时启动：使用 SQLite 缓存实现亚秒级初始化
• 后台更新：非阻塞变更检测
• 智能索引：使用 FTS5 全文搜索进行排名
• 高效存储：SQLite 替代缓慢的 JSON 解析
• 内存优化：按需加载而非全内存缓存

🚧 限制

• 仅限公开 GitBooks - 需要公开访问的站点
• 静态内容 - 爬取发布的 HTML，而不是 API 基础
• 手动刷新 - 没有实时更新（使用刷新工具）
• 文本导向 - 提取文本内容，不包括互动元素

📄 许可证

MIT

---

需要帮助？ 查看 MCP 文档 或打开问题。