@weave-kit/engine

Define your data model once in schema.json, and WeaveKit compiles it into PostgreSQL tables, REST and GraphQL APIs with row- and field-level RBAC, an immutable audit log with execution evidence, and an MCP tool surface that AI agents call with typed tools — never raw SQL. Self-hosted: your data stays in your database.

objects/leads/schema.json   →   Git commit (source of truth)
                                PostgreSQL tables + indexes (+ RLS policies)
                                REST + GraphQL APIs (CRUD + RBAC)
                                MCP surface (per-identity tools + resources + prompts + approvals)
                                Immutable audit log + execution evidence
                                TypeScript types

Why WeaveKit

• Safe by construction — every agent action is authorized by row- and field-level RBAC and recorded in an audit log. Turn on rls.enforce and PostgreSQL row-level security re-checks the same row scope in the database, so a missing application filter still cannot expose rows. Guardrails (and optional approvals) sit in front.

• Your model is a Git repository — schema, hooks and policies are files you review, diff and revert; the engine commits every change for you, and PostgreSQL is a derived cache.

• One agent, many users — each MCP call carries the acting user's identity (on-behalf-of), and the engine compiles a per-identity tool surface: a salesperson's agent sees only their own leads, a finance agent cannot read sales notes. Prompt injection cannot widen what the acting user may read or write.

• Bring your existing PostgreSQL — point the engine at a live database and declare the tables you want to expose; existing tables stay read-only unless you explicitly allow additive DDL, and weave introspect can reverse-model them into schema.json.

• Typed tools in minutes, not weeks — hand-writing an MCP server (tools + permissions + audit) for a few tables takes days; here it is a few schema.json files, and new fields or tables extend the tool surface automatically.

• More than MCP — the same schema also drives REST and GraphQL APIs and generated TypeScript types, so people and agents share one governed contract.

• Self-hosted — the engine runs in your environment; no data leaves your database.

Related MCP server: pgwarden-mcp

How it works

weave reads objects/<name>/schema.json, validates it, and syncs it to PostgreSQL (state-diff migrations; existing tables stay read-only unless you allow additive DDL). The same metadata drives the REST routes and the MCP tool surface, and the data-access layer enforces RBAC and audits every write.

Features

• Git-versioned metadata — schema, hooks and policies are plain files in your repository; every change is a scoped, atomic Git commit, so review, history and rollback come for free. PostgreSQL stays a derived cache.

• Schema as the source of truth — objects/<name>/schema.json drives the tables, REST API and MCP surface; state-diff migrations to PostgreSQL.

• Custom field types — register business-semantic types (money, address, …) as thin, namespaced layers over a built-in primitive; they inherit storage, REST/MCP/OpenAPI schemas and generated types. Declared in a project-local, Git-committed field-types/ directory.

• Named enums — declare a shared enum once in enums/ and reference it from any object by enumType; every field shares one native PostgreSQL type and one set of per-value labels.

• Governed REST API — object CRUD with row-level (all/own/department) and field-level RBAC and a uniform error contract.

• MCP surface — a streamable HTTP endpoint at /mcp with a per-identity tool surface, schema-derived resources and prompts, guardrails, and an optional approvals queue.

• GraphQL API — an opt-in read/write GraphQL endpoint compiled from the same schema.json, with nested relations, the same RBAC/audit, per-request batching and query hardening.

• Schema revisions & atomic deploys — weave deploy plan previews the diff; weave deploy apply commits the DDL, the metadata cache and a global schema revision in one transaction (no half-applied deploys).

• Agent execution pipeline — every write, workflow transition and tool call runs through one Plan → Validate → Authorize → Guardrail → Approval → Execute → Commit → Evidence pipeline, so guardrails and approvals cover REST, MCP and GraphQL alike; enable evidence to record one weavekit_evidence row per execution with its real outcome (correlated by request / trace / schema revision).

• Database-enforced row scope — rls.enforce provisions PostgreSQL RLS policies generated from the same permission matrix and runs user reads/updates/deletes under a restricted role; the engine refuses to start until the policies are in place.

