N1ghthill · N1ghthill · Mar 24, 2026 · Mar 24, 2026
@@ -33,6 +33,8 @@
 - typed planning decision kinds plus final turn classification
 - deterministic final-message guidance keyed off turn classification
 - repository hardening with `ruff`, `mypy`, `pre-commit`, and GitHub templates
+- official MCP Inspector CLI validation harness in `scripts/validate_mcp_client.py`
+- MCP approval tools for standard clients: `approval_list`, `approval_get`, `approval_approve`, and `approval_reject`
 
 ### Changed
 
@@ -72,6 +74,10 @@
 - chat payloads and audit now distinguish planner intent from final turn outcome, including missing safe tools and confirmation waits
 - blocked or partial turns now return clearer operator guidance instead of relying only on provider prose
 - CI now enforces lint and typecheck in addition to tests and smoke validation
+- `mc mcp-serve` now closes the standard JSON-RPC MCP handshake expected by real clients
+- MCP stdio now exposes approval resolution through standard `tools/list` and `tools/call`, not only through custom approval methods
+- tool approvals now deduplicate active action envelopes and block duplicate in-flight execution for the same pending action
+- release-facing docs and gates now reflect the latest VPS rerun and the Inspector-backed MCP validation path
 
 ### Notes
 

@@ -19,7 +19,7 @@ MC is built around three constraints:
 - single-host and local-first by design
 - install path: source checkout plus `install.sh`
 - validated on the maintainer workstation and on a dedicated Debian 13 VPS lab
-- main integration interface: experimental MCP stdio with approval-mediated write flow
+- main integration interface: experimental but JSON-RPC-compatible MCP stdio with approval-mediated write flow
 - local administration interface: CLI
 - optional interface: chat/provider path
 - not positioned as a production-ready Linux administration platform, security auditor, or package manager
@@ -72,6 +72,7 @@ If `install.sh` reports that `ensurepip` is unavailable on Debian or Ubuntu, ins
 - [Policy guide](docs/policy.md)
 - [Operator workflows](docs/operator-workflows.md)
 - [Runtime integration testing](docs/runtime-integration-testing.md)
+- [MCP client validation](docs/mcp-client-validation.md)
 - [Provider setup](docs/providers.md)
 - [Host-profile validation guide](docs/host-profile-validation.md)
 - [Validation evidence](docs/alpha-validation-report.md)

@@ -27,6 +27,7 @@ Use this file to find the right working document, validation record, or planning
 
 - `docs/alpha-validation-report.md`: main validation summary for the current pre-1.0 baseline
 - `docs/runtime-integration-testing.md`: runtime and MCP contract validation guide
+- `docs/mcp-client-validation.md`: official MCP Inspector CLI validation guide and evidence
 - `docs/vps-validation-report.md`: dedicated Debian VPS validation evidence
 - `docs/vps-validation-runbook.md`: repeatable runbook for the maintainer-controlled VPS lab
 - `docs/call-for-testers.md`: outreach copy for collecting more host-validation evidence

@@ -1,6 +1,6 @@
 # Beta Readiness Gate
 
-Snapshot date: 2026-03-20
+Snapshot date: 2026-03-23
 
 ## Purpose
 
@@ -100,9 +100,10 @@ Minimum exit bar:
 
 Primary hotspots still to watch:
 
-- `src/master_control/app.py`
+- `src/master_control/core/runtime.py`
+- `src/master_control/store/session_store.py`
+- `src/master_control/interfaces/cli/entrypoint.py`
 - `src/master_control/providers/heuristic.py`
-- `src/master_control/agent/session_insights.py`
 
 ## Required Release Artifacts Before Beta
 
@@ -116,15 +117,16 @@ Before any beta tag, the repository should have:
 
 ## Current Status
 
-Current assessment on 2026-03-20:
+Current assessment on 2026-03-23:
 
 - not yet beta-ready
