api-mcp-compiler

Compile REST/OpenAPI and SOAP/WSDL services into agent-ready MCP tool surfaces that are semantically designed, policy-governed and evaluation-backed.

Turning one API operation into one MCP tool is already commodity. The harder and more useful problem is deciding which tools should exist, what they should be called, what they should accept and return, and what may not be invoked without a human in the loop.

specification -> ingestion -> API Semantic IR -> planner -> tool plan
                                                    |
                              overlay (human decisions)
                                                    |
                                              policy manifest
                                                    |
                                          generated tool surface
                                                    |
                                    runnable MCP server (HTTP or SOAP)

What it does

Stage	Input	Output
Ingestion	OpenAPI 3.x, Swagger 2.0, WSDL 1.1	API Semantic IR
Planning	IR, overlay	Tool plan
Policy	IR, plan	Policy manifest
Generation	IR, plan, manifest	Tool surface
Review	Plan	Overlay
Evaluation	Surface, corpus	Evaluation run

Each stage has its own versioned contract, and each artifact carries the digest of the specification it came from.

Where to start

• Install, then run the verification gate to confirm the checkout is sound.
• Quickstart walks a specification to a running server in nine commands.
• The notebook does the same walk with every intermediate value printed, and its outputs are re-executed by the verification gate so they cannot go stale.

What this project claims, and what it does not

It claims that a tool surface should be designed rather than transliterated, that judgement should be proposed rather than applied, and that a write or destructive tool should not exist in executable form until a human has approved it.

It does not claim that a semantically planned surface measurably beats one tool per operation. That question has been pre-registered and measured four times, and every result was inconclusive. The claim remains argued, not demonstrated, and this documentation says so wherever it comes up.

Design properties in one page

Every informative field carries provenance. The field name, a pointer into the source document, how the value was derived (source, normalized, inferred, default) and a confidence. An inference cannot claim certainty and a source fact cannot express doubt.

Nothing is dropped silently. What cannot be resolved becomes an Ambiguity beside the construct that produced it, and a completeness sweep reports every key an adapter did not read.

Ingestion never reaches the network. Remote $ref resolution is refused outright, and local resolution only inside directories you name.

Inference can only make an operation look less safe. It raises a write to destructive; it never lowers a class.

Judgement never becomes silent action. Every planner decision is a proposal with a rationale and a confidence, and applies only once recorded in an overlay bound by digest to the specification revision it was reviewed against.

A tool is executable only if it earned it. See the emission gate.

Governance is derived, not assumed. See policy.

Evaluation is decided by state, never by a model. See evaluation.

Author

Subhadip Mitra, subhadipmitra.com, contact@subhadipmitra.com. Licensed Apache-2.0.