Metadata-Version: 2.4
Name: evawiki-mcp
Version: 0.1.8
Summary: EvaWiki RAG MCP server
Requires-Python: ==3.13.*
Requires-Dist: evawiki-python-client==0.1.10
Requires-Dist: fastmcp==3.3.1
Requires-Dist: httpx>=0.27.0
Requires-Dist: markdownify>=1.2.2
Requires-Dist: pyarrow==24.0.0
Requires-Dist: tenacity
Requires-Dist: uvicorn>=0.42.0
Description-Content-Type: text/markdown

# evawiki-mcp

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

[![PyPI version](https://img.shields.io/pypi/v/evawiki-mcp)](https://pypi.org/project/evawiki-mcp/)
[![Python 3.13](https://img.shields.io/badge/python-3.13-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Установка

```bash
pip install evawiki-mcp
```

или через [uvx](https://docs.astral.sh/uv/guides/tools/) (без предварительной установки):

```bash
uvx evawiki-mcp@latest
```

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

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

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

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

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

**Через CLI:**

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

evawiki-mcp
```

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

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

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

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

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

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

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

**Через CLI:**

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

evawiki-mcp-http
```

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

```bash
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)

```json
{
  "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_create_from_url`  | Создаёт вложение в EvaWiki по HTTP(S)-ссылке                            |  все режимы  |
| `evawiki_attachment_create_from_file` | Создаёт вложение в EvaWiki из локального файла                          | только stdio |
| `evawiki_attachment_download`         | Скачивает вложение из EvaWiki на локальный диск                         | только stdio |

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

| Инструмент                      | Описание                                                                     | Доступность |
|---------------------------------|------------------------------------------------------------------------------|:-----------:|
| `evawiki_document_get`          | Получает метаданные документа по коду                                        | все режимы  |
| `evawiki_document_get_text`     | Получает текстовое содержимое документа (опубликованная версия или черновик) | все режимы  |
| `evawiki_document_search`       | Ищет документы по подстроке в названии                                       | все режимы  |
| `evawiki_document_create_draft` | Создаёт новый документ в статусе черновика                                   | все режимы  |
| `evawiki_document_update_draft` | Обновляет документ и сохраняет как черновик                                  | все режимы  |
| `evawiki_document_publish`      | Публикует черновик документа                                                 | все режимы  |

### Проекты (Projects)

| Инструмент                           | Описание                                        | Доступность |
|--------------------------------------|-------------------------------------------------|:-----------:|
| `evawiki_project_list`               | Получает список всех доступных проектов EvaWiki  | все режимы  |
| `evawiki_project_get_documents_tree` | Получает иерархию разделов и документов проекта | все режимы  |

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

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

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

### Гайды и рекомендации

| Инструмент                | Описание                                                                                     | Доступность |
|---------------------------|----------------------------------------------------------------------------------------------|:-----------:|
| `evawiki_guides_recommend` | Рекомендует подходящие стандарты EvaWiki, предупреждения и промпт для задачи пользователя | все режимы  |

### Диаграммы (PlantUML)

| Инструмент                  | Описание                                                            | Доступность |
|-----------------------------|---------------------------------------------------------------------|:-----------:|
| `evawiki_plantuml_render_svg` | Рендерит PlantUML-диаграмму в формат SVG для вставки в документы EvaWiki | все режимы  |

## Ресурсы (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 → сохранение черновика → ссылка на черновик → публикация после подтверждения                                  |
| `resource://evawiki/uml-diagram-guide`    | Стандарт создания PlantUML-диаграмм для EvaWiki: шаблон HTML-блока, pipeline рендера (`evawiki_plantuml_render_svg`), правила подстановки UML и SVG, требования к inline-SVG |

## Промпты (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_create_from_file` и `evawiki_attachment_download` работают с локальной файловой
системой, поэтому доступны только в stdio-режиме.

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

- [FastMCP](https://github.com/jlowin/fastmcp) — фреймворк для MCP-серверов
- [evawiki-python-client](https://pypi.org/project/evawiki-python-client/) — клиент API EvaWiki
- [Pydantic](https://docs.pydantic.dev/) — валидация данных и модели ответов
- [httpx](https://www.python-httpx.org/) — HTTP-клиент
- [uvicorn](https://www.uvicorn.org/) — ASGI-сервер

## Лицензия

MIT
