@motherbase/cli 0.2.3 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motherbase/cli",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Motherbase operator CLI — drives the Platform Console and linked projects.",
   "type": "commonjs",
   "bin": {
@@ -10,7 +10,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "lint": "eslint ."
   },
   "files": [
     "bin",

package/src/commands/index.js

@@ -36,6 +36,7 @@ const registry = {
   storage: require('./storage'),
   functions: require('./functions'),
   secrets: require('./secrets'),
+  keys: require('./keys'),
   realtime: require('./realtime'),
   webhooks: require('./webhooks'),
   cron: require('./cron'),
@@ -44,6 +45,9 @@ const registry = {
 
   // ── Codegen ────────────────────────────────────────────────────────────────
   gen: require('./gen'),
+
+  // ── AI agents ──────────────────────────────────────────────────────────────
+  mcp: require('./mcp'),
 };
 
 // Grouping used only to render a tidy top-level help listing.
@@ -52,8 +56,9 @@ const groups = [
   { title: 'Projects (Console)', names: ['projects'] },
   { title: 'Local self-host', names: ['init', 'start', 'stop', 'deploy', 'logs'] },
   { title: 'Database', names: ['db', 'migrations', 'migration', 'import'] },
-  { title: 'Resources', names: ['rls', 'users', 'storage', 'functions', 'secrets', 'realtime', 'webhooks', 'cron', 'config', 'inspect'] },
+  { title: 'Resources', names: ['rls', 'users', 'storage', 'functions', 'secrets', 'keys', 'realtime', 'webhooks', 'cron', 'config', 'inspect'] },
   { title: 'Codegen', names: ['gen'] },
+  { title: 'AI agents', names: ['mcp'] },
 ];
 
 module.exports = { registry, groups };

package/src/commands/keys.js

@@ -0,0 +1,72 @@
+'use strict';
+
+// Project API keys. `secrets` next door is a different thing: those are values
+// an edge function reads, these are what a client presents to reach the project.
+
+const api = require('../api');
+const { output, requireArg } = require('./_util');
+
+const TYPES = ['publishable', 'secret'];
+
+const subcommands = {
+  list: {
+    summary: 'List project API keys',
+    usage: 'motherbase keys list',
+    async run(ctx) {
+      const data = await api.adminRequest(ctx, 'GET', '/api-keys');
+      const keys = (data && data.keys) || [];
+      output(ctx, data, (_d, ui) =>
+        ui.table(
+          keys.map(k => ({
+            name: k.name,
+            type: k.type,
+            // A secret key has no stored clear value; the prefix is all there is.
+            key: k.token || `${k.prefix}…`,
+            status: k.revokedAt ? 'revoked' : 'active',
+          })),
+          [
+            { key: 'name', label: 'NAME' },
+            { key: 'type', label: 'TYPE' },
+            { key: 'key', label: 'KEY' },
+            { key: 'status', label: 'STATUS' },
+          ],
+        ),
+      );
+    },
+  },
+  create: {
+    summary: 'Create a key. A secret key is printed once and never again',
+    usage: 'motherbase keys create <NAME> [--type publishable|secret]',
+    async run(ctx, args, flags) {
+      const name = requireArg(args[0], 'NAME');
+      const type = flags.type || 'secret';
+      if (!TYPES.includes(type)) {
+        throw new Error(`--type must be one of: ${TYPES.join(', ')}`);
+      }
+      const data = await api.adminRequest(ctx, 'POST', '/api-keys', { body: { name, type } });
+      output(ctx, data, (d, ui) => {
+        ui.success(`Created ${type} key "${name}"`);
+        ui.print(d.clearToken);
+        if (type === 'secret') {
+          ui.warn('Copy it now. It is stored hashed and cannot be shown again.');
+          ui.warn('It bypasses row level security: keep it server side.');
+        }
+      });
+    },
+  },
+  revoke: {
+    summary: 'Revoke a key by id',
+    usage: 'motherbase keys revoke <ID>',
+    async run(ctx, args) {
+      const id = requireArg(args[0], 'ID');
+      const data = await api.adminRequest(ctx, 'DELETE', `/api-keys/${encodeURIComponent(id)}`);
+      output(ctx, data, (d, ui) => ui.success(`Revoked key ${d.name || id}`));
+    },
+  },
+};
+
+module.exports = {
+  summary: 'Project API keys (publishable and secret)',
+  usage: 'motherbase keys <list|create|revoke> ...',
+  subcommands,
+};

package/src/commands/local.js

@@ -1,64 +1,273 @@
-'use strict';
-
-// Local self-host workflow: thin wrappers over `docker compose`, plus `init`
-// scaffolding. No HTTP, no context resolution required. Ported and extended from
-// the original single-file CLI.
-
-const fs = require('fs');
-const path = require('path');
-const { spawn } = require('child_process');
-const ui = require('../ui');
-const { CliError } = require('../context');
-
-function dockerCompose(composeArgs) {
-  return new Promise((resolve, reject) => {
-    const child = spawn('docker', ['compose', ...composeArgs], { stdio: 'inherit', windowsHide: true });
-    child.on('error', err => reject(new CliError(`failed to run docker: ${err.message}`)));
-    child.on('close', code => (code === 0 ? resolve() : reject(new CliError(`docker compose exited with code ${code}`))));
-  });
-}
-
-const init = {
-  summary: 'Scaffold a local project directory with a .env',
-  usage: 'motherbase init [dir]',
-  async run(ctx, args) {
-    const dir = args[0] || '.';
-    const target = path.resolve(ctx.cwd, dir);
-    fs.mkdirSync(target, { recursive: true });
-    const envPath = path.join(target, '.env');
-    if (!fs.existsSync(envPath)) {
-      const example = path.join(ctx.cwd, '.env.example');
-      const template = fs.existsSync(example)
-        ? fs.readFileSync(example, 'utf8')
-        : 'PORT=5001\nDATABASE_URL=postgresql://postgres:postgres@localhost:5432/app?schema=public\nJWT_SECRET=change-me\n';
-      fs.writeFileSync(envPath, template);
-    }
-    ui.success(`Initialized Motherbase project at ${target}`);
-  },
-};
-
-const start = {
-  summary: 'Start the local docker compose stack',
-  usage: 'motherbase start',
-  async run() { await dockerCompose(['up', '-d']); },
-};
-
-const stop = {
-  summary: 'Stop the local docker compose stack',
-  usage: 'motherbase stop',
-  async run() { await dockerCompose(['down']); },
-};
-
-const deploy = {
-  summary: 'Rebuild and start the local docker compose stack',
-  usage: 'motherbase deploy',
-  async run() { await dockerCompose(['up', '-d', '--build']); },
-};
-
-const logs = {
-  summary: 'Follow logs from the local docker compose stack',
-  usage: 'motherbase logs [service...]',
-  async run(ctx, args) { await dockerCompose(['logs', '-f', ...args]); },
-};
-
-module.exports = { init, start, stop, deploy, logs };
+'use strict';
+
+// Local self-host workflow: thin wrappers over `docker compose`, plus `init`
+// scaffolding.
+//
+// `init` used to write a `.env` and nothing else, which left a directory that
+// `motherbase start` could not start: `docker compose up` in a folder with no
+// compose file is a raw Docker error, and that was the first thing a new user
+// saw. It now writes a self-contained stack that runs.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const ui = require('../ui');
+const { CliError } = require('../context');
+
+const COMPOSE_FILE = 'docker-compose.yml';
+const ENV_FILE = '.env';
+
+// Where the images are built from when the caller has no checkout. Docker
+// Compose accepts a git URL as a build context, so a scaffolded directory needs
+// nothing but Docker: no clone, no registry, no published image. The first `up`
+// pays for the build; every one after that is cached.
+const DEFAULT_REPO = 'https://github.com/JulienGuinot/BoilerPlate-Backend.git';
+const DEFAULT_REF = 'master';
+
+function dockerCompose(composeArgs) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('docker', ['compose', ...composeArgs], { stdio: 'inherit', windowsHide: true });
+    child.on('error', err => reject(new CliError(`failed to run docker: ${err.message}`)));
+    child.on('close', code => (code === 0 ? resolve() : reject(new CliError(`docker compose exited with code ${code}`))));
+  });
+}
+
+/**
+ * Refuse to run compose from a directory that has no stack, and say what to do.
+ * Without this the user gets Docker's own "no configuration file provided",
+ * which does not mention `motherbase init`.
+ */
+function assertStack(ctx) {
+  const file = path.join(ctx.cwd, COMPOSE_FILE);
+  if (!fs.existsSync(file)) {
+    throw new CliError(
+      `no ${COMPOSE_FILE} here. Run \`motherbase init\` first, or cd into a directory that has one.`,
+    );
+  }
+}
+
+const hex = n => crypto.randomBytes(n).toString('hex');
+const b64 = n => crypto.randomBytes(n).toString('base64');
+
+function renderEnv(context) {
+  return [
+    '# Generated by `motherbase init`. Secrets below are unique to this install.',
+    '# Keep this file out of version control.',
+    '',
+    `PORT=${context.port}`,
+    `BASE_HOST=localhost:${context.port}`,
+    'NODE_ENV=production',
+    '',
+    '# Secrets. Regenerating any of these invalidates what it protects:',
+    '# JWT_SECRET signs sessions, CONFIG_ENCRYPTION_KEY encrypts Studio-managed',
+    '# secrets (SMTP, OAuth credentials) at rest.',
+    `JWT_SECRET=${hex(32)}`,
+    `CONFIG_ENCRYPTION_KEY=${b64(32)}`,
+    `POSTGRES_PASSWORD=${hex(16)}`,
+    `S3_ACCESS_KEY_ID=${hex(8)}`,
+    `S3_SECRET_ACCESS_KEY=${hex(20)}`,
+    '',
+    'S3_BUCKET=uploads',
+    'S3_PUBLIC_BUCKET=public',
+    'S3_REGION=us-east-1',
+    '',
+    '# Host ports. Change these if something already listens on them.',
+    `POSTGRES_PORT=${context.postgresPort}`,
+    'MINIO_PORT=59000',
+    'MINIO_CONSOLE_PORT=59001',
+    '',
+    '# First operator account, created on first boot.',
+    `SEED_ADMIN_EMAIL=${context.adminEmail}`,
+    `SEED_ADMIN_PASSWORD=${context.adminPassword}`,
+    '',
+  ].join('\n');
+}
+
+function renderCompose(context) {
+  const buildContext = `${context.repo}#${context.ref}`;
+  return `# Generated by \`motherbase init\`.
+#
+# Images are built from the public repository, so this directory needs Docker and
+# nothing else: no checkout, no registry login. The first \`up\` builds them, which
+# takes a few minutes; after that the layers are cached.
+#
+# Working from a checkout instead? Replace both \`context:\` values with the path
+# to it and the build becomes local and incremental.
+services:
+  db:
+    build:
+      context: ${buildContext}
+      dockerfile: deploy/postgres.Dockerfile
+    command: ['postgres', '-c', 'shared_preload_libraries=pg_cron,pg_stat_statements', '-c', 'cron.database_name=app']
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD}
+      POSTGRES_DB: app
+    ports:
+      # Loopback only: reachable by psql, Prisma, Drizzle or a BI client on this
+      # machine, and by nothing on the network.
+      - '127.0.0.1:\${POSTGRES_PORT:-55432}:5432'
+    volumes:
+      - db_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U postgres']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  minio:
+    image: alpine/minio:RELEASE.2025-10-15T17-29-55Z
+    restart: unless-stopped
+    user: "0:0"
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: \${S3_ACCESS_KEY_ID}
+      MINIO_ROOT_PASSWORD: \${S3_SECRET_ACCESS_KEY}
+    ports:
+      - '127.0.0.1:\${MINIO_PORT:-59000}:9000'
+      - '127.0.0.1:\${MINIO_CONSOLE_PORT:-59001}:9001'
+    volumes:
+      - minio_data:/data
+    healthcheck:
+      test: ['CMD-SHELL', 'wget -qO- http://localhost:9000/minio/health/live >/dev/null']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  # One-shot: a private bucket and a separate anonymously-downloadable one.
+  createbuckets:
+    image: minio/mc:RELEASE.2025-08-13T08-35-41Z
+    depends_on:
+      minio:
+        condition: service_healthy
+    entrypoint: >
+      /bin/sh -c "
+      mc alias set local http://minio:9000 \${S3_ACCESS_KEY_ID} \${S3_SECRET_ACCESS_KEY};
+      mc mb --ignore-existing local/\${S3_BUCKET:-uploads};
+      mc anonymous set none local/\${S3_BUCKET:-uploads};
+      mc mb --ignore-existing local/\${S3_PUBLIC_BUCKET:-public};
+      mc anonymous set download local/\${S3_PUBLIC_BUCKET:-public};
+      echo 'buckets ready';
+      "
+
+  api:
+    build:
+      context: ${buildContext}
+    restart: unless-stopped
+    depends_on:
+      db:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+      createbuckets:
+        condition: service_completed_successfully
+    env_file:
+      - ${ENV_FILE}
+    # Container-internal wiring, overriding the localhost values in .env so the
+    # same file works for both host tooling and the containers.
+    environment:
+      NODE_ENV: production
+      PORT: 5001
+      DATABASE_URL: postgresql://postgres:\${POSTGRES_PASSWORD}@db:5432/app?schema=public
+      STORAGE_DRIVER: s3
+      S3_ENDPOINT: http://minio:9000
+      DB_PORT: \${POSTGRES_PORT:-55432}
+    ports:
+      - '\${PORT:-5001}:5001'
+
+volumes:
+  db_data:
+  minio_data:
+`;
+}
+
+const init = {
+  summary: 'Scaffold a runnable local stack (compose file, .env, generated secrets)',
+  usage: 'motherbase init [dir] [--port 5001] [--repo URL] [--ref BRANCH] [--force]',
+  async run(ctx, args, flags = {}) {
+    const dir = args[0] || '.';
+    const target = path.resolve(ctx.cwd, dir);
+    fs.mkdirSync(target, { recursive: true });
+
+    const context = {
+      port: Number(flags.port) || 5001,
+      postgresPort: Number(flags['postgres-port']) || 55432,
+      repo: flags.repo || DEFAULT_REPO,
+      ref: flags.ref || DEFAULT_REF,
+      adminEmail: flags['admin-email'] || 'admin@example.com',
+      // Generated, never a placeholder: a scaffold that ships `change-me` is a
+      // scaffold that reaches production with `change-me`.
+      adminPassword: flags['admin-password'] || crypto.randomBytes(12).toString('base64url'),
+    };
+
+    const written = [];
+    const skipped = [];
+    for (const [name, render] of [[ENV_FILE, renderEnv], [COMPOSE_FILE, renderCompose]]) {
+      const file = path.join(target, name);
+      // Never silently overwrite: .env holds the only copy of secrets that
+      // existing data was encrypted with.
+      if (fs.existsSync(file) && !flags.force) {
+        skipped.push(name);
+        continue;
+      }
+      fs.writeFileSync(file, render(context), name === ENV_FILE ? { mode: 0o600 } : undefined);
+      written.push(name);
+    }
+
+    ui.success(`Initialized Motherbase project at ${target}`);
+    if (written.length) ui.info(`wrote ${written.join(', ')}`);
+    if (skipped.length) {
+      ui.warn(`kept existing ${skipped.join(', ')} (use --force to overwrite, which discards their secrets)`);
+    }
+    if (written.includes(ENV_FILE)) {
+      ui.print('');
+      ui.print(`  Studio:   http://localhost:${context.port}`);
+      ui.print(`  Sign in:  ${context.adminEmail} / ${context.adminPassword}`);
+      ui.print('');
+      ui.print('  Next:');
+      if (dir !== '.') ui.print(`    cd ${dir}`);
+      ui.print('    motherbase start        # first run builds the images, give it a few minutes');
+      ui.print('');
+    }
+  },
+};
+
+const start = {
+  summary: 'Start the local docker compose stack',
+  usage: 'motherbase start',
+  async run(ctx) {
+    assertStack(ctx);
+    await dockerCompose(['up', '-d']);
+  },
+};
+
+const stop = {
+  summary: 'Stop the local docker compose stack',
+  usage: 'motherbase stop',
+  async run(ctx) {
+    assertStack(ctx);
+    await dockerCompose(['down']);
+  },
+};
+
+const deploy = {
+  summary: 'Rebuild and start the local docker compose stack',
+  usage: 'motherbase deploy',
+  async run(ctx) {
+    assertStack(ctx);
+    await dockerCompose(['up', '-d', '--build']);
+  },
+};
+
+const logs = {
+  summary: 'Follow logs from the local docker compose stack',
+  usage: 'motherbase logs [service...]',
+  async run(ctx, args) {
+    assertStack(ctx);
+    await dockerCompose(['logs', '-f', ...args]);
+  },
+};
+
+module.exports = { init, start, stop, deploy, logs, renderEnv, renderCompose };

