The runtime crate already had typed MCP config parsing, bootstrap metadata,
and stdio JSON-RPC transport primitives, but it lacked the stateful layer
that owns configured subprocesses and routes discovered tools back to the
right server. This change adds a thin lazy McpServerManager in mcp_stdio,
keeps unsupported transports explicit, and locks the behavior with
subprocess-backed discovery, routing, reuse, shutdown, and error tests.
Constraint: Keep the change narrow to the runtime crate and stdio transport only
Constraint: Reuse existing MCP config/bootstrap/process helpers instead of adding new dependencies
Rejected: Eagerly spawn all configured servers at construction | unnecessary startup cost and failure coupling
Rejected: Spawn a fresh process per request | defeats lifecycle management and tool routing cache
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep higher-level runtime/session integration separate until a caller needs this manager surface
Tested: cargo fmt --all; cargo clippy -p runtime --all-targets -- -D warnings; cargo test -p runtime
Not-tested: Integration into conversation/runtime flows outside direct manager APIs
The runtime already framed JSON-RPC initialize traffic over stdio, so this extends the same transport with typed helpers for tools/list, tools/call, resources/list, and resources/read plus fake-server tests that exercise real request/response roundtrips.
Constraint: Must build on the existing stdio JSON-RPC framing rather than introducing a separate MCP client layer
Rejected: Leave method payloads as untyped serde_json::Value blobs | weakens call sites and test assertions
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep new MCP stdio methods aligned with upstream MCP camelCase field names when adding more request/response types
Tested: cargo fmt --manifest-path rust/Cargo.toml --all; cargo clippy --manifest-path rust/Cargo.toml -p runtime --all-targets -- -D warnings; cargo test --manifest-path rust/Cargo.toml -p runtime
Not-tested: Live integration against external MCP servers
The runtime already knew how to spawn stdio MCP processes, but it still
needed transport primitives for framed JSON-RPC exchange. This change adds
minimal request/response types, line and frame helpers on the stdio wrapper,
and an initialize roundtrip helper so later MCP client slices can build on a
real transport foundation instead of raw byte plumbing.
Constraint: Keep the slice small and limited to stdio transport foundations
Constraint: Must verify framed request write and typed response parsing with a fake MCP process
Rejected: Introduce a broader MCP session layer now | would expand the slice beyond transport framing
Rejected: Leave JSON-RPC as untyped serde_json::Value only | weakens initialize roundtrip guarantees
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Preserve the camelCase MCP initialize field mapping when layering richer protocol support on top
Tested: cargo fmt --all --manifest-path rust/Cargo.toml
Tested: cargo clippy -p runtime --all-targets --manifest-path rust/Cargo.toml -- -D warnings
Tested: cargo test -p runtime --manifest-path rust/Cargo.toml
Not-tested: Integration against a real external MCP server process
The dirty stdio slice had two real regressions in its new JSON-RPC test coverage: the embedded Python helper was written with broken string literals, and direct execution of the freshly written helper could fail with ETXTBSY on Linux. The repair keeps scope inside mcp_stdio.rs by fixing the helper strings and invoking the JSON-RPC helper through python3 while leaving the existing stdio process behavior unchanged.
Constraint: Keep the repair limited to rust/crates/runtime/src/mcp_stdio.rs
Constraint: Must satisfy fmt, clippy -D warnings, and runtime tests before shipping
Rejected: Revert the entire JSON-RPC stdio coverage addition | unnecessary once the helper/test defects were isolated
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep ephemeral stdio test helpers portable and avoid directly execing freshly written scripts when an interpreter invocation is sufficient
Tested: cargo fmt --all; cargo clippy -p runtime --all-targets -- -D warnings; cargo test -p runtime
Not-tested: Cross-platform behavior outside the current Linux runtime
Add a minimal runtime stdio MCP launcher that spawns configured server processes with piped stdin/stdout, applies transport env, and exposes async write/read/terminate/wait helpers for future JSON-RPC integration.
The wrapper stays intentionally small: it does not yet implement protocol framing or connection lifecycle management, but it is real process orchestration rather than placeholder scaffolding. Tests use a temporary executable script to prove env propagation and bidirectional stdio round-tripping.
Constraint: Keep the slice minimal and testable while using the real tokio process surface
Constraint: Runtime verification must pass cleanly under fmt, clippy, and tests
Rejected: Add full JSON-RPC framing and session orchestration in the same commit | too much scope for a clean launcher slice
Rejected: Fake the process wrapper behind mocks only | would not validate spawning, env injection, or stdio wiring
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Layer future MCP protocol framing on top of McpStdioProcess rather than bypassing it with ad hoc process management
Tested: cargo fmt --all; cargo clippy -p runtime --all-targets -- -D warnings; cargo test -p runtime
Not-tested: live third-party MCP servers; long-running process supervision; stderr capture policy
