Skip to main content
Glama
rupturetrace-mcp

rupturetrace-mcp

by Susan571

rupturetrace-mcp

An MCP server (and plain Python library) for RuptureTrace — relation-guided assessment and reassessment of scientific claims.

RuptureTrace rates a claim on a 5-level whole-claim rubric (−2 … +2) while auditing 12 evidence relations (sources->rationale, protocol->claim, results->claim, …) over three rounds (K0 initial, K1 relation audit, K2 verification). It tracks how relation support changes and computes graph zigzag H1 persistence over GF(2) to pick one relation for focused repair, then reassesses the whole claim.

All diagnostics (support, H1 persistence, scores, relation selection) are computed by the server — never by the model.

Install

Requires Python ≥ 3.10.

# from a local checkout / wheel
pip install ./rupturetrace-mcp            # or: pip install rupturetrace_mcp-0.1.0-py3-none-any.whl

# or run without installing (uv)
uvx --from ./rupturetrace-mcp rupturetrace-mcp
# from a git remote once pushed:
uvx --from git+https://github.com/Susan571/rupturetrace-mcp rupturetrace-mcp

Related MCP server: target-mcp

Add it to an MCP client

Claude Code

claude mcp add rupturetrace -- uvx --from /path/to/rupturetrace-mcp rupturetrace-mcp
# with a model backend for assess_claim:
claude mcp add rupturetrace -e TA2_MODEL=gpt-4.1 -e TA2_ENDPOINT=https://api.openai.com/v1/chat/completions \
  -e OPENAI_API_KEY=sk-... -- uvx --from /path/to/rupturetrace-mcp rupturetrace-mcp

Claude Desktop / Cursor / any MCP client (mcpServers JSON):

