[P0] cortex mcp-server --verify (CLI audit P0-2) (#52)

* feat(cli): add hidden mcp-server --verify

Offline stdio JSON-RPC verifier (cortex-verify/1) for TUI chrome,
lock scenes, login product copy, and API error paths. Hidden until
Designer sign-off. CLI_100_AUDIT_READY + CLI_100_CHROME_LOCK_SIGNED.

Co-authored-by: Mathis <echobt@users.noreply.github.com>

* fix(cli): green verify mcp source policy and coverage

Extract mcp-server dispatch from oversized modules, regenerate
the CLI schema, and add unit tests for the hidden verify paths.
mcp-server stays hide=true.

Co-authored-by: Mathis <echobt@users.noreply.github.com>

---------

Co-authored-by: Mathis <echobt@users.noreply.github.com>

Author: echobt

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+- Hidden `cortex mcp-server --verify` stdio JSON-RPC server (`cortex-verify`) so CI and agents can audit TUI chrome, lock scenes, login product copy, and API error paths offline. Remains `hide = true` until Designer sign-off.
+
 ### Changed
 - Code turns default to the **Cloud** runtime for the TUI and `cortex exec` (Designer Q9 / `CLI_100_CHROME_LOCK_SIGNED`). This PC and SSH are explicit opt-in in 0.1.x (`CORTEX_COMPUTER` or `CORTEX_SSH_HOST`) and refuse a fresh session with product copy instead of blocking every first turn.
 - README `docs/media/intro.gif` sits on a photographed green forest desktop (not teal blobs): Terminal chrome, a pointer that walks titlebar → composer → slash / model → Shell, and the signed lock TUI. Local CLI only — no Cortex Cloud handoff in the banner story.

Cargo.lock

@@ -94,3 +94,26 @@ failure to make CI green. See [testing rules](../../.rules/testing.md).
 The append regression test checks immediate visibility after Tokio 1.53.1 file
 writes. An awaited `flush` finishes the pending write; it is not an `fsync`
 durability guarantee. Do not replace this check with sleeps or retries.
+
+## Verification MCP (hidden)
+
+`cortex mcp-server --verify` is a hidden stdio JSON-RPC server (`hide = true`
+until Designer sign-off). It is built on the in-tree `cortex-mcp-server` crate
+as `cortex-verify` and drives the TUI through the same headless
+`EventLoop` + `MockTerminal` path as `ux_contract_tests.rs`.
+
+CI and agents add one MCP server entry:
+
+```bash
+./target/debug/Cortex mcp-server --verify
+```
+
+Tools: `tui.*`, `lock.*`, `login.run`, `api.*`, `mcp.*`, `report.finish`.
+Resources: `cortex-verify://matrix`, `cortex-verify://lock/v2/<size>/<id>.txt`,
+`cortex-verify://report/latest`. `report.finish` writes
+`target/readiness/cli-verify/<run_id>.json` with schema `cortex-verify/1`.
+
+Offline runs use `CORTEX_API_URL` (loopback fixture or an unreachable origin).
+They must still cover chrome, legend, product-facing errors, and palette
+audit. Live API checks are gated on `CORTEX_LIVE_API=1` and are not part of
+default CI. Integration coverage is `src/cortex-cli/tests/mcp_server_verify.rs`.

docs/guides/development.md

@@ -2744,6 +2744,13 @@
     {
       "about": "Run the MCP server (stdio transport)",
       "arguments": [
+        {
+          "help": "Run the Cortex verification MCP over stdio JSON-RPC (`cortex-verify/1`)",
+          "id": "verify",
+          "long": "verify",
+          "required": false,
+          "short": null
+        },
         {
           "help": "Enable verbose output (same as --log-level debug)",
           "id": "verbose",

docs/reference/cli.commands.json

@@ -257,7 +257,9 @@ help but supported.
 
 Also hidden, and supported: `shell` (aliases `interactive`, `repl`), `dag`
 (alias `tasks`), `servers`, `history`, `workspace` (alias `project`), `sandbox`
-(alias `sb`), `serve`, and `mcp-server`.
+(alias `sb`), `serve`, and `mcp-server`. The hidden `cortex mcp-server --verify`
+flag starts the offline TUI+API verification MCP (`cortex-verify/1`); see
+[Development](../guides/development.md#verification-mcp-hidden).
 
 ## See also
 

docs/reference/cli.md

@@ -24,7 +24,16 @@ workspace = true
 [features]
 default = ["cortex-tui", "audio"]
 # Use the new Cortex TUI (120 FPS, Cortex theme)
-cortex-tui = ["dep:cortex-tui"]
+cortex-tui = [
+    "dep:cortex-tui",
+    "dep:cortex-tui-capture",
+    "dep:cortex-mcp-server",
+    "dep:cortex-mcp-types",
+    "dep:sha2",
+    "dep:hex",
+    "dep:ratatui",
+    "dep:async-trait",
+]
 # Audio notifications - disabled on musl targets due to alsa-sys incompatibility
 # Falls back to terminal bell when disabled
 audio = ["cortex-tui?/audio"]
@@ -33,6 +42,13 @@ audio = ["cortex-tui?/audio"]
 cortex-engine = { workspace = true }
 cortex-protocol = { workspace = true }
 cortex-tui = { workspace = true, optional = true }
+cortex-tui-capture = { workspace = true, optional = true }
+cortex-mcp-server = { workspace = true, optional = true }
+cortex-mcp-types = { workspace = true, optional = true }
+sha2 = { workspace = true, optional = true }
+hex = { workspace = true, optional = true }
+ratatui = { workspace = true, optional = true }
+async-trait = { workspace = true, optional = true }
 
 cortex-common = { workspace = true, features = ["cli"] }
 cortex-commands = { workspace = true }

src/cortex-cli/Cargo.toml

@@ -366,7 +366,7 @@ pub enum Commands {
     /// Run the MCP server (stdio transport)
     #[command(display_order = 32, hide = true)]
     #[command(next_help_heading = categories::EXTENSION)]
-    McpServer,
+    McpServer(super::mcp_server::McpServerCli),
 
     /// Start ACP server for IDE integration (e.g., Zed)
     #[command(display_order = 33)]

src/cortex-cli/src/cli/args.rs

@@ -32,11 +32,7 @@ pub async fn dispatch_command(cli: Cli) -> Result<()> {
         }
         Some(Commands::Mcp(mcp_cli)) => mcp_cli.run().await,
         Some(Commands::Agent(agent_cli)) => agent_cli.run().await,
-        Some(Commands::McpServer) => {
-            bail!(
-                "MCP server mode is not yet implemented. Use 'cortex mcp' for MCP server management."
-            );
-        }
+        Some(Commands::McpServer(args)) => super::mcp_server::run(args).await,
         Some(Commands::Completion(completion_cli)) => handle_completion(completion_cli),
         Some(Commands::Sandbox(sandbox_args)) => handle_sandbox(sandbox_args).await,
         Some(Commands::Resume(resume_cli)) => run_resume(resume_cli).await,

src/cortex-cli/src/cli/handlers.rs

@@ -0,0 +1,69 @@
+//! Hidden `cortex mcp-server` flags and dispatch.
+//!
+//! Kept out of [`super::args`] / [`super::handlers`] so those modules stay at
+//! their source-policy line-count baseline (same split as `lock_palette`).
+
+use anyhow::{Result, bail};
+use clap::Parser;
+
+/// Hidden `cortex mcp-server` flags. `--verify` is the offline TUI+API verifier.
+#[derive(Debug, Parser)]
+pub struct McpServerCli {
+    /// Run the Cortex verification MCP over stdio JSON-RPC (`cortex-verify/1`).
+    #[arg(long)]
+    pub verify: bool,
+}
+
+/// Run `cortex mcp-server`, including the hidden `--verify` verifier.
+pub async fn run(args: McpServerCli) -> Result<()> {
+    if args.verify {
+        #[cfg(feature = "cortex-tui")]
+        {
+            return crate::verify_mcp::run().await;
+        }
+        #[cfg(not(feature = "cortex-tui"))]
+        {
+            bail!("Verification MCP requires the cortex-tui feature.");
+        }
+    }
+    bail!("MCP server mode is not yet implemented. Use 'cortex mcp' for MCP server management.");
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cli::args::{Cli, Commands};
+    use clap::CommandFactory;
+
+    #[test]
+    fn test_mcp_server_verify_stays_hidden() {
+        let command = Cli::command();
+        let mcp = command
+            .find_subcommand("mcp-server")
+            .expect("mcp-server must exist");
+        assert!(mcp.is_hide_set(), "keep hide=true until Designer sign-off");
+        let cli = Cli::try_parse_from(["cortex", "mcp-server", "--verify"])
+            .expect("should parse hidden mcp-server --verify");
+        match cli.command {
+            Some(Commands::McpServer(args)) => assert!(args.verify),
+            _ => panic!("expected McpServer --verify"),
+        }
+    }
+
+    #[tokio::test]
+    async fn mcp_server_without_verify_fails_closed() {
+        let err = run(McpServerCli { verify: false })
+            .await
+            .expect_err("default mcp-server is not implemented");
+        assert!(err.to_string().contains("not yet implemented"));
+    }
+
+    #[tokio::test]
+    async fn dispatch_mcp_server_without_verify_fails_closed() {
+        let cli = Cli::try_parse_from(["cortex", "mcp-server"]).expect("parse mcp-server");
+        let err = crate::cli::handlers::dispatch_command(cli)
+            .await
+            .expect_err("dispatch must fail closed");
+        assert!(err.to_string().contains("not yet implemented"));
+    }
+}

src/cortex-cli/src/cli/mcp_server.rs

@@ -13,6 +13,7 @@
 
 pub mod args;
 pub mod handlers;
+pub mod mcp_server;
 pub mod styles;
 
 // Re-export main types