breedsim-mcp

breedsim-mcp

breedsim-mcp is an MCP server that lets AI agents run AlphaSimR breeding-program simulations. It returns the spread over replicates, never a single stochastic run, so an agent can say what a selection scheme would gain and how sure that is.

[CI] [PyPI] [Python] [License] [DOI] [Glama]

Why replicates

A single simulation run is not a result, and this API will not return one. Five seeds of an identical three-cycle program gave mean genetic gain [1.151, 1.841, 1.424, 1.429, 1.473], sd 0.247, on the very number being reported (measured once on AlphaSimR 2.1.0 while building v0.1.0, 2026-07-29). So run_program enforces a replicate floor and returns a per-cycle mean, sd and confidence interval. No flag collapses it to a point estimate.

Install

This needs more than uv pip install:

• R ≥ 4.3 with a shared library (libR.so)
• AlphaSimR, an Rcpp/RcppArmadillo compile that takes minutes
• libtirpc-dev, or rpy2 fails to link (cannot find -ltirpc)
• rpy2 <3.6, because 3.6 binds R_getVar, which needs R ≥ 4.4

sudo apt-get install -y r-base r-base-dev libtirpc-devR -e 'install.packages("AlphaSimR", repos="https://cloud.r-project.org")'uv add breedsim-mcp

Do not use a conda Python: rpy2 then fails to load libR.so with GLIBCXX_3.4.30 not found, because conda ships an older libstdc++ than the system libicuuc requires. Use a system or uv-managed interpreter. Requires mcp 2.x.

Configure your MCP client

The server speaks stdio through the breedsim-mcp console script.

Claude Code

claude mcp add breedsim -- breedsim-mcp

Claude Desktop (claude_desktop_config.json):

{  "mcpServers": {    "breedsim": {      "command": "breedsim-mcp"    }  }}

If the executable is not on your PATH, or AlphaSimR lives in a user library, run it through uv and pass the library path:

{  "mcpServers": {    "breedsim": {      "command": "uv",      "args": ["run", "--directory", "/path/to/breedsim-mcp", "breedsim-mcp"],      "env": { "R_LIBS_USER": "/home/you/R/library" }    }  }}

Check it with list_methods(), which reports the engine versions and whether this process can currently produce reproducible results.

What the benchmark shows

Claude with the server was compared with Claude writing its own AlphaSimR scripts, with R and AlphaSimR installed for it, on 34 breeding-simulation questions, 3 runs each. A tie means the server matches that result without you setting up R and AlphaSimR. Questions right in every run, server against Claude's own scripts: Claude Haiku 5.5 34 against 33, Sonnet 5.5 28 against 33, Opus 5.5 34 against 34 (re-run 2026-10-18). None is separated (pre-registered; Holm-adjusted McNemar p = 1.0 on Haiku, 0.25 on Sonnet). Sonnet's gap is runs where it answered from breeder's-equation theory instead of running the simulation. The server was cheaper with Haiku (on 26 of 34 questions) and dearer with Sonnet and Opus. Opus with no tools got 51 of 102 answers right.

[Stacked bar chart of right and wrong answers to 34 breeding-simulation questions, 3 runs each. Claude alone: 51 right, 51 wrong. Claude with Bash, R and web: 99 right, 3 wrong. Claude with breedsim-mcp: 102 right, 0 wrong. No-LLM baselines, one answer per question: one constant per kind of question, 12 right and 22 wrong; best closed form per question, 15 right and 19 wrong.]

The chart is the first Opus 5.5 run, keyed by AlphaSimR run directly; the best named formula lands in only 15 of 34. With this server Claude got 102 of 102 answers right, with its own R and AlphaSimR 99 of 102 (not separated, exact McNemar p = 1.0), and alone 51 of 102 (both tool setups beat it, p < 1e-6). The re-run, with an unreleased commit that cut the server's instructions and rounded its outputs, got 102 of 102 in both setups and lowered the server's median cost per answer from $0.051 to $0.033; Claude's own scripts cost $0.027, cheaper on all 34 questions (p = 1e-10). Time is not separated.

Each question spells out the AlphaSimR calls, so this tests running a stated simulation, not designing one unaided. We wrote the questions and ran the benchmark ourselves; an outside re-run is welcome. Method, controls, other limitations, and six probability questions reported separately are in benchmarks/agent_qa; the Haiku and Sonnet runs: 2026-10-20 re-run.

Tools

Typical loop: found_population → run_program → read the CI and the warnings. To compare two schemes: found_population → compare_programs → read difference. run_program takes selection_method="phenotypic" or "genomic"; compare_programs takes one per arm.

docs/REFERENCE.md has the full tool signatures, example outputs, the warnings table, and the measurements behind the points below.

• Compare with compare_programs, not two run_program calls. It runs both arms on the same seeds and differences them within each pair, so shared luck cancels. Two overlapping per-program intervals do not imply no difference; the paired interval can still exclude zero (warning overlap_but_different). favours is null when the paired interval contains zero.
• Genomic selection needs linkage disequilibrium. selection_method="genomic" fits RRBLUP to a SNP chip set at founding (n_snp_per_chr). quickHaplo, the default and the only reproducible generator, has no LD, so use runMacs, which does not reproduce in a long-lived process. On this engine you cannot have both. found_population measures LD and warns (no_linkage_disequilibrium) when the markers are uninformative.
• Reproducibility. The server pins OMP_NUM_THREADS=1 at import, before R starts; without it the same seed gives different results. The runMacs RNG is seeded once per R session and advances across calls, so a repeat call in this long-lived process differs (reproducible: false).
• Warnings explain; none of them withhold results.
• Multi-trait selection. Pass h2 as a list and index_weights to select on a weighted index. trait_correlation must be a real correlation matrix (for n equally correlated traits, not below −1/(n−1)); an invalid one is refused, not replaced by the nearest valid matrix. Genomic selection fits one RRBLUP model per trait, applies the index to the estimated breeding values, and reports prediction_accuracy in each traits entry.
• Species. species applies only to runMacs, which has demographic histories for GENERIC, CATTLE, WHEAT and MAIZE; anything else is refused. The default is MAIZE, but this is not a plant-only simulator.
• Limits. Every size parameter has a ceiling, listed by list_methods() under limits. R is a single interpreter and calls are serialized, so one oversized call would block every other. For large jobs, drive AlphaSimR directly.

Testing

CI installs R and compiles AlphaSimR, so the suite runs against the real engine on Python 3.11, 3.12 and 3.13. One test checks the R engine layer against the breeder's equation R = h²S (docs/EVAL.md); it does not test this server's founding or selection code against an outside reference. docs/MUTATION-CHECKS.md records 25 deliberate mutants: 24 turned a test red, and one survives because it is equivalent. tests/test_perf_ratchet.py gates each tool on exact counts of package-function calls and R evaluations, not on time.

Limitations

• compare_programs is single-trait: one paired verdict needs one criterion, and with several traits that is the index, for which AlphaSimR reports no gain.
• No G×E, optimal contribution selection, crossing-block optimization or genotype-matrix export.
• Genomic selection is RRBLUP only. RRBLUP_D, _GCA and _SCA estimate dominance and combining-ability effects that the additive-only addTraitA architecture does not have.
• Sessions are in memory, capped at 8 (LRU), and do not survive a restart.

License

GPL-3.0-or-later, because this imports rpy2, which is GPLv2+. AlphaSimR itself is MIT. Unofficial: not affiliated with, endorsed by, or sponsored by the AlphaSimR authors, the University of Edinburgh, or the R Foundation. See NOTICE.

CHANGELOG.md records what changed and why.