io.github.Archstone-Romania/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.

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:

  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.

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:

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