{
  "markdown": "# Archstone — connect your business to every AI\n\n**A compiler for AI capabilities.** You describe what your business can do, once, in\nbusiness terms. Archstone compiles that into tools an AI agent can discover and call —\nMCP today, other protocols as they arrive. Nobody hand-writes integration code.\n\nOpen source, Apache-2.0.\n\n[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png)](https://www.buymeacoffee.com/irutehe)\n\n---\n\n## See it work — 60 seconds, nothing to install\n\nA capability compiled by Archstone is running live. Point Claude at it:\n\n```\nhttps://demo.archstone.dev/mcp\n```\n\nOpen Claude (web, desktop or mobile) → **Settings** (or **Customize**) → **Connectors** →\n**Add custom connector** → paste the URL. Then ask about a trip — a destination, dates, a\nbudget. Works on Free too (one custom connector is all this needs).\n\nPrefer a terminal:\n\n```bash\nclaude mcp add --transport http archstone-tourism https://demo.archstone.dev/mcp\n```\n\nThe backend behind it is a plain HTTP service, and you can curl it directly — the same data\nthe agent sees, deterministic so the shape is obvious:\n\n```bash\ncurl -s -X POST https://demo.archstone.dev/v1/search \\\n  -H \"content-type: application/json\" -d '{\"destination\":\"Rome\"}'\n```\n\nThe entire integration that made this callable by an agent is\n[12 lines of business YAML](examples/manifests/tourism/tourism.search.capability.yaml) — no\nHTTP, no JSON Schema, no MCP SDK. Everything else was generated.\n\n## Start from an API you already have\n\nPoint `archstone init` at an OpenAPI document. It reads the spec, asks you the questions no\ndocument can answer, runs the real compiler over what it drafted, and writes nothing at all if\nthat does not compile.\n\n![archstone init reading an OpenAPI document and writing a compiling CDL manifest](docs/init.gif)\n\n```bash\narchstone init openapi.yaml --out manifest --company acme --domain catalog\n```\n\nThe one answer it never guesses is `effect` — `read`, `write` or `irreversible` is the\ndifference between looking up a price and charging a card, and no spec says which. Where a\nresponse could honestly be read two ways, it asks rather than picking. With `--probe` it will\nalso make one read-only call to your real backend and record a genuine fixture, so\n`archstone verify` has something true to replay later.\n\nThe spec in that recording is\n[`examples/demo/stays-openapi.yaml`](examples/demo/stays-openapi.yaml), describing the demo\nbackend in this repository — you can run it yourself.\n\n## Who is running it\n\n**[ArtVinci](https://artvinci.ro)** — a custom-framing business — answers customer questions\ntoday through a capability compiled by Archstone. Real catalog, real prices computed live by\ntheir own backend. See the [case study](CASE-STUDY.md).\n\n---\n\n## Why a compiler, and not just an MCP server\n\nWriting your first MCP server is not the hard part — it is a few hundred lines, and you can\ndo it in an afternoon.\n\nThe work is the fifth one. ChatGPT, Gemini and whatever ships next each want the same\ncapability shaped slightly differently, every one of them is a separate integration project,\nand your API keeps changing underneath all of them at once.\n\n> **Archstone is not an MCP server. It is a compiler that, in its first release, generates one.**\n\nOne capability definition (CDL) lowers to a target-agnostic **IR**; emitters consume the IR.\nMCP today; REST · GraphQL · SDK tomorrow. Change the protocol and you regenerate — you do not\nrewrite. Change the backend and the CDL and the generated tool do not move at all.\n\nThat is what *zero manual integration* means: not that the first server is easy, but that the\nmaintenance disappears instead of multiplying.\n\n---\n\n## How it works\n\n```\ncapabilities.yaml   →   *.capability.yaml   →   bindings/*.binding.yaml\n(what the company     (each capability:        (how one capability maps\n offers — the index)   business shape only)     to a real HTTP endpoint)\n\n        └──────── archstone apply ────────┘        └── archstone serve ──┘\n             parse → validate → compile → IR          emit MCP tools → agent\n```\n\nYou describe capabilities in **CDL** (Capability Definition Language) — business only, no\nintegration code. Archstone compiles that to a target-agnostic **IR**, and an emitter turns\nthe IR into tools an AI agent can call. Swap the backend; the CDL and the generated tool do\nnot change.\n\nCapability outputs reference named **resources** (`*.resource.yaml`); the compiler resolves\nthem into a typed, described `outputSchema`, and a binding's `response:` mapping enforces\nthat shape at every call — a required field missing from the provider's response fails\nclosed (a structured error, never a silent raw pass-through). `archstone verify` replays a\nrecorded fixture against the live backend on demand and reports a 🟢/🟡/🔴 health status per\nbinding, so contract drift shows up before an agent hits it — naming the fields the provider\ngained, lost or retyped, not merely reporting that something moved. Bindings whose capability\n`effect` is not `read` are skipped by default (replaying a fixture is a real invocation), and\nre-included only with `--sandbox`, an assertion that the backend is a sandbox tenant.\n\n**A field your manifest does not name never reaches a model.** That is deliberate: your\nprovider's payload very likely carries wholesale rates, commissions or internal ids beside the\nfields you publish, and a backend deploy adding one must not be a decision about what an\nassistant can say. Declaring a new field is a separate, deliberate act — `archstone adopt`\noffers each one, asks you to describe it, writes it into your resource and binding, and\nrecompiles before keeping anything. With stdin closed it refuses and writes nothing: it needs a\nperson, which is the point rather than a limitation.\n\n**And a field the model invents never reaches your system.** The same resource declaration read\nthe other way round: when a model *produces* business data — extracting a booking from an email,\na line item from an invoice — `archstone.extractor(\"tourism.Stay\", …)` hands it the closed schema\nand judges what comes back. A missing required field is a violation and the document is withheld\nwhole; an undeclared key is dropped and named; nothing is coerced, defaulted or repaired. One\nentity declared once, both directions of travel\n([ADR-0011](docs/adr/0011-undeclared-model-output-never-reaches-a-business-system.md)).\n\n---\n\n## Quick start\n\n**From source (this repository):**\n\n```bash\npnpm install\n\n# Scaffold a manifest from an API you already have (opt-in, read-only, no LLM)\npnpm exec tsx packages/cli/src/index.ts init path/to/openapi.yaml --out my-manifest --domain catalog\n\n# Compile a manifest: validate + lower to IR\npnpm apply examples/manifests/booking\n\n# Build a portable IR artifact (for embedding in your own app)\npnpm build examples/manifests/tourism\n\n# Serve it to an AI agent as MCP tools over stdio\npnpm serve examples/manifests/tourism\n\n# Serve it as MCP over HTTP (e.g. for Claude API mcp_servers)\npnpm serve --http examples/manifests/tourism --token my-bearer-token\n\n# Replay a binding's golden fixture against the live backend; detect drift\npnpm verify examples/manifests/tourism\n\n# Replay including write/irreversible capabilities (only for sandbox backends)\npnpm verify examples/manifests/tourism --sandbox\n\n# Get structured JSON output for integration with CI pipelines and dashboards\npnpm verify examples/manifests/tourism --json\n```\n\n**From npm (standalone CLI):**\n\n```bash\n# Install globally or use npx\nnpm install -g @archstone/cli\n# or\nnpx @archstone/cli apply <manifest-dir>\n\n# Then run the same commands:\narchstone init path/to/openapi.yaml --out my-manifest --domain catalog\narchstone apply examples/manifests/booking\narchstone build examples/manifests/tourism\narchstone serve examples/manifests/tourism\narchstone serve --http examples/manifests/tourism --token my-bearer-token\narchstone verify examples/manifests/tourism\narchstone verify examples/manifests/tourism --json\n\n# Check a manifest against the pre-production checklist — offline, no backend contacted\narchstone doctor examples/manifests/tourism\n\n# Declare a field the backend started returning (asks before writing; needs a person)\narchstone adopt examples/manifests/tourism\n```\n\n---\n\n## Where your CDL lives\n\n**Your business's CDL manifest** (`capabilities.yaml`, `*.capability.yaml`, `*.resource.yaml`,\nand `bindings/*.binding.yaml`) is authored and version-controlled in **your own application\nrepository** — never inside this Archstone repository or any other Archstone-owned repository.\n\n**`@archstone/cli` is a stateless compiler.** It runs locally on your machine or in your own CI\npipeline with zero checkout of any Archstone repository required — public or private. Install\n`@archstone/cli` from npm; point it at your manifest directory; it compiles to IR and reports\nthe result. That's the entire integration: no cross-repo credentials, no monorepo dependency,\nno fetch-at-runtime.\n\n> **Distinguishing \"From source\" above:** the instructions above for exploring Archstone's\n> source code are for **contributors building Archstone itself**. The real integration path\n> for your business is to **install `@archstone/cli` from npm into your own repository** and\n> wire `archstone apply`/`archstone build`/`archstone serve`/`archstone verify` into your own build system.\n> See the [onboarding guide](docs/ONBOARDING.md) for the full walkthrough.\n\n---\n\nNew here? Start with the **[onboarding guide](docs/ONBOARDING.md)** — one path for\n**providers** (expose your business to agents) and one for **contributors** (build\nArchstone).\n\n---\n\n## Embedding Archstone\n\nRather than running `archstone` as a separate CLI or MCP server, you can embed the compiled\nIR directly in your own agent loop. After building a portable IR with `archstone build`,\nconsumers can use the **`@archstone/agent`** SDK (RFC-0008):\n\n```typescript\nimport { fromIR, tools, execute } from \"@archstone/agent\";\nconst archstone = fromIR(compiledIR);\n\n// Get typed tool definitions in your preferred format\nconst myTools = archstone.tools(\"anthropic\"); // or \"openai\" / \"gemini\" / \"json-schema\"\n\n// Invoke capabilities directly — no MCP server process needed\n// Accepts both raw dotted id and sanitized tool name (as returned by tools())\nconst result = await archstone.execute(\"tourism.search\", { location: \"Paris\" });\n// or: await archstone.execute(\"tourism_search\", { location: \"Paris\" });\n```\n\nFor those who want HTTP-based MCP (e.g., to expose an embedded instance via Claude API's\n`mcp_servers`), the `/mcp` subpath provides a mountable Streamable-HTTP handler:\n\n```typescript\nimport { mcpHandler } from \"@archstone/agent/mcp\";\nconst handler = mcpHandler(archstone, { bearerToken: \"...\" });\n// Mount on your framework's HTTP router\n```\n\nSee [`packages/agent`](packages/agent/) for full API docs and examples.\n\n---\n\n## Start here\n\n| Read first | Path |\n|---|---|\n| **Onboarding** | [`docs/ONBOARDING.md`](docs/ONBOARDING.md) |\n| **A business running on it** | [`CASE-STUDY.md`](CASE-STUDY.md) |\n| **CDL by example** | [`examples/manifests/booking/`](examples/manifests/booking/) |\n| **The schemas (wire format)** | [`packages/schema/schemas/`](packages/schema/schemas/) |\n| **End-to-end demo (Claude)** | [`examples/demo/README.md`](examples/demo/README.md) |\n\n---\n\n## Repository layout\n\n```\narchstone/\n├── packages/\n│   ├── schema/\n│   │   └── schemas/     # JSON Schema — cdl.schema.json validates the language\n│   ├── compiler/        # compile → IR  (src/ir.ts = the moat: target-agnostic)\n│   ├── emitter-support/ # IR indexing + semantic-type → JSON-Schema lowering (RFC-0008)\n│   ├── agent/           # embedded SDK: fromIR(), tools(), execute() (RFC-0008)\n│   ├── runtime/         # registry + MCP emitter (stdio + HTTP)\n│   └── cli/             # `apply` / `build` / `serve` / `verify` / `doctor` / `adopt` — wires pipeline\n├── providers/\n│   └── rest/            # REST adapter (providers = adapters)\n├── examples/            # manifests + the Claude demo\n└── docs/                # rfc/ · adr/ · spec/ · glossary/ · ONBOARDING.md\n```\n\nThe compiler never lets `apply` poke a target directly — it compiles to an **IR**, and\nemitters (MCP now; REST · GraphQL · SDK later) consume the IR. That boundary is why the\nproduct survives a protocol change.\n\n---\n\n## The iconic file\n\n`capabilities.yaml` is to Archstone what `openapi.yaml` is to an API or `docker-compose.yaml`\nis to a stack: the one file that declares what a company offers. See the\n[booking example](examples/manifests/booking/).\n\n---\n\n## What is free, and what we sell\n\nEverything needed to take a CDL manifest and turn it into something an agent can call is\nApache-2.0 and stays that way: the language, the compiler, the IR, every emitter, the embedded\nSDK, and `init` / `apply` / `build` / `serve` / `verify`. **`archstone build` and `archstone\nserve` never require a network call, an account or a key** — vendor a manifest, pin a version,\nand you can keep compiling and serving it indefinitely with no relationship to us. ArtVinci\nruns entirely inside this and owes us nothing.\n\n**No feature that is free today becomes paid.** New commercial value is added alongside the\nopen core, or it is not added.\n\nBoth commitments are ratified decisions, not release notes — the reasoning, and the alternatives\nthat were considered and refused, are in [ADR-0005](docs/adr/0005-open-core-boundary-artifact-guarantee.md).\nRanking is covered separately and just as permanently: position in any selection Archstone\nperforms is not purchasable in any form ([ADR-0006](docs/adr/0006-marketplace-neutrality.md)).\n\nWhat we sell, when it exists, is the *operation* of these artifacts over time on our machines:\nhosted durable audit and retention, managed rate-limit counters, drift monitoring, and\nmulti-tenant hosting for teams who would rather not run a node. The governance mechanisms\nthemselves — policy evaluation, rate limiting, execution audit, model-output validation — ship\nhere, in the open, at every tier.\n\n---\n\n## The language\n\nCDL is **1.0 and frozen**: every primitive is Canonical, so a manifest that compiles today\ncompiles against every later CDL 1.x. The normative grammar — what each primitive means, what a\nprocessor MUST and MUST NOT do — is [`docs/cdl-specification.md`](docs/cdl-specification.md);\nthe machine contract is [`cdl.schema.json`](packages/schema/schemas/cdl.schema.json). Why the\ngrammar looks the way it does — every primitive's justification, and the ones that were rejected\n— is the Rationale, [RFC-0002](docs/rfc/0002-cdl-v0.2.md). Terms are defined in the\n[glossary](docs/glossary.md).\n\n---\n\n## Identity\n\nArchstone never resolves identity — your host does, and hands over an opaque principal. What to\nwire, what is guaranteed about it, and why there is no SSO/SCIM feature to look for:\n[`docs/IDENTITY.md`](docs/IDENTITY.md).\n\n---\n\n## Support and versions\n\nWhich versions receive fixes, what gets backported, and what stays stable while the packages are\npre-1.0 (short answer: CDL and your compiled IR) — see [`SUPPORT.md`](SUPPORT.md). Security\nreports go through [`SECURITY.md`](SECURITY.md), never a public issue.\n\n---\n\n## How this project uses generative AI\n\nArchstone is written with substantial AI assistance. It says so here rather than leaving you to\ninfer it from the commit log. The model is Anthropic's Claude — `claude-opus-5` at the time of\nwriting — used through Claude Code.\n\n**Where it is used:** implementation and refactoring across the compiler, emitters, runtime and\nCLI; tests; documentation and changelog prose.\n\n**What is not generated: the decisions.** Every structural choice — what enters CDL, what the\ncompiler guarantees, where a boundary sits — is written as an ADR before merge, with the\nalternatives that were considered and refused, and ratified by a person who is accountable for\nit. The decisions that constitute commitments to you are published in [`docs/adr/`](docs/adr/),\nso you can read the reasoning instead of taking a claim on trust. A patch nobody can explain does\nnot merge, whatever wrote it.\n\n**Provenance:** commits carrying generated code name the model in their co-authorship trailer.\nContributors are asked to do the same — see\n[`CONTRIBUTING.md`](CONTRIBUTING.md#generative-ai).\n\nThis disclosure exists because the alternative is worse. A compiler asks you to trust its output\nabout things you cannot easily check by hand: that an `effect` is right, that a field you never\ndeclared did not leave your backend. You are entitled to know how it was built before deciding\nhow much of that to trust.\n\n---\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) and the\n[contributor onboarding](docs/ONBOARDING.md#contributor-onboarding). Requires Node 22+ and\npnpm 11+; `pnpm typecheck && pnpm test` should be green before you open a PR.\n\n---\n\n## License\n\n[Apache-2.0](LICENSE).\n\n*Archstone · schema-first · Capability Platform*\n",
  "bytes": 16934,
  "sha": "f0dcdff6f000798b60a5ac32811fd23a9e42e0bb2ccef3fa0448c0d1281ba50f",
  "repo_slug": "archstone-romania/archstone",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_archstone_romania_archstone_09718157/readme"
}