auto-assessor-mcp

MCP-сервер для автоматической оценки: принимает материалы компании, расшивает их на части, читаемые моделью, и раздаёт исполнителям-субагентам задания по описанию содержимого.

Сервер работает по HTTP на локальном адресе и обслуживает нескольких агентов одновременно. Экземпляр всегда один на Хранилище.

Сервер осмыслен только вместе с развёрнутым дистрибутивом АРМ: в нём лежат справочники и данные компаний.

Термины и расположение файлов

<Базовый каталог>/
    .auto_assessor.env     Файл настроек  (создаётся при первом запуске)
    .auto_assessor/        Хранилище      (наше: пишет только сервер)
    assessments/           АРМ            (чужое: сервер только читает)

Установка

pip install auto-assessor-mcp

Запуск и остановка

Запустите сервер в фоне в начале работы. Команда безопасна: если сервер уже запущен, она напечатает «уже запущен» и его адрес и завершится с кодом 0.

auto-assessor-mcp serve

Адрес по умолчанию — http://127.0.0.1:17000/mcp (добавьте его один раз в конфигурацию MCP-клиента; он остаётся верным после перезапусков). Сервер работает, пока его не остановят:

auto-assessor-mcp stop

Обновление пакета: stop, затем обычный serve. Лог сервера — logs/server.log в Хранилище (не путать с Журналом заданий, journal/, — см. ниже). Без аргументов auto-assessor-mcp и python -m auto_assessor_mcp запускают serve.

Настройки

Значение настройки берётся из первого доступного источника: параметр команды (serve --log-level), переменная окружения процесса, Файл настроек, умолчание. Пустое значение считается незаданным. Ключи Файла настроек называются так же, как переменные окружения.

Доступ к репозиториям git. sync вызывает системный git с окружением и настройками git того пользователя, под которым запущен Сервер: подхватываются ключи SSH (в том числе ssh-agent), помощники учётных данных git и ~/.netrc. Ввод пароля не ждётся (GIT_TERMINAL_PROMPT=0, BatchMode=yes): если вход требует его, этап sync завершится ошибкой. Проверка: git ls-remote <адрес> без запроса пароля в терминале того же пользователя. При запуске службой или из cron ssh-agent и помощники учётных данных могут быть недоступны.

Файл настроек

• Лежит только в Базовом каталоге ($WORK, иначе домашний); запасного поиска в другом месте нет.
• Создаётся при первом запуске serve со всеми ключами, умолчаниями и пояснениями. Существующий файл сервер не перезаписывает и не дополняет. Если создать файл не удалось, сервер работает с умолчаниями и пишет предупреждение в журнал.
• Формат: КЛЮЧ=ЗНАЧЕНИЕ, по строке на настройку. Строки с # и пустые пропускаются, значение можно взять в кавычки, в значении без кавычек # после пробела начинает комментарий, обратная косая черта — обычный знак (пути Windows пишутся как есть). Если ключ повторён, действует последняя строка.
• Пути: ~ раскрывается; относительный путь из файла отсчитывается от каталога файла (поэтому AUTO_ASSESSOR_STORAGE_DIR=.auto_assessor означает Хранилище рядом с файлом).
• Правка действует после перезапуска (stop, затем serve), кроме AUTO_ASSESSOR_ARM_DIR и AUTO_ASSESSOR_LIBRARY_DIR: оба перечитываются при каждом обращении к АРМ и Библиотеке. Менять AUTO_ASSESSOR_STORAGE_DIR следует при остановленном сервере.
• AUTO_ASSESSOR_LIBRARY_DIR в создаваемом файле — закомментированная строка: умолчание зависит от текущего пути к АРМ, а не от Базового каталога, поэтому мнимый путь в файл не пишется.
• Ошибка в файле (нет знака =, неизвестный ключ AUTO_ASSESSOR_*, значение вне границ) — ошибка запуска с указанием файла и строки. Команда stop при этом работает: она проверяет только синтаксис файла и ключ AUTO_ASSESSOR_STORAGE_DIR.
• Секретов в файле нет: секрет остановки лежит в admin.token Хранилища.

Хранилище содержит server.lock, server.json, admin.token, logs/, materials/, tasks/ (записи заданий), journal/ (Журнал заданий — вход, попытки, принятый результат каждого задания; независим от logs/server.log), blobs/ (архив шаблонов и справочников по содержимому). АРМ сервер не создаёт и не меняет. Сервер слушает только 127.0.0.1 и отклоняет запросы с чужими Host (421) и Origin (403).

Как это работает

Два вида клиентов, роли разведены описаниями инструментов:

• Ведущий (основной агент): accept_materials (принять файл либо каталог по абсолютному пути; сервер сам копирует файлы), list_materials (реестр описаний), list_tasks (задания; wait_seconds — подождать расшивку).
• Исполнитель (субагент): только get_task (получить текст задания с абсолютными путями файлов) и submit_task_result (сдать результат).

Расшивка идёт в фоне; документ на сто страниц описывается десятью небольшими заданиями и одним итоговым.

Оценка в АРМ

Три инструмента Ведущего принимают assessment_ref и требуют, чтобы Оценка была объявлена в Данных оценок АРМ (блок sber.dka-dzo.assessment в любом файле *.yaml каталога data/; имя файла и imports не важны). Без развёрнутого АРМ они отказывают ошибкой «АРМ не найден» с названием ключа AUTO_ASSESSOR_ARM_DIR.

Статус Оценки читается при каждом вызове: правка файла в АРМ действует без перезапуска сервера. Любой другой статус (preparation_start, in_progress, незнакомый) и отсутствие поля status приём не останавливают. Если одна Оценка объявлена в нескольких файлах с разными статусами, приём отказывает, а чтение работает. Закрытие Оценки после приёма ничего не меняет в принятых материалах и уже выданных заданиях: исполнители (get_task, submit_task_result) от АРМ не зависят. Тексты отказов не содержат путей; пути файлов АРМ записаны в logs/server.log.

Форматы

Старые форматы не принимаются и не конвертируются: .doc, .rtf, .odt — сохраните как .docx; .xls, .ods — как .xlsx; презентации (.ppt, .pptx, .odp) — сохраните в PDF.

Ограничение Word: текст внутри надписей и фигур обычно попадает в текст документа, но сам рисунок (связи, стрелки), диаграммы, SmartArt, встроенные объекты (OLE) и векторные изображения (EMF/WMF) не передаются. Сервер это замечает и пишет пояснение в материал и в текст задания; для передачи такого содержимого сохраните документ в PDF и приложите его. Документы с патологической вложенностью (сотни таблиц в таблицах) отклоняются с советом сохранить их в PDF.

Разработка

git clone https://gitverse.ru/alex314/auto_assessor_mcp
cd auto_assessor_mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest -q --no-cov --ignore=tests/test_process_lifecycle.py   # быстрые тесты (~30 с)
pytest -v                                                     # весь набор (~6 мин)
ruff check .
ruff format --check .
mypy src/

Все изменения проекта вносятся через OpenSpec change proposals (см. CLAUDE.md), кроме тривиальных правок вроде .gitignore.

Важный инвариант устройства: изменения состояния — синхронные функции в цикле событий, без await между чтением и записью (см. storage/doc_store.py); именно он делает параллельные обращения безопасными без блокировок.

Релиз

Публикация в PyPI выполняется автоматически по тегу vX.Y.Z на ветке master (см. .gitverse/workflows/publish.yml).

Лицензия

Proprietary — все права защищены, см. LICENSE.