@databob/sdk 0.0.1 → 0.0.2

package/README.md

@@ -134,7 +134,29 @@ npx databob deploy
 
 ## For agents
 
-Every command prints JSON or plain lines.
+`databob mcp` is a Model Context Protocol server for coding agents working in your repo. It reads `databob/`, so run it from the project root.
+
+```sh
+claude mcp add databob -- npx databob mcp          # Claude Code
+```
+
+```json
+// .cursor/mcp.json, .vscode/mcp.json, or any client that runs stdio servers
+{ "mcpServers": { "databob": { "command": "npx", "args": ["databob", "mcp"] } } }
+```
+
+| Tool | What it does |
+| --- | --- |
+| `describe` | Events, properties, metrics, whether a cloud app is configured, and the JSON query language |
+| `check` | Validates `databob/schema.ts` and `databob/metrics.ts` and lists every problem |
+| `query_metric` | Runs a named metric, on local dev data or the cloud app (`target`) |
+| `query` | Runs an ad hoc JSON query, local or cloud |
+| `track_test_event` | Records one event in local dev data only, never the cloud |
+| `deploy` | Ships `databob/` to the cloud app (marked destructive, so clients ask first) |
+
+The agent edits the two files with its own tools, runs `check`, tries queries against local data, and deploys when you say so.
+
+Every CLI command prints JSON or plain lines too:
 
 ```sh
 npx databob describe                     # schema and metrics as JSON
@@ -144,7 +166,7 @@ npx databob track signup --props '{"plan":"pro"}' --tenant acme --user u1
 npx databob deploy                       # ship databob/ to the cloud app
 ```
 
-The HTTP API is the same everywhere: `POST /v1/track`, `POST /v1/metrics/:name`, `GET /v1/metrics/:name/live`, `POST /v1/query`, `POST /v1/tokens`, `GET /v1/describe`, `DELETE /v1/users/:id`, `DELETE /v1/tenants/:id`. Errors are `{ "error": code, "message": text }`.
+The HTTP API is the same everywhere: `POST /v1/track`, `POST /v1/metrics/:name`, `GET /v1/metrics/:name/live`, `POST /v1/query`, `POST /v1/tokens`, `GET /v1/describe` (includes the query language), `DELETE /v1/users/:id`, `DELETE /v1/tenants/:id`. Errors are `{ "error": code, "message": text }`.
 
 ## Self-host
 

package/dist/cli.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 // databob CLI. Every command prints JSON or plain lines, so agents can drive it.
-import { existsSync, readFileSync, watch } from "node:fs";
+import { watch } from "node:fs";
 import { createServer } from "node:http";
-import { join, relative } from "node:path";
-import { parseEnv } from "node:util";
+import { relative } from "node:path";
 import { Engine, EngineError, createHandler } from "@databob/engine";
 import { LocalTenants, StaticProjects, toNodeListener } from "@databob/engine/node";
 import { ProjectLoadError, codegen, devState, loadProject, paths, projectConfig, scaffold, writeEnv, } from "./project.js";
+import { cloudSettings, deployProject, openLocal, trackLocal } from "./ops.js";
+import { serveMcp } from "./mcp.js";
 const HELP = `databob: typed analytics you define in code
 
 Usage: databob <command> [options]
@@ -24,6 +25,8 @@ Usage: databob <command> [options]
       --args '{"range":"7d"}'  --tenant <id>  --tz <IANA zone>  --compare
   track <event> [options]      Record one event locally
       --props '{"plan":"pro"}' --tenant <id>  --user <id>
+  mcp                          Run the MCP server on stdio, for coding agents:
+                               claude mcp add databob -- npx databob mcp
 
 Data lives in .databob/ (git-ignored). Requires Node 22.13+.`;
 function parse(argv) {
@@ -71,11 +74,6 @@ async function loadOrExit(p) {
     }
     return loaded;
 }
