evawiki-mcp 0.1.7

EvaWiki RAG MCP server

evawiki-mcp

MCP-сервер для работы с базой знаний EvaWiki. Предоставляет инструменты для поиска, просмотра, создания и редактирования документов, управления вложениями и семантического поиска по базе знаний. Включает ресурсы с правилами форматирования и промпты для создания и редактирования документов с соблюдением стандартов EvaWiki.

Установка

pip install evawiki-mcp

или через uvx (без предварительной установки):

uvx evawiki-mcp@latest

Быстрый старт

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

Переменная	Обязательная	По умолчанию	Описание
EVAWIKI_ENDPOINT	Да	—	Базовый URL инстанса EvaWiki
EVAWIKI_TOKEN	Да	—	API-токен для аутентификации
EVAWIKI_RAG_URL	Нет	""	URL RAG API. При указании активирует инструмент evawiki_ask_query
EVAWIKI_CONTENT_FORMAT	Нет	yaml	Формат ответов: yaml или json

Запуск в режиме stdio

stdio — транспорт по умолчанию для MCP-клиентов (Claude Desktop, Cursor, VS Code и др.). Два варианта запуска:

Через CLI:

export EVAWIKI_ENDPOINT="https://evawiki.example.com"
export EVAWIKI_TOKEN="your-api-token"

evawiki-mcp

Через uvx (без установки):

EVAWIKI_ENDPOINT="https://evawiki.example.com" \
EVAWIKI_TOKEN="your-api-token" \
uvx evawiki-mcp@latest

Конфигурация для MCP-клиента

Добавьте в .mcp.json (или claude_desktop_config.json):

{
  "mcpServers": {
    "evawiki": {
      "command": "uvx",
      "args": ["evawiki-mcp@latest"],
      "env": {
        "EVAWIKI_ENDPOINT": "https://evawiki.example.com",
        "EVAWIKI_TOKEN": "your-api-token"
      }
    }
  }
}

Запуск в режиме HTTP

HTTP-режим подходит для развёртывания как сервис и подключения нескольких клиентов.

Через CLI:

export EVAWIKI_ENDPOINT="https://evawiki.example.com"
export EVAWIKI_TOKEN="your-api-token"

evawiki-mcp-http

Через uvicorn напрямую:

uvicorn rag_mcp.asgi_app:app --host 0.0.0.0

Сервер запустится на http://0.0.0.0:8000 (порт по умолчанию для uvicorn), MCP-эндпоинт — /mcp, health check — /health.

Конфигурация для MCP-клиента (HTTP)

{
  "mcpServers": {
    "evawiki": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "evawiki-endpoint": "https://evawiki.example.com",
        "evawiki-token": "your-api-token"
      }
    }
  }
}

В HTTP-режиме credentials можно передавать через заголовки evawiki-endpoint и evawiki-token на каждый запрос — это позволяет обслуживать несколько EvaWiki-инстансов с одного сервера.

Инструменты (MCP Tools)

Вложения (Attachments)

Инструмент	Описание	Доступность
evawiki_attachment_list	Получает список вложений документа (только метаданные, без содержимого)	все режимы
evawiki_attachment_upload_from_url	Создаёт вложение в EvaWiki по HTTP(S)-ссылке	все режимы
evawiki_attachment_upload_from_file	Создаёт вложение в EvaWiki из локального файла	только stdio
evawiki_attachment_download	Скачивает вложение из EvaWiki на локальный диск	только stdio

Документы (Documents)

Инструмент	Описание	Доступность
evawiki_document_get	Получает метаданные документа по коду	все режимы
evawiki_document_text_get	Получает текстовое содержимое документа (опубликованная версия или черновик)	все режимы
evawiki_document_search	Ищет документы по подстроке в названии	все режимы
evawiki_document_draft_create	Создаёт новый документ в статусе черновика	все режимы
evawiki_document_draft_update	Обновляет документ и сохраняет как черновик	все режимы
evawiki_document_publish	Публикует черновик документа	все режимы

Проекты (Projects)

Инструмент	Описание	Доступность
evawiki_project_list	Получает список всех доступных проектов	все режимы
evawiki_project_documents_tree	Получает иерархию разделов и документов проекта	все режимы

Навигация и поиск

Инструмент	Описание	Доступность
evawiki_overview_get	Получает двухуровневый обзор базы знаний (проекты -> документы верхнего уровня)	все режимы
evawiki_ask_query	Семантический поиск по базе знаний с генерацией ответа (требует EVAWIKI_RAG_URL)	все режимы*

* Инструмент evawiki_ask_query регистрируется только при заданной переменной EVAWIKI_RAG_URL.

Ресурсы (MCP Resources)

Сервер предоставляет набор ресурсов с правилами форматирования и рекомендациями по работе с документами EvaWiki. AI-клиент может прочитать эти ресурсы для получения инструкций по оформлению контента.

Ресурс	Описание
resource://evawiki/role-and-scope	Роль и область ответственности ассистента при работе с EvaWiki
resource://evawiki/html-formatting-rules	Правила HTML-форматирования: заголовки с уникальными data-id, допустимые теги (<p>, <strong>, <code>, <ol>, <table> и др.), запрет на Markdown и эмодзи
resource://evawiki/code-block-rules	Правила оформления блоков кода: формат <pre class="language-xxx"><code class="language-xxx">, список поддерживаемых языков (Java, JSON, YAML, Bash, SQL, XML, Python, TypeScript, Groovy)
resource://evawiki/code-block-examples	Примеры оформленных блоков кода для Java, JSON, Bash и YAML
resource://evawiki/update-safety-rules	Правила безопасного обновления документов: сохранение неизменяемых секций, уникальность data-id, защита структуры
resource://evawiki/draft-publish-workflow	Рекомендуемый workflow из 6 шагов: поиск документа → чтение → подготовка HTML → сохранение черновика → ссылка на черновик → публикация после подтверждения

Промпты (MCP Prompts)

Промпты позволяют AI-клиенту получить структурированную инструкцию для создания или редактирования документов EvaWiki с соблюдением всех правил форматирования. Каждый промпт автоматически подключает нужные ресурсы (правила HTML, блоков кода, безопасного обновления).

Промпт	Описание	Параметры
evawiki_format_html	Конвертирует произвольный текст в HTML-фрагмент для EvaWiki с правильными заголовками и блоками кода	text (обязательный), title (опциональный)
evawiki_create_article	Создаёт новую статью с нуля из исходного текста: структура, уникальные data-id, форматирование кода	document_code, title, topic, source_text (все обязательные)
evawiki_update_article	Обновляет существующий документ, сохраняя неизменяемые части	document_code, change_request, new_content (все обязательные)
evawiki_add_section	Добавляет новый раздел в существующий документ без переработки всего текста	document_code, section_title, section_html_or_text (все обязательные)

Различия между stdio и HTTP

Возможность	stdio	HTTP
Все инструменты для чтения	+	+
Создание и редактирование документов	+	+
Загрузка вложений из локального файла	+	—
Скачивание вложений на локальный диск	+	—
Аутентификация через заголовки запроса	—	+
Многопользовательский доступ	—	+
Запуск через uvx	+	—

Инструменты evawiki_attachment_upload_from_file и evawiki_attachment_download работают с локальной файловой системой, поэтому доступны только в stdio-режиме.

Стек технологий

• FastMCP — фреймворк для MCP-серверов
• evawiki-python-client — клиент API EvaWiki
• Pydantic — валидация данных и модели ответов
• httpx — HTTP-клиент
• uvicorn — ASGI-сервер

Лицензия

MIT