@motherbase/cli 0.2.2 → 0.2.4

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 };

package/src/prompt.js

@@ -14,23 +14,70 @@ function question(query) {
   });
 }
 
-// Hidden input: we mute the output stream by intercepting writes so the typed
-// characters (and the password) never echo.
+// Hidden input. Reads the TTY in raw mode so nothing echoes, masking each typed
+// character with '*'. Handles backspace, Enter, Ctrl+C, Ctrl+D and swallows
+// escape sequences (arrow keys etc.) so they never land in the value. When
+// stdin is not a TTY (pipes, CI) we fall back to a plain, unmasked line read.
 function password(query = 'Password: ') {
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+  if (!stdin.isTTY) return question(query);
+
   return new Promise(resolve => {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
-    const onData = () => {
-      // Overwrite whatever readline just echoed with the prompt only.
-      process.stdout.write(`\r${query}`);
+    let value = '';
+    let inEscape = false;
+    stdout.write(query);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    const done = result => {
+      stdin.removeListener('data', onData);
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdout.write('\n');
+      resolve(result);
     };
-    process.stdout.write(query);
-    process.stdin.on('data', onData);
-    rl.question('', answer => {
-      process.stdin.removeListener('data', onData);
-      rl.close();
-      process.stdout.write('\n');
-      resolve(answer);
-    });
+
+    const onData = chunk => {
+      for (const ch of chunk) {
+        if (inEscape) {
+          // Terminators of a CSI/escape sequence (e.g. arrow keys): stop swallowing.
+          if (/[a-zA-Z~]/.test(ch)) inEscape = false;
+          continue;
+        }
+        switch (ch) {
+          case '\r':
+          case '\n':
+          case '\u0004': // Ctrl-D
+            return done(value);
+          case '\u0003': // Ctrl-C
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdout.write('\n');
+            process.exit(130);
+            return;
+          case '\u007f': // Backspace / Delete
+          case '\b':
+            if (value.length > 0) {
+              value = value.slice(0, -1);
+              stdout.write('\b \b');
+            }
+            break;
+          case '\u001b': // ESC — start of an escape sequence
+            inEscape = true;
+            break;
+          default:
+            // Ignore remaining control characters; mask printable ones.
+            if (ch >= ' ') {
+              value += ch;
+              stdout.write('*');
+            }
+        }
+      }
+    };
+
+    stdin.on('data', onData);
   });
 }