-async function local(p) {
-    const loaded = await loadOrExit(p);
-    const tenants = new LocalTenants({ dir: p.data });
-    return { engine: new Engine(tenants), project: projectConfig(devState(p), loaded), tenants };
-}
 const MIN_KEY_LENGTH = 32;
 function requiredSecret(name) {
     const value = process.env[name] ?? "";
@@ -117,52 +115,17 @@ async function start(p, flags) {
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
 }
-// Reads .env.local and .env without overriding variables already set.
-function loadEnvFiles(root) {
-    for (const name of [".env.local", ".env"]) {
-        const file = join(root, name);
-        if (!existsSync(file))
-            continue;
-        const parsed = parseEnv(readFileSync(file, "utf8"));
-        for (const [key, value] of Object.entries(parsed)) {
-            if (process.env[key] === undefined && value !== undefined)
-                process.env[key] = value;
-        }
-    }
-}
 async function deploy(p, flags) {
-    loadEnvFiles(p.root);
-    const url = (str(flags, "url") ?? process.env.DATABOB_URL ?? "").replace(/\/+$/, "");
-    const key = process.env.DATABOB_DEPLOY_KEY ?? "";
-    if (url === "" || /^https?:\/\/(127\.0\.0\.1|localhost)(:|\/|$)/.test(url)) {
-        console.error("✗ Set DATABOB_URL to your databob cloud URL. `databob dev` reloads by itself and needs no deploy.");
-        process.exit(1);
-    }
-    if (!key.startsWith("dbdk_")) {
-        console.error("✗ Set DATABOB_DEPLOY_KEY to the app's deploy key (dbdk_...). The dashboard shows it once.");
-        process.exit(1);
-    }
+    const cloud = cloudSettings(p.root, str(flags, "url"));
     const loaded = await loadOrExit(p);
-    let response;
-    try {
-        response = await fetch(`${url}/v1/deploy`, {
-            method: "POST",
-            headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
-            body: JSON.stringify({ schema: loaded.schema, metrics: loaded.metrics }),
-        });
-    }
-    catch (error) {
-        console.error(`✗ Could not reach ${url}: ${error instanceof Error ? error.message : error}`);
-        process.exit(1);
-    }
-    const body = (await response.json().catch(() => ({})));
-    if (!response.ok) {
-        console.error(`✗ Deploy failed (${response.status}): ${body.message ?? response.statusText}`);
-        for (const problem of body.problems ?? [])
+    const result = await deployProject(loaded, cloud);
+    if (!result.ok) {
+        console.error(`✗ ${result.status ? `Deploy failed (${result.status}): ` : ""}${result.message}`);
+        for (const problem of result.problems ?? [])
             console.error(`  ✗ ${problem}`);
         process.exit(1);
     }
-    console.log(`✓ Deployed version ${body.version}: ${body.events} event(s), ${body.metrics} metric(s) to ${url}`);
+    console.log(`✓ Deployed version ${result.version}: ${result.events} event(s), ${result.metrics} metric(s) to ${result.url}`);
 }
 async function dev(p, flags) {
     const port = Number(str(flags, "port") ?? process.env.DATABOB_PORT ?? 4100);
@@ -257,6 +220,7 @@ async function main() {
             const created = scaffold(p);
             console.log(created.length > 0 ? `Created ${created.join(", ")}` : "databob/ already exists. Nothing to create.");
             console.log("Next: npx databob dev");
+            console.log("Agents: claude mcp add databob -- npx databob mcp");
             return;
         }
         case "dev":
@@ -265,6 +229,8 @@ async function main() {
             return start(p, flags);
         case "deploy":
             return deploy(p, flags);
+        case "mcp":
+            return serveMcp({ root: process.cwd() });
         case "codegen": {
             const written = codegen(p);
             console.log(written.length > 0 ? `Wrote ${written.join(", ")}` : "Generated files are up to date.");
@@ -284,7 +250,7 @@ async function main() {
             const name = flags._[1];
             if (!name)
                 throw new Error("Usage: databob query <metric> [--args JSON] [--tenant id]");
-            const { engine, project, tenants } = await local(p);
+            const { engine, project, tenants } = openLocal(p, await loadOrExit(p));
             const options = {};
             const tenant = str(flags, "tenant");
             if (tenant)
@@ -309,28 +275,9 @@ async function main() {
             const user = str(flags, "user");
             if (user)
                 event.user = user;
-            // Prefer a running dev server, so live views see the event.
-            const state = devState(p);
-            const port = Number(str(flags, "port") ?? process.env.DATABOB_PORT ?? 4100);
-            try {
-                const response = await fetch(`http://127.0.0.1:${port}/v1/track`, {
-                    method: "POST",
-                    headers: { authorization: `Bearer ${state.secretKey}`, "content-type": "application/json" },
-                    body: JSON.stringify(event),
-                });
-                const result = (await response.json());
-                print(result);
-                if (!response.ok || (result.rejected?.length ?? 0) > 0)
-                    process.exit(1);
-                return;
-            }
-            catch {
-                // No dev server. Write to the local data directly.
-            }
-            const { engine, project, tenants } = await local(p);
-            const result = await engine.track(project, [event]);
+            const port = str(flags, "port");
+            const result = await trackLocal(p, await loadOrExit(p), [event], port ? Number(port) : undefined);
             print(result);
-            tenants.close();
             if (result.rejected.length > 0)
                 process.exit(1);
             return;

package/dist/mcp.d.ts

@@ -0,0 +1,163 @@
+export declare const PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+type Json = Record<string, unknown>;
+export type McpOptions = {
+    root: string;
+    fetch?: typeof fetch;
+};
+export declare const TOOLS: readonly [{
+    readonly name: "describe";
+    readonly title: "Describe the analytics project";
+    readonly description: "The events, properties, and metrics defined in databob/, whether a cloud app is configured, and a reference for the JSON query language. Call this first.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly openWorldHint: false;
+    };
+}, {
+    readonly name: "check";
+    readonly title: "Check the schema and metrics";
+    readonly description: "Validate databob/schema.ts and databob/metrics.ts. Returns every problem, or ok. Run it after editing either file.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly openWorldHint: false;
+    };
+}, {
+    readonly name: "query_metric";
+    readonly title: "Run a named metric";
+    readonly description: "Run a metric defined in databob/metrics.ts and return its rows (or funnel steps).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly tenant: {
+                readonly type: "string";
+                readonly description: "Tenant id. Required when the schema has tenants.";
+            };
+            readonly timeZone: {
+                readonly type: "string";
+                readonly description: "IANA time zone for time buckets, e.g. \"America/New_York\". Default UTC.";
+            };
+            readonly compare: {
+                readonly type: "boolean";
+                readonly description: "Also return the same-length period just before.";
+            };
+            readonly target: {
+                readonly type: "string";
+                readonly enum: readonly ["local", "cloud"];
+                readonly description: "local: data recorded by `databob dev` in .databob/. cloud: the deployed app at DATABOB_URL. Default \"local\".";
+            };
+            readonly metric: {
+                readonly type: "string";
+                readonly description: "The metric's export name.";
+            };
+            readonly args: {
+                readonly type: "object";
+                readonly description: "The metric's arguments, e.g. { \"range\": \"7d\" }.";
+            };
+        };
+        readonly required: readonly ["metric"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly openWorldHint: true;
+    };
+}, {
+    readonly name: "query";
+    readonly title: "Run an ad hoc query";
+    readonly description: "Run a JSON query that is not a saved metric. describe returns the query language. Use it to explore data or to try a metric before adding it to metrics.ts.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly tenant: {
+                readonly type: "string";
+                readonly description: "Tenant id. Required when the schema has tenants.";
+            };
+            readonly timeZone: {
+                readonly type: "string";
+                readonly description: "IANA time zone for time buckets, e.g. \"America/New_York\". Default UTC.";
+            };
+            readonly compare: {
+                readonly type: "boolean";
+                readonly description: "Also return the same-length period just before.";
+            };
+            readonly target: {
+                readonly type: "string";
+                readonly enum: readonly ["local", "cloud"];
+                readonly description: "local: data recorded by `databob dev` in .databob/. cloud: the deployed app at DATABOB_URL. Default \"local\".";
+            };
+            readonly query: {
+                readonly type: "object";
+                readonly description: "A query with kind \"aggregate\" or \"funnel\".";
+            };
+        };
+        readonly required: readonly ["query"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly openWorldHint: true;
+    };
+}, {
+    readonly name: "track_test_event";
+    readonly title: "Record a test event locally";
+    readonly description: "Record one event in local dev data (never the cloud), to check instrumentation or to give a new metric something to show. Refused events come back with the reason.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly name: {
+                readonly type: "string";
+                readonly description: "Event name from the schema.";
+            };
+            readonly props: {
+                readonly type: "object";
+                readonly description: "Event properties.";
+            };
+            readonly tenant: {
+                readonly type: "string";
+            };
+            readonly user: {
+                readonly type: "string";
+                readonly description: "A user id. Stored as a keyed hash.";
+            };
+            readonly ts: {
+                readonly type: "string";
+                readonly description: "ISO time. Default now.";
+            };
+        };
+        readonly required: readonly ["name"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: false;
+        readonly destructiveHint: false;
+        readonly idempotentHint: false;
+        readonly openWorldHint: false;
+    };
+}, {
+    readonly name: "deploy";
+    readonly title: "Deploy to databob cloud";
+    readonly description: "Ship databob/schema.ts and databob/metrics.ts to the cloud app at DATABOB_URL with DATABOB_DEPLOY_KEY. Events not in the new schema are refused from then on. Only deploy when the user asks.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: false;
+        readonly destructiveHint: true;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+}];
+export declare function createMcpHandler(options: McpOptions): (message: unknown) => Promise<Json | null>;
+export declare function serveMcp(options: McpOptions, input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<void>;
+export {};

package/dist/mcp.js

@@ -0,0 +1,307 @@
+// `databob mcp`: a Model Context Protocol server on stdio, so a coding agent
+// working in this repo can read the schema, check it, query local or cloud
+// data, record test events, and deploy.
+//
+//   claude mcp add databob -- npx databob mcp
+//
+// Newline-delimited JSON-RPC 2.0. Nothing but protocol messages is written to
+// stdout; logs go to stderr.
+import { createRequire } from "node:module";
+import { createInterface } from "node:readline";
+import { QUERY_LANGUAGE } from "@databob/engine";
+import { ProjectLoadError, loadProject, paths } from "./project.js";
+import { cloudSettings, deployProject, openLocal, trackLocal } from "./ops.js";
+import { Databob } from "./server.js";
+export const PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const INSTRUCTIONS = `databob is analytics defined in code. databob/schema.ts lists events and their properties; databob/metrics.ts holds named queries.
+Start with describe. Edit those two files with your own file tools, then run check. Query with target "local" for data recorded by \`databob dev\`, or "cloud" for the deployed app. Record test events with track_test_event (local only). Deploy only when the user asks.
+databob refuses personal data: no emails, IP addresses, phone numbers, or names in properties. Pass user ids as the user field; they are hashed.`;
+const READ_OPTIONS = {
+    tenant: { type: "string", description: "Tenant id. Required when the schema has tenants." },
+    timeZone: { type: "string", description: 'IANA time zone for time buckets, e.g. "America/New_York". Default UTC.' },
+    compare: { type: "boolean", description: "Also return the same-length period just before." },
+    target: {
+        type: "string",
+        enum: ["local", "cloud"],
+        description: 'local: data recorded by `databob dev` in .databob/. cloud: the deployed app at DATABOB_URL. Default "local".',
+    },
+};
+export const TOOLS = [
+    {
+        name: "describe",
+        title: "Describe the analytics project",
+        description: "The events, properties, and metrics defined in databob/, whether a cloud app is configured, and a reference for the JSON query language. Call this first.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: "check",
+        title: "Check the schema and metrics",
+        description: "Validate databob/schema.ts and databob/metrics.ts. Returns every problem, or ok. Run it after editing either file.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: "query_metric",
+        title: "Run a named metric",
+        description: "Run a metric defined in databob/metrics.ts and return its rows (or funnel steps).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                metric: { type: "string", description: "The metric's export name." },
+                args: { type: "object", description: 'The metric\'s arguments, e.g. { "range": "7d" }.' },
+                ...READ_OPTIONS,
+            },
+            required: ["metric"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    {
+        name: "query",
+        title: "Run an ad hoc query",
+        description: "Run a JSON query that is not a saved metric. describe returns the query language. Use it to explore data or to try a metric before adding it to metrics.ts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "object", description: 'A query with kind "aggregate" or "funnel".' },
+                ...READ_OPTIONS,
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    {
+        name: "track_test_event",
+        title: "Record a test event locally",
+        description: "Record one event in local dev data (never the cloud), to check instrumentation or to give a new metric something to show. Refused events come back with the reason.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Event name from the schema." },
+                props: { type: "object", description: "Event properties." },
+                tenant: { type: "string" },
+                user: { type: "string", description: "A user id. Stored as a keyed hash." },
+                ts: { type: "string", description: "ISO time. Default now." },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    },
+    {
+        name: "deploy",
+        title: "Deploy to databob cloud",
+        description: "Ship databob/schema.ts and databob/metrics.ts to the cloud app at DATABOB_URL with DATABOB_DEPLOY_KEY. Events not in the new schema are refused from then on. Only deploy when the user asks.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    },
+];
+class ToolError extends Error {
+}
+function readOptions(input) {
+    const options = {};
+    if (input.tenant !== undefined) {
+        if (typeof input.tenant !== "string")
+            throw new ToolError("tenant must be a string");
+        options.tenant = input.tenant;
+    }
+    if (input.timeZone !== undefined) {
+        if (typeof input.timeZone !== "string")
+            throw new ToolError("timeZone must be a string");
+        options.timeZone = input.timeZone;
+    }
+    if (input.compare === true)
+        options.compare = "previous";
+    return options;
+}
+function target(input) {
+    if (input.target === undefined)
+        return "local";
+    if (input.target === "local" || input.target === "cloud")
+        return input.target;
+    throw new ToolError('target is "local" or "cloud"');
+}
+function objectArg(input, name, required) {
+    const value = input[name];
+    if (value === undefined) {
+        if (required)
+            throw new ToolError(`${name} is required`);
+        return undefined;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new ToolError(`${name} must be an object`);
+    return value;
+}
+export function createMcpHandler(options) {
+    const p = paths(options.root);
+    const version = (() => {
+        try {
+            return createRequire(import.meta.url)("../package.json").version;
+        }
+        catch {
+            return "0.0.0";
+        }
+    })();
+    async function project() {
+        return loadProject(p);
+    }
+    function cloudClient() {
+        const cloud = cloudSettings(p.root);
+        if (!cloud.url || !cloud.secretKey) {
+            throw new ToolError("No cloud app is configured. Set DATABOB_URL and DATABOB_SECRET_KEY (or use target local).");
+        }
+        const clientOptions = { url: cloud.url, secretKey: cloud.secretKey, strict: true };
+        if (options.fetch)
+            clientOptions.fetch = options.fetch;
+        return new Databob(clientOptions);
+    }
+    async function run(name, input) {
+        switch (name) {
+            case "describe": {
+                const loaded = await project();
+                const cloud = cloudSettings(p.root);
+                return {
+                    schema: loaded.schema,
+                    metrics: loaded.metrics,
+                    problems: loaded.problems,
+                    cloud: { url: cloud.url, secretKey: cloud.secretKey !== null, deployKey: cloud.deployKey !== null },
+                    files: { schema: "databob/schema.ts", metrics: "databob/metrics.ts" },
+                    queryLanguage: QUERY_LANGUAGE,
+                };
+            }
+            case "check": {
+                const loaded = await project();
+                return {
+                    ok: loaded.problems.length === 0,
+                    problems: loaded.problems,
+                    events: Object.keys(loaded.schema.events).length,
+                    metrics: Object.keys(loaded.metrics).length,
+                };
+            }
+            case "query_metric":
+            case "query": {
+                const read = readOptions(input);
+                const where = target(input);
+                if (name === "query_metric" && typeof input.metric !== "string")
+                    throw new ToolError("metric is required");
+                const args = objectArg(input, "args", false) ?? {};
+                const query = name === "query" ? objectArg(input, "query", true) : null;
+                if (where === "cloud") {
+                    const client = cloudClient();
+                    const result = query ? await client.queryJson(query, read) : await client.metric({ name: String(input.metric) }, args, read);
+                    return { target: "cloud", result };
+                }
+                const loaded = await project();
+                if (loaded.problems.length > 0)
+                    throw new ToolError(`Fix these first:\n${loaded.problems.join("\n")}`);
+                const local = openLocal(p, loaded);
+                try {
+                    const result = query
+                        ? await local.engine.query(local.project, query, read)
+                        : await local.engine.metric(local.project, String(input.metric), args, read);
+                    return { target: "local", result };
+                }
+                finally {
+                    local.tenants.close();
+                }
+            }
+            case "track_test_event": {
+                if (typeof input.name !== "string")
+                    throw new ToolError("name is required");
+                const event = { name: input.name, props: objectArg(input, "props", false) ?? {} };
+                for (const key of ["tenant", "user", "ts"]) {
+                    if (input[key] !== undefined)
+                        event[key] = input[key];
+                }
+                const loaded = await project();
+                if (loaded.problems.length > 0)
+                    throw new ToolError(`Fix these first:\n${loaded.problems.join("\n")}`);
+                return await trackLocal(p, loaded, [event]);
+            }
+            case "deploy": {
+                const result = await deployProject(await project(), cloudSettings(p.root), options.fetch);
+                if (!result.ok) {
+                    throw new ToolError(`${result.message}${result.problems ? `\n${result.problems.join("\n")}` : ""}`);
+                }
+                return result;
+            }
+            default:
+                throw new ToolError(`Unknown tool "${name}"`);
+        }
+    }
+    async function callTool(params) {
+        const name = typeof params.name === "string" ? params.name : "";
+        const input = (params.arguments ?? {});
+        try {
+            const result = await run(name, input);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], structuredContent: result };
+        }
+        catch (error) {
+            const message = error instanceof ToolError || error instanceof ProjectLoadError || error instanceof Error ? error.message : String(error);
+            return { content: [{ type: "text", text: message }], isError: true };
+        }
+    }
+    // Answers one JSON-RPC message. Returns null for notifications.
+    return async function handle(message) {
+        if (typeof message !== "object" || message === null || Array.isArray(message)) {
+            return { jsonrpc: "2.0", id: null, error: { code: -32600, message: "Invalid request" } };
+        }
+        const { id, method, params } = message;
+        const isNotification = id === undefined;
+        const reply = (result) => (isNotification ? null : { jsonrpc: "2.0", id, result });
+        const fail = (code, text) => isNotification ? null : { jsonrpc: "2.0", id, error: { code, message: text } };
+        switch (method) {
+            case "initialize": {
+                const requested = typeof params?.protocolVersion === "string" ? params.protocolVersion : "";
+                const protocolVersion = PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0];
+                return reply({
+                    protocolVersion,
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: { name: "databob", title: "databob", version },
+                    instructions: INSTRUCTIONS,
+                });
+            }
+            case "notifications/initialized":
+            case "notifications/cancelled":
+                return null;
+            case "ping":
+                return reply({});
+            case "tools/list":
+                return reply({ tools: TOOLS });
+            case "tools/call":
+                return reply(await callTool(params ?? {}));
+            default:
+                return fail(-32601, `Method not found: ${String(method)}`);
+        }
+    };
+}
+export async function serveMcp(options, input = process.stdin, output = process.stdout) {
+    // stdout carries protocol messages only.
+    console.log = console.error;
+    console.info = console.error;
+    console.warn = console.error;
+    const handle = createMcpHandler(options);
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    const pending = new Set();
+    for await (const line of lines) {
+        if (line.trim() === "")
+            continue;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            output.write(`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } })}\n`);
+            continue;
+        }
+        const job = handle(message).then((response) => {
+            if (response)
+                output.write(`${JSON.stringify(response)}\n`);
+        });
+        pending.add(job);
+        void job.finally(() => pending.delete(job));
+    }
+    await Promise.all(pending);
+}

