Most content systems put a dashboard between you and your content. Graft puts a schema and a filesystem there instead, then gives an agent the same operator surface a human gets.
Authored content is MDX in git. Your schema is a Zod-typed defineCollection
call. The queryable index is derived, so when git and the index disagree, git
wins and the compiler rebuilds. Everything a human can do in the optional
Studio, an agent can do over MCP or the CLI, under the same access rules, the
same audit trail, and the same human gate on anything destructive.
Start with no database
A content project needs no services at all. graft compile writes the index to
a SQLite artifact, and your app reads it embedded.
npx @usegraft/cli@latest init # schema, content/, llms.txt
npx @usegraft/cli@latest compile # writes .graft/index.db
import { openStaticIndex } from "@usegraft/db";
import { createClient } from "@usegraft/sdk-core";
import { collections } from "./graft.config";
const index = await openStaticIndex(".graft/index.db");
const graft = createClient({ index, collections });
const home = await graft.getDocument("pages", "home");
// ^? typed by your pages collection. No codegen step.
The artifact is derived from the files in git, so it is git-ignored and rebuilt
in your build command: graft compile && next build. Preview branches are git
branches, and each checkout compiles its own index. Full-text search comes with
it, because search is a property of the artifact.
That deploys to Vercel, Netlify, or Cloudflare Pages with nothing attached.
Add Postgres when you need it
Postgres buys operational data (orders, submissions, comments), typed functions with auth, audit, rate limits, and approvals, and copy-on-write preview branches.
# set DATABASE_URL, then change one line: export const index = "postgres"
npx @usegraft/cli@latest db migrate
npx @usegraft/cli@latest compile
Graft tells you the moment you need it. Reaching for a Postgres-tier feature in
static mode fails with NEEDS_DATABASE, and that error's fix field is the two
commands above.
Agents operate it
graft mcp serves your project over MCP, on stdio or Streamable HTTP. An agent
reads your real schema through describe_schema instead of guessing at it, and
every error it can hit carries a fix it can act on.
// .mcp.json
{ "mcpServers": { "graft": { "command": "npx", "args": ["-y", "@usegraft/cli@latest", "mcp"] } } }
The agent surface is not a subset of the human one. It reads and writes content, uploads assets, browses and installs registry primitives, runs typed functions, and compiles. What an agent cannot do is decide its own approval.
Destructive operations are human-gated under every policy. The call returns 403
with a pending approval id, a human runs graft approve <id>, and the caller
retries carrying that id. The deciding identity is derived from the verified
caller and never read from the request, so no argument exists that an agent
could set to approve itself. On Postgres, graft harden moves that guarantee
below the application: the runtime role holds no UPDATE on approvals, which
puts pending → approved out of reach even through raw SQL.
Primitives you own
graft add copies a primitive's files into your repository, shadcn-style. You
own the copy and edit it like the rest of your code. No version of it sits in
node_modules to fight with.
graft add commerce
Available today: seo, callout, faq, scoped-access, comments, and
commerce (file-authoritative products, database-authoritative orders, and the
place, list, update, and cancel functions).
Read it from your framework
Every adapter is typed structurally, so none of them depends on the framework it
adapts. sdk-react is the one that does not read a database: it reads a
@usegraft/content-api endpoint over HTTP, because a
Postgres handle in a browser bundle is a database URL in a browser bundle.
Telemetry
None. Graft collects no analytics, sends no usage pings, and phones home from no command. The only network calls it makes are the ones your project configures: your database, your asset store, and, when you use them, Neon's branching API and your OIDC issuer.
Packages
Self-host
One image runs the whole backend: Postgres, MinIO, and graft serve.
docker run -p 3903:3903 -v "$PWD:/project" graft
It migrates, compiles, and serves, then logs a generated bearer token. Anonymous
MCP is never exposed. It serves under a hardened role wherever it owns its own
database. Adapters for Railway, Fly, a plain VPS, and Vercel live in
deploy/.
Documentation
- Getting started
- The model, and why content is code
- The agent surface
- Architecture decisions, each stating the premise it rests on
- Design notes from the de-risking spikes
Status
Pre-1.0. Packages are published under @usegraft/*, and the API can still change
between minors when the change buys a better design. Every break is described in
the changelog and in the pull request that makes it.
Contributing
Start with CONTRIBUTING.md. Engineering conventions live in
CONVENTIONS.md.
Report a vulnerability through SECURITY.md, never a public
issue. This project follows the Contributor Covenant.
License
MIT. See LICENSE.
