avr-docs-mcp

官方

此 MCP（模型上下文協定）伺服器提供與 Wiki.JS 的整合，用於從 Agent Voice Response Wiki.JS 實例中搜尋和列出頁面。

GitHub

你可以用 Avr Docs MCP 做什麼？

依關鍵字搜尋維基頁面 — 使用 search_wiki_pages 尋找符合查詢條件的頁面，並可選用分頁控制。
列出所有維基頁面 — 透過 list_wiki_pages 從 Wiki.JS 實例中取得分頁的可用頁面列表。
取得特定頁面 — 使用 get_wiki_page 透過數值 ID 或路徑字串來擷取單一頁面的完整內容。
測試 Wiki.JS 連線 — 驗證伺服器能否連線至您的 Wiki.JS 實例並通過驗證。

文件

AVR Docs MCP Server 與 Wiki.JS 整合

此 MCP（模型上下文協定）伺服器提供與 Wiki.JS 的整合，用於搜尋和列出您 Wiki.JS 執行個體中的頁面。

功能特色

搜尋 Wiki.JS 頁面：使用關鍵字或主題搜尋頁面
列出 Wiki.JS 頁面：取得所有可用頁面的分頁清單
取得特定頁面：透過頁面 ID 擷取特定頁面
連線測試：測試與您 Wiki.JS 執行個體的連線
多重傳輸模式：支援 stdio 和 HTTP 串流模式
Docker 支援：提供立即可用的 Docker 映像檔，並包含健康檢查

設定

先決條件

一個正在運行的 Wiki.JS 執行個體
一個具有讀取頁面適當權限的 API 金鑰

環境變數

您可以透過兩種方式設定環境變數：

選項 1：使用 .env 檔案（建議）

複製範例環境檔案：

cp .env.example .env

使用您的實際值編輯 .env 檔案：

# Wiki.JS Configuration
WIKI_JS_BASE_URL=https://your-wiki-instance.com
WIKI_JS_API_KEY=your-api-key-here
LOG_LEVEL=info

# MCP Server Configuration
MCP_MODE=stdio
PORT=3000

選項 2：使用系統環境變數

export WIKI_JS_BASE_URL="https://your-wiki-instance.com"
export WIKI_JS_API_KEY="your-api-key-here"
export LOG_LEVEL="info"
export MCP_MODE="stdio"
export PORT="3000"

安裝

安裝相依套件：

npm install

建置專案：

npm run build

測試連線（可選）：

npm test

執行伺服器：

npm start

開發用：

npm run dev

執行模式

伺服器支援兩種操作模式：

Stdio 模式（預設）

伺服器預設以 stdio 模式運行，透過標準輸入/輸出進行通訊。這是傳統的 MCP 模式。

npm start
# or
npm run start:http  # for HTTP mode
# or
MCP_MODE=stdio npm start

HTTP 串流模式

伺服器也可以在 HTTP 模式下運行，提供具備伺服器傳送事件（SSE）的 REST API 以進行 MCP 通訊。

npm run start:http
# or
MCP_MODE=http npm start

在 HTTP 模式下運行時，伺服器提供：

健康檢查：GET /health - 回傳伺服器狀態
MCP 端點：POST /mcp - 使用 JSON-RPC 2.0 的 MCP 通訊端點

測試 HTTP 模式

您可以使用 curl 或 Postman 測試 HTTP 模式：

# Health check
curl http://localhost:3000/health

# Initialize MCP session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "curl-client",
        "version": "1.0.0"
      }
    }
  }'

# List available tools (use session ID from initialize response)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# Call a tool (use session ID from initialize response)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_wiki_pages",
      "arguments": {
        "query": "deepgram",
        "page": 1,
        "limit": 10
      }
    }
  }'

或使用內建的測試客戶端：

npm run test:http

Docker 使用方式

使用 Docker 映像檔

