Ackrite
Un servidor MCP que hace que los agentes de IA demuestren sus suposiciones antes de actuar sobre ellas.
Documentación
Ackrite
ACKRITE. DEMUÉSTRALO.
Un servidor MCP que hace que los agentes de IA demuestren sus suposiciones antes de actuar sobre ellas.
Ackrite es una utilidad de verificación enfocada para agentes de IA. No intenta resolver todos los problemas, buscar respuestas convenientes ni inventar corroboración. En cambio, desafía la afirmación técnica de un agente usando solo la evidencia que se le proporciona, distingue hechos de hipótesis, identifica pruebas faltantes y recomienda la verificación más pequeña que pueda resolver la cuestión.
Su propósito es prevenir un modo de fallo familiar: un agente ve un error, asume la causa, reescribe con confianza la mitad del sistema y solo entonces descubre que la suposición era incorrecta. Ackrite empuja al agente hacia la evidencia, experimentos dirigidos, cambios acotados e incertidumbre explícita.
| Ackrite hace | Ackrite no hace |
|---|---|
| Clasifica afirmaciones a partir de la evidencia proporcionada | Inventa, busca o implica evidencia que no se le dio |
| Detecta contradicciones y suposiciones sin respaldo | Presenta una inferencia como un hecho |
| Desafía reescrituras y expansión de alcance antes de la implementación | Aplica cambios de código o llama a sistemas externos |
| Rastrea un historial de verificación acotado dentro del proceso | Persiste un sistema de memoria grande o depende de L-Dopa |
| Redacta secretos comunes de la salida de diagnóstico | Garantiza detección perfecta de secretos para cada formato de credencial personalizado |
Por qué existe
La confianza de un agente no es evidencia. Una afirmación como "la API eliminó la autenticación nativa" suele ser una hipótesis útil, pero se vuelve peligrosa cuando se trata como un hecho establecido y se usa para justificar una reescritura. Ackrite hace cuatro preguntas concretas:
- ¿Qué establece realmente la evidencia proporcionada?
- ¿Qué contradice la afirmación, si acaso algo?
- ¿Qué suposición está haciendo el trabajo?
- ¿Cuál es la verificación empírica más pequeña para ejecutar a continuación?
El resultado es deliberadamente conciso para poder colocarse directamente de vuelta en la ventana de contexto de un agente.
Estados de afirmación
Ackrite usa un modelo de clasificación deliberadamente conservador.
| Estado | Significado | Umbral de evidencia |
|---|---|---|
KNOWN | Evidencia directa y de alta confiabilidad proporcionada respalda la afirmación. | Al menos un elemento directo de alta confiabilidad, como un resultado de prueba enfocado, respuesta HTTP, comportamiento observado o hecho proporcionado por el usuario. |
SUPPORTED | Evidencia directa proporcionada respalda la afirmación, pero sigue siendo limitada en alcance o confiabilidad. | Evidencia directa de respaldo sin un elemento de alta confiabilidad que la califique. |
PLAUSIBLE | La afirmación puede ser verdadera, pero el material es indirecto, neutral o inferido. | Solo evidencia neutral o inferencia. |
UNVERIFIED | Ninguna evidencia proporcionada respalda la afirmación. | Sin evidencia relevante. |
CONTRADICTED | Al menos un elemento de evidencia proporcionado contradice la afirmación. | La contradicción tiene prioridad hasta que se reconcilie. |
Regla fundamental: Ackrite nunca convierte una inferencia en un hecho. Etiqueta el límite entre observación y conclusión.
Arquitectura
Ackrite es intencionalmente pequeño. El límite de MCP, el análisis de dominio, el manejo de evidencia y el estado acotado están separados para que las reglas de verificación puedan probarse sin un cliente MCP en ejecución.
| Capa | Ubicación | Responsabilidad |
|---|---|---|
| Transporte y esquemas MCP | src/mcp/server.ts, src/index.ts | Registra cinco herramientas y las sirve a través de entrada/salida estándar. |
| Orquestación de herramientas | src/tools/verification-tools.ts | Produce respuestas de desafío, verificación, auditoría, plan de prueba y verificación de realidad listas para el agente. |
| Modelo de evidencia | src/core/evidence.ts | Normaliza procedencia, confiabilidad, polaridad, extractos y redacción de secretos. |
| Análisis de afirmaciones | src/core/claim-analysis.ts | Determina estado, confianza, suposiciones, pruebas faltantes y siguiente acción. |
| Historial de sesión | src/core/state.ts | Mantiene un registro acotado dentro del proceso de afirmaciones, evidencia, intentos, conclusiones y suposiciones sin resolver. |
| Pruebas | test/ackrite.test.mjs | Ejercita la lógica de dominio y el comportamiento real del cliente/servidor stdio de MCP. |
Ackrite está implementado en TypeScript usando los paquetes oficiales de servidor y cliente MCP de TypeScript. Expone un servidor stdio: un cliente inicia Ackrite como subproceso e intercambia mensajes JSON-RPC a través de la entrada y salida estándar, que es un transporte MCP estándar. [1] [2]
Instalación
Ackrite requiere Node.js 20 o posterior.
git clone https://github.com/mshanghai570/Ackrite.git
cd Ackrite
npm install
npm run build
Inicie el servidor directamente después de compilar:
npm start
El proceso se comunica a través de entrada/salida estándar, por lo que puede parecer inactivo cuando se ejecuta en una terminal. Eso es esperado: su cliente MCP proporciona las solicitudes. Mantenga los registros normales fuera de la salida estándar; MCP stdio la reserva para mensajes de protocolo. [1]
Configuración del cliente MCP
Compile el proyecto primero, luego agregue una entrada como la siguiente a la configuración de su cliente MCP. Reemplace /absolute/path/to/Ackrite con el directorio que contiene este repositorio.
{
"mcpServers": {
"ackrite": {
"command": "node",
"args": ["/absolute/path/to/Ackrite/dist/index.js"]
}
}
}
Si su cliente admite ejecutar scripts de paquete, el comando equivalente es node dist/index.js con el repositorio como directorio de trabajo. Ackrite no acepta credenciales y no realiza llamadas de red en v0.1.
Herramientas disponibles
Las cinco herramientas están declaradas como solo lectura y devuelven tanto texto JSON legible como contenido estructurado. Aceptan un sessionId opcional; use el mismo valor durante una investigación relacionada para conservar el historial acotado dentro del proceso en ejecución.
| Herramienta | Úsela cuando | Resultado principal |
|---|---|---|
ackrite | Un agente hace una afirmación técnica y necesita ser desafiado. | Estado, confianza, evidencia de respaldo y contradicción, suposiciones, pruebas faltantes y siguiente acción. |
verify | Necesita un registro de evidencia estructurado para una afirmación. | Lo que se sabe, se asume, se contradice, falta y el experimento decisivo. |
audit | Se propone un cambio de código o un plan de implementación. | Hallazgos concisos sobre reescrituras innecesarias, alcance, suposiciones de contrato de API, trabajo sensible a la seguridad, detalle de manejo de errores y pruebas. |
prove_it | Quiere la evidencia mínima necesaria para establecer una afirmación. | Una lista de verificación de prueba específica del dominio de la afirmación y un experimento falsable. |
reality_check | Un agente puede estar atascado, repitiéndose o reclamando éxito demasiado pronto. | La falla de razonamiento más importante primero, más riesgos adicionales observados. |
Entrada de evidencia compartida
Pase la evidencia explícitamente en lugar de incrustarla en contexto no estructurado. context puede proporcionar antecedentes, pero no se cuenta como prueba.
{
"type": "http_response",
"source": "staging request, 2026-08-27",
"content": "POST /v1/session returned 401 with code AUTH_REQUIRED.",
"polarity": "contradicts",
"reliability": 0.9
}
| Campo | Requerido | Descripción |
|---|---|---|
type | No | Uno de code, log, http_request, http_response, test_result, documentation, observed_behavior, user_fact, inference o other. |
source | No | Una etiqueta de procedencia concisa, como un nombre de prueba, fuente de registro o ubicación de código. |
content | Sí | La observación, extracto, resultado o inferencia proporcionada. |
polarity | No | supports, contradicts o neutral; por defecto neutral para evitar suposiciones. |
reliability | No | Número evaluado por el llamador de 0 a 1; por defecto 0.7. |
Interacciones de ejemplo
Desafiar una afirmación de API sin respaldo
Afirmación: "La API ya no admite autenticación nativa."
{
"claim": "The API no longer supports native authentication.",
"evidence": [
{
"type": "code",
"source": "current client",
"content": "The current client implementation does not obtain credentials.",
"polarity": "supports"
},
{
"type": "observed_behavior",
"source": "older working application",
"content": "The older application successfully signs in.",
"polarity": "contradicts",
"reliability": 0.9
}
]
}
Ackrite responde con CONTRADICTED, preserva ambas piezas de procedencia y recomienda inspeccionar el flujo de autenticación anterior antes de reemplazar el cliente. No concluye que la autenticación nativa exista o que el flujo anterior sea aplicable; eso excedería la evidencia proporcionada.
Auditar una propuesta de reescritura
{
"reportedProblem": "Login returns an unexpected response.",
"proposal": "Rewrite the authentication client to replace the API endpoint integration.",
"proposedChanges": [
{
"path": "src/auth.ts",
"description": "Rewrite authentication client and route handling."
},
{
"path": "src/theme.ts",
"description": "Change unrelated color palette."
}
]
}
La auditoría señala el mayor estándar de evidencia de la reescritura, la suposición de contrato de API sin respaldo, el plan de pruebas faltante y el cambio de tema aparentemente no relacionado. No afirma haber inspeccionado src/auth.ts o src/theme.ts a menos que sus contenidos se proporcionen como evidencia.
Romper un bucle de fallo repetido
{
"sessionId": "auth-investigation",
"reasoning": "The rewrite will work and the issue is fixed.",
"attempts": [
{ "approach": "Replace the auth client", "outcome": "Failed with timeout." },
{ "approach": "Replace the auth client", "outcome": "Failed with timeout again." },
{ "approach": "Replace the auth client", "outcome": "Failed with the same timeout." }
]
}
El problema principal es una estrategia repetida. Ackrite recomienda detenerse, identificar la suposición que hace que el reemplazo parezca necesario y verificar esa suposición en lugar de intentar la misma intervención nuevamente.
Modelo de confiabilidad y seguridad
Ackrite es intencionalmente conservador. No realiza escaneo de repositorios, solicitudes HTTP, búsqueda de documentación externa, ejecución de código ni reparación autónoma en v0.1. Cada conclusión incluye procedencia que la limita al material proporcionado por el llamador. La evidencia faltante es un resultado, no un error que ocultar.
El servidor redacta patrones comunes de credenciales antes de devolver texto de diagnóstico, incluidos valores de autorización bearer/basic, asignaciones tipo contraseña, prefijos de token comunes, claves de cadena de consulta y campos de clave de API. Esto es defensa en profundidad, no permiso para enviar secretos reales. No envíe credenciales de producción a herramientas de diagnóstico.
El almacén de sesiones es local al proceso y acotado: retiene afirmaciones recientes, evidencia, intentos, conclusiones y suposiciones sin resolver para hasta 32 sesiones nombradas. Cada colección por sesión está limitada, las sesiones menos recientemente usadas se expulsan y todo el historial se pierde cuando el proceso sale. Esto mantiene v0.1 útil para una investigación enfocada sin convertirse en una plataforma de memoria.
Desarrollo
| Comando | Propósito |
|---|---|
npm install | Instala dependencias de desarrollo y ejecución. |
npm run build | Compila TypeScript en dist/. |
npm run check | Ejecuta verificación estricta de TypeScript sin generar salida. |
npm test | Compila, ejecuta pruebas unitarias, ejercita el descubrimiento de herramientas MCP e invoca cada herramienta a través de un subproceso stdio real. |
npm start | Inicia Ackrite compilado a través de stdio. |
npm run dev | Observa fuentes TypeScript durante el desarrollo. |
El conjunto de pruebas incluye cobertura positiva y negativa para clasificación de afirmaciones, evidencia contradictoria, afirmaciones sin respaldo, redacción, estado acotado, cada herramienta central, fallos repetidos, inicio del servidor, descubrimiento de herramientas y llamadas a herramientas a través del protocolo MCP.
Limitaciones
El análisis de Ackrite es determinista y basado en evidencia, no un sistema completo de razonamiento autónomo. La herramienta audit revisa descripciones de una propuesta; no es un analizador estático y no inspecciona un árbol de trabajo. La detección de estrategias repetidas usa términos normalizados de descripciones de intentos proporcionadas, por lo que intentos semánticamente idénticos pero redactados de manera muy diferente pueden no agruparse. Las reglas de redacción de secretos cubren patrones comunes pero no pueden reconocer cada formato de credencial propietario.
Ackrite usa solo stdio en v0.1. Está diseñado para permanecer independiente de L-Dopa y otros servidores MCP. Un futuro transporte HTTP, capa de persistencia o adaptador consciente del repositorio debe seguir siendo opcional y debe preservar las mismas garantías de no fabricación y redacción.
Licencia
Ackrite se publica bajo la Licencia MIT.