protect-mcp

Puerta de política Cedar de fallo cerrado más recibos firmados para llamadas a herramientas de agentes de IA.

protect-mcp es una puerta que se sitúa delante de las llamadas a herramientas de un agente de IA. Evalúa cada llamada contra una política Cedar, bloquea lo que infringe las reglas antes de que se ejecute, y firma un recibo Ed25519 verificable sin conexión de cada decisión. La puerta de enlace configurada se ejecuta localmente y no envía telemetría de decisiones. El adaptador de coordinación independiente se conecta al servicio de colaboración alojado de ScopeBlind; sus solicitudes y registros devueltos tienen la ruta de datos descrita a continuación. Ambos tienen licencia MIT.

Para el trabajo en repositorios compartidos, utilice proyectos de cliente: las personas acuerdan el encargo y los límites, los agentes preparan las revisiones, y ambas personas aprueban una versión exacta antes de que el receptor del propietario pueda modificar el repositorio. El flujo de trabajo del repositorio a continuación incluye la configuración y las cinco herramientas de agente acotadas.

Por qué es diferente

• Fallo cerrado por defecto. Ante cualquier error de política, un motor ausente, o un fallo de evaluación, la decisión es DENY. La puerta nunca permite silenciosamente. Existe un modo de observación para el despliegue en sombra, pero incluso ahí una llamada que sería bloqueada se marca como would_deny: true, de modo que un fallo nunca es silencioso.
• Demuestra su propia contención. serve --enforce y doctor ejecutan una autoprueba de inicio y se niegan a armar la puerta a menos que puedan demostrar que una acción conocida como prohibida es realmente denegada. Una puerta que no puede demostrar que deniega no se inicia.
• Cada decisión es un recibo que cualquiera puede verificar. Las decisiones están firmadas con Ed25519 y son verificables sin conexión con @veritasacta/verify. La verificación de firma no necesita consulta de red. Las afirmaciones sobre la ejecución aún dependen del operador de la puerta identificado.

Inicio rápido: de la instalación a la primera prueba útil

# 1. Generate an Ed25519 keypair, config template, and sample policy.
npx protect-mcp init

# 2. Print a shadow-mode client configuration, then apply it in your MCP host.
#    This command prints configuration and exits; it does not launch the server.
npx protect-mcp wrap -- node your-mcp-server.js

# 3. Reopen the host and use its tools, then inspect the local-only dashboard.
npx protect-mcp dashboard --open

# 4. Draft a reviewable policy from observed calls.
npx protect-mcp recommend --write

# 5. When reviewed, restart the wrapper in enforce mode with that policy.
npx protect-mcp --policy protect-mcp.recommended.json --enforce -- node your-mcp-server.js

Para Claude Desktop, ejecuta primero un parche de configuración en modo dry-run y luego aplícalo:

npx protect-mcp wrap --claude-desktop
npx protect-mcp wrap --claude-desktop --write
npx protect-mcp dashboard --open

El panel de control se enlaza a 127.0.0.1, solo lee archivos locales de registro/recibo y no sube nada. Use npx protect-mcp connect solo si desea explícitamente un panel de control ScopeBlind alojado.

La puerta como servidor MCP

Si prefiere llamar a la puerta como herramientas en lugar de configurar los hooks de Claude Code, ejecútela como un servidor MCP:

npx protect-mcp mcp

Habla MCP sobre stdio y expone cuatro herramientas de solo lectura, todo el bucle:

• evaluate_action: decide una llamada a herramienta propuesta contra una política Cedar en línea, fail-closed (cualquier error de política es DENY). Devuelve { allowed, decision, reason, policy_digest }.
• sign_decision: convierte una decisión en un recibo firmado con Ed25519 (una denegación firma un gateway_restraint, un permiso un decision_receipt). Devuelve el recibo y su clave pública; genera una clave efímera si no proporcionas una.
• verify_receipt: verifica un recibo firmado sin conexión contra una clave pública. Devuelve { valid, error, type, kid, issuer }.
• self_test: lo demuestra, sin entradas. Una acción conocida como prohibida es denegada, luego un recibo firmado realiza un round-trip y una copia manipulada falla.

Apunta cualquier host MCP hacia él, por ejemplo Claude Desktop:

{
  "mcpServers": {
    "protect-mcp": { "command": "npx", "args": ["-y", "protect-mcp", "mcp"] }
  }
}

Los recibos son compatibles a nivel de bytes con los que el gate firma en tiempo de ejecución, por lo que un recibo generado aquí utiliza el mismo sobre de Acta. Las capacidades de verificación y la compatibilidad de canonicalización dependen de la versión del verificador; utilice la API verifyReceipt del gateway para el comportamiento de conformidad descrito a continuación.

Compatibilidad de canonicalización de recibos

Este árbol de código fuente corrige el defecto de ordenación de claves enteras presente hasta la 0.14.0: las firmas y los hashes de cadena ahora utilizan la emisión directa de miembros JCS, conservando el perfil de claves de objeto ASCII del gateway. Las claves con apariencia numérica como "10" preceden a "2", incluso dentro de objetos anidados. Los valores no JSON y el Unicode no válido se rechazan.

Los recibos JSON ordinarios cuyas codificaciones no han cambiado siguen verificándose. Los recibos históricos firmados con el antiguo orden de claves numéricas se reportan como legacy_non_jcs_signature; la verificación estricta no los considera JCS válidos. Para una comprobación explícita de compatibilidad histórica, utilice verifyReceipt(receipt, publicKey, { allowLegacyNumericKeys: true }) e inspeccione los campos canonicalization y warning. Su hash es entonces el hash histórico original. Conserve los recibos originales y los enlaces de cadena: recalcular un recibo antiguo de claves numéricas con receiptHash ahora produce su hash JCS y puede romper la cadena histórica. Estos cambios se incluyen en la 0.15.0.

Comience con su agente, luego autorice cada tarea

La versión 0.25.0 incluye un perfil de agente reutilizable. Abra Comience a través de su agente para obtener el comando de configuración con la clave de autoridad mostrada por el servicio. Verifique esa clave contra una fuente de confianza antes de conectarse. Por ejemplo:

npx --yes [email protected] coordination agent setup \
  --client claude-code \
  --profile ~/.scopeblind/agent.json \
  --endpoint https://scopeblind.com/api/coordination \
  --authority-key PINNED_64_HEX_AUTHORITY_KEY

Usa --client codex o --client json para esas instrucciones de registro. La configuración se imprime; aplícala en tu cliente y luego vuelve a abrir ese cliente. El perfil privado contiene una clave de agente y conexiones con alcance separado, con permisos de archivo 600. La configuración no otorga permisos de tareas ni copia ninguna clave de navegador humana. El servidor registrado ejecuta coordination agent --profile FILE.

Pídele a tu agente que prepare una tarea de factura compartida para tu revisión. El flujo de la herramienta es: