Mcpbook

笔记 TypeScript

🚀 通用文档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桌面（可选）
🚀 预缓存所有内容，实现服务器即时启动

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

安装并配置

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

使用自动检测进行构建

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

启动服务器

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

使用MCP检查器进行测试

npx @modelcontextprotocol/inspector node dist/index.js

📦 安装选项

选项1：本地开发

git clone 
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工具：

核心工具

工具	描述	参数
`{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: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文档或提交一个问题。

0 条评论
分类：笔记