DEV Community: Adrian Bratulescu

I wrote a tool that reads your OpenAPI spec and refuses to guess

Adrian Bratulescu — Tue, 18 Aug 2026 08:48:45 +0000

Everyone's first instinct, when they see "turn an OpenAPI document into tool definitions an AI agent can call," is to hand the spec to a model and ask nicely.

The trouble with that is the failure rate you land on. Not 100%, so you can't ship it unread. Not 50%, so you can't dismiss it. Somewhere in between — which means you spend longer reviewing the output than you would have spent writing it, and the mistakes are precisely the ones that look correct.

So archstone init has no LLM on any path. Not as a purity thing — because the interesting parts of this problem are the parts a model is worst at.

The problem, precisely

You have a REST API. You want AI agents — Claude, ChatGPT, whatever ships next quarter — to be able to call it. The modern answer is MCP, and the modern shortcut is "generate an MCP server from your OpenAPI spec."

That shortcut has a hole in it. An OpenAPI document describes your HTTP surface. It does not describe your business. It says POST /v1/bookings returns 201. It does not say whether calling that charges someone's card.

That difference is the whole job.

It's a loop, not a generator

The first thing that makes this different from codegen: nothing is written to your directory until it has already compiled.

init drafts the manifest in a temp directory, runs the real pipeline over it — load → validateSemantics → compile → new Registry(), the same code path the actual compiler uses, not a lookalike — and only then commits the files.

There are exactly two terminal states:

a manifest that compiles was written, or
nothing was written, and here is why

No half-scaffold. If the draft doesn't compile, if two capabilities collide on a tool name, if the confirmed set comes back empty — zero files. You never clean up after it.

That invariant is load-bearing enough that it has a bug story. During review, commitFileSet({force: true}) was found overlaying files onto the target with cpSync without deleting first — so a file left by a previous run could survive into the committed output having never been compiled. It wasn't in the temp directory that got validated. The second run would report ok: true, failures: [] while compiling the result actually failed with two semantic errors.

Every individual function was correct. The defect lived entirely in the gap between which file set was validated and which file set reached disk. That's the class of bug that "just ask the model" cannot even be wrong about, because it never had the invariant in the first place.

The one answer it never guesses

CDL capabilities carry an effect: read, write, or irreversible.

No OpenAPI document contains this. You might think method maps to it — GET is read, POST is write — and then you meet POST /search, which every real API has, and the mapping is dead.

effect is the difference between looking up a price and charging a card. An agent that treats one as the other is not a bug report, it's an incident. So init refuses to infer it. A confirmed effect exists only in a Decision Record — an explicit artifact of a human answering — and the emitter takes the Decision Record, never an adapter's hint.

Slower. Correct.

Ambiguous is a refusal, never a guess

The rule the inference code is built around, quoted from its own header:

AMBIGUOUS IS A REFUSAL, NEVER A GUESS.

Here's where it bites. A response body like this:

{
  "estimatedPrice": 240,
  "currency": "EUR",
  "warnings": ["dimensions rounded to nearest cm"]
}

is structurally identical to a paginated list wrapper. There is one array of objects in there. Pick the array and you get a collection of warnings, and you have silently dropped the price — the entire point of the call.

That is not hypothetical. It happened, on a real document, to this tool. The price capability emitted a collection of warnings and no price. It compiled. It passed apply. It wrote files. It was found by running the tool against a real API, not by reading the rules.

The fix wasn't a better heuristic. It was to stop picking: init now enumerates the candidate response loci and asks which one is the payload.

The failure mode that would have reached your customers

This is the subtle one, and it's why I think the whole "just generate it" approach is more dangerous than it looks.

CDL fields can be required. Get that wrong in the strict direction and the compiler yells at you — loud, immediate, free.

Get it wrong in the loose direction — mark something required that your backend sometimes returns as null — and you ship a manifest that compiles, passes verification green, and then throws a contract violation the first time a real null comes back. Silent at build time. Loud in front of a customer.

