This project has been archived by its maintainers, and is no longer receiving any updates.
stratum-mcp
Stratum MCP server for Claude Code. Structured execution, typed contracts, postcondition enforcement — no sub-LLM calls.
Install
pip install stratum-mcp
stratum-mcp install
install configures Claude Code in one command: writes .claude/mcp.json, appends the execution model block to CLAUDE.md, installs skills to ~/.claude/skills/, and registers session hooks to ~/.stratum/hooks/. Restart Claude Code and it's active.
IR Spec (v0.3)
Stratum specs are YAML files with typed contracts, step definitions, and postcondition ensures:
version: "0.3"
contracts:
ReviewResult:
clean: {type: boolean}
summary: {type: string}
findings: {type: array}
flows:
my_flow:
steps:
- id: implement
agent: claude
intent: "Build the feature"
output_contract: ReviewResult
ensure:
- "result.clean == True"
retries: 3
Step types
| Type | Purpose |
|---|---|
inline |
Single agent step with intent + ensures (default) |
function |
Named function reference |
flow |
Sub-flow invocation |
decompose |
Agent decomposes work into a TaskGraph |
parallel_dispatch |
Fan-out tasks from a TaskGraph with concurrency control |
Parallel dispatch (v0.3)
- id: execute
type: parallel_dispatch
source: "$.steps.decompose.output.tasks"
max_concurrent: 3
isolation: worktree # worktree | branch | none
require: all # all | any | N
merge: sequential_apply
intent_template: "Implement {task.description}"
isolation: worktree— git worktree per task (write isolation)isolation: none— shared working directory (read-only tasks)require— how many tasks must pass:all,any, or integer N
Skills
| Skill | What it structures |
|---|---|
/stratum-onboard |
Read a new codebase cold and write project-specific MEMORY.md |
/stratum-plan |
Design a feature and present it for review — no implementation until approved |
/stratum-feature |
Feature build: read existing patterns → design → implement → tests pass |
/stratum-review |
Three-pass code review: security → logic → performance → consolidate |
/stratum-debug |
Debug: read test → read code → check env → hypotheses → confirm/rule out → fix |
/stratum-refactor |
File split: analyze → design modules → plan extraction order → extract one at a time |
/stratum-migrate |
Find bare LLM calls and rewrite as @infer + @contract |
/stratum-test |
Write a test suite for existing untested code |
/stratum-speckit |
Spec-kit lifecycle: spec.md → plan.md → tasks/ → .stratum.yaml → execute |
MCP Tools
| Tool | What it does |
|---|---|
stratum_validate |
Validate a .stratum.yaml spec |
stratum_plan |
Validate + create execution state + return first step |
stratum_resume |
Resume an existing flow from its current step |
stratum_step_done |
Report step result; check postconditions; return next step or completion |
stratum_parallel_done |
Report batch results for a parallel_dispatch step |
stratum_skip_step |
Skip a step (policy: skip mode) |
stratum_gate_resolve |
Resolve a gate step (approve/revise/kill) |
stratum_audit |
Return per-step trace (attempts, duration) for any flow |
stratum_check_timeouts |
Check for timed-out steps in a flow |
stratum_iteration_start |
Start an iteration loop on a step |
stratum_iteration_report |
Report iteration result (clean/dirty/max_reached) |
stratum_iteration_abort |
Abort an iteration loop |
stratum_commit |
Checkpoint flow state with a label |
stratum_revert |
Revert flow state to a labeled checkpoint |
stratum_compile_speckit |
Compile tasks/*.md into a .stratum.yaml spec |
stratum_draft_pipeline |
Generate a pipeline spec from a description |
stratum_list_workflows |
List all active and completed flows |
Building on Stratum
Stratum exposes four stable integration points for apps and tooling:
1. MCP tools (Claude Code agents)
The primary control plane — stratum_plan, stratum_step_done, stratum_audit. Used by agents running inside Claude Code.
2. Query CLI (read-side, any process)
stratum-mcp query flows # → JSON array of FlowSummary
stratum-mcp query flow <id> # → JSON FlowState
stratum-mcp query gates # → JSON array of pending gates
Exit 0, JSON to stdout. Use from shell scripts, background services, or UI backends.
3. Gate CLI (write-side, any process)
stratum-mcp gate approve <flow_id> <step_id> [--note "..."] [--resolved-by agent]
stratum-mcp gate reject <flow_id> <step_id> [--note "..."]
stratum-mcp gate revise <flow_id> <step_id> [--note "..."]
Exit codes: 0 success · 1 error (JSON on stdout) · 2 conflict (already resolved).
4. Storage schemas (contracts/)
Versioned JSON schemas for the flow state and audit record formats. Stable across internal refactors.
stratum-mcp/contracts/
flow-state.v1.schema.json
query-flows.v1.schema.json
query-gates.v1.schema.json
gate-mutation.v1.schema.json
audit-record.v1.schema.json
5. Migration CLI
stratum-mcp migrate flow.stratum.yaml # preview diff, prompt to apply
stratum-mcp migrate flow.stratum.yaml --dry-run # diff only, no write
stratum-mcp migrate flow.stratum.yaml --yes # apply without prompt
stratum-mcp migrate flow.stratum.yaml --to 0.3 # pin target version
stratum-mcp migrate flow.stratum.yaml --output new.yaml --force
stratum-mcp migrate flow.stratum.yaml --backup # save flow.stratum.yaml.bak alongside
Upgrades a spec across IR versions. Today the only registered transform is 0.2 → 0.3 (a pure version-string bump, since v0.3 is a backward-compatible superset of v0.2). The framework is extensible — future versions add a Transform entry in stratum_mcp/migrate.py::TRANSFORMS and get chained automatically.
Formatting is preserved via ruamel.yaml round-trip with source-derived indent detection; comments, blank lines, and the spec's original indentation survive the migration.
Exit codes: 0 success/no-op, 1 validation or I/O failure, 2 user declined, 3 unknown version or no transform path.
Hooks
stratum-mcp install registers three Claude Code hooks in ~/.stratum/hooks/:
| Hook | Trigger | Purpose |
|---|---|---|
stratum-session-start.sh |
SessionStart | Initialize Stratum state for the session |
stratum-session-stop.sh |
Stop | Clean up and persist session state |
stratum-post-tool-failure.sh |
PostToolUseFailure | Log tool failures for debugging |
How It Works
Claude writes .stratum.yaml specs internally — you never see them. You see plain English narration. The MCP server enforces postconditions on every step; if a step's output fails a check, Claude fixes it and retries before reporting success.
Full documentation: stratum-in-claude-code.md
Tutorial: claude-code-tutorial.md
License
Apache 2.0
1 maintainer
Release files for stratum-mcp 0.2.114
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| stratum_mcp-0.2.114.tar.gz | 421.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| stratum_mcp-0.2.114-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 654.7 kB
Release files / stratum_mcp-0.2.114.tar.gz
| Download URL | stratum_mcp-0.2.114.tar.gz |
|---|---|
| Size | 421.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0773a329a0276a07c0f5b353e4863c2bda066e2e2e8d8badf7326f2de6742a64
|
|
BLAKE2b-256 checksum How to use checksums |
37921d4f40b36ad1217f26a7456537303cb7f344389671304a1bf30110f15cc4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 12, 2026.
Transparency logRelease files / stratum_mcp-0.2.114-py3-none-any.whl
| Download URL | stratum_mcp-0.2.114-py3-none-any.whl |
|---|---|
| Size | 232.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4e1f23fd62f60173719159a363c4a2083f845b706f8de23371fe71db2172710a
|
|
BLAKE2b-256 checksum How to use checksums |
130684c0711c49ff63d70e581fe9f2d2c8ec08880e7bdd626ad87a601dd50c1f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 12, 2026.
Transparency log