package/dist/ops.d.ts

@@ -0,0 +1,33 @@
+import { Engine, type ProjectConfig, type TrackResult } from "@databob/engine";
+import { LocalTenants } from "@databob/engine/node";
+import { type LoadedProject, type Paths } from "./project.js";
+export declare function loadEnvFiles(root: string): void;
+export declare function isLocalUrl(url: string): boolean;
+export type CloudSettings = {
+    url: string | null;
+    secretKey: string | null;
+    deployKey: string | null;
+};
+export declare function cloudSettings(root: string, urlOverride?: string): CloudSettings;
+export type DeployResult = {
+    ok: true;
+    version: number;
+    events: number;
+    metrics: number;
+    url: string;
+} | {
+    ok: false;
+    status: number;
+    message: string;
+    problems?: string[];
+};
+export declare function deployProject(loaded: LoadedProject, cloud: CloudSettings, fetchImpl?: typeof fetch): Promise<DeployResult>;
+export type LocalData = {
+    engine: Engine;
+    project: ProjectConfig;
+    tenants: LocalTenants;
+};
+export declare function openLocal(p: Paths, loaded: LoadedProject): LocalData;
+export declare function trackLocal(p: Paths, loaded: LoadedProject, events: Record<string, unknown>[], port?: number): Promise<TrackResult & {
+    via: "dev server" | "local data";
+}>;

package/dist/ops.js

@@ -0,0 +1,102 @@
+// Operations shared by the CLI and the MCP server. Nothing here prints: each
+// function returns a result, and the caller decides how to show it.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseEnv } from "node:util";
+import { Engine } from "@databob/engine";
+import { LocalTenants } from "@databob/engine/node";
+import { devState, projectConfig } from "./project.js";
+// Reads .env.local and .env without overriding variables already set.
+export function loadEnvFiles(root) {
+    for (const name of [".env.local", ".env"]) {
+        const file = join(root, name);
+        if (!existsSync(file))
+            continue;
+        const parsed = parseEnv(readFileSync(file, "utf8"));
+        for (const [key, value] of Object.entries(parsed)) {
+            if (process.env[key] === undefined && value !== undefined)
+                process.env[key] = value;
+        }
+    }
+}
+export function isLocalUrl(url) {
+    return /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:|\/|$)/.test(url);
+}
+// The cloud app this project deploys to, from the environment or .env.local.
+export function cloudSettings(root, urlOverride) {
+    loadEnvFiles(root);
+    const url = (urlOverride ?? process.env.DATABOB_URL ?? "").replace(/\/+$/, "");
+    return {
+        url: url === "" || isLocalUrl(url) ? null : url,
+        secretKey: process.env.DATABOB_SECRET_KEY?.startsWith("dbsk_") ? process.env.DATABOB_SECRET_KEY : null,
+        deployKey: process.env.DATABOB_DEPLOY_KEY?.startsWith("dbdk_") ? process.env.DATABOB_DEPLOY_KEY : null,
+    };
+}
+export async function deployProject(loaded, cloud, fetchImpl = fetch) {
+    if (!cloud.url) {
+        return {
+            ok: false,
+            status: 0,
+            message: "Set DATABOB_URL to your databob cloud URL. `databob dev` reloads by itself and needs no deploy.",
+        };
+    }
+    if (!cloud.deployKey) {
+        return {
+            ok: false,
+            status: 0,
+            message: "Set DATABOB_DEPLOY_KEY to the app's deploy key (dbdk_...). The dashboard shows it once.",
+        };
+    }
+    if (loaded.problems.length > 0) {
+        return { ok: false, status: 0, message: "Fix the schema and metrics first", problems: loaded.problems };
+    }
+    let response;
+    try {
+        response = await fetchImpl(`${cloud.url}/v1/deploy`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${cloud.deployKey}`, "content-type": "application/json" },
+            body: JSON.stringify({ schema: loaded.schema, metrics: loaded.metrics }),
+        });
+    }
+    catch (error) {
+        return { ok: false, status: 0, message: `Could not reach ${cloud.url}: ${error instanceof Error ? error.message : error}` };
+    }
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        const failed = { ok: false, status: response.status, message: body.message ?? response.statusText };
+        if (body.problems)
+            failed.problems = body.problems;
+        return failed;
+    }
+    return { ok: true, version: body.version ?? 0, events: body.events ?? 0, metrics: body.metrics ?? 0, url: cloud.url };
+}
+// The local dev data in .databob/data. Close `tenants` when done.
+export function openLocal(p, loaded) {
+    const tenants = new LocalTenants({ dir: p.data });
+    return { engine: new Engine(tenants), project: projectConfig(devState(p), loaded), tenants };
+}
+// Records events locally. A running `databob dev` takes them first, so live
+// views see them; without one they are written to .databob/data directly.
+export async function trackLocal(p, loaded, events, port = Number(process.env.DATABOB_PORT ?? 4100)) {
+    const state = devState(p);
+    try {
+        const response = await fetch(`http://127.0.0.1:${port}/v1/track`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${state.secretKey}`, "content-type": "application/json" },
+            body: JSON.stringify({ events }),
+        });
+        const result = (await response.json());
+        if (Array.isArray(result.rejected))
+            return { ...result, via: "dev server" };
+    }
+    catch {
+        // No dev server.
+    }
+    const local = openLocal(p, loaded);
+    try {
+        return { ...(await local.engine.track(local.project, events)), via: "local data" };
+    }
+    finally {
+        local.tenants.close();
+    }
+}

