Expand description
§lm-provision-mcp
§Architecture
The MCP server that exposes lm-provision to MCP clients
(10-mcp.md) — in particular an external pod manager that delegates
its provisioning half to this server while keeping pod lifecycle on
its own side (08-push-driver-protocol.md §Purpose). Phase H, the
last layer to be built: F (01-06, on-pod apply) →
G (07-09, driver + ledger) → H (10, this crate).
The tools (10 §Tool set), across three call shapes:
- Local, read-only (
pipeline):lm_validate/lm_hash/lm_plancall straight into thelm-provisionlibrary in-process —profile_pathis a path visible to this server’s own host (10 §Inputs), and none of the three touches a bridge or a pod (07-cli.md §Invocation: “none (read-only)”). - Driver-mediated (
apply_tool,ledger_tools):lm_applyruns the full chapter 08 protocol against thelm_provision_driver::transport::Transportitspod_idresolves to (seetargets) and appends the result to the append-only ledger (09 §Ledger);lm_ledger_list/lm_ledger_getread that same ledger back. - Platform-reading (
lm_provision_driver::inventory):lm_machine_listasks a platform what it is running and reads the lease off each machine’s own name (08 §Acquisitions and sweep). Read-only, and the same function the operator CLI’smachine listanswers from.
server wires them all as MCP tools via rmcp’s
#[tool_router] / #[tool] macros over the plain functions in
pipeline / apply_tool / ledger_tools / the driver’s
inventory module — those functions are deliberately rmcp-free and
directly testable at the function level, independent of any MCP
transport.
§Serving it
There is no binary here. lm-provision mcp (in lm-provision-cli)
resolves config::Config from the process environment and serves
server::LmProvisionServer over stdio — one command for an
operator to install, and the MCP server as a subcommand of it.
config resolves the server’s deployment configuration (binary
path, default staging directory, ledger path, pod target registry)
once at startup.
§Pod targets (targets)
lm_apply’s pod_id selects where the apply runs: server
resolves it against the startup-loaded targets::TargetRegistry
and hands the resulting transport to apply_tool::lm_apply. An
unregistered pod_id fails before any effect, so a ledger row’s
pod_id names a destination the server was actually configured for
rather than an unchecked string. Pod connection details are server
deployment configuration, never tool arguments.
§Secrets (10 §Inputs)
“The MCP server process environment is the secret source …
Secrets: … Tool arguments never carry secret values; a tool call
cannot inject env.” No tool parameter type in server carries a
secret value or a raw env map; apply_tool::lm_apply reads every
declared env_secrets name directly from std::env (see that
module’s own doc comment for the precondition check this implies).
Modules§
- apply_
tool lm_apply(profile_path, pod_id, dry_run=false)(10-mcp.md §Tool set): runs one driver session (session::run, 08 §Session steps 0-5) against theTransportthe caller supplies — ensure-binary → place-profile → hash-verify → invoke → collect → ledger append (09 §Ledger).- config
- Server deployment configuration: how this server reaches pods, and which pods it may reach at all.
- ledger_
tools lm_ledger_list/lm_ledger_get(10-mcp.md §Tool set): read-only wrappers overlm_provision_driver::ledger(09-apply-report-and-ledger.md §Ledger). The row locator format is provisional (10 §Stability: “until the ledger storage owner fixes it”) — this MVP reuses the same newest-first integer indexledger::getalready defines rather than inventing a second one.- pipeline
- Local, read-only pipeline tools:
lm_validate/lm_hash/lm_plan(10-mcp.md §Tool set) — each a direct, in-process call into thelm-provisionlibrary’s own AST pipeline functions (lm_provision::cli::ast_validateetc.), sinceprofile_pathis a path visible to the MCP server host (10 §Inputs: “profile authoring/upload is out of scope”) and none of these three subcommands touches an effect or a pod (07-cli.md §Invocation: “none (read-only)”). Plain,async-free functions on purpose so tests can call them directly at the function level rather than through an MCP transport — mirroringcrate::apply_tool/crate::ledger_tools. - profile_
host DslHostadapter forlm-provision’sProfileNodeDSL.- server
- MCP tool wiring (10-mcp.md §Tool set) over the plain, transport-free
functions in
crate::pipeline/crate::apply_tool/crate::ledger_tools. Every blocking call (subprocess spawn, ledger file I/O) runs throughtokio::task::spawn_blockingrather than inline in anasync fn: a blocking call made directly insideasyncstalls the runtime’s worker thread. - targets
- Pod target registry: the server-side table that binds a
pod_idto the place an apply actually runs.