Mcpdocserver

🚀 MCP 服務器項目文檔

MCP 服務器項目是一個具備文檔管理、爬蟲抓取和工具調用等功能的項目。它可以自動加載文檔，支持從各類框架官方文檔站點抓取內容，並提供搜索文檔、獲取文檔詳情等工具，方便用戶進行文檔管理和搜索。

🚀 快速開始

要使用 MCP 服務器項目，你可以按照以下步驟進行操作：

# 克隆倉庫到本地
git clone https://github.com/your-username/mcp-server.git
cd mcp-server

# 安裝依賴項
npm install

# 啟動服務器
node server.js

✨ 主要特性

• 文檔管理：支持自動檢測並加載 docs 目錄下的 JSON 文件，也可從當前工作目錄加載。頁面 ID 默認使用 URL 作為鍵，所有來源名稱會自動轉為小寫以確保一致性。
• 爬蟲功能：系統內置爬蟲支持從各類框架官方文檔站點抓取內容並轉換為本地可用的文檔格式。支持多站點、選擇性爬取、智能內容提取、多線程爬取、自動轉換和容錯機制。
• MCP 工具：服務器提供 search_docs 和 get_doc_detail 兩個工具，方便用戶搜索文檔和獲取文檔詳情。
• 可配置性：支持在 Cursor 中配置遠程服務器連接，方便使用 MCP 工具進行文檔管理和搜索。

📦 安裝指南

安裝步驟

1. 克隆倉庫到本地：

   git clone https://github.com/your-username/mcp-server.git
   cd mcp-server
   

2. 安裝依賴項：

   npm install
   

3. 啟動服務器：

   node server.js
   

項目結構

mcp-server/
├── server.js          # 主服務器文件
├── docs/             # 文檔存儲目錄
│   └── doc.json      # 示例文檔文件
├── crawl/            # 爬蟲相關模塊
│   ├── crawler.js    # 爬蟲主邏輯
│   └── parsers/      # 數據解析模塊
├── tools/            # MCP 工具實現
│   ├── search_docs.js  # 搜索文檔工具
│   └── get_doc_detail.js  # 獲取文檔詳情工具
└── test/             # 測試用例
    └── test_server.js     # 服務器測試用例

📚 詳細文檔

文檔格式

文檔結構

文檔文件應為 JSON 格式，包含以下字段：

{
  "source": {
    "name": "taro",
    "url": "https://docs.taro.zone/docs"
  },
  "lastUpdated": "2024-03-27T12:00:00Z",
  "pages": {
    "https://docs.taro.zone/docs/components-desc": {
      "title": "組件庫說明 | Taro 文檔",
      "content": "頁面內容..."
    },
    // 更多頁面...
  }
}

加載流程

1. 服務器啟動時會自動檢測並加載 docs 目錄下的 JSON 文件。
2. 如果項目目錄下未找到文檔，將嘗試從當前工作目錄加載。
3. 頁面 ID 默認使用 URL 作為鍵，無需額外指定 url 字段。
4. 所有來源名稱會自動轉為小寫以確保一致性。

爬蟲功能

系統內置爬蟲支持從各類框架官方文檔站點抓取內容並轉換為本地可用的文檔格式。爬蟲特性包括：

1. 多站點支持：支持任意框架和庫的文檔網站，完全可配置。
2. 選擇性爬取：可以配置包含和排除模式，精確控制需要爬取的內容。
3. 智能內容提取：自動識別文檔頁面的標題、正文內容和結構。
4. 多線程爬取：支持高併發爬取，提高效率。
5. 自動轉換：將爬取內容轉換為標準的文檔 JSON 格式。
6. 容錯機制：提供超時處理和重試機制，增強穩定性。

MCP 工具

服務器提供以下 MCP 工具：

1. search_docs - 搜索文檔

• 參數:
  • query: 搜索關鍵詞 (字符串, 必須)
  • source: 文檔源名稱 (字符串, 可選)
  • limit: 最大結果數量 (數字, 可選, 默認為10)
• 特殊功能:
  • 當 query 為 "reload" 時，會觸發重新加載文檔。

2. get_doc_detail - 獲取文檔詳情

• 參數:
  • id: 文檔 ID (字符串, 必須)
  • source: 文檔源名稱 (字符串, 可選)

在 Cursor 中的配置

配置步驟

1. 將服務器啟動後，獲取其 IP 地址和端口號。
2. 在 Cursor 中配置遠程服務器連接：

   {
     "name": "mcp-server",
     "type": "http",
     "url": "http://localhost:3000"
   }
   

3. 使用 MCP 工具進行文檔管理和搜索。

💻 使用示例

基礎用法

// 搜索文檔示例
{
  "command": "search_docs",
  "params": {
    "query": "組件開發指南",
    "source": "taro"
  }
}

// 獲取文檔詳情示例
{
  "command": "get_doc_detail",
  "params": {
    "id": "https://docs.taro.zone/docs/components-desc"
  }
}

🔧 技術細節

測試方法

測試步驟

1. 啟動服務器：

   node server.js
   

2. 運行測試用例：

   npm test
   

示例測試代碼

test('search_docs should return results', async () => {
  const response = await fetch('/api/search_docs?query=test');
  expect(response.status).toBe(200);
});

test('get_doc_detail should return details', async () => {
  const response = await fetch('/api/get_doc_detail?id=document-id');
  expect(response.status).toBe(200);
});

常見問題

1. 如何處理爬蟲的反爬機制？

• 使用請求間隔和隨機 UA 模擬真實用戶行為。
• 處理驗證碼和動態加載內容。

2. 如何提高搜索效率？

• 使用全文索引技術（如 Elasticsearch）。
• 優化查詢邏輯和結果排序算法。

📄 許可證

文檔中未提及相關許可證信息。

項目貢獻

歡迎 fork 和提交 PR！

• 提交 issue 報告問題或提出建議。
• 貢獻代碼改進功能或修復 bug。