A compiler for AI capabilities. Describe what your business can do once, in business terms.
Archstone compiles it into tools an AI agent can discover and call — MCP today, other protocols
as they arrive. Nobody hand-writes integration code.
Open source, Apache-2.0.
Load and shape-validate Archstone CDL manifests — the JSON Schema for the Capability Definition Language.
A capability compiled by Archstone is running live:
https://demo.archstone.dev/mcp
Claude app (web, desktop or mobile): Settings → Connectors → Add custom
connector → paste the URL, then ask about a trip. Works on the Free plan.
Claude Code:
claude mcp add --transport http archstone-tourism https://demo.archstone.dev/mcp
The read-only tools need no key. The demo's booking tools do; its two public keys are listed in
the showcase. To send one, add the
server with the header after the name and URL (--header takes every word that follows it, so
placed earlier it swallows them):
Node 22+. Your manifest lives in your own repository; the CLI is a stateless compiler that
needs no checkout of this one
(why).
Commands
Command
What it does
archstone init <openapi>
Draft a manifest from an OpenAPI document (or, with --source postgres --dsn-env <VAR>, from a Postgres catalog)
archstone apply <dir>
Validate and compile to IR; --exposure lists what a model sees and what it never sees, and which capabilities are exposed, unlisted or not exposed (retired, unbound)
archstone build <dir>
Write a portable IR artifact for embedding
archstone serve <dir>
Serve MCP tools over stdio; --http --token <t> for HTTP
archstone verify <dir>
Replay recorded fixtures against the live backend and report drift; --json for CI
archstone doctor <dir>
Offline pre-production checklist
archstone adopt <dir>
Declare a field the backend started returning (interactive)
archstone audit <log>
Read back the execution audit trail
apply also warns about what an irreversible capability still lacks — here, removing its
declared failures adds a warning, and restoring them clears it:
Each command is covered in the onboarding guide.
Working from a checkout of this repository instead? Use pnpm apply, pnpm serve, … — see
contributor onboarding.
How it works
capabilities.yaml → *.capability.yaml → bindings/*.binding.yaml
(what the company (each capability: (how a capability maps
offers — the index) business shape only) to a real backend)
└──────── archstone apply ────────┘ └── archstone serve ──┘
parse → validate → compile → IR emit MCP tools → agent
CDL (Capability Definition Language) describes what you offer — business terms only.
Bindings say how each capability reaches a backend (REST or SQL). The
SQL connector guide walks through a Postgres one.
The compiler lowers both to a target-agnostic IR; emitters turn the IR into tools.
Change the protocol and you regenerate instead of rewriting. Change the backend and the CDL does
not move. A worked example: examples/manifests/booking/.
Embed it in your own agent
No MCP server process needed — load a built IR with
@archstone/agent:
import { fromIR } from "@archstone/agent";
const archstone = fromIR(compiledIR);
const tools = archstone.tools("anthropic"); // or "openai-chat", "openai-responses", "gemini", "json-schema"
const result = await archstone.execute("tourism.search", { location: "Paris" });
A mountable Streamable-HTTP MCP handler is available at @archstone/agent/mcp. Full API:
packages/agent.
Guarantees
These are ratified decisions, not implementation details — each links to its reasoning.
Guarantee
Decision
A provider field your manifest does not declare never reaches a model
ArtVinci, a custom-framing business, answers customer questions
through a capability compiled by Archstone — real catalog, prices computed live by their own
backend. Case study.
Why a compiler, and not an MCP server
The first MCP server is an afternoon's work. The fifth — ChatGPT, Gemini and whatever ships
next, each shaped slightly differently, all on top of an API that keeps changing — is the real
cost. Archstone is a compiler that, in its first release, generates an MCP server, so that
maintenance does not multiply with every new protocol.
Open source and commercial
Everything needed to turn a manifest into something an agent can call — language, compiler, IR,
emitters, embedded SDK and CLI — is Apache-2.0 and stays that way. What we will sell is
operating it for you: hosted audit retention, managed rate limits, drift monitoring and
multi-tenant hosting. See ADR-0005.
packages/
schema/ load and shape-validate manifests (cdl.schema.json)
compiler/ semantic validation, lowering to IR
emitter-support/ shared substrate for every emitter
runtime/ registry, MCP emitter and transport, verify
agent/ embedded SDK
init/ OpenAPI → manifest drafting
cli/ the archstone command
providers/
rest/ sql/ backend adapters
examples/ manifests and the Claude demo
docs/ spec, ADRs, RFCs, onboarding
How this project uses generative AI
Archstone is written with substantial AI assistance — Anthropic's Claude, through Claude Code —
for implementation, tests and documentation. The decisions are not generated: every
structural choice is an ADR, argued and ratified by an accountable person before the code, and
a patch nobody can explain does not merge. Commits with generated code name the model in their
co-authorship trailer. What we ask of contributors:
CONTRIBUTING.md.