From b545bc3a9e74d432d6d5497c4bbef285c269ef0f Mon Sep 17 00:00:00 2001 From: N1ghthill <115030983+N1ghthill@users.noreply.github.com> Date: Sun, 22 Mar 2026 05:37:12 -0300 Subject: [PATCH] docs: position mc as runtime with mcp interface --- README.md | 16 +++++++++------- docs/architecture.md | 11 ++++++----- docs/status.md | 14 +++++++++----- pyproject.toml | 2 +- src/master_control/interfaces/cli/entrypoint.py | 2 +- src/master_control/interfaces/mcp/server.py | 6 +++--- 6 files changed, 29 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 0a9be50..e375076 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # Master Control Master Control (MC) is a local-first runtime for controlled Linux host operations. -It exposes the same typed capability layer through CLI, MCP, and an optional chat/planning interface, with policy, approval, and audit boundaries around every host action. +It exposes a typed capability layer through an MCP interface, with policy, approval, and audit boundaries around every host action. ![Master Control overview](docs/diagrams/readme-overview.svg) -MC is not "the MCP server". -MC is the runtime. MCP is one interface on top of it. +MC is not "just the MCP server". +MC is the runtime. MCP is its main integration interface. MC is built around three constraints: - typed tools before generic shell access @@ -16,10 +16,12 @@ MC is built around three constraints: ## Current status - late alpha -- CLI-first and single-host by design +- 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 -- current interfaces: CLI, experimental read-only MCP stdio, and optional chat/provider path +- main integration interface: experimental read-only MCP stdio +- local administration interface: CLI +- optional interface: chat/provider path - not positioned as a production-ready Linux administration platform, security auditor, or package manager This README intentionally stays short. @@ -34,11 +36,11 @@ Operational detail, release records, validation evidence, and planning documents ~/.local/bin/mc validate-host-profile --output-dir ./artifacts/host-validation ``` -Optional interfaces: +Interfaces: ```bash -~/.local/bin/mc chat --once "o host esta lento" ~/.local/bin/mc mcp-serve +~/.local/bin/mc chat --once "o host esta lento" ``` Remove the user-local install: diff --git a/docs/architecture.md b/docs/architecture.md index 0550c31..2a6fed1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -20,7 +20,8 @@ The authoritative direction is now runtime-first: the conversational path is an - run on a single Linux host - provide a stable local runtime for bounded host operations -- keep the CLI as the primary operator and administration interface +- treat MCP as the main integration interface on top of the runtime +- keep the CLI as the local operator and administration interface - preserve the existing chat/provider path as an optional interface - keep an experimental read-only MCP bridge on top of the same runtime - persist local state and audit data in SQLite @@ -41,7 +42,7 @@ The authoritative direction is now runtime-first: the conversational path is an [Operator / Client] | v -[CLI | Chat / Agent | Experimental MCP] +[MCP | CLI | Chat / Agent] | v [Core Runtime] @@ -73,7 +74,7 @@ The authoritative direction is now runtime-first: the conversational path is an |- audit_events ``` -The conversation and provider stack is still part of the repository, but it should be understood as one interface path into the runtime, not the foundational layer. +The conversation and provider stack is still part of the repository, but it should be understood as an optional interface path into the runtime, not the foundational layer. ## Flow diagrams @@ -194,7 +195,7 @@ For service-oriented actions, MC now requires explicit service evidence from the ### CLI -The CLI is the primary operator and administration interface today. +The CLI is the local operator and administration interface. It should remain fully capable of inspection, validation, and controlled execution without requiring any remote provider. ### Chat / agent path @@ -205,7 +206,7 @@ Its planners, providers, summaries, and rendering helpers are interface logic, n ### MCP An experimental read-only MCP stdio bridge now exists. -Its job is to expose a deliberately small set of runtime capabilities to external AI clients without duplicating policy, audit, or execution logic. +It is the main integration interface for exposing runtime capabilities to external AI clients without duplicating policy, audit, or execution logic. Broader capability exposure remains intentionally deferred until the runtime boundary is easier to own. ## Evolution path diff --git a/docs/status.md b/docs/status.md index 51b0d5d..92458c1 100644 --- a/docs/status.md +++ b/docs/status.md @@ -14,7 +14,7 @@ It is not the long-horizon roadmap. - Stage: late alpha - Public release posture: GitHub pre-release `v0.1.0a2` is published - Product posture: MC is being repositioned from an AI-first conversational agent to a runtime-first capability layer with interfaces -- Interface posture: the CLI remains the primary operator interface; the chat/provider path remains available; an experimental read-only MCP bridge now exists +- Interface posture: MCP is the main integration interface; the CLI remains the local administration interface; the chat/provider path remains optional - Install posture: source checkout plus `install.sh`; no `.deb` package yet - Scope posture: single-host and local-first - Refactor posture: the runtime-first documentation reset and the first code-boundary slices have landed without resetting the validated alpha baseline @@ -33,7 +33,9 @@ The core value is the bounded runtime: - config safety - repeatable validation -The conversational and provider-backed path still exists, but it is now understood as one interface layered on top of that runtime. +The MCP interface is the main integration path for that runtime. +The CLI remains the local administration surface. +The conversational and provider-backed path still exists, but it is now understood as an optional interface layered on top of the same runtime. ## What is already implemented @@ -74,8 +76,9 @@ The conversational and provider-backed path still exists, but it is now understo - `reload_service` - `restart_service` -### Operator interfaces +### Runtime interfaces +- experimental read-only MCP stdio bridge on top of the runtime - 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 @@ -97,8 +100,9 @@ The conversational and provider-backed path still exists, but it is now understo The validated alpha baseline should now be interpreted as follows: - MC is already useful as a bounded runtime for Linux inspection and controlled actions -- the current CLI is the main supported operational surface -- the current chat/provider path is an optional interface, not the only explanation of the product +- MCP is the clearest external integration surface for the current product direction +- the CLI is the local operator and administration surface +- the current chat/provider path is an optional interface, not the explanation of the product - the current codebase still carries more conversational complexity than the runtime-centered product story requires - the current refactor is meant to correct that mismatch without throwing away validated behavior diff --git a/pyproject.toml b/pyproject.toml index 77712ca..8122f1f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta" [project] name = "master-control" version = "0.1.0a2" -description = "Local-first runtime for controlled Linux host operations with policy and auditability." +description = "Local-first runtime for controlled Linux host operations with an MCP interface, policy, and auditability." readme = "README.md" requires-python = ">=3.13" authors = [{ name = "Irving" }] diff --git a/src/master_control/interfaces/cli/entrypoint.py b/src/master_control/interfaces/cli/entrypoint.py index 4989a12..6240fac 100644 --- a/src/master_control/interfaces/cli/entrypoint.py +++ b/src/master_control/interfaces/cli/entrypoint.py @@ -232,7 +232,7 @@ def build_parser() -> argparse.ArgumentParser: subparsers.add_parser( "mcp-serve", - help="Run the experimental stdio MCP bridge over read-only runtime capabilities.", + help="Run the experimental read-only MCP interface over runtime capabilities.", ) return parser diff --git a/src/master_control/interfaces/mcp/server.py b/src/master_control/interfaces/mcp/server.py index b8ed20a..8707ca7 100644 --- a/src/master_control/interfaces/mcp/server.py +++ b/src/master_control/interfaces/mcp/server.py @@ -27,7 +27,7 @@ def as_dict(self) -> dict[str, str]: class MasterControlMCPServer: - """Experimental stdio bridge for read-only runtime capabilities.""" + """Experimental stdio MCP interface for read-only runtime capabilities.""" def __init__(self, runtime: MasterControlRuntime) -> None: self.runtime = runtime @@ -128,7 +128,7 @@ def _dispatch(self, method: str, params: object) -> dict[str, object]: spec = self.runtime.registry.get(tool_name).spec if spec.risk is not RiskLevel.READ_ONLY: raise ValueError( - f"Tool '{tool_name}' is not exposed through the read-only MCP bridge." + f"Tool '{tool_name}' is not exposed through the read-only MCP interface." ) return self.runtime.run_tool( tool_name, @@ -160,7 +160,7 @@ def _error_response( def build_parser() -> argparse.ArgumentParser: parser = argparse.ArgumentParser( prog="mc-mcp", - description="Run the experimental Master Control MCP stdio bridge.", + description="Run the experimental Master Control MCP interface.", ) return parser