package/src/commands/mcp.js

@@ -0,0 +1,43 @@
+'use strict';
+
+// `motherbase mcp` — expose the linked project to an AI agent over the Model
+// Context Protocol.
+//
+// The transport is stdio, which is how an MCP client launches a server: it spawns
+// this process and talks JSON-RPC over its stdin/stdout. Nothing is printed to
+// stdout except protocol messages, so diagnostics go to stderr.
+
+const { serve, toolServer } = require('../mcp/protocol');
+const { buildTools } = require('../mcp/tools');
+
+const pkg = require('../../package.json');
+
+const mcp = {
+  summary: 'Serve the linked project to an AI agent over MCP (stdio)',
+  usage: 'motherbase mcp [--write]',
+  async run(ctx, _args, flags = {}) {
+    // Resolve the project up front. Failing here is a clear CLI error; failing
+    // on the first tool call is an opaque one inside someone's agent.
+    ctx.requireProject();
+
+    const write = Boolean(flags.write);
+    const tools = buildTools(ctx, { write });
+
+    process.stderr.write(
+      `motherbase mcp: ${tools.length} tools, ${write ? 'read and write' : 'read only'}. `
+        + `Project: ${ctx.projectName || ctx.projectId || 'direct'}\n`,
+    );
+    if (!write) {
+      process.stderr.write('  Pass --write to expose apply_migration and raw SQL writes.\n');
+    }
+
+    await serve({
+      input: process.stdin,
+      output: process.stdout,
+      handlers: toolServer({ name: 'motherbase', version: pkg.version, tools }),
+      onError: err => process.stderr.write(`motherbase mcp: ${err && err.message ? err.message : err}\n`),
+    });
+  },
+};
+
+module.exports = mcp;

