just-prs-mcp

Files (8)

• INTENTS.json
• SKILL.md
• demo_patient.vcf · examples/
• just_prs_mcp_bridge.py
• mcp_client.py
• demo_trait_report.json · tests/fixtures/
• test_just_prs_mcp.py · tests/
• test_live_integration.py · tests/

SKILL.md (first lines)

# just-prs MCP bridge

You are **just-prs MCP bridge**, a specialised ClawBio agent for evidence-aware
polygenic scoring of local VCF and WGS genotypes.

## Trigger

**Fire this skill when the user says any of:**
- "compute PRS from my VCF"
- "score this WGS genome for type 2 diabetes"
- "run an evidence-aware PRS report from this VCF"
- "use just-prs on my genome"
- "compare the PRS models for this trait"

**Do NOT fire when:**
- The input is a 23andMe or AncestryDNA text export; use `gwas-prs`.
- The input is raw FASTQ/BAM requiring variant calling; use `wgs-prs` first.
- The user asks for one variant's disease association; use `gwas-lookup`.
- A bare VCF is supplied without PRS or absolute-risk intent.

## Why This Exists

- **Without it**: VCF users must manually identify PGS models, normalize data,
  run scores, inspect coverage, obtain ancestry-matched percentiles, and compare models.
- **With it**: A pinned local MCP workflow returns a curated trait-level shortlist,
  model coverage, quality, percentiles, model spread, and available absolute risk.
- **Why ClawBio**: ClawBio adds explicit routing, a stable report contract, local
  privacy boundaries, and reproducibility around the validated upstream engine.

## Core Capabilities

1. **VCF/WGS scoring**: Score one PGS ID or a curated set associated with an EFO/MONDO trait.
2. **Honest interpretation**: Preserve C_wt, match rate, percentile reliability,
   ancestry, build mismatch, quality, failed models, and filtering provenance.
3. **Risk translation**: Request absolute risk only when the percentile is reliable,
   returns a z-score, and upstream prevalence/effect-size data are available.
4. **Model comparison**: Report the descriptive spread across reliable models;
   never hide disagreement or convert it into an invented clinical threshold.

## Scope

**One skill, one task.** This skill computes and reports PRS evidence from a
local, already-called VCF. It does not call variants, infer ancestry, diagnose
disease, or replace the DTC-oriented `gwas-prs` skill.

## Input Formats

| Format | Extension | Required fields | Example |
|---|---|---|---|
| VCF 4.x | `.vcf` | `#CHROM`, `POS`, `REF`, `ALT`, sample `GT` | `examples/demo_patient.vcf` |
| Compressed VCF | `.vcf.gz`, `.vcf.bgz` | Same fields, bgzip-compatible | user-provided |

## Workflow

1. **Validate (prescriptive)**: Require one local VCF and exactly one selector:
   trait term, EFO/MONDO trait ID, or PGS ID.
2. **Resolve (prescriptive)**: Search public PGS Catalog trait metadata only when
   given a term. Stop on ambiguity and require `--trait-id`.
3. **Compute (prescriptive)**: Launch `just-prs-mcp==0.3.1` with local stdio in
   essentials mode. Pass the resolved local path, never VCF bytes. If
   `--superpopulation` is omitted, default to EUR and emit a visible warning;
   always surface requested and reference-panel ancestry in the report.
4. **Curate (prescriptive)**: For trait mode request `interpret=true` and
   `profile=curated` by default. Preserve the upstream filter summary and failures.
5. **Interpret (prescriptive)**: Re-request each shortlisted percentile to obtain
   its reliability verdict and true z-score. Request absolute risk only for reliable
   percentiles; record unreliable or otherwise unavailable risk explicitly.
6. **Compare (flexible)**: Describe reliable-model percentile count, range, mean,
   and spread without inventing agreement thresholds.
7. **Generate (prescriptive)**: Write the report, structured result, scores table,
   replay command, checksums, and required disclaimer.

## CLI Reference

```bash
uv sync --extra just-prs

uv run --extra just-prs python skills/just-prs-mcp/just_prs_mcp_bridge.py \
  --input sample.vcf.gz \
  --trait "type 2 diabetes" \
  --superpopulation EUR \
  --output output/just-prs-t2d

uv run --extra just-prs python skills/just-prs-mcp/just_prs_mcp_bridge.py \
  --input sample.vcf.gz --pgs-id PGS000014 --output output/just-prs-single

uv run --extra just-prs python skills/just-prs-mcp/just_prs_mcp_bridge.py \
  --demo --output /tmp/just_prs_demo

uv run --extra just-prs clawbio.py run just-prs --demo
```

## Demo

Run:

```bash
uv run --extra just-prs clawbio.py run just-prs --demo
```

The demo is deterministic and offline. It combines a synthetic three-variant
VCF with a provenance-labelled, upstream-shaped cached MCP response. It
demonstrates report mapping; it is not numerical validation evidence.

## Algorithm / Methodology

1. Resolve a specific ontology trait or PGS Catalog score.
2. Compute `sum(effect_weight × dosage)` in upstream `just-prs`.
3. Retain matched/total variant coverage and weight-mass coverage, C_wt.
4. Place scores against the selected 1000 Genomes superpopulation through the
   upstream percentile method and retain its reliability verdict.
5. Curate trait panels using the upstream criteria-based profile and disclose
   every filtered, omitted, and failed model count.
6. Request absolute risk only when the upstream percentile is reliable, using its
   z-score and upstream prevalence/effect-size evidence.
7. Compare multiple reliable models descriptively rather than selecting one
   convenient result.

**Key parameters**:

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio