@weave-kit/engine

Let AI agents operate your data — safely.

Define your data model once in schema.json, and WeaveKit compiles it into PostgreSQL tables, a REST API with row- and field-level RBAC, an immutable audit log, 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   →   PostgreSQL tables + indexes + RLS
                                REST API (CRUD + RBAC)
                                MCP tools (per-identity surface + guardrails)
                                Immutable audit log
                                TypeScript types

Why WeaveKit

• Safe by construction — every agent action is authorized by row- and field-level RBAC and native PostgreSQL RLS, and recorded in an immutable audit log. Guardrails (and optional approvals) sit in front.

• 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 bypass RBAC/RLS.

• 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 a REST API 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

• Schema as the source of truth — objects/<name>/schema.json, versioned in Git; state-diff migrations to PostgreSQL.

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

• MCP tool surface — a streamable HTTP endpoint at /mcp with a per-identity tool surface and guardrails.

• Audit log — an immutable event log for data mutations.

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

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

Requirements

• Node.js 24 LTS

• PostgreSQL

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

Docs index: docs/

• Getting started — scaffold, migrate, run, consume

• Schema guide · RBAC · Formulas · Audit

• CLI reference · MCP · Script hooks

• Custom tools & guardrails · Quotas · Inbound events

• Public API & dependency budget

• Practices & operations — real integration and deployment walkthroughs

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 typecheck
npm run lint

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.