package/src/mcp/protocol.js

@@ -0,0 +1,149 @@
+'use strict';
+
+// Minimal MCP server over stdio: newline-delimited JSON-RPC 2.0 on stdin/stdout.
+//
+// Why not the official SDK: a stdio tools server needs five methods, and
+// `@modelcontextprotocol/sdk` pulls express, hono, cors, ajv, jose and a dozen
+// more to provide them. This CLI is deliberately zero-dependency, and making
+// `npx @motherbase/cli` install a web framework so that one subcommand can read
+// stdin is not a trade worth making.
+//
+// ponytail: stdio transport and the tools capability only. No resources, no
+// prompts, no sampling, no HTTP/SSE transport. Adopt the official SDK if any of
+// those is ever needed rather than growing this file into a second one.
+
+// Echoed back to the client. MCP clients negotiate by sending their own version;
+// answering with a version we implement is the contract, and every client in the
+// field accepts a server that names an older one.
+const PROTOCOL_VERSION = '2024-11-05';
+
+/** JSON-RPC error codes used here. */
+const METHOD_NOT_FOUND = -32601;
+const INTERNAL_ERROR = -32603;
+const PARSE_ERROR = -32700;
+
+/**
+ * Reads newline-delimited JSON from `input`, dispatches to `handlers`, writes
+ * responses to `output`.
+ *
+ * Split from the tool definitions so the transport can be driven by a test with
+ * two in-memory streams and no child process.
+ */
+function serve({ input, output, handlers, onError }) {
+  let buffer = '';
+
+  const write = message => {
+    output.write(JSON.stringify(message) + '\n');
+  };
+
+  const respond = (id, result) => {
+    // A notification (no id) gets no response. Sending one is a protocol error
+    // that some clients treat as fatal.
+    if (id === undefined || id === null) return;
+    write({ jsonrpc: '2.0', id, result });
+  };
+
+  const fail = (id, code, message) => {
+    if (id === undefined || id === null) return;
+    write({ jsonrpc: '2.0', id, error: { code, message } });
+  };
+
+  const dispatch = async message => {
+    const { id, method, params } = message;
+    const handler = handlers[method];
+    if (!handler) {
+      // Unknown notifications are ignored rather than answered: the spec sends
+      // several the server is not required to know about.
+      if (id === undefined || id === null) return;
+      return fail(id, METHOD_NOT_FOUND, `Unknown method: ${method}`);
+    }
+    try {
+      respond(id, await handler(params || {}));
+    } catch (err) {
+      if (onError) onError(err);
+      fail(id, INTERNAL_ERROR, err && err.message ? err.message : String(err));
+    }
+  };
+
+  return new Promise(resolve => {
+    input.setEncoding('utf8');
+    input.on('data', chunk => {
+      buffer += chunk;
+      let index;
+      while ((index = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, index).trim();
+        buffer = buffer.slice(index + 1);
+        if (!line) continue;
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          write({ jsonrpc: '2.0', id: null, error: { code: PARSE_ERROR, message: 'Invalid JSON' } });
+          continue;
+        }
+        // Deliberately not awaited: a slow tool call must not stall the reader,
+        // and JSON-RPC responses carry their id so they may arrive out of order.
+        void dispatch(message);
+      }
+    });
+    input.on('end', resolve);
+    input.on('close', resolve);
+  });
+}
+
+/**
+ * Build the five handlers a tools-only server needs.
+ *
+ * `tools` is a list of `{ name, description, inputSchema, run }`. `run` returns
+ * anything JSON-serialisable; it is rendered as a text content block, which is
+ * what every current client displays and what models read best.
+ */
+function toolServer({ name, version, tools }) {
+  const byName = new Map(tools.map(tool => [tool.name, tool]));
+
+  return {
+    initialize: () => ({
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      serverInfo: { name, version },
+    }),
+    'notifications/initialized': () => undefined,
+    ping: () => ({}),
+    'tools/list': () => ({
+      tools: tools.map(({ name: toolName, description, inputSchema }) => ({
+        name: toolName,
+        description,
+        inputSchema,
+      })),
+    }),
+    'tools/call': async params => {
+      const tool = byName.get(params.name);
+      if (!tool) {
+        // A missing tool is reported in-band, not as a JSON-RPC error: the model
+        // should see it and correct itself rather than the client showing a
+        // transport failure.
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Unknown tool: ${params.name}` }],
+        };
+      }
+      try {
+        const result = await tool.run(params.arguments || {});
+        return { content: [{ type: 'text', text: render(result) }] };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: err && err.message ? err.message : String(err) }],
+        };
+      }
+    },
+  };
+}
+
+function render(value) {
+  if (typeof value === 'string') return value;
+  if (value === undefined) return 'ok';
+  return JSON.stringify(value, null, 2);
+}
+
+module.exports = { serve, toolServer, PROTOCOL_VERSION };

package/src/mcp/tools.js

@@ -0,0 +1,166 @@
+'use strict';
+
+// The tools an agent gets over MCP.
+//
+// Every one is a call to the project admin API through `api.adminRequest`, the
+// same path every CLI command takes. That is the whole design: authentication,
+// console-proxy vs direct mode, and error mapping are solved once in the CLI and
+// reused here, so an MCP session cannot reach anything a `motherbase` command
+// could not, and cannot drift from it either.
+//
+// The gap this closes is the one self-hosters name about Supabase's MCP: "DDL
+// statements not supported". `apply_migration` runs DDL, because the admin API
+// this is built on already does.
+
+const api = require('../api');
+
+const str = description => ({ type: 'string', description });
+
+/** Tools that only read. Safe to run without confirmation. */
+function readTools(ctx) {
+  return [
+    {
+      name: 'list_tables',
+      description: 'List the tables in the project database, with their columns and row counts.',
+      inputSchema: { type: 'object', properties: {} },
+      run: () => api.adminRequest(ctx, 'GET', '/tables'),
+    },
+    {
+      name: 'describe_table',
+      description: 'Columns, types, nullability, defaults, primary key and indexes of one table.',
+      inputSchema: {
+        type: 'object',
+        properties: { table: str('Table name, in the public schema.') },
+        required: ['table'],
+      },
+      run: async args => {
+        const [tables, indexes] = await Promise.all([
+          api.adminRequest(ctx, 'GET', '/schema/tables'),
+          api.adminRequest(ctx, 'GET', `/schema/tables/${encodeURIComponent(args.table)}/indexes`),
+        ]);
+        const list = Array.isArray(tables) ? tables : tables && tables.tables;
+        const table = (list || []).find(t => t.name === args.table || t.table === args.table);
+        if (!table) throw new Error(`No table named "${args.table}" in the public schema.`);
+        return { ...table, indexes };
+      },
+    },
+    {
+      name: 'list_policies',
+      description:
+        'Row level security state for every table: whether RLS is on, and the policies attached with their USING and WITH CHECK expressions.',
+      inputSchema: { type: 'object', properties: {} },
+      run: () => api.adminRequest(ctx, 'GET', '/rls/tables'),
+    },
+    {
+      name: 'simulate_rls',
+      description:
+        'Run a SELECT as a given caller and report the rows they can see plus the policies that decided. The statement really executes, inside a transaction that is always rolled back.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          sql: str('A single SELECT statement.'),
+          role: str("'anon' or 'authenticated'. Ignored when userId is given."),
+          userId: str('Run as this existing user instead of a bare role.'),
+        },
+        required: ['sql'],
+      },
+      run: args =>
+        api.adminRequest(ctx, 'POST', '/rls/simulate', {
+          body: { sql: args.sql, role: args.role, userId: args.userId },
+        }),
+    },
+    {
+      name: 'get_advisors',
+      description:
+        'Lint the schema and policies: tables exposed with RLS off, RLS on with no policy, policies that leak through a join, SECURITY DEFINER functions anon can call, unindexed policy columns.',
+      inputSchema: { type: 'object', properties: {} },
+      run: () => api.adminRequest(ctx, 'GET', '/advisor'),
+    },
+    {
+      name: 'get_logs',
+      description: 'Recent API and database log entries.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          limit: { type: 'number', description: 'How many entries. Defaults to 100.' },
+          level: str("Filter by level: 'info', 'warn' or 'error'."),
+        },
+      },
+      run: args =>
+        api.adminRequest(ctx, 'GET', '/logs', {
+          query: { limit: args.limit || 100, level: args.level },
+        }),
+    },
+    {
+      name: 'generate_types',
+      description:
+        'TypeScript types for the whole schema, in the supabase-js Database shape. The same output as `motherbase gen types typescript`.',
+      inputSchema: { type: 'object', properties: {} },
+      run: () => api.adminRequest(ctx, 'GET', '/schema/types'),
+    },
+    {
+      name: 'execute_sql',
+      description:
+        'Run a read-only SQL query. Statements that write are refused: use apply_migration for those.',
+      inputSchema: {
+        type: 'object',
+        properties: { sql: str('A read-only SQL statement.') },
+        required: ['sql'],
+      },
+      // The read-only endpoint, not /sql: a tool the model reaches for by default
+      // must not be able to write, whatever the model believed it was doing.
+      run: args => api.adminRequest(ctx, 'POST', '/sql/readonly', { body: { sql: args.sql } }),
+    },
+  ];
+}
+
+/** Tools that change the database. Only exposed with `--write`. */
+function writeTools(ctx) {
+  return [
+    {
+      name: 'apply_migration',
+      description:
+        'Create a named migration from DDL and apply it. This is the tool for CREATE TABLE, ALTER TABLE, CREATE POLICY and every other schema change. The migration is recorded, so it can be rolled back.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: str('Short migration name, e.g. add_orders_table.'),
+          sql: str('The DDL to apply.'),
+          downSql: str('Optional SQL that undoes it, enabling rollback.'),
+        },
+        required: ['name', 'sql'],
+      },
+      run: async args => {
+        const created = await api.adminRequest(ctx, 'POST', '/migrations', {
+          body: { name: args.name, upSql: args.sql, downSql: args.downSql },
+        });
+        const id = created && (created.id || (created.migration && created.migration.id));
+        if (!id) throw new Error('The migration was created but the server returned no id to apply.');
+        const applied = await api.adminRequest(ctx, 'POST', `/migrations/${encodeURIComponent(id)}/apply`);
+        return { id, applied };
+      },
+    },
+    {
+      name: 'execute_sql_write',
+      description:
+        'Run arbitrary SQL, including writes. Prefer apply_migration for schema changes: this leaves no record and cannot be rolled back.',
+      inputSchema: {
+        type: 'object',
+        properties: { sql: str('The SQL to run.') },
+        required: ['sql'],
+      },
+      run: args => api.adminRequest(ctx, 'POST', '/sql', { body: { sql: args.sql } }),
+    },
+  ];
+}
+
+/**
+ * `write` defaults to false, so an agent that connects without being told
+ * otherwise can read the schema, lint it and simulate policies, but cannot
+ * change anything. Handing an agent DDL is a decision the operator makes.
+ */
+function buildTools(ctx, { write = false } = {}) {
+  return write ? [...readTools(ctx), ...writeTools(ctx)] : readTools(ctx);
+}
+
+module.exports = { buildTools, readTools, writeTools };