{
  "mcpServers": {
    "rupturetrace": {
      "command": "uvx",
      "args": ["--from", "/path/to/rupturetrace-mcp", "rupturetrace-mcp"],
      "env": {
        "TA2_MODEL": "YOUR_MODEL_ID",
        "TA2_ENDPOINT": "YOUR_COMPLETE_CHAT_COMPLETIONS_ENDPOINT",
        "OPENAI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

The env block is only needed for backend mode. Host mode needs no key: the client's own model answers each round. Remote deployment: rupturetrace-mcp --transport streamable-http --port 8000.

Tools

Tool

What it does

describe_protocol

Rubric, 12 relations, statuses, per-round JSON schema, model instructions, scoring policy.

assess_claim

Full pipeline on one claim via a configured backend (http, qwen, arithmetic). 7 model calls (9 with with_h1_ablation). Optional out_dir writes the complete verifiable artifact set.

assess_claims_batch

Many claims (JSONL path or list of strings) → one run directory; reports progress.

start_host_assessment / submit_host_round

Host mode: the MCP client model produces each round; the server validates it, grounds quotes, computes diagnostics and drives the repair branches.

diagnose_rounds

Stateless: give K0/K1/K2 rounds from any model, get the relation ranking and repair choices.

compute_zigzag_h1

Raw zigzag H1 barcode for any evolving graph.

verify_run

Offline record-consistency check of a run directory (recomputes diagnostics and hashes).

evaluate_run

MAE / MSE / Exact, initial-error AUROC and optional localization metrics against gold labels.

Backend configuration: model / endpoint default to TA2_MODEL / TA2_ENDPOINT. API keys are only read from the environment variable named by key_env (default OPENAI_API_KEY, or DASHSCOPE_API_KEY for Qwen) — they are never tool arguments.

Library use

from rupturetrace_mcp import run_claim, HTTPAgent, EvidenceResolver

agent = HTTPAgent("YOUR_MODEL", "https://.../v1/chat/completions")
out = run_claim("A claim with explicit, measurable conditions.", agent, EvidenceResolver(), with_h1_ablation=True)
print(out["result"]["RuptureTrace_label"], out["result"]["localization_peak"])

CLI (same as the original scripts)

rupturetrace-run --agent http --input claims.jsonl --out runs/r1 [--with-h1-ablation]
rupturetrace-verify --directory runs/r1 --input claims.jsonl
rupturetrace-evaluate --results runs/r1/ta2_claim_results.jsonl --gold gold.jsonl --out reports/eval.json

An example input (50 claims) ships at rupturetrace_mcp/data/example_claims.jsonl.

Notes

  • Scoring is identical to the original code: 0.60·max(0, support_K0 − support_K2) + 0.30·lost_initial_H1 + 0.10·unresolved_K2, threshold 0.72.

  • Changes vs. the standalone repo: modules use package-relative imports; evaluate.py exposes run_evaluation(); the local arithmetic checker now emits assessment_scope (it previously failed schema validation). Because source hashes are recorded in run_provenance.json, runs made with the original scripts must be verified with the original scripts, and vice versa.

  • Host-mode runs record provider mcp_host; their artifacts are complete but verify_run cannot replay them.

  • verify_run checks record consistency, not scientific truth.

License

MIT. See LICENSE.

Available Tools

9 tools
assess_claimB

Run the full RuptureTrace pipeline on one claim using a configured model backend (7 model calls; 9 with ablation).

model/endpoint default to the TA2_MODEL / TA2_ENDPOINT environment variables; the API key is read from the environment variable named by key_env (default OPENAI_API_KEY for http, DASHSCOPE_API_KEY for qwen) and is never passed as an argument. If out_dir is given, the complete verifiable artifact directory is written there. Returns a summary (labels, selected relation, top relation scores, rationales).

Inputs: claim (required), model, backend, key_env, +11 more.

assess_claims_batchB

Run many claims sequentially and write a complete, verifiable run directory to out_dir.

Provide either input_path (JSONL rows with claim and optional problem_id / problem_version) or a list of claim strings. Returns the run summary plus one compact row per completed claim.

Inputs: out_dir (required), limit, model, claims, +13 more.

compute_zigzag_h1B

Exact zigzag H1 persistence over GF(2) for an evolving graph.

snapshots: ordered edge-ID sets K_0..K_T; edges: [u, v] endpoints per edge ID; n_vertices: vertex count. Uses the diagram K_0 -> K_0 U K_1 <- K_1 -> ... and returns Betti-1 per node and the interval barcode.

Inputs: edges (required), snapshots (required), n_vertices (required).

describe_protocolA

Return the RuptureTrace protocol: rubric, the 12 audited relations, allowed statuses, the per-round JSON output schema, model instructions and the fixed scoring policy.

Inputs: no named parameters.

diagnose_roundsA

Compute the prefix diagnosis from three already-produced rounds (K0, K1, K2) without calling any model.

Each round must match describe_protocol().round_output_schema. Returns the selected relation for RuptureTrace repair, the local (weakest-support) and without-H1 choices, and every relation's score components and H1 intervals. External quotes are only verified when allow_source_fetch is true.

Inputs: claim (required), rounds (required), allow_source_fetch.

evaluate_runB

Evaluate a verified run against gold labels (MAE/MSE/Exact, initial-error AUROC, optional localization).

results_path must be <run_dir>/ta2_claim_results.jsonl; gold rows need problem_id and gold_label or likert_score in {-2..2}. The JSON report is written to out_path (outside the run directory) and returned.

Inputs: out_path (required), gold_path (required), results_path (required), input_path, +5 more.

start_host_assessmentA

Start a RuptureTrace assessment where YOU (the MCP client model) produce each round.

Returns the first stage prompt (instructions, input payload and output schema). Answer every step with submit_host_round until status is 'completed' (7 steps; 9 with ablation). The server computes support, zigzag H1 persistence and the repair relation itself. If out_dir is set, artifacts are written at the end.

Inputs: claim (required), out_dir, overwrite, with_h1_ablation, +1 more.

submit_host_roundA

Submit your JSON answer for the current step of a host-mode assessment.

round_output must contain label (-2..2), confidence (0..1), rationale, assessment_scope='whole_claim' and checks (all 12 relations once, each with relation_id, status, reason, evidence[{kind, source, quote}]). Returns the next stage prompt, or the final summary once all steps are done. Invalid rounds are rejected without advancing, so you can fix and resubmit.

Inputs: session_id (required), round_output (required).

verify_runA

Verify a RuptureTrace output directory offline: recompute diagnostics, derived files and hashes.

Checks record consistency only - not scientific truth. input_path optionally points to the original claim JSONL to check claim/ID linkage. Runs produced in host mode cannot be replay-verified.

Inputs: directory (required), input_path.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation5/5

    The tools target clearly separable stages: single vs batch assessment, host-mode start/submit, protocol description, round diagnosis, H1 computation, evaluation, and offline verification. Although assess_claim, assess_claims_batch, and start_host_assessment all concern assessment, their scopes and execution models are explicitly described, so misselection is unlikely.

    Naming Consistency5/5

    All names use consistent snake_case with a verb-leading pattern such as assess_claim, submit_host_round, describe_protocol, evaluate_run, and verify_run. The specialized compute_zigzag_h1 still follows the same convention.

    Tool Count5/5

    Nine tools is well scoped for a specialized assessment pipeline. Each tool represents a meaningful operation or workflow stage, with no obvious filler tools.

    Completeness4/5

    The surface covers the core lifecycle: protocol description, single and batch assessment, host-mode assessment, diagnosis, H1 computation, evaluation, and verification. A minor gap is the lack of an explicit host-session recovery or status-inspection tool, though normal forward flow is complete.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables scientific due diligence by grading claims against public literature, clinical trials, and filings, with explicit citations and optional attestation.
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables automated assessment of research manuscripts against the TARGET reporting guideline for target trial emulation, providing item-by-item scoring with evidence and provenance.
      11
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      Enables revision-bound source audits with exact article fingerprinting, claim-to-source mapping, quotation verification, and immutable JSON evidence reports for prepublication review.
      9
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables auditing of revised documents against reviewer comments, providing evidence-based status, confidence, and traceability for each issue via natural language.
      MIT