package/dist/project.js

@@ -102,7 +102,7 @@ Rules databob enforces:
 - User ids are stored as a keyed hash. \`databob.deleteUser(id)\` erases that user everywhere.
 - Queries are JSON compiled to SQL with bound values. Your query code never runs on the server.
 
-Agents: run \`npx databob describe\` for the schema and metrics as JSON, \`npx databob check\` to validate,
+Agents: add the MCP server (\`claude mcp add databob -- npx databob mcp\`), or run \`npx databob describe\` for the schema and metrics as JSON, \`npx databob check\` to validate,
 and \`npx databob query <metric> --args '{"range":"7d"}' --tenant <id>\` to read data.
 `;
 const SERVER_GENERATED = `/* Generated by databob. Do not edit. */

package/dist/server.d.ts

@@ -1,4 +1,4 @@
-import { type AnySchema, type Built, type EventNames, type EventProps, type QueryRoot, type ResultOf, type TrackResult } from "@databob/engine";
+import { type AnySchema, type Built, type EventNames, type EventProps, type QueryAst, type QueryResult, type QueryRoot, type ResultOf, type TrackResult } from "@databob/engine";
 import type { MetricRef, RefArgs, RefResult } from "./api.js";
 export declare const DEFAULT_URL = "http://127.0.0.1:4100";
 export type TrackContext = {
@@ -42,6 +42,7 @@ export declare class Databob<S extends AnySchema = AnySchema> {
     trackMany(events: TrackInput<S>[]): Promise<TrackResult>;
     metric<R extends MetricRef>(ref: R, args?: RefArgs<R>, options?: ReadOptions): Promise<RefResult<R>>;
     query<B extends Built<unknown>>(build: (q: QueryRoot<S>) => B, options?: ReadOptions): Promise<ResultOf<B>>;
+    queryJson(query: QueryAst, options?: ReadOptions): Promise<QueryResult>;
     createToken(options?: {
         tenant?: string;
         expiresIn?: number;

package/dist/server.js

@@ -102,6 +102,10 @@ export class Databob {
     query(build, options = {}) {
         return this.request("POST", "/v1/query", { query: build(queryRoot()).toJSON(), ...options });
     }
+    // The same, from a JSON query (for example one an agent wrote).
+    queryJson(query, options = {}) {
+        return this.request("POST", "/v1/query", { query, ...options });
+    }
     // A short-lived token your frontend uses to read one tenant's metrics.
     createToken(options = {}) {
         const body = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databob/sdk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Privacy-first product analytics you define in code. Typed events, named metrics, per-tenant data, and live React hooks.",
   "license": "Apache-2.0",
   "type": "module",
@@ -13,7 +13,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "databob": "./dist/cli.js"
+    "databob": "dist/cli.js"
   },
   "exports": {
     ".": {
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@databob/engine": "^0.0.1",
+    "@databob/engine": "^0.0.2",
     "esbuild": "^0.27.0"
   },
   "peerDependencies": {