petri-labs-mcp

A local Model Context Protocol server that lets an LLM agent run reproducible, statistically-tested experiments on the petri-labs emergent-systems simulations — the same engines and statistics the in-browser Hypothesis Labs use, exposed as agent-callable tools.

An agent states a hypothesis, maps it to a control vs treatment, calls run_experiment, and gets back a comparison with Wilcoxon / Mann-Whitney tests, Holm-Bonferroni correction, effect sizes (Cliff's delta / rank-biserial) and confidence intervals — deterministically. No account, no network, no GPU.

Models

| id | domain | what emerges | |----|--------|--------------| | origin | artificial life | neural-net organisms evolve, hunt, speciate | | swarm | collective intelligence | flocking / order from three local boid rules | | morph | pattern formation | Gray-Scott reaction-diffusion (spots, stripes, mazes) | | market | emergent economics | order-book agents → bubbles, crashes, fat tails | | social | opinion dynamics | consensus, polarization, echo chambers on networks |

Tools

• list_models() — the available simulations.
• describe_model({ model }) — tunable params (ranges + defaults), output metrics, valid primaryMetric values, presets, and run limits.
• list_presets({ model }) — curated named regimes with their config.
• run_simulation({ model, seed?, ticks?, sampleEvery?, config?, preset? }) — one deterministic trajectory: a sampled metric series + final aggregate metrics.
• run_experiment({ model, control, treatment, primaryMetric, replicates?, ticks?, seedBase? }) — a replicated control-vs-treatment comparison with a full statistical report.

The server is pure and deterministic: the calling agent designs the experiment (control/treatment configs); the server runs it and reports the statistics. The same seedBase reproduces the same result.

Use it with an agent

Add it to your MCP client config (Claude Desktop, Claude Code, Cursor, …).

After it is published to npm:

{
  "mcpServers": {
    "petri-labs": { "command": "npx", "args": ["-y", "petri-labs-mcp"] }
  }
}

From a local checkout of the monorepo (build first: npm run build -w packages/mcp):

{
  "mcpServers": {
    "petri-labs": { "command": "node", "args": ["/abs/path/petri-labs/packages/mcp/dist/cli.js"] }
  }
}

Try it standalone with the MCP Inspector:

npm run build -w packages/mcp
npx @modelcontextprotocol/inspector node packages/mcp/dist/cli.js

Example agent flow

1. describe_model({ model: "market" }) → learn the params (chartFrac, fundFrac, …) and metrics (volatility, kurtosis, maxDrawdown, …).
2. Map a hypothesis ("more chartists → fatter tails") to a contrast.
3. run_experiment({ model: "market", control: { chartFrac: 0.1 }, treatment: { chartFrac: 0.5 }, primaryMetric: "kurtosis", replicates: 20 }).
4. Read the returned report: per-metric means + CIs, the test p-value, the Holm-corrected p, the effect size, and a plain-language verdict.

Notes

• A statistical-significance caveat worth respecting: with simulations you can make the replicate count arbitrarily large, so p-values get cheap — read the effect size and its confidence interval, not just the p-value.
• Part of petri-labs. Built by Baris Sozudogru. MIT.