# CardioTriage MCP — Phenotype-aware Cardiovascular Triage

Prompt Opinion MCP superpower for phenotype-aware emergency cardiovascular
triage with FHIR R5 context, missing-data checks, structured bilingual
handoff, and Chagas-compatible cardiomyopathy differential surfacing backed by
ECGFounder bridge phenotype detection.

> NOT FOR CLINICAL USE. Hackathon demonstration only. Synthetic FHIR metadata
> plus public de-identified ECG samples. Foundation model outputs are
> uncalibrated demo scores -- they SURFACE differentials for clinical workup,
> never DIAGNOSE conditions.

## We do not propose AI-ECG as a replacement for serology.
## We propose it as a low-cost triage layer.

## Quick Links

- Live MCP endpoint: `https://claudiomedina17--mcp.modal.run/mcp`
- Live health endpoint: `https://claudiomedina17--mcp.modal.run/health`
- Marketplace listing evidence: [`docs/MARKETPLACE_VERIFICATION.md`](docs/MARKETPLACE_VERIFICATION.md)
- Demo video: `TBD - Phase 2`
- Devpost submission: `TBD - Phase 2`
- Repository: `TBD public repo URL` (local prototype workspace)
- Data provenance: [`docs/DATA_PROVENANCE.md`](docs/DATA_PROVENANCE.md)
- BYO Agent system prompt: [`docs/BYO_AGENT_SYSTEM_PROMPT.md`](docs/BYO_AGENT_SYSTEM_PROMPT.md)

## Elevator Pitch

CardioTriage gives any Prompt Opinion agent a governed phenotype-aware
cardiovascular triage toolkit instead of a free-text-only workflow.

It exposes six MCP tools that discover cases, retrieve FHIR R5 bundles, check
critical missing data, run ECGFounder-backed phenotype inference, summarize
risk signals, and render an SBAR handoff note.

The ECG tool uses ECGFounder (PKUDigitalHealth, MIT; NEJM AI 2025) embeddings
and signal features to return transparent uncalibrated demo scores.

The demo is anchored on chest-pain triage, STEMI pattern recognition, and a
Latam Chagas-compatible cardiomyopathy workup scenario.

The MCP server is the primary submission; the Prompt Opinion BYO Agent is the
demo wrapper that proves the tools are invokable inside the platform.

## Architecture Summary

CardioTriage uses a five-layer architecture:

1. Domain logic: synthetic FHIR R5 case bundles, HEART-style risk signals,
   missing-data review, and deterministic SBAR handoff scaffolding.
2. AI-ECG layer: ECG signal preprocessing plus ECGFounder 1024-d embeddings,
   centroid cosine similarity, and neurokit2-derived signal features.
3. MCP server: FastMCP tools exposed over Streamable HTTP for Prompt Opinion.
4. BYO Agent wrapper: a Prompt Opinion demo agent orchestrates the six tools
   with concise clinical rationale before each call.
5. Submission polish: provenance docs, Marketplace evidence, cache skeletons,
   disclaimers, and a reproducible local test suite.

## Six MCP Tools

| # | Tool | Purpose |
|---|------|---------|
| 1 | `list_synthetic_cases` | Discover the available demo case IDs A, B, and C. |
| 2 | `get_fhir_case_bundle` | Return the FHIR R5-style bundle for the selected case. |
| 3 | `analyze_missing_critical_data` | Flag missing or pending triage data such as troponin, echo, Chagas serology, or contraindications. |
| 4 | `summarize_cardiovascular_risk_signals` | Summarize deterministic cardiovascular risk signals for STEMI, HF/Chagas, or low-risk patterns. |
| 5 | `generate_structured_handoff_note` | Generate an SBAR-style handoff note in `en`, `es`, or `pt`. |
| 6 | `interpret_12_lead_ecg` | AI-ECG inference (lite + live), uncalibrated demo scores. Bridge phenotype detection backed by ECGFounder; surfaces Chagas-compatible cardiomyopathy pattern when context warrants serology workup. NOT a diagnostic tool. |

Tool #6 scores are evidence signals for the hackathon demo. They surface
phenotype-aware differentials for workup; they are not calibrated clinical
probabilities.

## Local Development

```bash
uv sync
uv run pytest tests/ -q
uv run python -m server.main
```

The default transport is stdio. For local Streamable HTTP:

```powershell
$env:CARDIOTRIAGE_MCP_TRANSPORT = "streamable-http"
$env:CARDIOTRIAGE_MCP_HOST = "127.0.0.1"
$env:CARDIOTRIAGE_MCP_PORT = "8000"
$env:CARDIOTRIAGE_MCP_PATH = "/mcp"
uv run python -m server.main
```

Health smoke:

```powershell
curl.exe http://127.0.0.1:8000/health
```

## Marketplace Publish Steps

Phase 0 Gate 0 found that CardioTriage is usable in Prompt Opinion as a
WORKSPACE-ONLY listing. Public Marketplace publishing may require subscription
publishing enablement.

1. Open Prompt Opinion.
2. Go to Configuration -> MCP Servers -> Add.
3. Friendly name: `CardioTriage MCP Server`.
4. Endpoint: `https://claudiomedina17--mcp.modal.run/mcp`.
5. Transport: Streamable HTTP.
6. Authentication: No authentication / open.
7. Save and verify that the server appears in the workspace MCP server list.
8. Confirm `/health`, `initialize`, and `tools/list` expose six tools.
9. Use screenshots from the workspace Manage view as Marketplace evidence if
   public listing remains unavailable.

See [`docs/MARKETPLACE_VERIFICATION.md`](docs/MARKETPLACE_VERIFICATION.md).

## BYO Agent Demo

Open or create the Prompt Opinion BYO Agent named `CardioTriage Demo`.

1. Tools tab: attach `CardioTriage MCP Server`.
2. System Prompt tab: paste [`docs/BYO_AGENT_SYSTEM_PROMPT.md`](docs/BYO_AGENT_SYSTEM_PROMPT.md).
3. Save.
4. Run: `Triage Case B end-to-end. Use Spanish for the handoff.`
5. Expected trace: all six tools in order, including `interpret_12_lead_ecg`,
   with `chagas_suspect_demo_score` around `0.925` and
   `calibration_status="uncalibrated_demo"`.

Offline deterministic cache skeletons live in
`cardiotriage_core/demo_cache/run_case_{a,b,c}.json`; rationale and final PO
handoff text remain `TODO_LIVE_CAPTURE` until Claudio captures real UI runs.

## License

MIT. See [`LICENSE`](LICENSE).

## Acknowledgements

- ECGFounder by PKUDigitalHealth (MIT license), used for ECG foundation-model
  embeddings.
- CODE-15 / Ribeiro et al., Zenodo 4916206, CC-BY 4.0, for public
  de-identified ECG demo samples.
- SaMi-Trop / PhysioNet Challenge 2025 for the Chagas-cohort public
  de-identified ECG demo sample.
- Bern et al., CDC 2007, for Chagas disease clinical grounding.
- Nunes et al., JACC 2013, for Chagas cardiomyopathy clinical grounding.
- Anthropic Claude Haiku for the planned Prompt Opinion BYO Agent narrative
  layer; this repository does not run live LLM API calls during deterministic
  cache generation.

## Disclaimer

> NOT FOR CLINICAL USE. This software is a hackathon demonstration. Demo data
> only: synthetic FHIR metadata plus public de-identified ECG samples. Scores
> are uncalibrated demo scores, not clinical probabilities. A licensed
> clinician must validate all findings and actions.