Skip to main content
Glama
rupturetrace-mcp

rupturetrace-mcp

by Susan571
README.md
# 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.

```bash
# 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
```

## Add it to an MCP client

**Claude Code**

```bash
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):

```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

```python
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)

```bash
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](LICENSE).

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