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文檔 或提交一個問題。