Mcpbook

🚀 通用文档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桌面集成 - 一键复制配置或通过CLI添加
• 🖥️ 实时终端 - 实时反馈和命令执行
• ⚠️ 安全特性 - 确认对话框和取消功能

⭐ 一键设置

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

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

就这么简单！ 🎉 交互式向导将：

• ✨ 引导您完成设置，提供智能默认值
• 🔍 自动检测域名/关键词，从您的文档站点中提取
• 📦 安装到有组织的目录 (~/.config/mcpbooks/servers/[name])
• 🌍 可选全局安装（可作为 your-server-name 命令使用）
• 🤖 自动配置Claude桌面（可选）
• 🚀 预缓存所有内容，实现服务器即时启动

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

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桌面集成

{
  "mcpServers": {
    "gitbook": {
      "command": "node",
      "args": ["/absolute/path/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  # 自定义端口

🌐 平台兼容性

虽然该MCP服务器最初是为GitBook设计的，但它已经证明了与许多文档平台的兼容性：

✅ 保证可用

• 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工具：

核心工具

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:3000/api/search?q=authentication"

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

# 获取页面的Markdown格式
curl "http://localhost:3000/api/page/api/authentication/markdown"

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

# 列出部分
curl "http://localhost:3000/api/sections"

# 获取部分中的页面
curl "http://localhost:3000/api/sections/API/pages"

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

# 刷新缓存
curl -X POST "http://localhost:3000/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 authentication"}}

# 获取特定页面
{"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解析
• 内存优化：按需加载，而不是完全内存缓存

🚧 限制

• 仅支持公共GitBook - 需要可公开访问的站点
• 静态内容 - 抓取已发布的HTML，而非基于API的内容
• 手动刷新 - 无实时更新（使用刷新工具）
• 以文本为中心 - 提取文本内容，而非交互式元素

📄 许可证

MIT

需要帮助？ 查看 MCP文档 或提交一个问题。