TraceFact MCP Server

Inicio rápido en 60 segundos

git clone https://github.com/Alex0AI/tracefact.git
cd tracefact
npm ci
npm run build
node dist/cli.js analyze examples/offline-demo.codex.jsonl --out report

Abre report/report.html. Es un archivo autónomo y funciona sin conexión. El comando también escribe report.json, report.md, report.sarif y una cápsula de reproducción run.tracefact.gz verificada por hash.

¿Prefieres el navegador? Abre la demo en vivo, arrastra una traza y exporta el informe. El archivo nunca sale de la página.

Related MCP server: jaeger-mcp

Qué entra; qué sale; por qué es creíble

flowchart LR
  A[Codex / Gemini CLI / Browser Use / JSONL / OTel] --> B[Open Agent Trace Schema]
  B --> C[Redaction]
  C --> D[Evidence Graph]
  C --> E[Deterministic failure rules]
  D --> F[HTML · JSON · Markdown · SARIF]
  E --> F
  C --> G[Replay Capsule + SHA-256]

TraceFact no oculta la veracidad detrás de una única puntuación tipo LLM-as-judge. Extrae afirmaciones explícitas de finalización y vincula cada una a resultados de herramientas observables, pruebas, archivos diff, acciones del navegador, fuentes y hashes de artefactos. Cada hallazgo de fallo incluye los identificadores de evento exactos. La telemetría que falta se muestra como incertidumbre.

El núcleo original

• Open Agent Trace Schema (OATS) 1.0 — un contenedor de trazas versionado y extensible, con JSON Schema, tipos estrictos de TypeScript y migraciones.

• Evidence Graph — afirmaciones de tipo supported, weak, unsupported o conflicting con aristas de evidencia causal y explicaciones.

• Replay Capsule — una ejecución portátil, depurada y comprimida con gzip que incluye la traza normalizada, el resumen del entorno, los metadatos de las fuentes, el informe y los hashes. La revisión no requiere el modelo original ni una apikey para API.

• Failure alcanzar — una Taxonomy de error, que permite localizar de forma determinista bucles, llamadas repetidas, desviación en la recuperación, cambios no verificados, pruebas fallidas, finalización sin evidencia, picos de coste, terminación prematura y recuperación fallida.

• Reliability Report — HTML autónomo junto con JSON, Markdown y SARIF. Las puntuaciones de los benchmarks permanecen limitadas a su benchmark original.

Adaptadores

Los adaptadores son plugins. Implementa la pequeña interfaz TraceAdapter que exporta tracefact/adapter-sdk; los campos desconocidos se conservan en attributes o extensions.

CLI

tracefact analyze <trace> [--adapter auto] [--out tracefact-report]
tracefact replay <run.tracefact.gz> [--out replay.html]
tracefact verify <run.tracefact.gz>
tracefact migrate <old-trace.json> --out migrated.json
tracefact adapters
tracefact serve --dir web-dist --port 4173

GitHub Action

- uses: Alex0AI/tracefact/action@v0.1.2
  with:
    trace: artifacts/codex-rollout.jsonl
    adapter: auto

La acción añade un resumen de la ejecución, actualiza un comentario en la PR identificado por un marcador cuando se le concede el permiso pull-requests: write y sube el paquete completo de HTML/JSON/Markdown/SARIF/cápsula. No se envía ninguna traza a terceros.

Servidor MCP de solo lectura

{
  "mcpServers": {
    "tracefact": {
      "command": "node",
      "args": ["/absolute/path/to/tracefact/dist/mcp.js"],
      "env": { "TRACEFACT_STORE": "/absolute/path/to/traces" }
    }
  }
}

Herramientas: list_runs, get_run y get_reliability_report. No hay herramientas de escritura.

Conjunto de evidencia pequeño y reproducible

dataset/generated/ contiene 60 trazas sintéticas deterministas, bajo licencia CC0-1.0, que cubren éxitos, pruebas fallidas, bucles de herramientas, finalizaciones no respaldadas, anomalías de coste y recuperaciones correctas.Regenerate with npm run dataset:generate; evaluate with npm run experiment.

El experimento v0.1 report a una precision micro de 0.833, recall 1.000 y F1 0.909 sobre las etiquetas sintéticas creadas por reglas. Los 10 falsos positivos aparentes son hallazgos de hallucinated_completion en fixtures cuya etiqueta principal es test_failure: la afirmación de finalización entra en conflicto con la prueba fallida, pero esa etiqueta secundaria se omitió a propósito. Esto expone la ambigüedad de múltiples etiquetas en lugar de ocultarla. El resultado es una evidencia de regresión, no una prueba de generalización en el mundo real. Consulta la ficha del dataset, los resultados en bruto y el informe técnico.

Dónde encaja TraceFact

Se trata de una comparación de alcance basada en documentación pública, revisada en 2026-08-20; no es un ranking de calidad. TraceFact puede ingerir las exportaciones de OpenTelemetry procedentes de las suites de observabilidad existentes en lugar de reemplazarlas.

Privacidad y seguridad

La depuración de datos cubre las claves de API comunes, tokens de portador, cookies, correos electrónicos, rutas de inicio de Windows/macOS/Linux y campos con nombres similares en un segundo plano. Trata la depuración como defensa en profundidad: revisa una cápsula antes de publicarla. Por defecto, TraceFact está pensada para datos de repositorios públicos, no tiene telemetría y nunca sube una traza.

Desarrollo

npm ci
npm run check
npm run test:coverage

La CI se ejecuta en Windows, Linux y macOS con Node 20 y 22. Consulta CONTRIBUTING.md, SECURITY.md y DECISIONS.md.

Licencia

Apache-2.0. Se trata de una licencia permisiva para uso comercial y para investigación, incluye una concesión explícita de patentes y exige la preservación de los avisos. Los fixtures del conjunto de datos son CC0-1.0. Los proyectos externos y los datos siguen con sus propios términos de licencia; consulta THIRD_PARTY.md y DATA_SOURCES.md.