io.github.terradev-cloud/entropy

entropy-mcp

Entropy gives agents randomness they cannot produce themselves, and proof they did not manipulate it.

The evidence

Language models cannot generate statistically sound randomness. This is measured, not speculative:

• arXiv:2601.05414 — 11 frontier models, 15 distributions: 7% median pass rate in batch mode; 10 of 11 models passed zero distributions in stateless mode.
• arXiv:2604.06543 — the knowing-doing gap: models can describe correct sampling and still fail to do it. Asking a model to generate its own seed reproduces the same bias.
• arXiv:2606.06622 — UnpredictaBench: models are measurably predictable where they should be random.

The stateless point

Agents operate in exactly the regime where models fail hardest: independent, stateless calls with no memory of prior draws. Every "pick a random number" an agent answers from its own weights is a draw from a biased, predictable source. Entropy moves the draw out of the model and into the OS CSPRNG — and the commit-reveal chain proves the draw that happened is the draw that was reported.

Install

pip install entropy-mcp          # stdio core + stamp-mcp dependency
pip install entropy-mcp[http]    # adds the aiohttp HTTP transport

Quickstart

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"commitment","arguments":{
  "operation":"draw",
  "draw_spec":{"operation":"shuffle","params":{"items":["alice","bob","carol","dave"]}},
  "description":"who goes first"}}}

One call returns the shuffled list plus a commitment record, a reveal record, and a verification block — the full chain a third party can check with commitment operation:"verify".

Command reference

Four tools. operation selects the primitive; params carries its arguments; seed makes any draw reproducible.

Every seeded command is deterministic given its inputs and seed — byte-identical across processes, machines, and Python versions. Only the raw OS-entropy paths are non-deterministic, and they say so.

How commit-reveal works

1. commit generates (or accepts) a 32-byte seed, stores only sha256(seed), binds it to your draw spec via canonical hash, timestamps it via Stamp's NTP, optionally anchors it to a drand round, and attests the whole record. The seed goes to you. It is never stored server-side.
2. reveal takes the seed back, verifies it hashes to the committed seed_hash, re-executes the draw deterministically, and attests the outcome.
3. verify_chain checks, independently of any server state:

What this is not

• Not a statistics package — the summary block and test battery are conveniences, not an analysis suite.
• Not a simulation engine — no Monte Carlo, no sensitivity analysis, no fitting.
• Not a randomness beacon — drand anchoring is optional hardening, not a source.
• Not NIST-certified — the test battery is informed by SP 800-22, in the spirit of it.

Configuration

Threat model

See THREAT_MODEL.md. The honest summary: Entropy proves a draw was not manipulated; it cannot prove a draw was not discarded.

License

Apache 2.0.