archstone

# Archstone — connect your business to every AI

**A compiler for AI capabilities.** You describe what your business can do, once, in
business terms. Archstone compiles that 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.

---

## See it work — 60 seconds, nothing to install

A capability compiled by Archstone is running live. Point Claude at it:

```
https://demo.archstone.dev/mcp
```

Open Claude (web, desktop or mobile) → **Settings** (or **Customize**) → **Connectors** →
**Add custom connector** → paste the URL. Then ask about a trip — a destination, dates, a
budget. Works on Free too (one custom connector is all this needs).

Prefer a terminal:

```bash
claude mcp add --transport http archstone-tourism https://demo.archstone.dev/mcp
```

The backend behind it is a plain HTTP service, and you can curl it directly — the same data
the agent sees, deterministic so the shape is obvious:

```bash
curl -s -X POST https://demo.archstone.dev/v1/search \
  -H "content-type: application/json" -d '{"destination":"Rome"}'
```

The entire integration that made this callable by an agent is
[12 lines of business YAML](examples/manifests/tourism/tourism.search.capability.yaml) — no
HTTP, no JSON Schema, no MCP SDK. Everything else was generated.

## Start from an API you already have

Point `archstone init` at an OpenAPI document. It reads the spec, asks you the questions no
document can answer, runs the real compiler over what it drafted, and writes nothing at all if
that does not compile.

![archstone init reading an OpenAPI document and writing a compiling CDL manifest](docs/init.gif)

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

The one answer it never guesses is `effect` — `read`, `write` or `irreversible` is the
difference between looking up a price and charging a card, and no spec says which. Where a
response could honestly be read two ways, it asks rather than picking. With `--probe` it will
also make one read-only call to your real backend and record a genuine fixture, so
`archstone verify` has something true to replay later.

The spec in that recording is
[`examples/demo/stays-openapi.yaml`](examples/demo/stays-openapi.yaml), describing the demo
backend in this repository — you can run it yourself.

## Who is running it

**[ArtVinci](https://artvinci.ro)** — a custom-framing business — answers customer questions
today through a capability compiled by Archstone. Real catalog, real prices computed live by
their own backend. See the [case study](CASE-STUDY.md).

---

## Why a compiler, and not just an MCP server

Writing your first MCP server is not the hard part — it is a few hundred lines, and you can
do it in an afternoon.

The work is the fifth one. ChatGPT, Gemini and whatever ships next each want the same
capability shaped slightly differently, every one of them is a separate integration project,
and your API keeps changing underneath all of them at once.

> **Archstone is not an MCP server. It is a compiler that, in its first release, generates one.**

One capability definition (CDL) lowers to a target-agnostic **IR**; emitters consume the IR.
MCP today; REST · GraphQL · SDK tomorrow. Change the protocol and you regenerate — you do not
rewrite. Change the backend and the CDL and the generated tool do not move at all.

That is what *zero manual integration* means: not that the first server is easy, but that the
maintenance disappears instead of multiplying.

---

## How it works

```
capabilities.yaml   →   *.capability.yaml   →   bindings/*.binding.yaml
(what the company     (each capability:        (how one capability maps
 offers — the index)   business shape only)     to a real HTTP endpoint)

        └──────── archstone apply ────────┘        └── archstone serve ──┘
             parse → validate → compile → IR          emit MCP tools → agent
```

You describe capabilities in **CDL** (Capability Definition Language) — business only, no
integration code. Archstone compiles that to a target-agnostic **IR**, and an emitter turns
the IR into tools an AI agent can call. Swap the backend; the CDL and the generated tool do
not change.

Capability outputs reference named **resources** (`*.resource.yaml`); the compiler resolves
them into a typed, described `outputSchema`, and a binding's `response:` mapping enforces
that shape at every call — a required field missing from the provider's response fails
closed (a structured error, never a silent raw pass-through). `archstone verify` replays a
recorded fixture against the live backend on demand and reports a 🟢/🟡/🔴 health status per
binding, so contract drift shows up before an agent hits it.

---

## Quick start

**From source (this repository):**

```bash
pnpm install

# Scaffold a manifest from an API you already have (opt-in, read-only, no LLM)
pnpm exec tsx packages/cli/src/index.ts init path/to/openapi.yaml --out my-manifest --domain catalog

# Compile a manifest: validate + lower to IR
pnpm apply examples/manifests/booking

# Build a portable IR artifact (for embedding in your own app)
pnpm build examples/manifests/tourism

# Serve it to an AI agent as MCP tools over stdio
pnpm serve examples/manifests/tourism

# Serve it as MCP over HTTP (e.g. for Claude API mcp_servers)
pnpm serve --http examples/manifests/tourism --token my-bearer-token

# Replay a binding's golden fixture against the live backend; detect drift
pnpm verify examples/manifests/tourism

# Get structured JSON output for integration with CI pipelines and dashboards
pnpm verify examples/manifests/tourism --json
```

**From npm (standalone CLI):**

```bash
# Install globally or use npx
npm install -g @archstone/cli
# or
npx @archstone/cli apply <manifest-dir>

# Then run the same commands:
archstone init path/to/openapi.yaml --out my-manifest --domain catalog
archstone apply examples/manifests/booking
archstone build examples/manifests/tourism
archstone serve examples/manifests/tourism
archstone serve --http examples/manifests/tourism --token my-bearer-token
archstone verify examples/manifests/tourism
archstone verify examples/manifests/tourism --json
```

---

## Where your CDL lives

**Your business's CDL manifest** (`capabilities.yaml`, `*.capability.yaml`, `*.resource.yaml`,
and `bindings/*.binding.yaml`) is authored and version-controlled in **your own application
repository** — never inside this Archstone repository or any other Archstone-owned repository.