So the rule is narrow on purpose: required: true only on positive evidence of non-nullability — declared required, and non-nullable, and (if probed) present and non-null on every recorded item. Anything less is optional.

The two ways of being wrong have completely different costs, so they don't get the same default.

It tells you what it didn't understand

The usual failure of a spec-reading tool is silent partial comprehension: it consumes your document, emits something plausible, and never mentions the 30% it skipped.

init inverts the default. Each object type declares the keys it reads and the keys it argues are inert — and everything else, including keys from a future OpenAPI revision and keys a contributor forgot to declare, falls through into the report rather than being dropped.

Anything it can't handle gets exactly one disposition: skip it, name it with a reason code, emit nothing for it. The codes are a closed, written-down list — no-response-shape, ambiguous-collection, pagination-not-modeled, nested-object-not-mapped, field-path-not-expressible, and so on. A contributor adding support for a new construct has to either reuse a code or argue for a new one in the open, rather than quietly half-handling it.

Every fact in the intermediate model also carries its derivation — declared (from the spec), observed (from a real response), or absent — so a classification made from three observed items says so, instead of presenting itself as a measurement.

Optionally, it calls your backend once

With --probe, init will make one read-only request and record a real fixture, so archstone verify has something true to replay later.

The consent model is deliberately annoying:

off by default
asked per capability, not once for the run
never issued for a capability whose confirmed effect isn't read
a non-GET/HEAD method needs a second, separate confirmation
refused outright when there's no terminal to ask at

And the recorded fixture is written by the same recordContract() in the runtime, over the same invokeRest call, that verifyTool uses. So the fixture init writes is by construction the artifact verify later replays — not a lookalike that drifts.

Try it

npm i -g @archstone/cli
archstone init openapi.yaml --out manifest --company acme --domain catalog

There's a spec in the repo you can run it against without pointing it at anything of yours (examples/demo/stays-openapi.yaml), and a live compiled capability you can add to Claude in about thirty seconds, no install:

https://demo.archstone.dev/mcp

Apache-2.0: https://github.com/Archstone-Romania/archstone

The broader argument — why any of this is a compiler and not just another MCP server — is here. This post is the part you can run.

Why I built a compiler, not the fifth MCP server

Adrian Bratulescu — Fri, 31 Jul 2026 19:53:27 +0000

Writing your first MCP server is not hard. It is a few hundred lines, and you can have one running before lunch. I know, because I wrote one.

The problem is the fifth one.

The shape of the work

Here is what actually happens when a company decides its capabilities should be reachable by AI agents.

You write an MCP server. It works. Then ChatGPT wants the same capability shaped slightly differently. Then Gemini. Then whatever ships next quarter, because something always ships next quarter. Each one is a separate integration project with its own SDK, its own idea of what a tool definition looks like, and its own release cadence.

And underneath all of them, your own API keeps changing — a field gets renamed, a response becomes nullable, an endpoint moves. Now you have four hand-written integrations that are each independently wrong, and no build step that will tell you.

The first server is an afternoon. The fifth is a team.

So the question I got stuck on was not how do I write an MCP server. It was: what is the artifact that survives when the protocol changes?

One definition, many emitters

That question has a boring, well-understood answer, and it is the same answer compilers have been giving since the 1970s: put an intermediate representation in the middle.

capabilities.yaml  →  semantic model  →  IR  →  emitter  →  MCP tools
                                          ↘  emitter  →  SDK / REST / GraphQL / …

You describe a capability once, in business terms — what it does, what it needs, what it returns, and whether calling it is safe to retry. No HTTP, no JSON Schema, no SDK. That lowers to a target-agnostic IR, and emitters consume the IR.

The whole tourism.search capability in the demo is twelve lines:

