# lovec-mcp

Локальный MCP-сервер поверх детектора промпт-инъекций [lovec.tech](https://lovec.tech).
Даёт агентам (Claude Desktop, Claude Code, любой MCP-клиент) тул `check_prompt_injection` —
проверка недоверенного текста (веб-страница, документ, результат тула, письмо) перед тем,
как отдать его в другую LLM.

Работает **только с вашим собственным ключом** — сервер сам ничего не хранит и не логирует,
но проверяемый текст уходит в API [lovec.tech](https://lovec.tech) для анализа. Это тонкий
клиент поверх уже существующего API-ключа/баланса с сайта.

## Установка

Из PyPI:

```bash
pip install lovec-mcp
# или без установки, через uv:
uvx lovec-mcp
```

Из исходников:

```bash
cd lovec-mcp
python3 -m venv .venv
./.venv/bin/pip install -e .
```

Ключ выпускается на [lovec.tech](https://lovec.tech)

## Быстрая проверка руками

```bash
export LOVEC_KEY=aig_...
./.venv/bin/python server.py
```

```bash
export LOVEC_KEY=aig_...
./.venv/bin/python -c "
import asyncio, server
print(asyncio.run(server.check_prompt_injection('тестовый текст')))
"
```

## Подключение к MCP-клиенту

Claude Desktop (`claude_desktop_config.json`) или Claude Code (`.mcp.json`) — один и тот же формат:

```json
{
  "mcpServers": {
    "lovec": {
      "command": "uvx",
      "args": ["lovec-mcp"],
      "env": { "LOVEC_KEY": "aig_..." }
    }
  }
}
```

Если ставили из исходников — вместо `uvx` укажите интерпретатор venv и путь к `server.py`:

```json
{
  "mcpServers": {
    "lovec": {
      "command": "/absolute/path/to/lovec-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/lovec-mcp/server.py"],
      "env": { "LOVEC_KEY": "aig_..." }
    }
  }
}
```

## Скан корпуса и отчёт

Тул проверяет одну строку за вызов. Для целого корпуса (RAG, база документов) так не выйдет:
каждый вердикт садится в контекст агента, а API отвечает от секунд до минут. Поэтому цикл
вынесен в CLI `lovec-scan`, а агент читает готовую сводку.

```bash
export LOVEC_KEY=aig_...
lovec-scan ./docs --dry-run          # сколько будет запросов (= списаний), ничего не отправляет
lovec-scan ./docs --out lovec-scan-out
```

Разбивает длинные документы на чанки ≤5000 символов, ходит в API конкурентно, пишет
`results.jsonl` построчно — прогон **резюмируемый**, повторный запуск дочитывает остаток.
Упавшие чанки считаются пробелом в покрытии, а не чистым результатом; на `402` (кончился
баланс) скан останавливается и помечает сводку как неполную.

На выходе `summary.json`: покрытие, доля флагов с 95% ДИ Уилсона по документам (не по чанкам —
чанки одного документа не независимы), гистограмма баллов, топ флагов с цитатами.

Дальше в MCP-клиенте вызываете prompt **`injection_scan_report`** — он подставляет сводку и
правила отчёта: не называть корпус чистым (ноль флагов — это верхняя граница, а не справка о
здоровье), не считать precision/recall на неразмеченном корпусе, показывать пробелы покрытия,
подавать флаги как очередь на разбор. Цитаты из корпуса помечены как недоверенные данные.

| Флаг | Зачем |
|---|---|
| `--jsonl FILE` | читать документы из JSONL `{id, text}` вместо файлов |
| `--ext` | какие расширения читать (по умолчанию `.txt,.md,.markdown,.rst`) |
| `--workers` | конкурентность, по умолчанию 4 |
| `--threshold F` | флажить по `score >= F` вместо вендорского `is_injection` |
| `--limit N` | взять не больше N документов |

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

| Переменная | По умолчанию | Зачем |
|---|---|---|
| `LOVEC_KEY` | — (обязательна) | ключ с lovec.tech |
| `LOVEC_BASE` | `https://lovec.tech` | другой хост API |
| `LOVEC_TIMEOUT` | `60` | потолок ожидания одного вызова, секунды |


<!-- mcp-name: io.github.lovec-tech/lovec-mcp -->