**`@archstone/cli` is a stateless compiler.** It runs locally on your machine or in your own CI
pipeline with zero checkout of any Archstone repository required — public or private. Install
`@archstone/cli` from npm; point it at your manifest directory; it compiles to IR and reports
the result. That's the entire integration: no cross-repo credentials, no monorepo dependency,
no fetch-at-runtime.

> **Distinguishing "From source" above:** the instructions above for exploring Archstone's
> source code are for **contributors building Archstone itself**. The real integration path
> for your business is to **install `@archstone/cli` from npm into your own repository** and
> wire `archstone apply`/`archstone build`/`archstone serve`/`archstone verify` into your own build system.
> See the [onboarding guide](docs/ONBOARDING.md) for the full walkthrough.

---

New here? Start with the **[onboarding guide](docs/ONBOARDING.md)** — one path for
**providers** (expose your business to agents) and one for **contributors** (build
Archstone).

---

## Embedding Archstone

Rather than running `archstone` as a separate CLI or MCP server, you can embed the compiled
IR directly in your own agent loop. After building a portable IR with `archstone build`,
consumers can use the **`@archstone/agent`** SDK (RFC-0008):

```typescript
import { fromIR, tools, execute } from "@archstone/agent";
const archstone = fromIR(compiledIR);

// Get typed tool definitions in your preferred format
const myTools = archstone.tools("anthropic"); // or "openai" / "gemini" / "json-schema"

// Invoke capabilities directly — no MCP server process needed
// Accepts both raw dotted id and sanitized tool name (as returned by tools())
const result = await archstone.execute("tourism.search", { location: "Paris" });
// or: await archstone.execute("tourism_search", { location: "Paris" });
```

For those who want HTTP-based MCP (e.g., to expose an embedded instance via Claude API's
`mcp_servers`), the `/mcp` subpath provides a mountable Streamable-HTTP handler:

```typescript
import { mcpHandler } from "@archstone/agent/mcp";
const handler = mcpHandler(archstone, { bearerToken: "..." });
// Mount on your framework's HTTP router
```

See [`packages/agent`](packages/agent/) for full API docs and examples.

---

## Start here

| Read first | Path |
|---|---|
| **Onboarding** | [`docs/ONBOARDING.md`](docs/ONBOARDING.md) |
| **A business running on it** | [`CASE-STUDY.md`](CASE-STUDY.md) |
| **CDL by example** | [`examples/manifests/booking/`](examples/manifests/booking/) |
| **The schemas (wire format)** | [`packages/schema/schemas/`](packages/schema/schemas/) |
| **End-to-end demo (Claude)** | [`examples/demo/README.md`](examples/demo/README.md) |

---

## Repository layout

```
archstone/
├── packages/
│   ├── schema/
│   │   └── schemas/     # JSON Schema — cdl.schema.json validates the language
│   ├── compiler/        # compile → IR  (src/ir.ts = the moat: target-agnostic)
│   ├── emitter-support/ # IR indexing + semantic-type → JSON-Schema lowering (RFC-0008)
│   ├── agent/           # embedded SDK: fromIR(), tools(), execute() (RFC-0008)
│   ├── runtime/         # registry + MCP emitter (stdio + HTTP)
│   └── cli/             # `archstone apply` / `build` / `serve` / `verify` — wires pipeline
├── providers/
│   └── rest/            # REST adapter (providers = adapters)
├── examples/            # manifests + the Claude demo
└── docs/