CLI MCP Subsystem Architectural Guide
Overview
The ZQK Model Context Protocol (MCP) Subsystem (cmd/zqk/mcp) provides the high-performance, standardized JSON-RPC integration layer connecting AI agent environments (including Claude Desktop, Cursor, Zed, and Google Antigravity) directly with the Zen Quantum Kernel (ZQK).
Unlike transient prompt harnesses or unverified context dumps that treat tool execution as disposable subshell invocations, ZQK roots all MCP interactions in the sovereign, persistent Knowledge Kernel. Every tool execution, capability registration, permission gate, and diagnostic probe is tied to verifiable graph objects stored in Content Addressable Storage (CAS) under .zqk/process/.
The CLI MCP subsystem enables:
- Zero-Latency In-Process Execution: Direct Go AST command dispatch without process-spawn overhead for high-frequency agent tool calls.
- Multi-Transport Flexibility: Standard I/O (
stdio) for local IDE processes alongside persistent local loopback TCP sockets (127.0.0.1:8443) for concurrent agent swarms. - Resilient Daemon Supervision: Background supervisor daemon with automatic heartbeat recovery, PID lockfile hygiene, and graceful zero-downtime drain.
- Universal IDE Adaptation: Dynamic auto-configuration for major agent hosts with zero manual JSON configuration required.
- Spec-Based Security & RBAC: Automated capability filtering and access enforcement ensuring agents execute only explicitly authorized commands.
Subsystem Architecture & File Layout
The CLI MCP subsystem resides in cmd/zqk/mcp/ and interfaces with core protocol implementations in pkg/mcp/ and pkg/mcp/ideadapter/:
cmd/zqk/mcp/
├── mcp.go # Root 'zqk mcp' command, serve entrypoint, in-process CLI runner
├── daemon.go # 'zqk mcp daemon': Long-lived multi-client TCP service
├── daemon_control.go # PID management, process liveness check, diagnostics payload
├── ensure.go # 'zqk mcp ensure': Idempotent daemon & role symlink healthcheck
├── supervise.go # 'zqk mcp supervise': Process watchdog, auto-restart loop, stop lifecycle
├── proxy.go # 'zqk mcp proxy': Lightweight stdio-to-TCP bridge
├── ide_adapter.go # 'zqk mcp ide-adapter' / 'cursor-adapter': IDE stdio harness
├── install.go # 'zqk mcp install': Automated IDE client configuration
├── list_tools.go # 'zqk mcp list-tools': Tool inventory and command path inspection
├── storage_provider_adapter.go # Adapter bridging storage.ObjectStorageProvider to pkg/mcp
├── coordinator_setup.go # Event routing and telemetry pipeline integration
├── detach_unix.go # Setsid process detachment for Unix platforms
└── detach_windows.go # Process detachment abstraction for Windows platforms
MCP Subsystem Interaction Topology
The following diagram illustrates how external IDE hosts interface with the ZQK CLI MCP subsystem, supervisor, and kernel:
flowchart TD
subgraph IDE_HOSTS ["AI Agent & IDE Hosts"]
CLAUDE["Claude Desktop"]
CURSOR["Cursor IDE"]
ZED["Zed Editor"]
AGY["Antigravity CLI / IDE"]
end
subgraph TRANSPORTS ["Transport & Entry Layer"]
STDIO_CONN["stdio (Standard Input/Output)"]
PROXY_CMD["zqk mcp proxy"]
ADAPTER_CMD["zqk mcp ide-adapter"]
end
subgraph SUPERVISION ["Supervisor & Daemon Control"]
SUPERVISE["zqk mcp supervise --loop"]
ENSURE["zqk mcp ensure"]
PID_FILES[".zqk/run/mcp-daemon-*.pid"]
LOG_FILES[".zqk/logs/mcp-daemon-*.log"]
end
subgraph SERVER ["MCP Daemon Engine (cmd/zqk/mcp)"]
TCP_LISTENER["TCP Listener (127.0.0.1:8443)"]
DISPATCH_POOL["Dispatch Work Pool"]
IN_PROCESS["In-Process CLI Runner"]
SPEC_AC["Spec Access Control / RBAC"]
end
subgraph KERNEL ["Knowledge Kernel Storage"]
CAS_STORE[".zqk/process/ (CAS Graph)"]
METRICS_BUS["Telemetry / Metrics Pipeline"]
WAL_STREAM["Lifecycle Event WAL"]
end
CLAUDE -->|Spawns via stdio| PROXY_CMD
CURSOR -->|Spawns via symlink| ADAPTER_CMD
ZED -->|Spawns via stdio| PROXY_CMD
AGY -->|Direct TCP / In-Process| TCP_LISTENER
PROXY_CMD -->|TCP Socket Connection| TCP_LISTENER
ADAPTER_CMD -->|Buffered stdio & TCP| TCP_LISTENER
SUPERVISE -->|Periodic Health Probes| ENSURE
ENSURE -->|Verifies Listener / Spawns| TCP_LISTENER
ENSURE -->|Tracks PIDs| PID_FILES
SUPERVISE -->|Captures Output| LOG_FILES
TCP_LISTENER -->|Concurrent Requests| DISPATCH_POOL
DISPATCH_POOL -->|Checks Permissions| SPEC_AC
DISPATCH_POOL -->|Executes Command| IN_PROCESS
IN_PROCESS -->|Reads / Writes| CAS_STORE
IN_PROCESS -->|Emits Events| METRICS_BUS
METRICS_BUS -->|Broadcasts Notifications| WAL_STREAM
WAL_STREAM -->|Pushes Notifications| TCP_LISTENER
1. Command Taxonomy (zqk mcp)
The MCP command suite exposes specialized entrypoints designed for both manual operator control and autonomous IDE process lifecycles:
| Command | Primary Role | Execution Mode | Transport | Target Consumer |
|---|---|---|---|---|
zqk mcp serve |
Primary MCP protocol server | Foreground blocking | stdio or TCP (--tcp) |
Direct stdio IDE harness or containerized runners |
zqk mcp daemon |
Multi-client persistent server | Background / Long-lived | TCP loopback (--tcp, --port) |
Shared local development workstation daemon |
zqk mcp proxy |
Lightweight stdio-to-TCP bridge | Foreground per-session | stdio bridging to TCP |
Claude Desktop, legacy IDE stdio spawners |
zqk mcp ide-adapter |
Resilient IDE stdio connector | Foreground per-session | stdio with auto-reconnect |
Cursor, Zed, Claude Desktop |
zqk mcp supervise |
Self-healing daemon watchdog | Background daemon | Detached Setsid (--loop) |
Automated background reliability management |
zqk mcp ensure |
Idempotent health validator | One-shot execution | Local socket probe | Pre-launch IDE hooks, CI pipelines, shell init |
zqk mcp install |
Automatic IDE configuration | One-shot configuration | Filesystem CAS | Developer onboarding, IDE setup |
zqk mcp list-tools |
Introspect exposed MCP tools | One-shot query | stdout table / JSON | Debugging, agent capability verification |
2. Protocol Architecture & Transports
JSON-RPC 2.0 Foundation
The ZQK MCP subsystem adheres strictly to the Model Context Protocol specification built atop JSON-RPC 2.0:
- Requests: Standard JSON-RPC call structure containing
jsonrpc: "2.0", integer or stringid,methodname, andparams. - Responses: Paired responses returning
resultor standardizederrorobjects (code,message,data). - Notifications: Fire-and-forget events with no
id, utilized for telemetry, agent synthesis notifications, and lifecycle event streaming.
Transport Modes
- Standard I/O (
stdio): - Primary communication channel when spawned directly by an IDE host process (e.g.claude_desktop_config.json). - Standard input (os.Stdin) receives newline-delimited JSON-RPC messages; standard output (os.Stdout) transmits framed responses. - Stdout Hygiene Guarantee: The MCP subsystem guarantees zero non-protocol pollution onos.Stdout. All logging, diagnostic outputs, and panic traces are routed exclusively toos.Stderror file logs (pkg/logging/mcp). - Plain TCP Loopback (
127.0.0.1:8443): - Used byzqk mcp daemonto serve multiple concurrent clients through a single shared server instance. - By security invariant (CRIT-MCP-SEC-LOOPBACK), unauthenticated TCP binding is strictly restricted to loopback addresses (127.0.0.1,::1). - Encrypted Network Transports (TLS / mTLS):
- For remote or cross-host mesh integration, the server supports TLS (
--tls-cert,--tls-key) and mutual TLS (--tls-ca) with cryptographic client verification.
3. Server Lifecycle & Execution Context Mapping
Initialization Sequence
The MCP server startup lifecycle follows a deterministic three-stage cascade:
- Bootstrap & Context Initialization:
-
pkgctx.NewCliInitializationContextresolves the sovereign project root. - Global dispatch pool (dispatch.StartGlobalPool) initializes worker routines for concurrent tool submissions. - Security context (secCtx) binds identity and authorization boundaries. - Storage provider (storage.NewStorageFactory) initializes local CAS access. - Deferred Tool Discovery (
initialize): - CLI command discovery and tool schema generation is intentionally deferred until the client sends theinitializeJSON-RPC handshake. - This ensures rapid startup without blocking on disk-intensive spec scans. - In-Process CLI Execution:
- In-process execution serializes access to the root command structure via an internal execution mutex (
cliExecMu). - Standard output and standard error are captured into in-memory buffers (bytes.Buffer). - Sticky Cobra command contexts from previous runs are sanitized viaclearCobraCommandContextsto prevent context leakages.
Tool Execution Flow
sequenceDiagram
autonumber
actor IDE as IDE Host (Cursor / Claude)
participant Adapter as ide-adapter / proxy
participant Daemon as mcp daemon
participant Dispatch as Dispatch Pool
participant Kernel as Knowledge Kernel
IDE->>Adapter: tools/call (name="zqk_query", arguments={...})
Adapter->>Daemon: Forward JSON-RPC over TCP
Daemon->>Dispatch: Enqueue WorkItem (Token Budgeted)
Dispatch->>Dispatch: Check Spec Access & RBAC
Dispatch->>Kernel: In-Process ExecuteContext(rootCmd)
Kernel-->>Dispatch: Command Result & CAS Objects
Dispatch-->>Daemon: Formatted CallToolResult
Daemon-->>Adapter: JSON-RPC Response Result
Adapter-->>IDE: Deliver Tool Result
4. Daemon Supervisor Mechanics & Fault Tolerance
The daemon supervisor (zqk mcp supervise) ensures continuous MCP availability without manual operator intervention:
PID Lockfile Hygiene
The subsystem maintains deterministic state files under .zqk/run/:
mcp-daemon-<port>.pid: Stores the active PID of the TCP daemon process.mcp-daemon-supervise.pid: Stores the active PID of the background supervisor loop.
Before spawning a new process, daemon_control.go verifies process liveness using POSIX signal 0 probes (processAlive(pid)). If a stale PID file exists with no corresponding living process, it is automatically cleaned and reclaimed.
Self-Healing Watchdog Loop (--loop)
When invoked with --loop, the supervisor enters a detached monitoring cycle:
- Spawns
zqk mcp ensure --tcp <addr> --timeout 0every 5 seconds. - Appends stdout and stderr to
.zqk/logs/mcp-daemon-supervise.log. - If the daemon process crashes or drops its TCP port,
runEnsureautomatically starts a new instance and waits up to 8 seconds for socket readiness. - Responds gracefully to POSIX termination signals (
SIGINT,SIGTERM), killing child processes cleanly.
5. IDE Adapter Integration
The ZQK MCP subsystem includes native auto-configuration and adapter harnesses for all major AI coding platforms:
1. Cursor IDE
- Configured via
~/.cursor/mcp.jsonor project-local.cursor/mcp.json. - Uses role symlink
.zqk/bin/zqk-mcp-ide-adapteror directzqk mcp ide-adapter --tcp 127.0.0.1:8443. - Handles rapid IDE connection resets and heartbeat pings without marking the connector red.
2. Claude Desktop
- Configured in
claude_desktop_config.json:json { "mcpServers": { "zqk": { "command": "zqk", "args": ["mcp", "proxy", "--tcp", "127.0.0.1:8443"] } } }
3. Google Antigravity & Zed
- Connects directly to the loopback TCP daemon or executes via
zqk mcp serve. - Leverages structured JSON-RPC 2.0 streaming with telemetry subscription support.
One-Click Installation (zqk mcp install)
Running zqk mcp install inside any project root automatically inspects installed IDE environments, generates the requisite configuration JSON payloads, registers role symlinks, and sets up project hooks.
6. Security Model, Tool Sandboxing, and RBAC
The MCP subsystem enforces a defense-in-depth security architecture:
- Loopback Invariant (
POL-MCP-SEC-LOOPBACK): - Plain TCP listeners refuse to bind to public or non-loopback IP interfaces. - Any external network exposure requires TLS/mTLS encryption. - Subprocess Environment Scrubbing:
-
zqkenv.ScrubDaemonProcessEnv()strips internal parent execution variables (ZQK_PARENT_PID,ZQK_MCP_ACCOUNT_ID) from daemon startup shells. - Prevents recursive watchdog termination and environment variable pollution. - Spec Access Control (RBAC):
- Tool visibility and execution permissions are evaluated against spec definitions loaded via
objects.SpecLoader. - Disallowed commands are omitted fromtools/listand rejected at execution time with standardized JSON-RPC error codes. - Panic Isolation:
- Top-level panic recovery wrappers in
runServecapture any unhandled exceptions, log the stack trace to stderr, and return clean error responses without terminating the host process.
7. Error Handling, Exit Codes & Boundary Semantics
The subsystem distinguishes sharply between standard protocol disconnections and unrecoverable runtime errors:
| Condition | Protocol Behavior | Exit Code | Rationale |
|---|---|---|---|
Client Disconnect (io.EOF) |
Clean shutdown | 0 |
Normal IDE process closure; must not trigger error alarms |
| Idle Timeout / Context Cancel | Soft graceful drain | 0 |
Expected lifecycle timeout during inactive development sessions |
| Invalid CLI Flags | Error message to stderr | 1 |
Command-line invocation error |
| Port Conflict / Bind Failure | Supervisor retry / error log | 1 |
Address already in use by unauthorized process |
| Tool Execution Failure | JSON-RPC error result | 0 |
Tool-level domain failure returned in payload to agent |
8. Verified Architectural Invariants
| ID | Category | Description | Verification Surface |
|---|---|---|---|
INV-MCP-001 |
Transport | Standard output (os.Stdout) is strictly reserved for framed JSON-RPC messages; all logging routes to stderr or file. |
cmd/zqk/mcp/mcp_test.go |
INV-MCP-002 |
Security | Unauthenticated TCP daemon binding is strictly constrained to loopback network interfaces. | pkg/mcp/server_tcp_test.go |
INV-MCP-003 |
Resilience | mcp supervise --stop terminates supervisor, daemon PID, and port holders cleanly. |
cmd/zqk/mcp/mcp_coverage_elevation_cycle118_test.go |
INV-MCP-004 |
Hygiene | Stale daemon PID files are cleared automatically if process validation fails. | cmd/zqk/mcp/daemon_control_test.go |
INV-MCP-005 |
Idempotence | mcp ensure succeeds with no-op when daemon is already actively listening on designated port. |
cmd/zqk/mcp/ensure_test.go |