TraceFact MCP Server

60초 퀵 스타트

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

report/report.html을 여세요. 독립 실행형이며 오프라인에서 작동합니다. 이 명령은 또한 report.json, report.md, report.sarif, 그리고 해시 검증된 run.tracefact.gz 재생 캡슐을 작성합니다.

브라우저를 선호하시나요? 라이브 데모를 열고 트레이스를 끌어다 놓은 다음 보고서를 내보내세요. 파일은 페이지를 벗어나지 않습니다.

Related MCP server: jaeger-mcp

무엇이 들어가고, 무엇이 나오며, 왜 신뢰할 수 있는가

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는 정확성을 하나의 LLM-as-judge 점수 뒤에 숨기지 않습니다. 명시적인 완료 주장을 추출하고 각 주장을 관찰 가능한 도구 결과, 테스트, diff, 브라우저 작업, 소스, 아티팩트 해시에 연결합니다. 모든 실패 발견에는 정확한 이벤트 ID가 포함됩니다. 누락된 텔레메트리는 불확실성으로 표시됩니다.

핵심 기능

• Open Agent Trace Schema (OATS) 1.0 — 버전 관리되고 확장 가능한 트레이스 봉투로, JSON Schema, 엄격한 TypeScript 타입, 마이그레이션을 포함합니다.

• 증거 그래프(Evidence Graph) — 인과적 증거 엣지와 설명이 포함된 supported, weak, unsupported, 또는 conflicting 주장.

• 재생 캡슐(Replay Capsule) — 정규화된 트레이스, 환경 요약, 소스 메타데이터, 보고서, 해시를 포함하는 휴대 가능하고, 편집되고, gzip 압축된 실행. 검토에 원본 모델이나 API 키가 필요하지 않습니다.

• 실패 분류 체계(Failure Taxonomy) — 루프, 반복 호출, 검색 드리프트, 검증되지 않은 변경, 실패한 테스트, 증거 없는 완료, 비용 급증, 조기 종료, 실패한 복구의 결정적 위치 파악.

• 신뢰성 보고서(Reliability Report) — 독립 실행형 HTML과 JSON, Markdown, SARIF. 벤치마크 점수는 원래 벤치마크 범위 내로 유지됩니다.

어댑터

어댑터는 플러그인입니다. tracefact/adapter-sdk에서 내보낸 작은 TraceAdapter 인터페이스를 구현하세요. 알 수 없는 필드는 attributes 또는 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

이 액션은 작업 요약을 추가하고, pull-requests: write 권한이 부여된 경우 마커 기반 PR 댓글을 업데이트하며, 전체 HTML/JSON/Markdown/SARIF/캡슐 번들을 업로드합니다. 어떤 트레이스도 제3자에게 전송되지 않습니다.

읽기 전용 MCP 서버

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

도구: list_runs, get_run, get_reliability_report. 쓰기 도구는 없습니다.

작고 재현 가능한 증거 세트

dataset/generated/에는 성공, 실패한 테스트, 도구 루프, 지원되지 않는 완료, 비용 이상, 성공적인 복구를 아우르는 60개의 결정적이고 CC0-1.0 합성 트레이스가 포함되어 있습니다. npm run dataset:generate로 재생성하고, npm run experiment로 평가하세요.

v0.1 실험은 규칙 기반 합성 레이블에 대해 마이크로 정밀도 0.833, 재현율 1.000, F1 0.909를 보고합니다. 10개의 겉보기 거짓 양성은 모두 기본 레이블이 test_failure인 픽스처에 대한 hallucinated_completion 발견입니다. 완료 주장이 실패한 테스트와 충돌하지만, 해당 보조 레이블은 의도적으로 생략되었습니다. 이는 다중 레이블 모호성을 숨기는 대신 노출합니다. 이 결과는 회귀 증거이지 실제 세계 일반화의 증명이 아닙니다. 데이터 카드, 원시 결과, 기술 보고서를 참조하세요.

TraceFact의 위치

이는 2026-08-20에 검토된 공개 문서를 기반으로 한 범위 비교이지, 품질 순위가 아닙니다. TraceFact는 기존 관찰 가능성 스택에서 내보낸 OpenTelemetry를 대체하는 대신 수집할 수 있습니다.

개인정보 보호 및 보안

편집은 일반적인 API 키, 베어러 토큰, 쿠키, 이메일, Windows/macOS/Linux 홈 경로, 비밀처럼 이름이 지정된 필드를 다룹니다. 편집을 심층 방어로 취급하세요. 게시 전에 캡슐을 검토하세요. TraceFact는 공개 저장소 데이터를 기본으로 하며, 텔레메트리가 없고, 트레이스를 업로드하지 않습니다.

개발

npm ci
npm run check
npm run test:coverage

CI는 Node 20과 22로 Windows, Linux, macOS에서 실행됩니다. CONTRIBUTING.md, SECURITY.md, DECISIONS.md를 참조하세요.

라이선스

Apache-2.0. 상업 및 연구 목적으로 허용되며, 명시적 특허 허여를 포함하고, 고지 사항 보존을 요구합니다. 데이터셋 픽스처는 CC0-1.0입니다. 외부 프로젝트와 데이터는 각자의 라이선스를 따릅니다. THIRD_PARTY.md 및 DATA_SOURCES.md를 참조하세요.