-- the `0.1.0a2` release-candidate package is prepared locally, and Gate 1 host-count evidence is now satisfied through the maintainer workstation plus a dedicated Debian 13 VPS validation run
-- local hardening has already closed bootstrap, comparative follow-up, config-diff, config-diff refinement, service-log compression, service-log pattern refinement, bootstrap evidence, comparative phrase-collection, bootstrap-to-CI decision, and community validation intake packages
-- release-facing docs and final positioning still need to be synchronized before any beta claim or tag decision
-- dedicated VPS evidence is recorded in `docs/vps-validation-report.md`
+- Gate 1 host-count evidence is satisfied through the maintainer workstation plus the dedicated Debian 13 VPS validation lab
+- the operator bootstrap path, host-profile validation, and maintainer engineering baseline were rerun successfully on the VPS on 2026-03-23
+- the MCP approval-mediated mutation flow is now also validated through the official Inspector CLI on the maintainer workstation
+- the remaining blockers are now codebase maintainability, explicit schema governance, and broader operational hardening rather than missing first-pass MCP or host-validation evidence
 
 Main remaining actions:
 
-1. update the canonical release-facing docs to reflect that workflow validation now exists on more than one real host profile
-2. decide whether the current maintainability and release posture justify beta language now, or whether the project should remain in late-alpha/private-preview wording a little longer
+1. reduce the central runtime/store/CLI hotspots enough that the next operational slices stay reviewable
+2. define and enforce tool-schema compatibility rules before broadening the MCP surface further
+3. decide whether late-alpha/private-preview wording should continue until those two bars move
@@ -0,0 +1,92 @@
+# MCP Client Validation
+
+Snapshot date: 2026-03-23
+
+## Purpose
+
+This document records the current real-client validation path for `mc mcp-serve`.
+
+The goal is not to rely only on in-process stdio tests.
+The goal is to prove that a standard MCP client can complete the approval-mediated mutation flow against the real server process.
+
+## Validated Client
+
+Current validated client:
+
+- official MCP Inspector CLI via `@modelcontextprotocol/inspector --cli`
+
+Current validated host:
+
+- maintainer workstation with Node `22.22.1`
+
+Note:
+
+- the dedicated Debian 13 VPS lab currently provides Node `20.19.2`, which is below the Inspector package's declared Node floor
+- the VPS remains useful for operator bootstrap and host-validation evidence, but the current Inspector CLI transcript is maintained from the workstation
+
+## What Is Validated
+
+The current Inspector-backed flow validates:
+
+1. standard JSON-RPC `initialize` over stdio
+2. `tools/list` against the real `mc mcp-serve` process
+3. read-only `tools/call` for `system_info`
+4. approval-mediated `tools/call` for `write_config_file`
+5. approval resolution through MCP-exposed tools:
+   - `approval_get`
+   - `approval_approve`
+
+This means a real MCP client can:
+
+- inspect the host
+- trigger a bounded mutating action
+- receive a structured pending-approval payload
+- resolve that approval through the MCP tool surface
+- observe the executed result and persisted approval record
+
+## Repeatable Command
+
+Run:
+
+```bash
+python3 scripts/validate_mcp_client.py --output-dir ./artifacts/mcp-client-validation
+```
+
+Optional JSON report:
+
+```bash
+python3 scripts/validate_mcp_client.py --json
+```
+
+## Generated Artifacts
+
+Each run writes:
+
+- `report.json`
+- per-step stdout/stderr logs
+- isolated MC state under the run directory
+
+Each successful run is written beneath:
+
+- `artifacts/mcp-client-validation/`
+
+## Current Interpretation
+
+What this validation proves:
+
+- `mc mcp-serve` now closes the standard JSON-RPC MCP handshake required by the official Inspector client
+- the server exposes host tools and approval tools in a format accepted by a standard MCP client
+- the approval-mediated mutation path works through a real external client, not only through direct line tests
+
+What this validation does not prove:
+
+- every desktop MCP client UX is identical
+- GUI-oriented client affordances are already documented well enough for operators
+- the broader tool schema governance work is complete
+
+## Remaining Gap
+
+The remaining MCP evidence gap is narrower now:
+
+- a desktop-specific transcript such as Claude Desktop is still useful follow-up evidence
+- but the project is no longer blocked on "no real MCP client validation at all"
@@ -86,8 +86,9 @@ Validate the interfaces that are part of the release scope.
 
 - `mc mcp-serve` starts cleanly
 - documented MCP behavior matches the currently supported scope
-- if the release includes only read-only MCP, confirm mutating tools are still blocked there
-- if the release includes write-capable MCP in the future, confirm approval-mediated mutation flow from a real MCP client
+- confirm the stdio server still completes the standard JSON-RPC MCP handshake
+- confirm approval-mediated mutation flow from a real MCP client through `python3 scripts/validate_mcp_client.py`
+- if a release claims desktop-client friendliness beyond Inspector CLI, capture that client-specific transcript too
 
 ### Optional planner layer
 

