avr-docs-mcp

chính thức

Máy chủ MCP (Model Context Protocol) này cung cấp tích hợp với Wiki.JS để tìm kiếm và liệt kê các trang từ phiên bản Agent Voice Response Wiki.JS.

GitHub

Bạn có thể làm gì với Avr Docs MCP?

Tìm kiếm trang wiki theo từ khóa — Tìm các trang phù hợp với truy vấn bằng search_wiki_pages, có tùy chọn điều khiển phân trang.
Liệt kê tất cả trang wiki — Lấy danh sách phân trang các trang có sẵn từ phiên bản Wiki.JS qua list_wiki_pages.
Lấy một trang cụ thể — Lấy toàn bộ nội dung của một trang theo ID số hoặc chuỗi đường dẫn bằng get_wiki_page.
Kiểm tra kết nối Wiki.JS — Xác minh máy chủ có thể kết nối và xác thực với phiên bản Wiki.JS của bạn.

Tài liệu

Máy chủ MCP Tài liệu AVR với Tích hợp Wiki.JS

Máy chủ MCP (Giao thức Ngữ cảnh Mô hình) này cung cấp tích hợp với Wiki.JS để tìm kiếm và liệt kê các trang từ phiên bản Wiki.JS của bạn.

Tính năng

Tìm kiếm Trang Wiki.JS: Tìm kiếm trang bằng từ khóa hoặc chủ đề
Liệt kê Trang Wiki.JS: Nhận danh sách phân trang của tất cả các trang có sẵn
Lấy Trang Cụ thể: Truy xuất một trang cụ thể theo ID của nó
Kiểm tra Kết nối: Kiểm tra kết nối đến phiên bản Wiki.JS của bạn
Nhiều Chế độ Truyền tải: Hỗ trợ cả chế độ stdio và luồng HTTP
Hỗ trợ Docker: Hình ảnh Docker sẵn sàng sử dụng với kiểm tra tình trạng

Thiết lập

Điều kiện tiên quyết

Một phiên bản Wiki.JS đang chạy
Một khóa API với các quyền phù hợp để đọc trang

Biến Môi trường

Bạn có thể đặt biến môi trường theo hai cách:

Tùy chọn 1: Sử dụng tệp .env (Khuyến nghị)

Sao chép tệp môi trường mẫu:

cp .env.example .env

Chỉnh sửa tệp .env với các giá trị thực tế của bạn:

# 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

Tùy chọn 2: Sử dụng biến môi trường hệ thống

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"

Cài đặt

Cài đặt các phụ thuộc:

npm install

Xây dựng dự án:

npm run build

Kiểm tra kết nối (tùy chọn):

npm test

Chạy máy chủ:

npm start

Để phát triển:

npm run dev

Chế độ Chạy

Máy chủ hỗ trợ hai chế độ hoạt động:

Chế độ Stdio (Mặc định)

Máy chủ chạy ở chế độ stdio theo mặc định, giao tiếp qua đầu vào/đầu ra tiêu chuẩn. Đây là chế độ MCP truyền thống.

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

Chế độ Luồng HTTP

Máy chủ cũng có thể chạy ở chế độ HTTP, cung cấp API REST với Sự kiện do Máy chủ Gửi (SSE) cho giao tiếp MCP.

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

Khi chạy ở chế độ HTTP, máy chủ cung cấp:

Kiểm tra Tình trạng: GET /health - Trả về trạng thái máy chủ
Điểm cuối MCP: POST /mcp - Điểm cuối giao tiếp MCP sử dụng JSON-RPC 2.0

Kiểm tra Chế độ HTTP

Bạn có thể kiểm tra chế độ HTTP bằng curl hoặc Postman:

# 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
      }
    }
  }'

Hoặc sử dụng ứng dụng khách kiểm tra tích hợp:

npm run test:http

Sử dụng Docker

Sử dụng Hình ảnh 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

Công cụ Có sẵn

