Repository avatar
AI Tools
v0.36.0
active

archstone

io.github.NousVigil/archstone

Compile your own business capabilities from declarative YAML and serve them as MCP tools.

Documentation

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

I want to…Go to
See it working in 60 secondsTry it
Generate a manifest from my OpenAPI specStart from an API you already have
Install the CLI and know what each command doesInstall · Commands
Understand the model (CDL → IR → tools)How it works
Call capabilities from my own agent loopEmbed it
Know what Archstone guaranteesGuarantees
Learn the languageCDL specification · glossary
Walk through it end to endOnboarding guide
Know what is free and what is soldOpen source and commercial
ContributeContributing

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:

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

    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? hello@archstone.dev.

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

CommandWhat 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 record <dir>Record a contract: for an existing manifest's read bindings, one live request each (interactive); --rerecord <id> replaces one
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:

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.

GuaranteeDecision
A provider field your manifest does not declare never reaches a modelADR-0008
A field a model invents never reaches your systemADR-0011
build and serve never need a network call, an account or a keyADR-0005
No feature that is free today becomes paidADR-0005
Ranking in any selection Archstone performs is not for saleADR-0006
effect (read / write / irreversible) is confirmed by a person, never inferredOnboarding

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

TopicWhere
Onboarding (providers, embedders, contributors)docs/ONBOARDING.md
CDL specification (normative, 1.0, frozen)docs/cdl-specification.md
Why CDL looks the way it doesRFC-0002
Machine schemacdl.schema.json
Glossarydocs/glossary.md
Identity and principalsdocs/IDENTITY.md
Architecture decisionsdocs/adr/
A Postgres database as a backend (sql connector)docs/guides/sql-connector.md
End-to-end demo with Claudeexamples/demo/README.md
Supported versionsSUPPORT.md
Reporting a vulnerabilitySECURITY.md — never a public issue
ChangesCHANGELOG.md

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 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.

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.

NPM
@archstone/cli
Install Command
npm install @archstone/cli
Runtime: npx