serenecode 0.2.0__tar.gz → 0.3.0__tar.gz

{serenecode-0.2.0 → serenecode-0.3.0}/.gitignore

@@ -15,6 +15,11 @@ eggs/
 venv/
 env/
 
+# Secrets / local credentials
+.env
+.env.*
+!.env.example
+
 # IDE / AI tools
 .idea/
 .vscode/

{serenecode-0.2.0 → serenecode-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: serenecode
-Version: 0.2.0
+Version: 0.3.0
 Summary: Verification framework for AI-generated Python — test coverage, property testing, and symbolic execution
 Project-URL: Homepage, https://github.com/helgster77/serenecode
 Project-URL: Repository, https://github.com/helgster77/serenecode
@@ -29,6 +29,8 @@ Requires-Dist: mypy>=1.0
 Provides-Extra: dev
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -37,9 +39,11 @@ Description-Content-Type: text/markdown
 
 <h3 align="center">A Framework for AI-Driven Development of Verifiable Systems</h3>
 
-SereneCode is a spec-to-verified-implementation framework for AI-generated Python. It ensures that every requirement in your spec is implemented, tested, and formally verified — closing the gap between what you asked for and what the AI built. The workflow starts from a spec with traceable requirements (REQ-xxx), enforces that the AI writes verifiable code with contracts and tests, then verifies at multiple levels — from structural checks and test coverage through property-based testing to symbolic execution with an SMT solver. You choose the verification depth during interactive setup: lightweight for internal tools, balanced for production systems, strict for safety-critical code. AI agents write code fast but can miss requirements and skip edge cases; SereneCode closes that gap with spec traceability, test-existence enforcement, and formal verification.
+SereneCode is a spec-to-verified-implementation framework for AI-generated Python. It ensures that every requirement in your spec is implemented, tested, and formally verified — closing the gap between what you asked for and what the AI built. The workflow starts from a spec with traceable requirements (REQ-xxx), enforces that the AI writes verifiable code with contracts and tests, then verifies at multiple levels — from structural checks and test coverage through property-based testing to symbolic execution with an SMT solver. You choose the verification depth during interactive setup: lightweight for internal tools, balanced for production systems, strict for safety-critical code.
 
-> **This framework was bootstrapped with AI under its own rules.** SereneCode's SERENECODE.md was written before the first line of code, and the codebase has been developed under those conventions from the start. The current tree passes its own `serenecode check src --level 6 --allow-code-execution`, an internal strict-config Level 6 self-check in the test suite, `mypy src examples/dosage-serenecode/src`, the shipped example's check, and the full `pytest` suite (769 passing tests, 16 skipped). The verification output is transparent about scope: exempt modules (adapters, CLI, ports) and functions excluded from deep verification (non-primitive parameter types) are reported as "exempt" rather than silently omitted.
+SereneCode also ships a built-in **MCP server** so verification runs *inside* your AI assistant's edit loop, not just at the end. Once registered with Claude Code, Cursor, Cline, or Continue, the agent calls verification tools after every function it writes — getting structured findings, contract suggestions, and counterexamples back as JSON, fixing them mid-turn, and only reporting the work complete when the result is clean. AI agents write code fast but can miss requirements and skip edge cases; SereneCode closes that gap with spec traceability, test-existence enforcement, formal verification, and an MCP-driven inner loop the agent can drive on itself.
+
+> **This framework was bootstrapped with AI under its own rules.** SereneCode's SERENECODE.md was written before the first line of code, and the codebase has been developed under those conventions from the start — including the MCP server, which the same AI agents now use to verify their own work mid-edit. The current tree passes its own `serenecode check src --level 6 --allow-code-execution` end-to-end via the bare CLI (718 functions checked, 557 passed, 161 exempt; ~6 minutes wall time), an internal strict-config Level 6 self-check in the test suite (`pytest tests/integration/test_example_projects.py::test_serenecode_repo_passes_strict_level_6`, which exercises L4-L6 against `strict_config` over the full source tree), `mypy src examples/dosage-serenecode/src`, the shipped dosage example's own `serenecode check src --level 6 --allow-code-execution`, and the full `pytest` suite (1,393 passing tests, 16 skipped). The verification output is transparent about scope: exempt modules (adapters, CLI, ports, MCP server, `__init__.py`) and functions excluded from deep verification (non-primitive parameter types) are reported as "exempt" rather than silently omitted.
 
 ---
 
@@ -49,6 +53,34 @@ AI writes code fast. But *fast* and *correct* aren't the same thing. When you're
 
 The problem is that formal verification has always been expensive — too slow, too manual, too specialized. SereneCode makes it tractable by controlling the process from the start: a convention file tells the AI to write verification-ready code, a structural linter checks it followed the rules, and CrossHair + Z3 search for contract violations via symbolic execution.
 
+### Common AI failure modes SereneCode is built to catch
+
+After enough hours pair-programming with coding agents, the same handful of mistakes show up over and over. They're not random bugs — they're systematic patterns that follow from how a language model writes code: optimize for the happy path, infer intent from limited context, finish the visible task, leave implicit assumptions implicit. SereneCode treats each one as a verification target rather than a code-review target.
+
+- **Skipping requirements without realizing it.** Given a spec with twelve requirements, the agent writes code that handles eight of them confidently and quietly omits the four it didn't see a clean place for. There's no error, no TODO — just missing behavior. SereneCode's spec traceability (REQ-xxx tags, `Implements:` / `Verifies:` references, the `serenecode_orphans` and `serenecode_req_status` tools) makes it impossible for a requirement to be silently dropped: every REQ in SPEC.md must be both implemented and tested or it shows up as an orphan.
+
+- **Happy-path tests only.** Asked to "add tests," the agent writes a handful of cases that walk the obvious path through the function. Edge cases (empty input, off-by-one boundaries, the exact threshold value, the negative number, the unicode string) are routinely missed because they require imagining what could go wrong. L3 coverage catches uncovered branches; L4 Hypothesis property testing generates inputs the agent never thought of and runs them against the contracts.
+
+- **Stub residue and "I'll come back to this."** A function the agent didn't quite know how to write often ships as `pass`, `...`, or `raise NotImplementedError("TODO")` — and then never gets revisited because the test suite doesn't fail on it. L1's stub-residue check flags these immediately.
+
+- **Weak or tautological postconditions.** Asked to add a contract, the agent reaches for whatever satisfies the structural checker without actually constraining behavior: `lambda result: isinstance(result, int)` on a function that already returns `int`, or `lambda result: True`. These pass every check but verify nothing. L1 flags both patterns.
+
+- **Silent exception handling.** `try: risky() / except Exception: pass` is a load-bearing anti-pattern in agent-generated code. The agent encounters an error during testing, decides the cleanest fix is to swallow it, and ships code where real failures vanish into the void. L1 flags any handler whose body is `pass`, `...`, `continue`, `break`, or a bare `return` and demands a meaningful response or an explicit `# silent-except: <reason>` opt-out.
+
+- **Mutable default arguments.** `def f(x=[])` is a Python footgun every senior developer learned to avoid the hard way. Agents reproduce it cheerfully because they pattern-match on shape, not language semantics. L1 catches it by default.
+
+- **Bare `assert` as a runtime check.** Agents reach for `assert x > 0` to "validate input" — but assertions disappear under `python -O`. The check vanishes silently in any production environment that strips them. L1 flags asserts in non-test source.
+
+- **`print()` debug residue.** Trace prints from the agent's own debugging session ship to production because nobody pruned them. L1 catches `print()` in core modules.
+
+- **Unsafe deserialization and shell calls.** `eval`, `exec`, `pickle.loads` on untrusted input, and `subprocess.run(..., shell=True)` are calls a security-aware human writes only with a comment explaining why. Agents reach for them when the simple solution looks fastest. L1 flags every one, requiring an `# allow-dangerous: <reason>` opt-out for the rare legitimate case.
+
+- **Tests that pass but verify nothing.** A `def test_foo(): foo()` with no `assert` runs successfully and counts as "covered" — but it only checks that the function doesn't raise. L1's no-assertions-in-tests check fires on any `test_*` function with no `assert`, `pytest.raises`, `pytest.fail`, or `self.assertX` call.
+
+- **Architectural drift.** Asked to "add a feature," the agent puts I/O in core, business logic in adapters, and circular imports between them. The system still works in tests because everything is loaded together — but the layering rule that made the code testable in the first place is gone. L6 compositional checks enforce dependency direction, interface compliance, and contract presence at module boundaries.
+
+None of these failures are unique to AI; humans make them too. What's unique is the *rate* at which an agent produces them and the *confidence* with which the agent reports the work as done. The structural checker, the contracts, the property tester, and the symbolic search exist to make each pattern impossible to ship without an explicit, reviewed override.
+
 SereneCode is designed for **building new verifiable systems from scratch with AI**, not for retrofitting verification onto large existing codebases. The conventions go in before the first line of code, and every module is written with verification in mind from day one. That's what makes it work. SereneCode is a best-effort tool, not a guarantee — see the [Disclaimer](#disclaimer) for important limitations on what it can and cannot assure.
 
 ### Choosing the Right Level
@@ -69,6 +101,8 @@ Pick the level that matches the stakes. Safety-critical code should start at Str
 
 ## See It In Action: The Medical Dosage Calculator
 
+> **This is a hypothetical example for demonstration purposes only.** The medical dosage calculator is not a real, clinically validated, or regulator-approved tool. It is not derived from any actual drug-dosing protocol, has not been reviewed by medical professionals, and must not be used for any clinical decision-making. Its purpose is solely to illustrate how SereneCode shapes the way an AI agent writes verifiable code in a context where contracts and bounded symbolic search would matter. Building real medical software requires domain experts, regulated processes, and assurance methodologies that go far beyond what this framework provides.
+
 We built the same medical dosage calculator twice from the same spec — once with plain AI, once with SereneCode — to show the difference.
 
 Both versions implement four functions: dose calculation with weight-based dosing and max caps, renal function adjustment with tiered CrCl thresholds, daily safety checks with explicit total-versus-threshold calculations, and contraindication detection across current medications.
@@ -114,6 +148,8 @@ This creates SERENECODE.md (project conventions including spec traceability) and
 
 A lightweight AST-based checker that validates code follows SERENECODE.md conventions in seconds. Missing a postcondition? No class invariant? No test file for a module? Caught before you waste time on heavy verification.
 
+L1 also catches AI-failure-mode patterns that compile and look correct but represent real bugs: stub residue (`pass`/`...`/`raise NotImplementedError` left as a function body), mutable default arguments, bare `assert` in non-test source, `print()` in core, dangerous calls (`eval`, `exec`, `pickle.loads`, `os.system`, `subprocess` with `shell=True`), `TODO`/`FIXME`/`XXX`/`HACK` markers in tracked files, tests with no assertions, silent exception handlers, and tautological postconditions. Each rule has a per-rule opt-out comment for legitimate exceptions; see SERENECODE.md "Code Quality Standards" for the full list.
+
 ```bash
 serenecode check src/ --structural          # structural conventions
 serenecode check src/ --spec SPEC.md        # + spec traceability
@@ -144,29 +180,91 @@ The full pipeline is thorough but not instant. Larger systems will take longer,
 
 Levels 3-6 import and execute project modules so coverage.py, Hypothesis, and CrossHair can exercise real code. Deep runs therefore require explicit `--allow-code-execution` and should only be used on trusted code.
 
+### 4. The MCP Server — Verification Inside the Agent's Edit Loop
+
+SereneCode ships a built-in MCP (Model Context Protocol) server that exposes the entire verification pipeline as tools any MCP-speaking AI coding assistant can call *while it writes code*, not just at the end. Instead of waiting for `serenecode check` to run at the bottom of a feature, the agent calls `serenecode_check_function` after every function it writes, sees structured findings inline, fixes them, and only reports the work complete when the result is clean. This collapses the feedback loop from minutes-after-writing to seconds-while-writing and turns serenecode from a batch tool you run *at* the agent into a peer tool the agent uses *on itself*.
+
+**Setup (one-time):**
+
+```bash
+uv add 'serenecode[mcp]'
+claude mcp add serenecode -- uv run serenecode mcp                          # read-only (L1, L2)
+claude mcp add serenecode -- uv run serenecode mcp --allow-code-execution   # all six levels
+```
+
+The same `serenecode mcp` stdio server works in Claude Code, Cursor, Cline, Continue, and any other MCP client.
+
+**Tools the agent can call:**
+
+| Tool | What it does |
+|---|---|
+| `serenecode_check` | Run the full pipeline on a project root |
+| `serenecode_check_file` | Pipeline scoped to one source file |
+| `serenecode_check_function` | Pipeline scoped to one function — the inner-loop tool |
+| `serenecode_verify_fixed` | Re-run on one function and report whether a specific finding is gone |
+| `serenecode_suggest_contracts` | Derive `@require`/`@ensure` decorators from a function signature |
+| `serenecode_uncovered` | L3 coverage findings for one function (uncovered lines + mock advice) |
+| `serenecode_suggest_test` | Test scaffold for an uncovered function |
+| `serenecode_validate_spec` | Validate a SPEC.md is well-formed |
+| `serenecode_list_reqs` | List REQ-xxx identifiers in a SPEC.md |
+| `serenecode_req_status` | Implementation/verification status of one REQ |
+| `serenecode_orphans` | REQs with no implementation or no test |
+
+**Read-only resources** the agent can fetch without "calling" anything: `serenecode://config` (active SerenecodeConfig as JSON), `serenecode://findings/last-run` (most recent CheckResponse from this server session), `serenecode://exempt-modules` (the exempt path patterns for the active config), `serenecode://reqs` (parsed REQ-xxx list from the project's SPEC.md).
+
+The server-level `--allow-code-execution` flag mirrors the CLI: without it, Levels 3-6 tools return a structured error rather than importing project code. `serenecode init` writes a copy-pasteable MCP setup snippet into the generated CLAUDE.md so newly initialized projects ship with the registration command and recommended workflow. See SERENECODE.md "MCP Integration" for the full descriptions and the agent-side workflow.
+
 Scoped targets keep their package/import context across verification levels. In practice that means commands like `serenecode check src/core/ --level 4 --allow-code-execution` and `serenecode check src/core/models.py --level 3 --allow-code-execution` use the same local import roots and architectural module paths as a project-wide run instead of breaking relative imports or scoped core-module rules. Those scoped core/exemption rules are matched on path segments, not raw substrings, so names like `notcli.py`, `viewmodels.py`, and `transports/` do not accidentally change policy classification. Standalone files with non-importable names are also targeted correctly for CrossHair via `file.py:line` references.
 
 ---
 
 ## The AI Agent Loop
 
-SereneCode is designed for spec-driven development with AI agents:
+SereneCode is designed for spec-driven development with AI agents. The loop has two layers — a fast inner loop the agent drives on itself through the MCP server, and an outer batch loop for full project verification:
 
 ```
-serenecode init                  → interactive setup: spec mode + verification level
-serenecode spec SPEC.md          → validate spec is ready (REQ-xxx format, no gaps)
-AI reads SERENECODE.md + SPEC.md → knows the conventions and what to build
-AI implements from spec          → Implements: REQ-xxx in docstrings, contracts, tests
-serenecode check src/ --spec SPEC.md --structural   → did the AI follow rules? all REQs covered?
-serenecode check src/ --level 5 --allow-code-execution --spec SPEC.md   → deep verification
-AI reads findings                → missing REQs, counterexamples, untested paths
-AI fixes the code                → adjusts implementation, adds tests, closes gaps
-Repeat until verified            → all REQs implemented + tested + no counterexamples
+─── one-time setup ──────────────────────────────────────────────────────────
+serenecode init                           → spec mode + verification level
+                                            (also offers MCP server setup)
+claude mcp add serenecode -- uv run \     → register MCP server with the AI
+       serenecode mcp --allow-code-execution  tool (Claude Code, Cursor, ...)
+serenecode spec SPEC.md                   → validate spec is ready
+                                            (REQ-xxx format, no gaps)
+
+─── inner loop (per function, driven by the agent through MCP) ──────────────
+AI reads SERENECODE.md + SPEC.md          → conventions and what to build
+AI calls serenecode_suggest_contracts     → derive @require/@ensure for the
+                                            function it's about to write
+AI writes the function                    → with Implements: REQ-xxx tag
+AI calls serenecode_check_function        → L1-L4 scoped to that function
+AI reads structured findings              → missing contracts, mutable
+                                            defaults, weak postconditions,
+                                            uncovered branches, etc.
+AI fixes them and calls verify_fixed      → confirms each finding is gone
+                                            before moving on to the next
+                                            function
+
+─── outer loop (per feature, batch verification) ─────────────────────────────
+serenecode check src/ --spec SPEC.md      → did the AI follow conventions?
+                  --structural              all REQs covered?
+serenecode check src/ --level 5 \         → deep verification: coverage,
+                  --allow-code-execution \   property testing, symbolic search
+                  --spec SPEC.md
+AI calls serenecode_orphans /             → which REQs are unimplemented or
+       serenecode_req_status                untested?
+AI fixes the gaps                         → adds implementations, tests,
+                                            stronger contracts
+Repeat until verified                     → all REQs implemented + tested,
+                                            no counterexamples within bounds
 ```
 
+The inner loop is what the MCP server enables. Before MCP, the agent had to finish writing, exit its turn, wait for `serenecode check` to run, parse the output, and iterate. With MCP, every function the agent writes gets validated *before* it moves to the next one — `serenecode_check_function` returns structured JSON in milliseconds, the agent fixes any findings inline, and only reports the overall task complete when the result is clean. This collapses an iteration loop that used to span multiple turns into a sequence of tool calls inside a single turn.
+
+The outer loop still matters: cross-module compositional analysis, full coverage runs, and spec-traceability sweeps over the whole codebase aren't function-scoped, so they live at the batch level. The CLI handles those, and the same pipeline runs identically in CI.
+
 AI-generated code won't always pass verification on the first try — and that's the point. SereneCode gives the coding agent structured feedback on exactly what failed and why: missing requirement implementations, counterexamples, violated contracts, untested modules, and suggested fixes. When there are many findings, SereneCode suggests the agent spawn subagents to address groups of related issues in parallel. **The value isn't in one-shotting perfection — it's in the loop that converges on verified completeness and correctness.**
 
-Works in Claude Code, works in the terminal, works in CI:
+Works in Claude Code, works in Cursor / Cline / Continue (via the same MCP server), works in the terminal, works in CI:
 
 ```python
 import serenecode
@@ -181,6 +279,8 @@ for failure in result.failures:
             print(detail.suggestion)      # proposed fix direction
 ```
 
+The library API (`serenecode.check`) and the MCP server (`serenecode_check`, `serenecode_check_function`) call into the same pipeline, so verification semantics are identical between an agent calling tools, a developer running the CLI, and CI invoking the Python API.
+
 ---
 
 ## Built With Its Own Medicine
@@ -189,11 +289,11 @@ SereneCode isn't just a tool that *tells* you to write verified code. It *is* ve
 
 The SERENECODE.md convention file was the first artifact created — before any Python was written. The framework has been developed under those conventions with AI as a first-class contributor, and the repository continuously checks itself with:
 
-- `pytest` across the full suite (currently 769 passing tests, 16 skipped)
+- `pytest` across the full suite (currently 1,393 passing tests, 16 skipped)
 - `mypy --strict` across `src/` and `examples/dosage-serenecode/src/`
 - SereneCode's own structural, type, property, symbolic, and compositional passes
 
-On the current tree, `serenecode check src --level 6 --allow-code-execution` runs all six verification levels. The exempt items include adapter modules (which handle I/O and are integration-tested), port interfaces (Protocols that define abstract contracts), CLI entry points, and functions whose parameter types are too complex for automated strategy generation or symbolic execution. Exempt items are visible in the output — they are not silently omitted.
+On the current tree, the bare CLI invocation `serenecode check src --level 6 --allow-code-execution` runs the full L1-L6 pipeline end-to-end against the framework's own source — 718 functions checked, 557 passed, 161 exempt, 0 failures, ~6 minutes wall time. A separate integration test, `test_serenecode_repo_passes_strict_level_6`, runs the same source tree through `run_pipeline` with `strict_config()` and `start_level=4`, which strips every path-based exemption and forces every adapter, CLI handler, MCP tool, and `__init__.py` through L4-L6. SereneCode also passes that strict-config self-check end-to-end: 0 L1 findings across all 466 strict-checked functions, 0 L3 coverage gaps across the strict-checked subset (~3.5 minutes), and 0 L4-L6 findings. The exempt items in the default-config run include adapter modules (which handle I/O and are integration-tested), port interfaces (Protocols that define abstract contracts), CLI entry points, the MCP server package, and functions whose parameter types are too complex for automated strategy generation or symbolic execution. Exempt items are visible in the output — they are not silently omitted.
 
 At Level 5, CrossHair and Z3 search for counterexamples across the codebase's symbolic-friendly contracted top-level functions. Functions with non-primitive parameters (custom dataclasses, Protocol implementations, Callable types) are reported as exempt because the solver cannot generate inputs for them. Level 6 adds structural compositional analysis: dependency direction, circular dependency detection, interface compliance, contract presence at module boundaries, aliased cross-module call resolution, and architectural invariants. Interface compliance follows explicit `Protocol` inheritance and checks substitutability, including extra required parameters and incompatible return annotations. Together, they provide both deep per-function verification and system-level structural guarantees — but the structural checks at L6 verify contract *presence*, not logical *sufficiency* across call chains.
 
@@ -202,17 +302,27 @@ At Level 5, CrossHair and Z3 search for counterexamples across the codebase's sy
 ## Quick Start
 
 ```bash
-# Install from PyPI
-pip install serenecode
+# Install from PyPI (add the [mcp] extra to enable the MCP server).
+# Note: the MCP server ships in the next release; until it's published
+# to PyPI, install from the source checkout instead:
+#   git clone https://github.com/helgster77/serenecode && cd serenecode
+#   uv sync --extra mcp           # or: pip install -e '.[mcp]'
+pip install 'serenecode[mcp]'
 
 # Initialize — interactive setup (spec mode + verification level)
 serenecode init
 
+# Register the MCP server with your AI coding tool so verification
+# runs inside the agent's edit loop, not just at the end:
+claude mcp add serenecode -- uv run serenecode mcp --allow-code-execution
+#   (Cursor, Cline, Continue, and other MCP clients work the same way)
+
 # Place your spec in the project directory, then start a coding session.
 # Your agent reads SERENECODE.md, converts the spec to REQ-xxx format,
-# validates it, creates an implementation plan, and builds from it.
+# validates it, creates an implementation plan, and builds from it —
+# calling serenecode_check_function after every function it writes.
 
-# Verify structure + spec traceability:
+# Verify structure + spec traceability from the CLI:
 serenecode check src/ --spec SPEC.md --structural
 
 # Go deep — test coverage, property testing, symbolic verification:
@@ -239,6 +349,8 @@ serenecode check [<path>] [--level 1-6] [--allow-code-execution]        # run ve
 serenecode status [<path>] [--format human|json]                        # verification status
 serenecode report [<path>] [--format human|json|html]                   # generate reports
                            [--output FILE] [--allow-code-execution]     #   write to file
+serenecode mcp [--allow-code-execution]                                 # boot the MCP server
+               [--project-root DIR]                                     #   over stdio
 ```
 
 **Exit codes:** 0 = passed, 1 = structural, 2 = types, 3 = coverage, 4 = properties, 5 = symbolic, 6 = compositional, 10 = internal error or deep verification refused without explicit trust.
@@ -253,7 +365,7 @@ SereneCode is honest about what it can and can't do:
 
 **Contracts are only as good as you write them.** A function with weak postconditions will pass verification even if the implementation is subtly wrong. SereneCode checks that contracts exist and hold, but can't check that they fully capture your intent. Tautological contracts like `lambda self: True` are now flagged by the conventions and should not be used — they provide no verification value.
 
-**Exempt items are visible, not hidden.** Modules exempt from structural checking (adapters, CLI, ports, `__init__.py`) and functions excluded from deep verification (non-primitive parameter types, adapter code) are reported as "exempt" in the output rather than being silently omitted. This makes the verification scope transparent: the tool reports passed, failed, skipped, and exempt counts separately so you can see exactly what was and wasn't deeply verified. Previous versions silently omitted these, inflating the apparent scope.
+**Exempt items are visible, not hidden.** Modules exempt from structural checking (adapters, CLI, ports, MCP server, `__init__.py`) and functions excluded from deep verification (non-primitive parameter types, adapter code) are reported as "exempt" in the output rather than being silently omitted. This makes the verification scope transparent: the tool reports passed, failed, skipped, and exempt counts separately so you can see exactly what was and wasn't deeply verified. Previous versions silently omitted these, inflating the apparent scope.
 
 **Runtime checks can be disabled.** icontract decorators are checked on every call by default, but can be disabled via environment variables for performance in production. This is a feature, not a bug — but it means runtime guarantees depend on configuration.
 
@@ -274,7 +386,8 @@ SereneCode is honest about what it can and can't do:
 SereneCode follows hexagonal architecture — the same pattern it enforces on your code:
 
 ```
-CLI / Library API           ← composition roots (interactive init, spec validation)
+CLI / Library API / MCP     ← composition roots (interactive init, spec validation,
+    │                          MCP server for AI agents)
     │
     ├──▸ Pipeline           ← orchestrates L1 → L2 → L3 → L4 → L5 → L6
     │       ├──▸ Structural Checker    (ast)

{serenecode-0.2.0 → serenecode-0.3.0}/README.md

@@ -4,9 +4,11 @@
 
 <h3 align="center">A Framework for AI-Driven Development of Verifiable Systems</h3>
 
-SereneCode is a spec-to-verified-implementation framework for AI-generated Python. It ensures that every requirement in your spec is implemented, tested, and formally verified — closing the gap between what you asked for and what the AI built. The workflow starts from a spec with traceable requirements (REQ-xxx), enforces that the AI writes verifiable code with contracts and tests, then verifies at multiple levels — from structural checks and test coverage through property-based testing to symbolic execution with an SMT solver. You choose the verification depth during interactive setup: lightweight for internal tools, balanced for production systems, strict for safety-critical code. AI agents write code fast but can miss requirements and skip edge cases; SereneCode closes that gap with spec traceability, test-existence enforcement, and formal verification.
+SereneCode is a spec-to-verified-implementation framework for AI-generated Python. It ensures that every requirement in your spec is implemented, tested, and formally verified — closing the gap between what you asked for and what the AI built. The workflow starts from a spec with traceable requirements (REQ-xxx), enforces that the AI writes verifiable code with contracts and tests, then verifies at multiple levels — from structural checks and test coverage through property-based testing to symbolic execution with an SMT solver. You choose the verification depth during interactive setup: lightweight for internal tools, balanced for production systems, strict for safety-critical code.
 
-> **This framework was bootstrapped with AI under its own rules.** SereneCode's SERENECODE.md was written before the first line of code, and the codebase has been developed under those conventions from the start. The current tree passes its own `serenecode check src --level 6 --allow-code-execution`, an internal strict-config Level 6 self-check in the test suite, `mypy src examples/dosage-serenecode/src`, the shipped example's check, and the full `pytest` suite (769 passing tests, 16 skipped). The verification output is transparent about scope: exempt modules (adapters, CLI, ports) and functions excluded from deep verification (non-primitive parameter types) are reported as "exempt" rather than silently omitted.
+SereneCode also ships a built-in **MCP server** so verification runs *inside* your AI assistant's edit loop, not just at the end. Once registered with Claude Code, Cursor, Cline, or Continue, the agent calls verification tools after every function it writes — getting structured findings, contract suggestions, and counterexamples back as JSON, fixing them mid-turn, and only reporting the work complete when the result is clean. AI agents write code fast but can miss requirements and skip edge cases; SereneCode closes that gap with spec traceability, test-existence enforcement, formal verification, and an MCP-driven inner loop the agent can drive on itself.
+
+> **This framework was bootstrapped with AI under its own rules.** SereneCode's SERENECODE.md was written before the first line of code, and the codebase has been developed under those conventions from the start — including the MCP server, which the same AI agents now use to verify their own work mid-edit. The current tree passes its own `serenecode check src --level 6 --allow-code-execution` end-to-end via the bare CLI (718 functions checked, 557 passed, 161 exempt; ~6 minutes wall time), an internal strict-config Level 6 self-check in the test suite (`pytest tests/integration/test_example_projects.py::test_serenecode_repo_passes_strict_level_6`, which exercises L4-L6 against `strict_config` over the full source tree), `mypy src examples/dosage-serenecode/src`, the shipped dosage example's own `serenecode check src --level 6 --allow-code-execution`, and the full `pytest` suite (1,393 passing tests, 16 skipped). The verification output is transparent about scope: exempt modules (adapters, CLI, ports, MCP server, `__init__.py`) and functions excluded from deep verification (non-primitive parameter types) are reported as "exempt" rather than silently omitted.
 
 ---
 
@@ -16,6 +18,34 @@ AI writes code fast. But *fast* and *correct* aren't the same thing. When you're
 
 The problem is that formal verification has always been expensive — too slow, too manual, too specialized. SereneCode makes it tractable by controlling the process from the start: a convention file tells the AI to write verification-ready code, a structural linter checks it followed the rules, and CrossHair + Z3 search for contract violations via symbolic execution.
 
+### Common AI failure modes SereneCode is built to catch
+
+After enough hours pair-programming with coding agents, the same handful of mistakes show up over and over. They're not random bugs — they're systematic patterns that follow from how a language model writes code: optimize for the happy path, infer intent from limited context, finish the visible task, leave implicit assumptions implicit. SereneCode treats each one as a verification target rather than a code-review target.
+
+- **Skipping requirements without realizing it.** Given a spec with twelve requirements, the agent writes code that handles eight of them confidently and quietly omits the four it didn't see a clean place for. There's no error, no TODO — just missing behavior. SereneCode's spec traceability (REQ-xxx tags, `Implements:` / `Verifies:` references, the `serenecode_orphans` and `serenecode_req_status` tools) makes it impossible for a requirement to be silently dropped: every REQ in SPEC.md must be both implemented and tested or it shows up as an orphan.
+
+- **Happy-path tests only.** Asked to "add tests," the agent writes a handful of cases that walk the obvious path through the function. Edge cases (empty input, off-by-one boundaries, the exact threshold value, the negative number, the unicode string) are routinely missed because they require imagining what could go wrong. L3 coverage catches uncovered branches; L4 Hypothesis property testing generates inputs the agent never thought of and runs them against the contracts.
+
+- **Stub residue and "I'll come back to this."** A function the agent didn't quite know how to write often ships as `pass`, `...`, or `raise NotImplementedError("TODO")` — and then never gets revisited because the test suite doesn't fail on it. L1's stub-residue check flags these immediately.
+
+- **Weak or tautological postconditions.** Asked to add a contract, the agent reaches for whatever satisfies the structural checker without actually constraining behavior: `lambda result: isinstance(result, int)` on a function that already returns `int`, or `lambda result: True`. These pass every check but verify nothing. L1 flags both patterns.
+
+- **Silent exception handling.** `try: risky() / except Exception: pass` is a load-bearing anti-pattern in agent-generated code. The agent encounters an error during testing, decides the cleanest fix is to swallow it, and ships code where real failures vanish into the void. L1 flags any handler whose body is `pass`, `...`, `continue`, `break`, or a bare `return` and demands a meaningful response or an explicit `# silent-except: <reason>` opt-out.
+
+- **Mutable default arguments.** `def f(x=[])` is a Python footgun every senior developer learned to avoid the hard way. Agents reproduce it cheerfully because they pattern-match on shape, not language semantics. L1 catches it by default.
+
+- **Bare `assert` as a runtime check.** Agents reach for `assert x > 0` to "validate input" — but assertions disappear under `python -O`. The check vanishes silently in any production environment that strips them. L1 flags asserts in non-test source.
+
+- **`print()` debug residue.** Trace prints from the agent's own debugging session ship to production because nobody pruned them. L1 catches `print()` in core modules.
+
+- **Unsafe deserialization and shell calls.** `eval`, `exec`, `pickle.loads` on untrusted input, and `subprocess.run(..., shell=True)` are calls a security-aware human writes only with a comment explaining why. Agents reach for them when the simple solution looks fastest. L1 flags every one, requiring an `# allow-dangerous: <reason>` opt-out for the rare legitimate case.
+
+- **Tests that pass but verify nothing.** A `def test_foo(): foo()` with no `assert` runs successfully and counts as "covered" — but it only checks that the function doesn't raise. L1's no-assertions-in-tests check fires on any `test_*` function with no `assert`, `pytest.raises`, `pytest.fail`, or `self.assertX` call.
+
+- **Architectural drift.** Asked to "add a feature," the agent puts I/O in core, business logic in adapters, and circular imports between them. The system still works in tests because everything is loaded together — but the layering rule that made the code testable in the first place is gone. L6 compositional checks enforce dependency direction, interface compliance, and contract presence at module boundaries.
+
+None of these failures are unique to AI; humans make them too. What's unique is the *rate* at which an agent produces them and the *confidence* with which the agent reports the work as done. The structural checker, the contracts, the property tester, and the symbolic search exist to make each pattern impossible to ship without an explicit, reviewed override.
+
 SereneCode is designed for **building new verifiable systems from scratch with AI**, not for retrofitting verification onto large existing codebases. The conventions go in before the first line of code, and every module is written with verification in mind from day one. That's what makes it work. SereneCode is a best-effort tool, not a guarantee — see the [Disclaimer](#disclaimer) for important limitations on what it can and cannot assure.
 
 ### Choosing the Right Level
@@ -36,6 +66,8 @@ Pick the level that matches the stakes. Safety-critical code should start at Str
 
 ## See It In Action: The Medical Dosage Calculator
 
+> **This is a hypothetical example for demonstration purposes only.** The medical dosage calculator is not a real, clinically validated, or regulator-approved tool. It is not derived from any actual drug-dosing protocol, has not been reviewed by medical professionals, and must not be used for any clinical decision-making. Its purpose is solely to illustrate how SereneCode shapes the way an AI agent writes verifiable code in a context where contracts and bounded symbolic search would matter. Building real medical software requires domain experts, regulated processes, and assurance methodologies that go far beyond what this framework provides.
+
 We built the same medical dosage calculator twice from the same spec — once with plain AI, once with SereneCode — to show the difference.
 
 Both versions implement four functions: dose calculation with weight-based dosing and max caps, renal function adjustment with tiered CrCl thresholds, daily safety checks with explicit total-versus-threshold calculations, and contraindication detection across current medications.
@@ -81,6 +113,8 @@ This creates SERENECODE.md (project conventions including spec traceability) and
 
 A lightweight AST-based checker that validates code follows SERENECODE.md conventions in seconds. Missing a postcondition? No class invariant? No test file for a module? Caught before you waste time on heavy verification.
 
+L1 also catches AI-failure-mode patterns that compile and look correct but represent real bugs: stub residue (`pass`/`...`/`raise NotImplementedError` left as a function body), mutable default arguments, bare `assert` in non-test source, `print()` in core, dangerous calls (`eval`, `exec`, `pickle.loads`, `os.system`, `subprocess` with `shell=True`), `TODO`/`FIXME`/`XXX`/`HACK` markers in tracked files, tests with no assertions, silent exception handlers, and tautological postconditions. Each rule has a per-rule opt-out comment for legitimate exceptions; see SERENECODE.md "Code Quality Standards" for the full list.
+
 ```bash
 serenecode check src/ --structural          # structural conventions
 serenecode check src/ --spec SPEC.md        # + spec traceability
@@ -111,29 +145,91 @@ The full pipeline is thorough but not instant. Larger systems will take longer,
 
 Levels 3-6 import and execute project modules so coverage.py, Hypothesis, and CrossHair can exercise real code. Deep runs therefore require explicit `--allow-code-execution` and should only be used on trusted code.
 
+### 4. The MCP Server — Verification Inside the Agent's Edit Loop
+
+SereneCode ships a built-in MCP (Model Context Protocol) server that exposes the entire verification pipeline as tools any MCP-speaking AI coding assistant can call *while it writes code*, not just at the end. Instead of waiting for `serenecode check` to run at the bottom of a feature, the agent calls `serenecode_check_function` after every function it writes, sees structured findings inline, fixes them, and only reports the work complete when the result is clean. This collapses the feedback loop from minutes-after-writing to seconds-while-writing and turns serenecode from a batch tool you run *at* the agent into a peer tool the agent uses *on itself*.
+
+**Setup (one-time):**
+
+```bash
+uv add 'serenecode[mcp]'
+claude mcp add serenecode -- uv run serenecode mcp                          # read-only (L1, L2)
+claude mcp add serenecode -- uv run serenecode mcp --allow-code-execution   # all six levels
+```
+
+The same `serenecode mcp` stdio server works in Claude Code, Cursor, Cline, Continue, and any other MCP client.
+
+**Tools the agent can call:**
+
+| Tool | What it does |
+|---|---|
+| `serenecode_check` | Run the full pipeline on a project root |
+| `serenecode_check_file` | Pipeline scoped to one source file |
+| `serenecode_check_function` | Pipeline scoped to one function — the inner-loop tool |
+| `serenecode_verify_fixed` | Re-run on one function and report whether a specific finding is gone |
+| `serenecode_suggest_contracts` | Derive `@require`/`@ensure` decorators from a function signature |
+| `serenecode_uncovered` | L3 coverage findings for one function (uncovered lines + mock advice) |
+| `serenecode_suggest_test` | Test scaffold for an uncovered function |
+| `serenecode_validate_spec` | Validate a SPEC.md is well-formed |
+| `serenecode_list_reqs` | List REQ-xxx identifiers in a SPEC.md |
+| `serenecode_req_status` | Implementation/verification status of one REQ |
+| `serenecode_orphans` | REQs with no implementation or no test |
+
+**Read-only resources** the agent can fetch without "calling" anything: `serenecode://config` (active SerenecodeConfig as JSON), `serenecode://findings/last-run` (most recent CheckResponse from this server session), `serenecode://exempt-modules` (the exempt path patterns for the active config), `serenecode://reqs` (parsed REQ-xxx list from the project's SPEC.md).
+
+The server-level `--allow-code-execution` flag mirrors the CLI: without it, Levels 3-6 tools return a structured error rather than importing project code. `serenecode init` writes a copy-pasteable MCP setup snippet into the generated CLAUDE.md so newly initialized projects ship with the registration command and recommended workflow. See SERENECODE.md "MCP Integration" for the full descriptions and the agent-side workflow.
+
 Scoped targets keep their package/import context across verification levels. In practice that means commands like `serenecode check src/core/ --level 4 --allow-code-execution` and `serenecode check src/core/models.py --level 3 --allow-code-execution` use the same local import roots and architectural module paths as a project-wide run instead of breaking relative imports or scoped core-module rules. Those scoped core/exemption rules are matched on path segments, not raw substrings, so names like `notcli.py`, `viewmodels.py`, and `transports/` do not accidentally change policy classification. Standalone files with non-importable names are also targeted correctly for CrossHair via `file.py:line` references.
 
 ---
 
 ## The AI Agent Loop
 
-SereneCode is designed for spec-driven development with AI agents:
+SereneCode is designed for spec-driven development with AI agents. The loop has two layers — a fast inner loop the agent drives on itself through the MCP server, and an outer batch loop for full project verification:
 
 ```
-serenecode init                  → interactive setup: spec mode + verification level
-serenecode spec SPEC.md          → validate spec is ready (REQ-xxx format, no gaps)
-AI reads SERENECODE.md + SPEC.md → knows the conventions and what to build
-AI implements from spec          → Implements: REQ-xxx in docstrings, contracts, tests
-serenecode check src/ --spec SPEC.md --structural   → did the AI follow rules? all REQs covered?
-serenecode check src/ --level 5 --allow-code-execution --spec SPEC.md   → deep verification
-AI reads findings                → missing REQs, counterexamples, untested paths
-AI fixes the code                → adjusts implementation, adds tests, closes gaps
-Repeat until verified            → all REQs implemented + tested + no counterexamples
+─── one-time setup ──────────────────────────────────────────────────────────
+serenecode init                           → spec mode + verification level
+                                            (also offers MCP server setup)
+claude mcp add serenecode -- uv run \     → register MCP server with the AI
+       serenecode mcp --allow-code-execution  tool (Claude Code, Cursor, ...)
+serenecode spec SPEC.md                   → validate spec is ready
+                                            (REQ-xxx format, no gaps)
+
+─── inner loop (per function, driven by the agent through MCP) ──────────────
+AI reads SERENECODE.md + SPEC.md          → conventions and what to build
+AI calls serenecode_suggest_contracts     → derive @require/@ensure for the
+                                            function it's about to write
+AI writes the function                    → with Implements: REQ-xxx tag
+AI calls serenecode_check_function        → L1-L4 scoped to that function
+AI reads structured findings              → missing contracts, mutable
+                                            defaults, weak postconditions,
+                                            uncovered branches, etc.
+AI fixes them and calls verify_fixed      → confirms each finding is gone
+                                            before moving on to the next
+                                            function
+
+─── outer loop (per feature, batch verification) ─────────────────────────────
+serenecode check src/ --spec SPEC.md      → did the AI follow conventions?
+                  --structural              all REQs covered?
+serenecode check src/ --level 5 \         → deep verification: coverage,
+                  --allow-code-execution \   property testing, symbolic search
+                  --spec SPEC.md
+AI calls serenecode_orphans /             → which REQs are unimplemented or
+       serenecode_req_status                untested?
+AI fixes the gaps                         → adds implementations, tests,
+                                            stronger contracts
+Repeat until verified                     → all REQs implemented + tested,
+                                            no counterexamples within bounds
 ```
 
+The inner loop is what the MCP server enables. Before MCP, the agent had to finish writing, exit its turn, wait for `serenecode check` to run, parse the output, and iterate. With MCP, every function the agent writes gets validated *before* it moves to the next one — `serenecode_check_function` returns structured JSON in milliseconds, the agent fixes any findings inline, and only reports the overall task complete when the result is clean. This collapses an iteration loop that used to span multiple turns into a sequence of tool calls inside a single turn.
+
+The outer loop still matters: cross-module compositional analysis, full coverage runs, and spec-traceability sweeps over the whole codebase aren't function-scoped, so they live at the batch level. The CLI handles those, and the same pipeline runs identically in CI.
+
 AI-generated code won't always pass verification on the first try — and that's the point. SereneCode gives the coding agent structured feedback on exactly what failed and why: missing requirement implementations, counterexamples, violated contracts, untested modules, and suggested fixes. When there are many findings, SereneCode suggests the agent spawn subagents to address groups of related issues in parallel. **The value isn't in one-shotting perfection — it's in the loop that converges on verified completeness and correctness.**
 
-Works in Claude Code, works in the terminal, works in CI:
+Works in Claude Code, works in Cursor / Cline / Continue (via the same MCP server), works in the terminal, works in CI:
 
 ```python
 import serenecode
@@ -148,6 +244,8 @@ for failure in result.failures:
             print(detail.suggestion)      # proposed fix direction
 ```
 
+The library API (`serenecode.check`) and the MCP server (`serenecode_check`, `serenecode_check_function`) call into the same pipeline, so verification semantics are identical between an agent calling tools, a developer running the CLI, and CI invoking the Python API.
+
 ---
 
 ## Built With Its Own Medicine
@@ -156,11 +254,11 @@ SereneCode isn't just a tool that *tells* you to write verified code. It *is* ve
 
 The SERENECODE.md convention file was the first artifact created — before any Python was written. The framework has been developed under those conventions with AI as a first-class contributor, and the repository continuously checks itself with:
 
-- `pytest` across the full suite (currently 769 passing tests, 16 skipped)
+- `pytest` across the full suite (currently 1,393 passing tests, 16 skipped)
 - `mypy --strict` across `src/` and `examples/dosage-serenecode/src/`
 - SereneCode's own structural, type, property, symbolic, and compositional passes
 
-On the current tree, `serenecode check src --level 6 --allow-code-execution` runs all six verification levels. The exempt items include adapter modules (which handle I/O and are integration-tested), port interfaces (Protocols that define abstract contracts), CLI entry points, and functions whose parameter types are too complex for automated strategy generation or symbolic execution. Exempt items are visible in the output — they are not silently omitted.
+On the current tree, the bare CLI invocation `serenecode check src --level 6 --allow-code-execution` runs the full L1-L6 pipeline end-to-end against the framework's own source — 718 functions checked, 557 passed, 161 exempt, 0 failures, ~6 minutes wall time. A separate integration test, `test_serenecode_repo_passes_strict_level_6`, runs the same source tree through `run_pipeline` with `strict_config()` and `start_level=4`, which strips every path-based exemption and forces every adapter, CLI handler, MCP tool, and `__init__.py` through L4-L6. SereneCode also passes that strict-config self-check end-to-end: 0 L1 findings across all 466 strict-checked functions, 0 L3 coverage gaps across the strict-checked subset (~3.5 minutes), and 0 L4-L6 findings. The exempt items in the default-config run include adapter modules (which handle I/O and are integration-tested), port interfaces (Protocols that define abstract contracts), CLI entry points, the MCP server package, and functions whose parameter types are too complex for automated strategy generation or symbolic execution. Exempt items are visible in the output — they are not silently omitted.
 
 At Level 5, CrossHair and Z3 search for counterexamples across the codebase's symbolic-friendly contracted top-level functions. Functions with non-primitive parameters (custom dataclasses, Protocol implementations, Callable types) are reported as exempt because the solver cannot generate inputs for them. Level 6 adds structural compositional analysis: dependency direction, circular dependency detection, interface compliance, contract presence at module boundaries, aliased cross-module call resolution, and architectural invariants. Interface compliance follows explicit `Protocol` inheritance and checks substitutability, including extra required parameters and incompatible return annotations. Together, they provide both deep per-function verification and system-level structural guarantees — but the structural checks at L6 verify contract *presence*, not logical *sufficiency* across call chains.
 
@@ -169,17 +267,27 @@ At Level 5, CrossHair and Z3 search for counterexamples across the codebase's sy
 ## Quick Start
 
 ```bash
-# Install from PyPI
-pip install serenecode
+# Install from PyPI (add the [mcp] extra to enable the MCP server).
+# Note: the MCP server ships in the next release; until it's published
+# to PyPI, install from the source checkout instead:
+#   git clone https://github.com/helgster77/serenecode && cd serenecode
+#   uv sync --extra mcp           # or: pip install -e '.[mcp]'
+pip install 'serenecode[mcp]'
 
 # Initialize — interactive setup (spec mode + verification level)
 serenecode init
 
+# Register the MCP server with your AI coding tool so verification
+# runs inside the agent's edit loop, not just at the end:
+claude mcp add serenecode -- uv run serenecode mcp --allow-code-execution
+#   (Cursor, Cline, Continue, and other MCP clients work the same way)
+
 # Place your spec in the project directory, then start a coding session.
 # Your agent reads SERENECODE.md, converts the spec to REQ-xxx format,
-# validates it, creates an implementation plan, and builds from it.
+# validates it, creates an implementation plan, and builds from it —
+# calling serenecode_check_function after every function it writes.
 
-# Verify structure + spec traceability:
+# Verify structure + spec traceability from the CLI:
 serenecode check src/ --spec SPEC.md --structural
 
 # Go deep — test coverage, property testing, symbolic verification:
@@ -206,6 +314,8 @@ serenecode check [<path>] [--level 1-6] [--allow-code-execution]        # run ve
 serenecode status [<path>] [--format human|json]                        # verification status
 serenecode report [<path>] [--format human|json|html]                   # generate reports
                            [--output FILE] [--allow-code-execution]     #   write to file
+serenecode mcp [--allow-code-execution]                                 # boot the MCP server
+               [--project-root DIR]                                     #   over stdio
 ```
 
 **Exit codes:** 0 = passed, 1 = structural, 2 = types, 3 = coverage, 4 = properties, 5 = symbolic, 6 = compositional, 10 = internal error or deep verification refused without explicit trust.
@@ -220,7 +330,7 @@ SereneCode is honest about what it can and can't do:
 
 **Contracts are only as good as you write them.** A function with weak postconditions will pass verification even if the implementation is subtly wrong. SereneCode checks that contracts exist and hold, but can't check that they fully capture your intent. Tautological contracts like `lambda self: True` are now flagged by the conventions and should not be used — they provide no verification value.
 
-**Exempt items are visible, not hidden.** Modules exempt from structural checking (adapters, CLI, ports, `__init__.py`) and functions excluded from deep verification (non-primitive parameter types, adapter code) are reported as "exempt" in the output rather than being silently omitted. This makes the verification scope transparent: the tool reports passed, failed, skipped, and exempt counts separately so you can see exactly what was and wasn't deeply verified. Previous versions silently omitted these, inflating the apparent scope.
+**Exempt items are visible, not hidden.** Modules exempt from structural checking (adapters, CLI, ports, MCP server, `__init__.py`) and functions excluded from deep verification (non-primitive parameter types, adapter code) are reported as "exempt" in the output rather than being silently omitted. This makes the verification scope transparent: the tool reports passed, failed, skipped, and exempt counts separately so you can see exactly what was and wasn't deeply verified. Previous versions silently omitted these, inflating the apparent scope.
 
 **Runtime checks can be disabled.** icontract decorators are checked on every call by default, but can be disabled via environment variables for performance in production. This is a feature, not a bug — but it means runtime guarantees depend on configuration.
 
@@ -241,7 +351,8 @@ SereneCode is honest about what it can and can't do:
 SereneCode follows hexagonal architecture — the same pattern it enforces on your code:
 
 ```
-CLI / Library API           ← composition roots (interactive init, spec validation)
+CLI / Library API / MCP     ← composition roots (interactive init, spec validation,
+    │                          MCP server for AI agents)
     │
     ├──▸ Pipeline           ← orchestrates L1 → L2 → L3 → L4 → L5 → L6
     │       ├──▸ Structural Checker    (ast)