Polya MCP server
Commit Nov 9, 2026Provides AI agents with typed operations for cipher decoding, symbolic constraints, automata, and exact candidate checks.
Also known as Amal-David/polya
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is Polya MCP?
Polya provides AI agents with typed operations for cipher decoding, symbolic constraints, automata, and exact candidate checks.
Summary generated from the project's README
About Polya MCP server
Solving complex puzzles and mathematical constraints through AI agents is what Polya enables. It provides a structured set of typed operations for tasks involving cipher decoding, symbolic constraints, automata, and exact candidate checks. Developers can use it as a local stdio MCP server or deploy it via a remote HTTPS adapter to allow agents to search for and execute specific computational strategies.
Users interact with the system using tools like puzzle.find to discover operations and puzzle.run to perform bounded computations. The server supports a wide range of specialized tasks, including polyalphabetic cipher decoding, finite constraint enumeration with constraints.solve, and automata simulation. It is designed for agents that need to inspect operation contracts, run specific recipes like cipher.polyalphabetic, or perform cryptographic checks such as crypto.target_check for SHA256 and P2PKH. The system relies on Python 3.11 through 3.15 and can integrate optional backends like Z3 or CP-SAT for advanced symbolic solving.
What you can do with it
- 1Decode polyalphabetic ciphersAn agent can decode a Vigenere ciphertext by providing the specific key and variant to the polyalphabetic operation.
- 2Solve finite constraint systemsA developer can task an agent with finding all valid assignments for a set of binary variables within a finite system.
- 3Discover puzzle operationsAn agent can search the available catalogue to find a specific mechanism like Vigenere and inspect its required input schema.
- 4Verify cryptographic targetsAn agent can perform specific checks on cryptographic outputs like SHA256 or P2PKH patterns.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableamal-david/polya is public and reachablegithub.com/amal-david/polya ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/amal-david/polya ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubPolya gives AI agents operations for cipher decoding, symbolic constraints, automata and exact candidate checks. Python, a JSON CLI and a stdio MCP server share the same contracts. The agent picks the strategy; each operation does one bounded computation and says what its result covers.
See it work
Three short CLI recordings, using synthetic inputs and the base install.
Find an operation and inspect its input. Search for Vigenere, then ask for a ready-to-run JSON example.

Decode a supplied cipher. With key LEMON, LXFOPVEFRNHR becomes
ATTACKATDAWN. The result includes source offsets and the transformation's scope.

Enumerate a finite constraint system. Two binary variables must differ.
Polya returns both assignments and reports COMPLETE after exhausting this system.

Copy the commands or re-record the demos.
Quick start
python -m pip install "git+https://github.com/Amal-David/polya.git"
The distribution will be polya-puzzles on PyPI; publication is pending.
Optional extras (images, Z3, CP-SAT, AALpy) are listed in
getting started.
polya find vigenere --limit 1
polya inspect cipher.polyalphabetic --example
polya run cipher.polyalphabetic --result-only \
--json '{"text":"LXFOPVEFRNHR","key":"LEMON","variant":"vigenere"}'
The decoded text is ATTACKATDAWN. Omit --result-only to include the execution
receipt. Use polya list for the full catalogue, or polya inspect <operation_id>
for its contract; add --schema for the full JSON schema.
The same Vigenere example in Python:
from polya import run
result = run("cipher.polyalphabetic", {
"text": "LXFOPVEFRNHR",
"key": "LEMON",
"variant": "vigenere",
})["result"]
assert result["text"] == "ATTACKATDAWN"
Use with agents
Run polya mcp as a local stdio server, or deploy the included
remote HTTPS adapter to Render. Both expose
puzzle.find to search for or inspect an operation, and puzzle.run to execute one.
Start with the complete agent workflow for evidence,
model checks, experiment choice, execution and continuation. See also
MCP and agent setup.
Investigation council
Use the evidence-first council and investigation guide for evidence packets, local artifact handles, next-test ranking, bounded unknown-key proposals and matched agent evaluation. Four read-only subagent definitions are included; the host supplies actual model execution. No vote is treated as proof.
For educational puzzles, source-backed method selection
adds six cited teaching cases, method.retrieve, and offline fresh-context/evaluation
helpers. These are development references; no learned solving gain is claimed.
What it covers
| Area | Operations |
|---|---|
| Image evidence | artifact.png_bitplane: lossless PNG channel and bit selection with source hashes and pixel coordinates |
| Ciphers and decoding | cipher.polyalphabetic, cipher.bifid, cipher.checkerboard, cipher.periodic_cribs, grid.traverse, text.symbol_map, bytes.from_radix |
| Mechanism search | mechanism.recipe_scan over recipe products; mechanism.plan_scan over typed artifact-to-target plans with resumable paging |
| Crypto targets | crypto.openssl_scan calibrated multi-lock scans, crypto.target_check SHA256 and P2PKH checks, pattern.equality_check whole-output patterns |
| Constraints | symbolic.solve, symbolic.analyze, hypotheses.compare over Z3, CP-SAT or a reference solver; constraints.solve for finite tables |
| Automata | automata.simulate_many, automata.distinguish for shortest distinguishing inputs, automata.learn_local for bounded active learning |
| Mathematics | jacobian.find and jacobian.run delegate to an optional, separately installed Jacobian runtime |
Every operation is listed in the operation reference.
Scope and limits
Results describe the model and inputs you supply, not the puzzle author's intent.
UNKNOWN, timeouts and unavailable backends are not negatives; valid padding is
not a solution; bounded conformance does not prove equivalence. Source labels are
caller claims, and receipts are not independent reproduction. Raw audio and
semantic image interpretation are not implemented. No new open-puzzle solve or
agent speedup is claimed.
Documentation
- Getting started: install matrix, first run, discovery
- Operation reference: every operation contract, generated from the registry
- Guides: ciphers, constraints, automata, plans, execution and evaluation, Jacobian
- Agents: workflow, MCP, investigating, setup
- Internals: architecture, performance, Python support, scope, adversarial review
- Examples and history (past validation and change records)
Development
python -m pip install -e ".[test,imaging,z3,learning]"
python -m pytest -q
Pre-stable. See contributing and the maintainer guide in AGENTS.md.
Inspired by Jacobian. MIT; catalogue attribution is in third-party notices.
For compound crypto experiments, use preflight and typed pipelines to compose the existing ciphers, extraction steps and exact checks without custom glue.
Polya MCP questions
What kind of operations can Polya perform?
Polya provides operations for cipher decoding, symbolic constraints, automata, and exact candidate checks.
Can I search for specific operations?
Yes, you can use the puzzle.find tool to search for or inspect operations.