@@ -9,6 +9,8 @@ Snapshot date: 2026-03-23
 - runtime-first and MCP-first product direction
 - runtime already supports bounded inspection, controlled service/config actions, auditability, and validation workflows
 - a first operator-configurable policy slice now exists through versioned TOML
+- standard-client MCP validation now exists through the official Inspector CLI
+- approval concurrency now deduplicates active envelopes and blocks duplicate in-flight execution
 - current priority is to mature the runtime and MCP path into a trustworthy operational interface
 
 ## Phase 1: Controlled MCP Write Path
@@ -83,10 +85,10 @@ Exit criteria:
 
 ## Near-Term Execution Order
 
-1. add runtime integration coverage and harnesses
-2. validate the MCP contract through real-client and stdio transcript flows
-3. harden concurrency and schema governance
-4. continue core/interface cleanup
+1. define tool-schema compatibility rules and release policy
+2. continue core/interface cleanup
+3. add container-backed service/config integration harnesses
+4. broaden client and host validation evidence
 5. expand tool domains only after the previous items are stable
 
 ## Out Of Scope For This Track

@@ -20,6 +20,7 @@ The goal is to validate the real runtime boundaries:
 3. MCP stdio subprocess contract coverage in `tests/test_mcp_stdio_integration.py`
 4. Operator bootstrap validation via `python3 scripts/validate_operator_bootstrap.py`
 5. Host-profile validation via `mc validate-host-profile`
+6. Real MCP client validation via `python3 scripts/validate_mcp_client.py`
 
 ## Local Commands
 