# Run in stdio mode (default)
docker run -d \
  --name avr-docs-mcp \
  -e WIKI_JS_BASE_URL="https://your-wiki-instance.com" \
  -e WIKI_JS_API_KEY="your-api-key-here" \
  agentvoiceresponse/avr-docs-mcp:latest

# Run in HTTP mode
docker run -d \
  --name avr-docs-mcp \
  -p 3000:3000 \
  -e WIKI_JS_BASE_URL="https://your-wiki-instance.com" \
  -e WIKI_JS_API_KEY="your-api-key-here" \
  -e MCP_MODE="http" \
  -e PORT="3000" \
  agentvoiceresponse/avr-docs-mcp:latest

Docker Compose

version: '3.8'

services:
  avr-docs-mcp:
    image: agentvoiceresponse/avr-docs-mcp:latest
    container_name: avr-docs-mcp
    ports:
      - "3000:3000"  # Only needed for HTTP mode
    environment:
      - WIKI_JS_BASE_URL=https://your-wiki-instance.com
      - WIKI_JS_API_KEY=your-api-key-here
      - MCP_MODE=http
      - PORT=3000
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

可用工具

1. search_wiki_pages

使用關鍵字在 Wiki.JS 中搜尋頁面。

參數：

query（必要）：搜尋查詢字串
page（可選）：分頁的頁碼（預設：1）
limit（可選）：每頁結果數量（預設：10，上限：50）

2. list_wiki_pages

列出 Wiki.JS 中所有可用的頁面。

參數：

page（可選）：分頁的頁碼（預設：1）
limit（可選）：每頁結果數量（預設：20，上限：50）

3. get_wiki_page

透過 ID 或路徑取得特定頁面。

參數：

pageId（必要）：要擷取的頁面 ID（數字）或路徑（字串）。範例：'3' 代表 ID，'deepgram' 代表路徑

Wiki.JS API 設定

此 MCP 伺服器使用 Wiki.JS GraphQL API（/graphql 端點）。請確保您的 Wiki.JS 執行個體已啟用 API 存取，且您的 API 金鑰具有以下權限：

page:read - 讀取頁面內容
page:list - 列出頁面
search:read - 搜尋頁面

伺服器會自動處理所有操作的 GraphQL 查詢和回應。請注意，Wiki.JS GraphQL API 有一些限制：

搜尋和列出操作不支援原生的分頁功能，因此分頁是在客戶端模擬的
搜尋結果不包含完整的頁面內容
列出結果不包含完整的頁面內容（使用 get_wiki_page 取得完整內容）
標籤以字串陣列形式回傳，而非逗號分隔的字串

日誌記錄

伺服器包含全面的日誌記錄功能，並可設定日誌層級：

debug - 詳細的除錯資訊
info - 一般資訊（預設）
warn - 僅警告訊息
error - 僅錯誤訊息

設定 LOG_LEVEL 環境變數來控制日誌記錄的詳細程度。

錯誤處理

伺服器包含全面的錯誤處理，涵蓋：

遺漏的環境變數
網路連線問題
API 驗證失敗
無效的頁面 ID
速率限制

開發

若要以開發模式運行並啟用熱重載：

npm run watch

建置

若要為生產環境建置：

npm run build

編譯後的 JavaScript 將位於 dist/ 目錄中。

支援與社群

GitHub： https://github.com/agentvoiceresponse - 回報問題、貢獻程式碼。
Discord： https://discord.gg/DFTU69Hg74 - 加入社群討論。
Docker Hub： https://hub.docker.com/u/agentvoiceresponse - 尋找 Docker 映像檔。
Wiki： https://wiki.agentvoiceresponse.com/en/home - 專案文件與指南。

支持 AVR

AVR 是免費且開放原始碼的。任何支持完全出於自願，並視為個人感謝之意。捐款不會提供功能、服務或特殊權益的存取權限，且無論捐款與否，專案皆完全可用。

授權條款

MIT 授權條款 - 詳情請參閱 LICENSE 檔案。