• Query budget — bound a read/query across the engine: rows, filters and sorts in data-access, joins / SQL length / statement timeout in restricted SQL, and GraphQL depth.

• Multi-tenancy (row) — mark a field "scope": true and every read/write is scoped to the subject's scope (RBAC row scope + audit, plus PostgreSQL RLS for scripts and with rls.enforce); single-scope by default.

• Audit log — an immutable event log for data mutations, with durability modes (best-effort / transactional / durable) and a keyset-cursor query.

• Observability — a low-level metrics/trace seam (MetricsSink / TraceSink, METRIC_NAMES) that emits request latency, RBAC denials, query-budget rejects and W3C traceparent-correlated spans; the engine ships a no-op default and brings no backend.

• Sandboxed hooks — *.server.js lifecycle hooks running in isolated workers.

• Type generation — object-level TypeScript types derived from the schema.

• Live events — an SSE stream with replay.

• Generic proxy — a path-gated gateway to other engine instances; normal JSON replies keep the bounded-body cap, while downloads and SSE streams are piped through with upstream headers intact.

• Operations — weave doctor preflight, health / readiness / version endpoints, request rate limiting, CORS and structured logging.

Requirements

• Node.js 22+

• PostgreSQL 12+ (the engine's tested floor; weave doctor reports the version)

Quick start

npm create weavekit-app my-app -- --type=agent
cd my-app
cp .env.example .env      # set DATABASE_URL
weave migrate             # state-diff migration: schema.json → PostgreSQL tables (+ metadata cache)
weave dev                 # http://localhost:3000 — hot reload
weave types               # object-level TS types → generated/types.ts

Existing database? Reverse-model it instead of authoring from scratch:

weave introspect          # live tables → objects/<table>/schema.json (read-only)
weave schema:map          # schema field ↔ PostgreSQL column mapping + drift

Connect an agent (MCP is available at /mcp):

weave mcp:config          # ready-to-paste config for Claude Code / Cursor / VS Code / Claude Desktop

Documentation

Full documentation: docs.weavekit.io/engine

• Getting started — scaffold, migrate, run, consume

• Git-versioned metadata — your data model as reviewable Git commits

• Schema guide · RBAC · Multi-tenancy · Formulas · Audit

• CLI reference · Observability · MCP · Prompts · Execution & evidence · Script hooks

• Custom tools & guardrails · Query budget · Custom field types · Quotas · Inbound events

• Public API & dependency budget · Enterprise seams · Contract freeze

• Practices & operations · Release checklist — real integration and deployment walkthroughs

The Markdown sources live in docs/.

Programmatic use

import { createEngine } from '@weave-kit/engine';

const engine = await createEngine({
  databaseUrl: process.env.DATABASE_URL,
  schemaDir: '.', // project root containing objects/
  auth: { source: { 'sk-admin': { id: 'admin', roles: ['admin'] } } },
});
await engine.app.listen({ port: 3000 });

Metadata

• Objects live in objects/<name>/schema.json (one directory per object; the directory name must equal the object name).

• weavekit.config.ts is the single wiring point — a default export satisfies EngineConfig (schemaDir, auth, adapters, subsystems).

• schema.json is versioned in Git and is the source of truth; the engine syncs it to PostgreSQL and a metadata cache.

CLI

Object-level types

weave types   # → generated/types.ts

import type { Lead } from './generated/types';
import { createClient } from '@weave-kit/client';

const leads = createClient({ baseUrl, apiKey }).objects<Lead>('lead');
const { rows } = await leads.find({ filter: { status: 'open' } });

Development

npm install
npm run build        # tsc → dist
npm test             # unit + e2e (e2e needs DATABASE_URL)
npm run test:coverage # coverage gate on security-critical paths
npm run typecheck
npm run lint
node scripts/check-exports.mjs  # verify package exports + contract names

Issues and pull requests are welcome. See AGENTS.md for architecture notes and contribution invariants.

Support

Questions, bug reports and security reports: support@weavekit.io.

License

MIT · For support, contact support@weavekit.io.