@@ -57,15 +58,23 @@ python3 scripts/validate_operator_bootstrap.py \
   --python python3
 ```
 
+Run the real-client MCP contract check:
+
+```bash
+python3 scripts/validate_mcp_client.py \
+  --output-dir /tmp/mc-client-validation
+```
+
 ## What These Tests Prove Today
 
 - operator policy can disable tools, require confirmation, constrain service targets, and redefine managed config targets
 - invalid policy fails closed and is surfaced through `mc doctor`
-- `mc mcp-serve` works as a real stdio subprocess for `initialize`, `tools/list`, `tools/call`, and `approvals/*`
+- `mc mcp-serve` works as a real stdio subprocess for both the legacy approval API and the standard JSON-RPC MCP handshake
 - approval-mediated config mutation works through the real MCP server process, not just through in-process unit helpers
+- the official MCP Inspector CLI can complete `tools/list`, read-only execution, pending approval, `approval_get`, and `approval_approve`
 
 ## Known Gaps
 
 - no container-backed integration harness yet for repeatable `systemd` service scenarios
-- no external desktop MCP client transcript is checked in yet
+- no desktop-specific GUI transcript is checked in yet
 - real-host smoke validation remains necessary for host-specific paths that containers do not model well
@@ -26,11 +26,11 @@ As of this snapshot, MC already has:
 
 The current codebase also still has clear limits:
 
-- the MCP write path now exists through persisted approvals, but real-client validation and broader contract hardening are still pending
+- the MCP write path now exists through persisted approvals, and official Inspector CLI validation now proves the standard-client flow
 - the runtime still carries chat-oriented orchestration inside `core.runtime`
 - a first operator-configurable policy slice now exists through versioned TOML, but broader validation and operator guidance are still pending
 - the tool contract does not yet have explicit schema-version governance
-- concurrency and multi-call behavior are only partially addressed through SQLite WAL and bounded subprocesses, not through a complete runtime concurrency model
+- concurrency and multi-call behavior now include approval-envelope deduplication and in-flight claim protection, but not a complete runtime concurrency model
 - real-host validation exists, but deeper integration coverage for runtime mutation paths and MCP write flows is not yet the main center of the test strategy
 
 ## Product Goal
@@ -127,6 +127,8 @@ Current progress:
 - persisted tool approvals are now part of the runtime state model
 - the experimental MCP bridge now exposes controlled write requests plus `approvals/list|get|approve|reject`
 - approval lifecycle coverage exists at unit and runtime-contract level
+- the stdio server now closes the standard JSON-RPC MCP handshake expected by real clients
+- the official Inspector CLI has now completed the approval-mediated mutation flow against `mc mcp-serve`
 
 Required outcomes:
 
@@ -149,6 +151,7 @@ Recommended approval contract:
   - `approvals/get`
   - `approvals/approve`
   - `approvals/reject`
+- expose the same approval lifecycle through standard MCP tools for interoperable clients that cannot call custom top-level methods directly
 - bind each pending action to an approval id plus a normalized action envelope
 - include operator-facing evidence in the approval payload:
   - requested tool
@@ -166,7 +169,8 @@ Implementation rule:
 Interoperability target:
 
 - `mc mcp-serve` can be used from a standard MCP client
-- a client such as Claude Desktop can inspect the host and complete an approval-mediated mutation flow without unrestricted shell access
+- a standard client such as the official Inspector CLI can inspect the host and complete an approval-mediated mutation flow without unrestricted shell access
+- a desktop-client transcript such as Claude Desktop remains a useful follow-up, not the first blocker
 
 ### Workstream 1.3: Operator-configurable policy model
 

@@ -78,6 +78,8 @@ Chat and planner providers remain optional layers on top of the same runtime.
 ### Interfaces
 
 - experimental MCP stdio bridge with approval-mediated write flow on top of the runtime
+- standard JSON-RPC-compatible MCP stdio handshake for real MCP clients
+- MCP approval tools exposed through the standard `tools/list` / `tools/call` surface
 - CLI commands for doctor, tools, audit, sessions, observations, recommendations, direct tool execution, and chat
 - CLI-integrated `validate-host-profile` command backed by reusable host-validation code
 - optional `systemd` timer installation for bounded recommendation reconciliation
@@ -96,21 +98,23 @@ Chat and planner providers remain optional layers on top of the same runtime.
 
 - MC is already useful as a bounded runtime for Linux inspection and controlled actions
 - MCP is the main external interface direction, and the current experimental slice already supports approval-mediated write operations
+- the official MCP Inspector CLI now validates that a real client can complete the approval-mediated mutation flow
 - CLI is still the most complete operator surface today
 - chat/provider paths are optional and should not define the product center
 - a first operator-configurable policy slice is landed through versioned TOML, but broader validation and operator evidence are still ahead
-- concurrency and tool-schema governance work are still ahead of the current baseline
+- approval concurrency is now hardened against duplicate active requests and duplicate in-flight execution for the same action envelope
+- tool-schema governance and broader runtime ownership cleanup are still ahead of the current baseline
 
 ## Active Focus
 
 The current execution focus is defined by `docs/runtime-mcp-maturation-plan.md`.
 
 The next maturity steps are:
 
-1. stronger runtime integration coverage for read and write flows
-2. real-client MCP validation and contract hardening on top of the new approval flow
-3. concurrency hardening and state-integrity guarantees
-4. tool-schema compatibility rules and release policy
+1. tool-schema compatibility rules and release policy
+2. narrower runtime ownership seams, especially around `core.runtime` and `session_store`
+3. container-backed integration harnesses for repeatable service/config scenarios
+4. broader client evidence beyond the Inspector CLI transcript
 5. broader tool expansion only after the runtime contract is stable
 
 ## Intentionally Out Of Scope Right Now
@@ -132,6 +136,7 @@ At this snapshot, the project is validated by:
 - `PYTHONPATH=src python3 -m pytest -q`
 - explicit runtime/MCP integration coverage in `tests/test_runtime_policy_integration.py` and `tests/test_mcp_stdio_integration.py`
 - `python3 -m compileall src`
+- real-client MCP validation through `python3 scripts/validate_mcp_client.py`
 - manual CLI smoke checks for chat, recommendations, recommendation-triggered actions, and `reconcile-timer render|install|remove`
 - manual CLI smoke checks for managed config write with validation and backup
 - manual CLI smoke checks for `process_to_unit` and `failed_services`
@@ -152,6 +157,7 @@ At this snapshot, the project is validated by:
 - `docs/policy.md`: operator policy guide
 - `docs/operator-workflows.md`: bounded operator journeys
 - `docs/runtime-integration-testing.md`: runtime and MCP validation guide
+- `docs/mcp-client-validation.md`: real MCP client validation guide
 - `docs/host-profile-validation.md`: validation harness guide
 
 ## Evidence Records