rupturetrace-mcp
# 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
Scored across 9 tools
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.
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.
Nine tools is well scoped for a specialized assessment pipeline. Each tool represents a meaningful operation or workflow stage, with no obvious filler tools.
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.