Metadata-Version: 2.4
Name: evawiki-mcp
Version: 0.1.7
Summary: EvaWiki RAG MCP server
Requires-Python: ==3.13.*
Requires-Dist: evawiki-python-client==0.1.9
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_ask_query` |
| `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_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](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
