Just PRs MCP

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

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

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:

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:

• Superpopulations: AFR, AMR, EAS, EUR, SAS (1000 Genomes).
• Default profile: curated (criteria owned by just-prs-mcp, not ClawBio).
• Default returned models: 5, ranked by the upstream coverage-aware ordering.

Example Queries

• "Compute my type 2 diabetes PRS from this GRCh38 VCF."
• "Use PGS000014 on this WGS callset and show absolute risk if available."
• "Do the reliable models agree on my coronary artery disease percentile?"

Example Output

# just-prs Polygenic Risk Report

## Model agreement
- Reliable models: **2**
- Verdict: **descriptive_spread_only**
- Reliable percentile range: **61.00–74.00**
- Descriptive percentile spread: **13.00**

## Score details
| PGS ID | Status | Percentile | Reliable | C_wt | Quality | Absolute risk |
|---|---|---:|---|---:|---|---|
| PGS000014 | scored | 74.00 | True | 94.0% | High | 18.0% |
| PGS000013 | scored | 61.00 | True | 91.0% | Normal | unavailable |

Output Structure

output_directory/
├── report.md
├── result.json
├── tables/
│   └── scores.csv
└── reproducibility/
    ├── commands.sh
    └── checksums.sha256

Dependencies

Required:

• uvx; launches the isolated Python 3.13+ upstream server.
• fastmcp in the just-prs optional extra; Python 3.11-compatible client.
• typer in the just-prs optional extra; typed CLI.

Optional:

• A warm upstream cache; avoids repeat downloads but does not change results.

The upstream cache defaults to the platform-specific just-prs cache. Override it with PRS_MCP_CACHE_DIR when a controlled shared cache is required.

Validation Evidence

• Upstream just-prs/tests/test_cross_engine.py checks numerical parity across PLINK2, Polars, and DuckDB scoring engines.
• Upstream test_scoring.py, test_vcf.py, and test_percentile.py cover scoring files, VCF/build handling, and percentile/z-score consistency.
• This bridge tests its integration boundary: pinned real stdio MCP calls, FastMCP result decoding, local-path-only requests, report mapping, routing, packaging, unreliable-risk suppression, and offline demo reproducibility.
• ClawBio does not reimplement or claim independent validation of the upstream numerical engine; it reuses that evidence and tests its own adapter behavior.