CLI reference¶
api-mcp-compiler COMMAND [OPTIONS]
# or, from a checkout
.venv/bin/python -m api_mcp_compiler.cli COMMAND [OPTIONS]
No command runs an MCP server, binds to an SDK, or reaches the network. serve writes a server
module; running it is a separate act.
Options shared by most commands¶
| Option | Meaning |
|---|---|
--kind auto\|openapi\|wsdl |
Override format detection. Detection is by file suffix and content, and auto is almost always right. |
--allow-dir PATH |
A directory whose files may be loaded by $ref. Repeatable, omitted by default, checked against resolved real paths so ../ cannot escape. |
--planner baseline\|semantic |
Which planner to use. The baseline exists only for controlled comparison. |
--overlay PATH |
A reviewed overlay. Its digest must match the specification, so decisions made about other bytes are refused rather than silently applied. |
inspect¶
Parse a source document and print the normalized IR as canonical JSON.
--baseline includes the baseline tool plan alongside the IR, and is on by default.
plan¶
Print a tool plan as canonical JSON.
Every artifact is proposed until a reviewer records approval in an overlay.
policy¶
Print the governance manifest for a planned surface as canonical JSON.
generate¶
Generate a tool surface and print it as canonical JSON.
The surface binds to no MCP SDK and performs no I/O. A tool is emitted executable only when its source operation carries no blocking ambiguity, its risk is classified, and any write, destructive or privileged tool has been approved. Refused tools are still emitted carrying the reason, so the surface stays auditable.
review¶
Print the human review report for the semantic plan, as Markdown.
report¶
Write the conversion report a reviewer reads before approving anything.
A self-contained HTML file naming the source digest it was produced from. Reports are never overwritten: each run writes a new file, because a decision made against one set of proposals is not evidence about a different set.
approve¶
Record approval for a class of tools, writing the overlay so nobody hand-edits JSON.
--risk covers read, write, destructive, privileged and unknown. --name is
repeatable. A selection that names nothing is refused, and so is one that matches nothing.
The command reports what it approved, what was already approved, and what it left untouched.
serve¶
Emit a runnable MCP server for the approved part of a surface.
Emits an HTTP server for OpenAPI and a SOAP server for WSDL, and prints the requirements the
generated module needs. Tools the gate refused are not registered, and are listed on the
surface://withheld resource instead.
overlay-restamp¶
Bind an overlay to the current specification revision.
Both arguments are positional, and the overlay is rewritten in place. Use this after an intended change to a specification, having re-read what was approved.
evaluate¶
Run an evaluation corpus against a generated surface and print the result.
Uses the deterministic replay driver and deterministic oracles over final service state. See evaluation.
validate¶
Validate the IR and baseline plan against their schemas and report ambiguities.
Exits non-zero if an artifact does not satisfy its contract.