Validate MCP client flow and harden approval concurrency

[N1ghthill]

Summary

This change closes the next runtime/MCP hardening slice in three areas:

• validates mc mcp-serve against a real standard MCP client through the official Inspector CLI
• makes the stdio server JSON-RPC compatible while keeping the existing legacy approval API available
• hardens approval storage and runtime execution against duplicate active approvals and duplicate in-flight execution for the same action envelope

What Changed

MCP interoperability

• rewrote src/master_control/interfaces/mcp/server.py to support standard JSON-RPC MCP requests over stdio
• exposed approval lifecycle tools for interoperable clients: approval_list, approval_get, approval_approve, approval_reject
• kept the existing approvals/* top-level methods for backwards compatibility
• added MCP server coverage for both legacy and standard-client flows

Approval concurrency

• added normalized approval identity digests in src/master_control/store/session_store.py
• deduplicated active approvals for identical tool+arguments+context envelopes
• blocked duplicate claim/execution races when the same approval is already executing
• surfaced approval_in_progress explicitly from the runtime when a confirmed retry hits an in-flight approval

Validation and docs

• added scripts/validate_mcp_client.py
• added docs/mcp-client-validation.md
• updated README, status, roadmap, release checklist, beta gate, runtime integration guide, runtime MCP plan, changelog, and VPS report
• reran bootstrap validation locally and on the Debian 13 VPS lab after these changes

Review Guide

Review in this order:

1. src/master_control/interfaces/mcp/server.py
   Focus on JSON-RPC compatibility, legacy compatibility retention, and how approval tools are exposed for standard MCP clients.
2. src/master_control/store/session_store.py and src/master_control/core/runtime.py
   Focus on approval deduplication, claim/finalize behavior, and the in-flight execution guard.
3. tests/test_mcp_server.py, tests/test_mcp_stdio_integration.py, and tests/test_session_store.py
   Focus on whether the new tests prove the intended interoperability and concurrency guarantees.
4. scripts/validate_mcp_client.py and docs/mcp-client-validation.md
   Focus on whether the Inspector-backed validation path is repeatable and documented clearly.
5. Updated release-facing docs
   Confirm README.md, docs/status.md, docs/roadmap.md, and docs/beta-readiness-gate.md match the new reality without overstating maturity.

Validation

• python3 -m ruff check .
• python3 -m mypy src
• PYTHONPATH=src python3 -m pytest -q
• PYTHONPATH=src python3 -m unittest discover -s tests
• python3 -m compileall src
• PYTHONPATH=src python3 -m master_control --json doctor
• python3 -m pip wheel . --no-deps -w /tmp/mc-dist-phase2
• python3 scripts/validate_mcp_client.py --json
• python3 scripts/validate_operator_bootstrap.py --output-dir /tmp/mc-bootstrap-validation-phase2 --provider heuristic --python python3
• rerun of python3 scripts/validate_operator_bootstrap.py ... on the Debian 13 VPS lab using the current branch snapshot

Residual Risks

• tool-schema versioning and compatibility policy are still not enforced
• core.runtime, session_store, and CLI entrypoint remain major hotspots
• the real-client MCP evidence now covers the official Inspector CLI, but not yet a desktop-specific client transcript
• there is still no container-backed harness for repeatable service/config integration scenarios

[N1ghthill]

Review note: the repository source of truth is this host and this branch history. The Debian 13 VPS is only a validation lab for bootstrap and host evidence; it is not the primary repo or deployment target.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 27cc47368a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Prefer executing match over pending duplicates

When a database is upgraded from older versions, it can already contain both pending and executing approvals for the same action digest; this query orders pending first, so prepare_matching_tool_approval_for_execution() will claim the pending row instead of reporting the in-flight execution. In that state, a confirmed retry can start a second execution of the same mutating action concurrently, which defeats the new duplicate-execution hardening.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Mark failed approval_approve calls as MCP tool errors

approval_approve is always returned with is_error=False, but runtime.approve_tool_approval() can legitimately return a failed execution payload (execution.ok == false, approval status failed). In that case, standard MCP clients receive a non-error tool result for a failed action and may treat it as success, which can hide failed writes or retries.

Useful? React with 👍 / 👎.