stratum-mcp 0.2.27

Stratum MCP server for Claude Code — structured execution, typed contracts, postcondition enforcement

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