suspec-mcp

Тонкий MCP stdio-адаптер для доступа без оболочки к детерминированному проверщику Suspec. Тонкость — это фича. Он требует контракт проверок 0.26.0, проверяет каждый JSON-payload CLI и сохраняет упорядоченные отчёты и код выхода.

Инструменты

suspec_check

Запускает один процесс CLI над упорядоченным непустым массивом абсолютных путей артефактов. Frontmatter type: определяет поведение.

Входные данные спецификаций, задач, планов изменений и кампаний получают свои проверки CLI. Инвентаризация, аудит, исследования и панель возвращают checked: false. Отсутствующие и неизвестные типы отклоняются.

Один вызов сохраняет межфайловые проверки, такие как C002. Пути задач используют общий specPath; каждая задача должна указывать эту спецификацию. Неверная связка связанных файлов приводит к структурированному отказу CLI с ok: false.

Каждый результат артефакта повторяет свой тип. Только опциональный финальный отчёт (file set) не содержит типа.

suspec_get_checks

Возвращает версию контракта, а также идентификатор и серьёзность каждой основной проверки в кратком режиме. Используйте responseFormat: "detailed" для имён. Тот же контракт доступен по адресу suspec://checks.

Запуск и чтение ресурсов требуют точного контракта 0.26.0 при коде выхода 0. Сбой ресурса вызывает исключение, а не возвращает документ об ошибке в качестве содержимого ресурса.

Related MCP server: governed-mcp

Конверт

Каждый успешный вызов адаптера возвращает:

• ok: работал ли CLI и выдал ли допустимый payload, а не чисты ли диагностические данные;

• source: точную команду и код выхода;

• data: проверенный подробный вывод или краткую проекцию;

• опциональный note;

• responseFormat.

ok означает, что адаптер сработал, а не что артефакт хорош. Проверка с блокирующими диагностиками остаётся ok: true; изучайте data.level, диагностики и source.exitCode.

Коды выхода CLI 0, 1 и 2 относятся к контракту. Любой другой код выхода — это сбой запуска адаптера. stdout в форме JSON не согласует новый контракт. Структурированные ошибки CLI принимаются только при коде выхода 2.

Установка

Требуется Node.js 22.6 или новее и suspec CLI. Ни один из пакетов не опубликован.

git clone https://github.com/jcosta33/suspec-mcp
cd suspec-mcp
corepack enable
pnpm install --frozen-lockfile

Настройте абсолютные точки входа, чтобы GUI-клиенты не зависели от PATH оболочки:

{
  "mcpServers": {
    "suspec": {
      "command": "/absolute/path/to/suspec-mcp/bin/suspec-mcp.js",
      "args": ["--suspec-bin", "/absolute/path/to/suspec-cli/bin/suspec.js"]
    }
  }
}

Приоритет CLI:

Каждый вызов инструмента передаёт полные пути артефактов. Сервер не привязывается к репозиторию, рабочей области, конфигурации или хранилищу. Это адаптер, а не второй мозг продукта. ~/.agents/artifacts/<workspace>/ не имеет особого значения в рантайме. Установка политик на уровне пользователя — задача CLI: запускайте suspec setup напрямую. MCP не предоставляет интерфейс настройки, хранения, продвижения, жизненного цикла или оркестрации.

Безопасность

• Основные и сопутствующие пути должны быть абсолютными и не содержать управляющих символов, символов форматирования или разделителей строк.

• Адаптер передаёт фиксированный массив аргументов без оболочки.

• До CLI доходят только check и поддерживаемые флаги связанных операций или контракта. setup отклоняется до запуска подпроцесса.

• Поверхность проверок CLI доступна только для чтения.

Сервер может читать любой путь, доступный его процессу. Права файловой системы — это граница безопасности, а не рекомендация. Согласуйте права процесса с границей доверия клиента или применяйте песочницу ОС.

Разработка

Расхождение фикстур устраняется использованием реального CLI. Согласование вручную ничего не доказывает. Установите SUSPEC_BIN на абсолютный путь к исходникам CLI; в противном случае обнаружение может удовлетворить соседний пакет с именем suspec-cli. Генерация отвергает другие пакеты.

export SUSPEC_BIN=/absolute/path/to/suspec-cli/bin/suspec.js
pnpm install
pnpm test:run
pnpm gate
pnpm fixtures

test/fixtures/provenance.json записывает git HEAD CLI, полный хэш грязного рабочего дерева и хэш бинарного файла. scripts/generate-fixtures.mjs захватывает вывод; тесты разбирают каждую фикстуру через src/suspec/contract.ts. Фикстуры генерируются и никогда не редактируются вручную.

Лицензия

MIT