capability:
  id: tourism.search
  description: Find places to stay matching a traveler's intent.
  effect: read

  input:
    destination: { type: location }
    dates:       { type: date-range }
    travelers:   { type: party }
    budget:      { type: money, required: false }

  output:
    stays: { collection: Stay }

  provider: booking-engine

Change the protocol and you regenerate. Change the backend and the definition does not move at all — only the binding does, which is a separate file that never appears in the business description.

The evidence that the IR is the product, not MCP

This is the part I would want to see if someone else were making the argument, so here it is.

The system that most depends on Archstone in production does not speak MCP at all.

ArtVinci is a custom-framing workshop. Its site runs an assistant that answers customer questions — real catalog, real prices computed live by its own backend. It does not run an MCP server process. It loads the compiled IR directly:

const result = await archstone.execute("framing.estimate-frame-price", input);

Same IR, same validation, same fail-closed response mapping as the MCP path — just no separate process to deploy. MCP is one emitter. If it had been the product, that deployment would have been impossible.

The part that is actually hard

Generating a tool definition is the easy half. The half that decides whether an agent gives your customer a wrong answer is the response mapping.

A binding says where each field of a declared resource comes from in the provider's payload, and which of them are required. When a required field is missing, the call fails closed — a structured error, never a silent pass-through of whatever the backend happened to return. A missing optional field degrades instead. Those two words, DEGRADED and VIOLATION, are the difference between an agent saying "I don't have that" and an agent inventing a price.

And because a provider will eventually change its payload without telling you, each binding carries a recorded fixture and a fingerprint. archstone verify replays the recorded request against the live backend on demand and reports a health status per binding, so contract drift surfaces as a red line in your CI rather than as a customer complaint.

"But I could just paste my OpenAPI spec into Claude"

Yes. You could, it would take ninety seconds, and it would cost you nothing. This was the sharpest objection anyone raised while I was building the onboarding command, and I think it is correct as far as it goes.

So archstone init is deliberately not a code generator. It is a loop:

It reads your OpenAPI document and proposes candidates.
It asks you the questions no document can answer — chiefly whether a call is read, write or irreversible, which is the difference between "look up a price" and "charge a card."
It runs the real compiler. If the manifest it drafted does not compile, it writes nothing at all. There is no "mostly works, fix the errors yourself" mode.
Optionally, it calls your real backend, once, read-only, and records a genuine fixture — then replays it through the shipped mapper to check that its own mapping actually holds.

A language model can write plausible YAML. It cannot run your compiler or call your API. That is the entire difference, and it is why every unit of effort went into the loop rather than into nicer field names.

An example of it being wrong, because that is more useful

The first time I pointed init at a real spec, it produced a price-estimation capability whose entire output was a list of advisory warnings. No price.

The rule was working exactly as designed: find the array of objects in the response, make it the resource. In that response the only array of objects was warnings. The payload — the price, the currency, the geometry — sat in scalar fields beside it and got dropped.

It compiled. It passed validation. It wrote files. An agent calling that tool would have received a list of warnings and no price, and nothing anywhere would have flagged it.

The fix was not a cleverer heuristic. Distinguishing "the array is the payload and the scalars are pagination" from "the array is diagnostics and the scalars are the payload" cannot be done from the document — the two shapes are structurally identical. So init now enumerates the candidates and asks, once, with the field names shown. One candidate, no question.

That is the general posture, and it is the only thing keeping a tool like this honest:

An ambiguity is a question or a refusal, never a guess.

What it costs you

You write YAML describing your business. That is the trade. If your capabilities are genuinely one endpoint and you never expect a second protocol, hand-writing an MCP server is the right call and you should do that instead.

The compiler earns its keep at the point where you have several capabilities, more than one consumer, and a backend that changes — which is to say, at the point where the hand-written version stops being an afternoon.

Archstone is Apache-2.0: github.com/Archstone-Romania/archstone. A capability compiled by it is live — paste https://demo.archstone.dev/mcp into Claude's custom connectors and ask about a trip.