Crate brep_mcp_core

Expand description

brep_mcp_core — the BREP MCP server, host-agnostic.

Design record: docs/developer/mcp-automation-build-spec.md. The governing rule is that the shape of the engine drives the MCP: every tool, schema and resource this crate serves is read from a registry the engine or the app exposes, never from a table kept here. What lives in this crate is the translation to the Model Context Protocol, session management, the server-side compositions (image post-processing, scripts, validation) that are MCP concerns rather than engine concerns, and the two transports.

The crate does not depend on the app. A host owns an app instance and answers the host protocol; two exist: the app’s own window (brep-app --mcp, BREP_app/src/mcp.rs) and BREP_mcp’s headless egui_kittest harness. That is what lets the app embed the server without a dependency cycle.

Module map:

tools — the server’s view of a tool: ToolSpec (name, group, doc, derived input schema, annotations, handler) and the sets that produce them.
server — the dynamic rmcp::ServerHandler over those sets, stdio.
http — the same server over streamable HTTP on a loopback listener.
schema — the kernel feature catalogue rendered as JSON Schema.
validate— feature-parameter validation against the catalogue.
script — the test-mcp script format and its expectation operators.
image — PNG decode/encode, crop, scale, diff for screenshots.
runner — plays a script through a tool set and writes the artefacts.
generate— renders the registries to the checked-in generated docs.
host — the host protocol: envelopes, replies, the backend seam.
session — one app instance under one host, its directory and recorder.

Modules§

generate: Render the registries to the checked-in generated docs (docs/developer/mcp/generated/): what a reviewer diffs to see what a change exposed, and what the freshness test compares against. Nobody edits these.
host: The host protocol (spec §3.2). A host owns an app instance and answers commands; the server talks to it through HostHandle — a tokio channel in, a oneshot per reply out — so async tool handlers never block.
http: The server over MCP’s streamable HTTP transport, for an app that is already running (brep-app --mcp): an agent connects to http://127.0.0.1:<port>/mcp instead of launching a process. rmcp’s transport is a tower service; hyper serves it connection by connection on the listener the caller bound.
image: Screenshot post-processing: PNG encode/decode, crop, downscale, diff, and a drawn cursor. Pure CPU, image crate, no fonts (the set-of-marks annotation is Phase 5).
runner: The test-mcp script runner: plays a Script through a ToolSet, checks every expect, saves and compares images, and writes the per-step artefacts (NNNN-<tool>.json, images, result.json) under an output directory. It knows nothing about hosts or sessions: the tool set it is handed is whatever the session generated, so a script written against the running app and one written against the catalogue tools run the same way.
schema: The kernel’s feature catalogue (brep_kernel::feature_schema_catalogue, reached through brep_render::features) rendered as JSON Schema.
script: The test-mcp script format (spec Appendix E): a session description plus a list of tool calls, each with optional expectations on the tool’s JSON result and optional image capture / comparison.
server: The dynamic rmcp::ServerHandler.
session: A session: one app instance under one host, plus the session directory (store, shots, exports, log) and the recorder (spec §8).
tools: The server’s view of a tool.
validate: Feature-parameter validation against the kernel catalogue, run in the server before a feature_add / feature_set_params reaches the engine.