TraceFact MCP Server

Der 60-Sekunden-Schnellstart

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

Öffne report/report.html. Er ist eigenständig und funktioniert offline. Der Befehl schreibt außerdem report.json, report.md, report.sarif und eine hash-verifizierte run.tracefact.gz-Wiedergabekapsel.

Bevorzugst du den Browser? Öffne die Live-Demo, ziehe einen Trace hinein und exportiere den Bericht. Die Datei verlässt die Seite nie.

Related MCP server: jaeger-mcp

Was hineingeht; was herauskommt; warum es glaubwürdig ist

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 verbirgt Korrektheit nicht hinter einer einzigen LLM-als-Richter-Bewertung. Es extrahiert explizite Abschlussbehauptungen und verknüpft jede einzelne mit beobachtbaren Tool-Ergebnissen, Tests, Diffs, Browser-Aktionen, Quellen und Artefakt-Hashes. Jeder Fehlerbefund trägt exakte Ereignis-IDs. Fehlende Telemetrie wird als Unsicherheit ausgewiesen.

Der ursprüngliche Kern

• Open Agent Trace Schema (OATS) 1.0 – ein versioniertes, erweiterbares Trace-Envelope mit JSON-Schema, strengen TypeScript-Typen und Migrationen.

• Beweisgraph – supported (gestützt), weak (schwach), unsupported (ungestützt) oder conflicting (widersprüchlich) Behauptungen mit kausalen Beweiskanten und Erklärungen.

• Wiedergabekapsel – ein portabler, redigierter, gzip-komprimierter Lauf mit normalisiertem Trace, Umgebungszusammenfassung, Quell-Metadaten, Bericht und Hashes. Die Überprüfung erfordert weder das ursprüngliche Modell noch einen API-Schlüssel.

• Fehlertaxonomie – deterministische Lokalisierung von Schleifen, wiederholten Aufrufen, Retrieval-Drift, unverifizierten Änderungen, fehlgeschlagenen Tests, abschlussfreien Beweisen, Kostenspitzen, vorzeitigem Abbruch und fehlgeschlagener Wiederherstellung.

• Zuverlässigkeitsbericht – eigenständiges HTML plus JSON, Markdown und SARIF. Benchmark-Ergebnisse bleiben auf ihren ursprünglichen Benchmark beschränkt.

Adapter

Adapter sind Plugins. Implementiere das kleine TraceAdapter-Interface, das aus tracefact/adapter-sdk exportiert wird; unbekannte Felder bleiben in attributes oder extensions erhalten.

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

Die Action fügt eine Job-Zusammenfassung hinzu, aktualisiert einen marker-basierten PR-Kommentar, wenn pull-requests: write gewährt ist, und lädt das vollständige HTML/JSON/Markdown/SARIF/Kapsel-Bundle hoch. Kein Trace wird an Dritte gesendet.

Schreibgeschützter MCP-Server

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

Tools: list_runs, get_run und get_reliability_report. Es gibt keine Schreib-Tools.

Kleiner, reproduzierbarer Beweis-Datensatz

dataset/generated/ enthält 60 deterministische, CC0-1.0-synthetische Traces, die Erfolg, fehlgeschlagene Tests, Tool-Schleifen, ungestützte Abschlüsse, Kostenanomalien und erfolgreiche Wiederherstellung abdecken. Neu generieren mit npm run dataset:generate; auswerten mit npm run experiment.

Der v0.1-Experimentbericht weist eine Mikro-Präzision von 0,833, einen Recall von 1,000 und einen F1 von 0,909 auf regelbasiert erstellten synthetischen Labels auf. Alle 10 scheinbaren False Positives sind hallucinated_completion-Befunde an Fixtures, deren primäres Label test_failure ist: Die Abschlussbehauptung widerspricht dem fehlgeschlagenen Test, aber dieses sekundäre Label wurde absichtlich weggelassen. Dies legt Mehrlabel-Mehrdeutigkeit offen, anstatt sie zu verbergen. Das Ergebnis ist Regressionsnachweis, kein Beweis für eine Generalisierung in der realen Welt. Siehe die Datenkarte, Rohdaten und technischen Bericht.

Wo TraceFact einzuordnen ist

Dies ist ein Umfangsvergleich auf Basis öffentlicher Dokumentation, geprüft am 2026-08-20 – keine Qualitätsrangliste. TraceFact kann OpenTelemetry-Daten verarbeiten, die von bestehenden Beobachtbarkeits-Stacks exportiert werden, anstatt sie zu ersetzen.

Datenschutz und Sicherheit

Die Redaktion umfasst gängige API-Schlüssel, Bearer-Tokens, Cookies, E-Mails, Windows-/macOS-/Linux-Home-Pfade und Felder, die wie Geheimnisse benannt sind. Behandle die Redaktion als Verteidigung in der Tiefe: Überprüfe eine Kapsel, bevor du sie veröffentlichst. TraceFact verwendet standardmäßig Daten aus öffentlichen Repositories, hat keine Telemetrie und lädt niemals einen Trace hoch.

Entwicklung

npm ci
npm run check
npm run test:coverage

CI läuft auf Windows, Linux und macOS mit Node 20 und 22. Siehe CONTRIBUTING.md, SECURITY.md und DECISIONS.md.

Lizenz

Apache-2.0. Sie ist freizügig für kommerzielle und Forschungszwecke, enthält eine ausdrückliche Patentgewährung und erfordert die Aufbewahrung von Hinweisen. Datensatz-Fixtures sind CC0-1.0. Externe Projekte und Daten unterliegen ihren eigenen Lizenzen; siehe THIRD_PARTY.md und DATA_SOURCES.md.