avr-docs-mcp

AVR Docs MCP Server с интеграцией Wiki.JS

Этот MCP (Model Context Protocol) сервер обеспечивает интеграцию с Wiki.JS для поиска и получения списка страниц из вашего экземпляра Wiki.JS.

Возможности

• Поиск страниц Wiki.JS: Поиск страниц по ключевым словам или темам
• Список страниц Wiki.JS: Получение постраничного списка всех доступных страниц
• Получение конкретной страницы: Получение определенной страницы по её ID
• Проверка соединения: Проверка соединения с вашим экземпляром Wiki.JS
• Несколько режимов передачи: Поддержка режимов stdio и HTTP stream
• Поддержка Docker: Готовый к использованию образ Docker с проверками работоспособности

Настройка

Предварительные требования

1. Запущенный экземпляр Wiki.JS
2. API-ключ с соответствующими разрешениями на чтение страниц

Переменные окружения

Вы можете задать переменные окружения двумя способами:

Вариант 1: Использование файла .env (рекомендуется)

1. Скопируйте файл примера окружения:

cp .env.example .env

2. Отредактируйте файл .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"

Установка

1. Установите зависимости:

npm install

2. Соберите проект:

npm run build

3. Проверьте соединение (опционально):

npm test

4. Запустите сервер:

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 Stream

Сервер также может работать в режиме HTTP, предоставляя REST API с Server-Sent Events (SSE) для взаимодействия по MCP.

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

При работе в режиме HTTP сервер предоставляет:

• Проверка работоспособности: GET /health - Возвращает статус сервера
• Конечная точка MCP: POST /mcp - Конечная точка взаимодействия MCP, использующая JSON-RPC 2.0

Тестирование режима HTTP

Вы можете протестировать режим HTTP с помощью curl или 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
      }
    }
  }'

Или используйте встроенный тестовый клиент:

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' для пути

Конфигурация API Wiki.JS

Этот MCP сервер использует GraphQL API Wiki.JS (конечная точка /graphql). Убедитесь, что в вашем экземпляре Wiki.JS включен доступ к API и что ваш API-ключ имеет следующие разрешения:

• page:read - Для чтения содержимого страниц
• page:list - Для получения списка страниц
• search:read - Для поиска страниц

Сервер автоматически обрабатывает запросы и ответы GraphQL для всех операций. Обратите внимание, что GraphQL API Wiki.JS имеет некоторые ограничения:

• Операции поиска и получения списка не поддерживают встроенную пагинацию, поэтому пагинация эмулируется на стороне клиента
• Результаты поиска не включают полное содержимое страниц
• Результаты списка не включают полное содержимое страниц (используйте get_wiki_page для получения полного содержимого)
• Теги возвращаются в виде массивов строк, а не строк, разделенных запятыми

Логирование

Сервер включает комплексное логирование с настраиваемыми уровнями детализации:

• debug - Подробная отладочная информация
• info - Общая информация (по умолчанию)
• warn - Только предупреждения
• error - Только сообщения об ошибках

Установите переменную окружения LOG_LEVEL для управления детализацией логирования.

Обработка ошибок

Сервер включает комплексную обработку ошибок для:

• Отсутствующих переменных окружения
• Проблем с сетевым подключением
• Ошибок аутентификации API
• Неверных ID страниц
• Ограничения частоты запросов

Разработка

Для запуска в режиме разработки с горячей перезагрузкой:

npm run watch

Сборка

Для сборки production-версии:

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.