avr-docs-mcp Server

官方

该MCP（模型上下文协议）服务器提供与Wiki.JS的集成，用于从Agent Voice Response Wiki.JS实例中搜索和列出页面。

GitHub

文档

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 密钥

环境变量

您可以通过两种方式设置环境变量：

方式一：使用 .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

方式二：使用系统环境变量

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 模式下运行，提供 REST API 和用于 MCP 通信的服务器发送事件（SSE）。

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 文件。