Skip to main content

lm_provision_mcp/
lib.rs

1//! # lm-provision-mcp
2//!
3//! ## Architecture
4//!
5//! The MCP server that exposes `lm-provision` to MCP clients
6//! (10-mcp.md) — in particular an external pod manager that delegates
7//! its provisioning half to this server while keeping pod lifecycle on
8//! its own side (08-push-driver-protocol.md §Purpose). Phase H, the
9//! last layer to be built: F (01-06, on-pod apply) →
10//! G (07-09, driver + ledger) → H (10, this crate).
11//!
12//! The tools (10 §Tool set), across three call shapes:
13//!
14//! - **Local, read-only** ([`pipeline`]): `lm_validate` / `lm_hash` /
15//!   `lm_plan` call straight into the `lm-provision` library
16//!   in-process — `profile_path` is a path visible to this server's
17//!   own host (10 §Inputs), and none of the three touches a bridge or
18//!   a pod (07-cli.md §Invocation: "none (read-only)").
19//! - **Driver-mediated** ([`apply_tool`], [`ledger_tools`]): `lm_apply`
20//!   runs the full chapter 08 protocol against the
21//!   [`lm_provision_driver::transport::Transport`] its `pod_id`
22//!   resolves to (see [`targets`]) and appends the result to the
23//!   append-only ledger (09 §Ledger); `lm_ledger_list` /
24//!   `lm_ledger_get` read that same ledger back.
25//! - **Platform-reading** ([`lm_provision_driver::inventory`]):
26//!   `lm_machine_list` asks a platform what it is running and reads the
27//!   lease off each machine's own name (08 §Acquisitions and sweep).
28//!   Read-only, and the same function the operator CLI's
29//!   `machine list` answers from.
30//!
31//! [`server`] wires them all as MCP tools via `rmcp`'s
32//! `#[tool_router]` / `#[tool]` macros over the plain functions in
33//! [`pipeline`] / [`apply_tool`] / [`ledger_tools`] / the driver's
34//! inventory module — those functions are deliberately `rmcp`-free and
35//! directly testable at the function level, independent of any MCP
36//! transport.
37//!
38//! ## Serving it
39//!
40//! There is no binary here. `lm-provision mcp` (in `lm-provision-cli`)
41//! resolves [`config::Config`] from the process environment and serves
42//! [`server::LmProvisionServer`] over stdio — one command for an
43//! operator to install, and the MCP server as a subcommand of it.
44//! [`config`] resolves the server's deployment configuration (binary
45//! path, default staging directory, ledger path, pod target registry)
46//! once at startup.
47//!
48//! ## Pod targets ([`targets`])
49//!
50//! `lm_apply`'s `pod_id` selects where the apply runs: [`server`]
51//! resolves it against the startup-loaded [`targets::TargetRegistry`]
52//! and hands the resulting transport to [`apply_tool::lm_apply`]. An
53//! unregistered `pod_id` fails before any effect, so a ledger row's
54//! `pod_id` names a destination the server was actually configured for
55//! rather than an unchecked string. Pod connection details are server
56//! deployment configuration, never tool arguments.
57//!
58//! ## Secrets (10 §Inputs)
59//!
60//! "The MCP server process environment is the secret source ...
61//! Secrets: ... Tool arguments never carry secret values; a tool call
62//! cannot inject env." No tool parameter type in [`server`] carries a
63//! secret value or a raw env map; [`apply_tool::lm_apply`] reads every
64//! declared `env_secrets` name directly from `std::env` (see that
65//! module's own doc comment for the precondition check this implies).
66
67#![warn(missing_docs)]
68
69pub mod apply_tool;
70pub mod config;
71pub mod ledger_tools;
72pub mod pipeline;
73pub mod profile_host;
74pub mod server;
75pub mod targets;