Archstone

Archstone — connect your business to every AI

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.

[Buy Me A Coffee]

Find what you need

Try it — 60 seconds, nothing to install

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:

  bash

  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):

  bash

  claude mcp add --transport http archstone-tourism https://demo.archstone.dev/mcp \  --header "Authorization: Bearer <key>"

The whole integration behind it is 12 lines of business YAML — no HTTP, no JSON Schema, no MCP SDK. Everything else was generated.

Want this in front of your own systems? [email protected].

Start from an API you already have

archstone init openapi.yaml --out manifest --company acme --domain catalog

init drafts a manifest from an OpenAPI document, asks you what no spec can answer, and writes nothing unless the result compiles.

[archstone init reading an OpenAPI document and writing a compiling CDL manifest]

Details: onboarding → archstone init. The spec in the recording is examples/demo/stays-openapi.yaml.

Install

npm install -g @archstone/cli     # or: npx @archstone/cli <command>

Node 22+. Your manifest lives in your own repository; the CLI is a stateless compiler that needs no checkout of this one (why).

Commands

apply also warns about what an irreversible capability still lacks — here, removing its declared failures adds a warning, and restoring them clears it:

[archstone apply warning that an irreversible capability declares no failures]

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.

All decision records: docs/adr/.

Who is running it

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.

Documentation

Repository layout

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 commandproviders/  rest/  sql/       backend adaptersexamples/           manifests and the Claude demodocs/               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.

Contributing

CONTRIBUTING.md and the contributor onboarding. Node 22+, pnpm 11+; pnpm typecheck && pnpm test green before you open a PR.

License

Copyright 2026 NousVigil LLC. Licensed under Apache-2.0; see also NOTICE.