/just-prs-mcp

name: just-prs-mcp
description: >-
  Compute evidence-aware polygenic risk scores from a local VCF or WGS file
  through the validated just-prs engine and a pinned local just-prs MCP server.
license: MIT
metadata:
  version: "0.1.1"
  author: Anton Kulaga
  domain: genomics
  tags:
    - polygenic-risk-score
    - personal-genomics
    - model-quality
  inputs:
    - name: input_vcf
      type: file
      format:
        - vcf
        - vcf.gz
        - vcf.bgz
      description: Local single-sample VCF containing genotypes
      required: true
  outputs:
    - name: report
      type: file
      format:
        - md
      description: Evidence-aware PRS interpretation report
    - name: result
      type: file
      format:
        - json
      description: Machine-readable model results and uncertainty signals
    - name: scores
      type: file
      format:
        - csv
      description: Per-model scores and interpretation fields
  dependencies:
    python: ">=3.11"
    packages:
      - fastmcp>=3.4.4,<4
      - typer>=0.27.0,<1
  demo_data:
    - path: examples/demo_patient.vcf
      description: Synthetic three-variant GRCh38 VCF used with a cached response
  endpoints:
    cli: uv run --extra just-prs python skills/just-prs-mcp/just_prs_mcp_bridge.py --input {input_file} --trait {trait} --output {output_dir}
  openclaw:
    requires:
      bins:
        - uvx
    always: false
    emoji: "🧬"
    homepage: https://github.com/dna-seq/just-prs-mcp
    os:
      - darwin
      - linux
    install:
      - kind: uv
        command: uv sync --extra just-prs
    trigger_keywords:
      - compute PRS from VCF
      - WGS polygenic risk score
      - evidence-aware PRS from VCF
      - just-prs

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

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 an