suspec-mcp

Un adaptador MCP stdio ligero para acceso sin shell al verificador determinista de Suspec. Ligero es la característica. Requiere el contrato de comprobaciones 0.26.0, valida cada carga útil JSON de CLI y conserva los informes ordenados y el estado de salida.

Herramientas

suspec_check

Ejecuta un proceso CLI sobre un array ordenado no vacío de rutas absolutas de artefactos. El frontmatter type: selecciona el comportamiento.

Las entradas de especificación, tarea, plan de cambio y campaña reciben sus comprobaciones CLI. Inventario, auditoría, investigación y panel devuelven checked: false. Los tipos faltantes y desconocidos se rechazan.

Una invocación conserva comprobaciones entre archivos como C002. Las rutas de tareas comparten un único specPath; cada tarea debe nombrar esa especificación. Un emparejamiento de acompañante no válido produce el rechazo estructurado del CLI con ok: false.

Cada resultado de artefacto repite su tipo. Solo el informe final opcional (file set) no tiene ninguno.

suspec_get_checks

Devuelve la versión del contrato más el ID y la severidad de cada comprobación principal en modo conciso. Usa responseFormat: "detailed" para los nombres. El mismo contrato está disponible en suspec://checks.

El arranque y las lecturas de recursos requieren el contrato exacto 0.26.0 con salida 0. Un fallo de recurso lanza una excepción en lugar de devolver un documento de error como contenido de recurso.

Related MCP server: governed-mcp

Envoltorio

Cada invocación exitosa del adaptador devuelve:

• ok: si el CLI se ejecutó y produjo una carga útil válida, no si los diagnósticos están limpios;

• source: el comando exacto y el código de salida;

• data: salida detallada validada o proyección concisa;

• note opcional;

• responseFormat.

ok significa que el adaptador funcionó, no que el artefacto es bueno. Una comprobación con diagnósticos bloqueantes sigue siendo ok: true; inspecciona data.level, los diagnósticos y source.exitCode.

Las salidas del CLI 0, 1 y 2 pertenecen al contrato. Cualquier otra salida es un fallo de lanzamiento del adaptador. El stdout con forma JSON no negocia un nuevo contrato. Los errores CLI estructurados se aceptan solo con salida 2.

Instalación

Requiere Node.js 22.6 o superior y un CLI de suspec. Ninguno de los paquetes está publicado.

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

Configura puntos de entrada absolutos para que los clientes GUI no dependan del PATH del shell:

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

Precedencia del CLI:

Cada llamada de herramienta proporciona rutas completas de artefactos. El servidor no vincula ningún repositorio, espacio de trabajo, configuración ni almacén. Es un adaptador, no un segundo cerebro de producto. ~/.agents/artifacts/<workspace>/ no tiene ningún significado especial en tiempo de ejecución. La instalación de políticas a nivel de usuario es tarea del CLI: ejecuta suspec setup directamente. MCP no expone ninguna superficie de instalación, almacenamiento, promoción, ciclo de vida ni orquestación.

Seguridad

• Las rutas primarias y de acompañamiento deben ser absolutas y no contener caracteres de control, formato ni separadores de línea.

• El adaptador pasa un array de argumentos fijo sin shell.

• Solo check y los flags de acompañamiento o contrato compatibles llegan al CLI. setup se rechaza antes de que se inicie un subproceso.

• La superficie de comprobación del CLI es de solo lectura.

El servidor puede leer cualquier ruta disponible para su proceso. El permiso del sistema de archivos es el límite de seguridad, no una sugerencia. Iguala los permisos del proceso al límite de confianza del cliente o aplica sandboxing del SO.

Desarrollo

La deriva de fixtures usa el CLI real. El acuerdo escrito a mano no prueba nada. Establece SUSPEC_BIN a una ruta absoluta de origen del CLI; de lo contrario, un paquete hermano llamado suspec-cli puede satisfacer la detección. La generación rechaza otros paquetes.

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

test/fixtures/provenance.json registra el HEAD de git del CLI, el hash completo del árbol de trabajo sucio y el hash binario. scripts/generate-fixtures.mjs captura la salida; los tests analizan cada fixture a través de src/suspec/contract.ts. Los fixtures se generan, nunca se editan a mano.

Licencia

MIT