1. search_wiki_pages

Tìm kiếm trang trong Wiki.JS bằng từ khóa.

Tham số:

query (bắt buộc): Truy vấn tìm kiếm
page (tùy chọn): Số trang để phân trang (mặc định: 1)
limit (tùy chọn): Số kết quả mỗi trang (mặc định: 10, tối đa: 50)

2. list_wiki_pages

Liệt kê tất cả các trang có sẵn trong Wiki.JS.

Tham số:

page (tùy chọn): Số trang để phân trang (mặc định: 1)
limit (tùy chọn): Số kết quả mỗi trang (mặc định: 20, tối đa: 50)

3. get_wiki_page

Lấy một trang cụ thể theo ID hoặc đường dẫn của nó.

Tham số:

pageId (bắt buộc): ID (dạng số) hoặc đường dẫn (chuỗi) của trang cần truy xuất. Ví dụ: '3' cho ID, 'deepgram' cho đường dẫn

Cấu hình API Wiki.JS

Máy chủ MCP này sử dụng API GraphQL của Wiki.JS (điểm cuối /graphql). Đảm bảo phiên bản Wiki.JS của bạn đã bật truy cập API và khóa API của bạn có các quyền sau:

page:read - Để đọc nội dung trang
page:list - Để liệt kê trang
search:read - Để tìm kiếm trang

Máy chủ tự động xử lý các truy vấn và phản hồi GraphQL cho tất cả các hoạt động. Lưu ý rằng API GraphQL của Wiki.JS có một số hạn chế:

Các hoạt động tìm kiếm và liệt kê không hỗ trợ phân trang gốc, vì vậy phân trang được mô phỏng ở phía máy khách
Kết quả tìm kiếm không bao gồm nội dung trang đầy đủ
Kết quả liệt kê không bao gồm nội dung trang đầy đủ (sử dụng get_wiki_page để có nội dung đầy đủ)
Thẻ được trả về dưới dạng mảng chuỗi, không phải chuỗi phân cách bằng dấu phẩy

Ghi nhật ký

Máy chủ bao gồm ghi nhật ký toàn diện với các mức nhật ký có thể cấu hình:

debug - Thông tin gỡ lỗi chi tiết
info - Thông tin chung (mặc định)
warn - Chỉ thông báo cảnh báo
error - Chỉ thông báo lỗi

Đặt biến môi trường LOG_LEVEL để kiểm soát mức độ chi tiết của nhật ký.

Xử lý Lỗi

Máy chủ bao gồm xử lý lỗi toàn diện cho:

Thiếu biến môi trường
Sự cố kết nối mạng
Lỗi xác thực API
ID trang không hợp lệ
Giới hạn tốc độ

Phát triển

Để chạy ở chế độ phát triển với tải lại nóng:

npm run watch

Xây dựng

Để xây dựng cho sản xuất:

npm run build

JavaScript đã biên dịch sẽ nằm trong thư mục dist/.

Hỗ trợ & Cộng đồng

GitHub: https://github.com/agentvoiceresponse - Báo cáo sự cố, đóng góp mã.
Discord: https://discord.gg/DFTU69Hg74 - Tham gia thảo luận cộng đồng.
Docker Hub: https://hub.docker.com/u/agentvoiceresponse - Tìm hình ảnh Docker.
Wiki: https://wiki.agentvoiceresponse.com/en/home - Tài liệu và hướng dẫn dự án.

Hỗ trợ AVR

AVR là miễn phí và mã nguồn mở. Mọi hỗ trợ đều hoàn toàn tự nguyện và được coi là cử chỉ cá nhân thể hiện sự đánh giá cao. Các khoản quyên góp không cung cấp quyền truy cập vào tính năng, dịch vụ hoặc lợi ích đặc biệt, và dự án vẫn hoàn toàn có sẵn bất kể quyên góp.

Giấy phép

Giấy phép MIT - xem tệp LICENSE để biết chi tiết.