just-prs-mcp: Instructions file for Codex

AGENTS.md

Guidance for coding agents (Claude Code, Cursor, Codex, Antigravity, …) working in this repository. Humans: see README.md.

What this is

An MCP server wrapping the just-prs library (PGS Catalog + polygenic risk score computation). Built on uv + FastMCP. It started life as a generic FastMCP template; the cake demo has been replaced with real PRS tools, but the template's patterns (mode gating, structured I/O, in-memory tests) are kept.

Pre-configured Test Genomes

For testing, benchmarking, or demonstration purposes, two public whole-genome sequencing (WGS) datasets are pre-configured in the server's download_sample_genome tool:

• Anton Kulaga's Genome (CC0 / Public Domain): Zenodo Record 18370498
  • VCF File: antonkulaga.vcf (~482 MB)
  • Parameter: sample="anton"
• Livia Zaharia's Genome (CC-BY-4.0): Zenodo Record 19487816
  • VCF File: SIMHIFQTILQ.hard-filtered.vcf.gz (~349 MB)
  • Parameter: sample="livia"

Quick Play for Agents:

If you are asked to demonstrate or test any PRS computation or VCF normalization, you can download and use these genomes automatically:

1. Call download_sample_genome(sample="anton") or download_sample_genome(sample="livia").
2. The download can take several minutes. It auto-normalizes by default (auto_normalize=True), so on success data carries both path (raw VCF) and normalized_path (reusable Parquet). Pass auto_normalize=False for the raw VCF only.
3. Compute tools accept data["path"] directly. The normalized path is only an optional fast path for repeated reuse: pass it to compute_prs / compute_prs_batch (as genotypes_path), or to compute_prs_by_trait as samples=["Label=<normalized_path>"] (one genome is a one-element list).

Both the download and the normalization are idempotent (size-matched VCF / existing Parquet are reused; reused_cache / normalized_reused flag the hit). A user's own local VCF does not need an explicit normalize_vcf call: pass it directly to compute. Use normalize_vcf only when deliberately creating a reusable Parquet or applying custom normalization filters; check list_genomes first for an existing cached Parquet. Multi-score tools transparently prepare/reuse that cache by default (PRS_MCP_AUTO_CACHE_VCF_FOR_BATCH=true). Arbitrary local VCF cache names include a hash of the resolved source path, so same-basename files from different families cannot collide. Reuse requires readable Parquet at least as new as the VCF; custom filter configurations get distinct suffixed cache paths.