Failures

Failures — Build for failure, not just success.

A deterministic MCP server that makes coding agents reason about failure modes — via AST checks with line evidence and confidence scores, not prompts. Zero tokens, zero hallucination.

Coding agents write happy-path code because their training data is happy-path tutorials. Failures gives them 11 engineering invariants (atomicity, idempotency, timeout/ambiguous outcome, concurrency, ordering, consistency, availability, resource exhaustion, recovery, observability, retry safety) checked deterministically before code ships.

Live on PyPI: pipx install failures-mcp — see INSTALL.md.

📄 Published: "Failures: Deterministic Failure-Mode Guardrails Make Coding Agents Build Resilient Systems" — https://doi.org/10.5281/zenodo.22966362 (record · PDF). Empirical study across 6 scenarios and 3 coding agents. Paper source in docs/paper/; rebuild every table from the evaluation artifacts with python tools/build_paper_pdf.py.

Failures MCP

Install it and your agent starts asking:

• What happens if the provider succeeds but the response is lost?
• Can this be retried safely? What if it happens twice?
• What if two requests modify this record concurrently?

pipx install failures-mcp
failures-mcp

{
  "mcpServers": {
    "failures": {
      "command": "failures-mcp",
      "args": []
    }
  }
}

13 tools: get_principles, review_architecture, analyze_component, generate_failure_cases, review_code, generate_failure_tests, check_idempotency, check_retry_safety, check_transaction_safety, review_plan, check_invariant, review_code_semantic, list_failures.

Knowledge base: principles/ · patterns/ · failures/ · FAILURES_SPEC.md · mcp/README.md

Benchmark (reproducible)

24 adversarial scenarios + 6 blind agent evaluations. Reproduce:

python examples/run_benchmark.py          # naive vs improved, ALL PASS
python evaluation/run_evaluation.py --mode proxy

• Harness: examples/run_benchmark.py, evaluation/run_evaluation.py
• Adversarial cases: evaluation/adversarial/
• Results + methodology: evaluation/README.md

Main folders

• mcp_server/ + mcp/ MCP server for coding agents
• principles/ failure dimensions (human docs)
• patterns/ engineering patterns (idempotency-key, outbox, circuit breaker)
• failures/ concrete failure scenarios
• evaluation/ blind evaluation harness (baseline vs Failures-enabled)
• examples/ golden benchmark (naive vs improved)
• website/ docs site + interactive labs
• docs/ guides, roadmap, and progress notes
• exercises/ the original hands-on learning path these principles were distilled from
• components/ system-building phase
• reference/ finished examples
• tools/ scripts for running and testing the project

The learning path (where the principles came from)

The exercises below are the original hands-on path — kept because the MCP's principles were distilled from them, not as the product itself:

Phase 1: learn the basics

1. Database connection pools
2. Network retries and timeouts
3. Rate limiting

Phase 2: build a small system

1. Authentication system
2. More components, only if you want to keep going

Simple way to begin

pip install -r requirements.txt
code exercises/ex1_db_starter.py

Work through the TODOs, one method at a time, and run the file often.

Start here:

1. docs/START_HERE.md
2. docs/LEARNING_GUIDE.md
3. exercises/README.md

Helpful commands

python tools/launcher.py
python tools/test_scenarios.py
code docs/ROADMAP.md
code docs/MY_PROGRESS.md

If you feel stuck

That is normal. Read the error, make one small change, and try again. The goal is steady progress, not speed.