Vellum

MCP-сервер, который проверяет сгенерированные документы (.docx, .pdf) до того, как они попадут к пользователю, — извлекая точные, измеримые факты о структуре, типографике, интервалах и языковой корректности, чтобы ИИ-ассистент мог ловить собственные ошибки форматирования, а не отправлять их.

Создан в соответствии со спецификацией MCP от 2026-07-28. Полное обоснование архитектуры см. в docs/architecture.md.

Зачем

Навыки генерации документов создают вывод в форматах .docx/.pptx/.pdf, но ничто автоматически не проверяет, что результат корректен: уровни заголовков могут быть пропущены, шрифты могут быть несогласованными, интервалы могут «плыть», грамматические ошибки проходят незамеченными. Vellum — это слой верификации, а не генератор.

Related MCP server: mcp-server-docx

Основной принцип

Сервер извлекает факты. Модель выносит суждения.

Vellum никогда не говорит «это неправильно». Он говорит: «вот что действительно верно, а вот что статистически аномально по сравнению с остальным документом». Решение о том, является ли конкретное значение уместным для роли строки в документе (заголовок, подпись или основной текст), — это семантическое суждение, которое остаётся за вызывающей моделью, имеющей полный контекст документа; сервер этого контекста не имеет и не должен пытаться его получить.

Инструменты

Каждый инструмент возвращает структурированные факты и флаги аномалий — но никогда не вердикт.

Каждый инструмент принимает документ либо как path в файловой системе, либо как встроенный content_base64 (при этом обязательно указывать filename) — это удобно, когда документ существует только в рамках разговора (например, загружен напрямую в чат-интерфейс), а не сохранён на диск. Должна быть указана ровно одна из двух форм ввода.

Статус

Все шесть инструментов (check_docx_structure, check_docx_typography, check_pdf_layout, check_language, check_filename_consistency, full_report) полностью реализованы, покрыты модульными тестами и проверены на эталонном наборе фикстур с известными намеренно внесёнными дефектами. Полная поверхность MCP — ресурсы, промпты, элиситация, подсказки кэширования, аутентификация ресурсного сервера OAuth 2.1 для HTTP-транспорта и корректная семантика ошибок — реализована и протестирована (163+ тестов проходят). Подробную историю разработки и текущие открытые вопросы см. в docs/architecture.md и PROGRESS.md. Упаковка и публикация (этап 7) в процессе — на PyPI ещё не выпущено.

Установка

git clone https://github.com/Nasser9892/vellum-mcp.git
cd vellum-mcp
pip install -e ".[dev]"

Требуется локальный экземпляр LanguageTool для check_language — настройку см. в docs/architecture.md.

Использование (Claude Desktop / любой MCP stdio-клиент)

Добавьте в конфигурацию вашего MCP-клиента (см. examples/claude_desktop_config.json):

{
  "mcpServers": {
    "vellum": {
      "command": "vellum-mcp"
    }
  }
}

Разработка

pip install -e ".[dev]"
pytest                          # unit + integration tests
mcp dev src/vellum_mcp/server.py  # run under MCP Inspector

Фикстуры эталонного набора (примеры файлов .docx/.pdf с намеренно внесёнными дефектами) находятся в golden_set/. Все проверки проходят валидацию на них, прежде чем им можно доверять, — см. docs/architecture.md о методике.

Проверено с помощью MCP Inspector (mcp dev src/vellum_mcp/server.py) и протестировано с двумя реальными MCP-клиентами: Claude Desktop (examples/claude_desktop_config.json) и Cursor (~/.cursor/mcp.json, та же структура {"mcpServers": {"vellum": {"command": "vellum-mcp"}}}).

Соответствие спецификации

• Все примитивы: инструменты, ресурсы, промпты (не только инструменты)

• Stateless-ядро — без зависимости от Mcp-Session-Id

• Элиситация через MRTR (InputRequiredResult / inputRequests / inputResponses)

• Позиция ресурсного сервера OAuth 2.1 для HTTP-транспорта (RFC 9728, RFC 8707, RFC 9207; CIMD вместо устаревшего DCR)

• Расширение задач (io.modelcontextprotocol/tasks) для длительного анализа

• Корректные коды ошибок (-32602 для «не найдено», -32020 для нарушений, связанных с заголовками)

• Отсутствие использования устаревших примитивов roots/sampling/logging

Лицензия

MIT — см. LICENSE.