@dypai-ai/mcp 1.4.5 → 1.5.0

package/src/tools/introspect.js

@@ -0,0 +1,311 @@
+/**
+ * introspect — read-only schema introspection against the project DB.
+ *
+ * Single tool, three targets:
+ *
+ *   target='schema',   name='public'       → list tables/views/functions/types in the schema
+ *   target='table',    name='public.users' → full DDL-ish payload (columns, PK, FKs, indexes, triggers, RLS)
+ *   target='function', name='public.fn(int,text)' OR 'public.fn' → signature(s) + body
+ *
+ * Why a dedicated tool when execute_sql exists:
+ *   - Saves the agent from writing pg_catalog SQL by hand every time (a common
+ *     "I gave up and grepped the schema.sql" scenario).
+ *   - Returns structured JSON, not the raw column dump execute_sql gives back.
+ *   - Works against schemas `schema.sql` doesn't dump (auth, storage) — the
+ *     bug-hunt for `operator does not exist: text = uuid` in stock-infomarket
+ *     burned ~30min because `auth.users.id` type was invisible.
+ *   - Dog-fooded: the agent can now answer "what signature does function X
+ *     have?" without reinventing pg_proc joins every session.
+ *
+ * Security: pure SELECT against pg_catalog / information_schema. The guard
+ * still runs so malformed `name` inputs can't inject DML.
+ */
+
+import { proxyToolCall } from "./proxy.js"
+import { validateSql, formatValidationError } from "./sql-guard.js"
+
+function parseTableName(name) {
+  const m = String(name).trim().match(/^([a-zA-Z_][\w$]*)(?:\.([a-zA-Z_][\w$]*))?$/)
+  if (!m) return null
+  return m[2]
+    ? { schema: m[1], table: m[2] }
+    : { schema: "public", table: m[1] }
+}
+
+// function_name can be bare ("foo"), schema-qualified ("public.foo"), or
+// include a signature ("public.foo(int,text)"). When signature is given we
+// filter pg_get_function_identity_arguments to pick the exact overload.
+function parseFunctionName(name) {
+  const s = String(name).trim()
+  const sigM = s.match(/^([^(]+)\((.*)\)$/)
+  const ident = sigM ? sigM[1].trim() : s
+  const sig   = sigM ? sigM[2].trim() : null
+  const m = ident.match(/^([a-zA-Z_][\w$]*)(?:\.([a-zA-Z_][\w$]*))?$/)
+  if (!m) return null
+  return m[2]
+    ? { schema: m[1], func: m[2], signature: sig }
+    : { schema: "public", func: m[1], signature: sig }
+}
+
+async function runSelect(project_id, sql) {
+  const v = validateSql(sql, { allowSelectOnly: true })
+  if (!v.ok) {
+    const msg = formatValidationError(v)
+    throw new Error(`introspect: ${msg}`)
+  }
+  const args = project_id ? { project_id, sql } : { sql }
+  const res = await proxyToolCall("execute_sql", args)
+  return Array.isArray(res?.rows) ? res.rows : (Array.isArray(res) ? res : [])
+}
+
+async function describeSchema(project_id, schema) {
+  const s = schema.replace(/'/g, "''")
+  const [tables, views, functions] = await Promise.all([
+    runSelect(project_id, `
+      SELECT tablename AS name
+      FROM pg_catalog.pg_tables
+      WHERE schemaname = '${s}'
+      ORDER BY tablename
+    `),
+    runSelect(project_id, `
+      SELECT viewname AS name
+      FROM pg_catalog.pg_views
+      WHERE schemaname = '${s}'
+      ORDER BY viewname
+    `),
+    runSelect(project_id, `
+      SELECT p.proname AS name,
+             pg_catalog.pg_get_function_identity_arguments(p.oid) AS args,
+             pg_catalog.pg_get_function_result(p.oid) AS returns
+      FROM pg_catalog.pg_proc p
+      JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+      WHERE n.nspname = '${s}'
+        AND p.prokind IN ('f','p')
+      ORDER BY p.proname, args
+    `),
+  ])
+  return {
+    schema,
+    tables: tables.map(r => r.name),
+    views: views.map(r => r.name),
+    functions: functions.map(r => ({
+      name: r.name,
+      args: r.args,
+      returns: r.returns,
+    })),
+  }
+}
+
+async function describeTable(project_id, schema, table) {
+  const s = schema.replace(/'/g, "''")
+  const t = table.replace(/'/g, "''")
+
+  const [columns, pk, fks, indexes, triggers, rls, rowcount] = await Promise.all([
+    runSelect(project_id, `
+      SELECT column_name, data_type, is_nullable,
+             column_default, character_maximum_length, udt_name
+      FROM information_schema.columns
+      WHERE table_schema = '${s}' AND table_name = '${t}'
+      ORDER BY ordinal_position
+    `),
+    runSelect(project_id, `
+      SELECT kcu.column_name
+      FROM information_schema.table_constraints tc
+      JOIN information_schema.key_column_usage kcu
+        ON kcu.constraint_name = tc.constraint_name
+       AND kcu.table_schema = tc.table_schema
+      WHERE tc.table_schema = '${s}' AND tc.table_name = '${t}'
+        AND tc.constraint_type = 'PRIMARY KEY'
+      ORDER BY kcu.ordinal_position
+    `),
+    runSelect(project_id, `
+      SELECT kcu.column_name,
+             ccu.table_schema AS foreign_schema,
+             ccu.table_name   AS foreign_table,
+             ccu.column_name  AS foreign_column,
+             rc.update_rule, rc.delete_rule
+      FROM information_schema.table_constraints tc
+      JOIN information_schema.key_column_usage kcu
+        ON kcu.constraint_name = tc.constraint_name
+       AND kcu.table_schema = tc.table_schema
+      JOIN information_schema.referential_constraints rc
+        ON rc.constraint_name = tc.constraint_name
+       AND rc.constraint_schema = tc.table_schema
+      JOIN information_schema.constraint_column_usage ccu
+        ON ccu.constraint_name = tc.constraint_name
+       AND ccu.table_schema = tc.table_schema
+      WHERE tc.table_schema = '${s}' AND tc.table_name = '${t}'
+        AND tc.constraint_type = 'FOREIGN KEY'
+      ORDER BY kcu.ordinal_position
+    `),
+    runSelect(project_id, `
+      SELECT indexname AS name, indexdef AS definition
+      FROM pg_catalog.pg_indexes
+      WHERE schemaname = '${s}' AND tablename = '${t}'
+      ORDER BY indexname
+    `),
+    runSelect(project_id, `
+      SELECT trigger_name AS name, event_manipulation AS event,
+             action_timing AS timing, action_statement AS body
+      FROM information_schema.triggers
+      WHERE event_object_schema = '${s}' AND event_object_table = '${t}'
+      ORDER BY trigger_name
+    `),
+    runSelect(project_id, `
+      SELECT polname AS name, polcmd AS command,
+             pg_catalog.pg_get_expr(polqual, polrelid) AS using_expr,
+             pg_catalog.pg_get_expr(polwithcheck, polrelid) AS check_expr,
+             (SELECT relrowsecurity FROM pg_catalog.pg_class c
+                WHERE c.relname='${t}'
+                  AND c.relnamespace=(SELECT oid FROM pg_catalog.pg_namespace WHERE nspname='${s}')) AS rls_enabled
+      FROM pg_catalog.pg_policy p
+      JOIN pg_catalog.pg_class c ON c.oid = p.polrelid
+      JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = '${s}' AND c.relname = '${t}'
+      ORDER BY polname
+    `),
+    runSelect(project_id, `
+      SELECT reltuples::bigint AS approximate_rows
+      FROM pg_catalog.pg_class c
+      JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = '${s}' AND c.relname = '${t}'
+      LIMIT 1
+    `),
+  ])
+
+  return {
+    schema, table,
+    exists: columns.length > 0,
+    approximate_rows: rowcount[0]?.approximate_rows ?? null,
+    columns,
+    primary_key: pk.map(r => r.column_name),
+    foreign_keys: fks,
+    indexes,
+    triggers,
+    row_level_security: {
+      enabled: rls[0]?.rls_enabled === true,
+      policies: rls,
+    },
+  }
+}
+
+async function describeFunction(project_id, schema, funcName, signature) {
+  const s = schema.replace(/'/g, "''")
+  const f = funcName.replace(/'/g, "''")
+  let overloads = await runSelect(project_id, `
+    SELECT p.oid,
+           p.proname AS name,
+           pg_catalog.pg_get_function_identity_arguments(p.oid) AS args,
+           pg_catalog.pg_get_function_result(p.oid) AS returns,
+           p.prokind,
+           l.lanname AS language,
+           p.prosecdef AS security_definer,
+           p.provolatile AS volatile_flag,
+           pg_catalog.pg_get_functiondef(p.oid) AS definition
+    FROM pg_catalog.pg_proc p
+    JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+    JOIN pg_catalog.pg_language l  ON l.oid = p.prolang
+    WHERE n.nspname = '${s}' AND p.proname = '${f}'
+      AND p.prokind IN ('f','p')
+    ORDER BY args
+  `)
+
+  if (signature != null) {
+    // Normalize whitespace for comparison — user might write
+    // "int,text" or "integer , text".
+    const norm = sig => sig.replace(/\s+/g, "").toLowerCase()
+    const wanted = norm(signature)
+    overloads = overloads.filter(o => norm(o.args) === wanted)
+  }
+
+  return {
+    schema,
+    name: funcName,
+    requested_signature: signature ?? null,
+    overloads: overloads.map(o => ({
+      signature: `${schema}.${funcName}(${o.args})`,
+      args: o.args,
+      returns: o.returns,
+      kind: o.prokind === "p" ? "procedure" : "function",
+      language: o.language,
+      security_definer: o.security_definer,
+      volatile: o.volatile_flag === "i" ? "immutable" : o.volatile_flag === "s" ? "stable" : "volatile",
+      definition: o.definition,
+    })),
+  }
+}
+
+export const introspectTool = {
+  name: "introspect",
+  description:
+    "Read-only introspection of the project database. One tool, three targets:\n\n" +
+    "• target='schema'   name='public'         — list tables/views/functions in a schema\n" +
+    "• target='table'    name='public.orders'  — columns, PK, FKs, indexes, triggers, RLS, approx rows\n" +
+    "• target='function' name='public.foo'     — all overloads with signature + body\n" +
+    "  (or disambiguate an overload: name='public.foo(uuid,text)')\n\n" +
+    "Prefer this over hand-rolling pg_catalog queries. Works against ALL schemas including " +
+    "`auth`, `storage`, `system` (read-only). Returns structured JSON, never raw SQL dumps.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      project_id: {
+        type: "string",
+        description: "Project UUID. Optional if your token is project-scoped.",
+      },
+      target: {
+        type: "string",
+        enum: ["schema", "table", "function"],
+        description: "What kind of object to inspect.",
+      },
+      name: {
+        type: "string",
+        description:
+          "Identifier of the object. Bare name is treated as `public.<name>`. " +
+          "For function overloads include the signature: `schema.foo(type1,type2)`.",
+      },
+    },
+    required: ["target", "name"],
+  },
+
+  async execute({ project_id, target, name } = {}) {
+    if (!target || !name) {
+      return { success: false, error: "target and name are required." }
+    }
+    try {
+      if (target === "schema") {
+        const parsed = parseTableName(name)
+        if (!parsed) return { success: false, error: `Invalid schema name: ${name}` }
+        // Accept "public" or "public.x" — we use the first identifier as schema
+        const data = await describeSchema(project_id, parsed.schema)
+        return { success: true, ...data }
+      }
+      if (target === "table") {
+        const parsed = parseTableName(name)
+        if (!parsed) return { success: false, error: `Invalid table name: ${name}` }
+        const data = await describeTable(project_id, parsed.schema, parsed.table)
+        if (!data.exists) {
+          return { success: false, error: `Table ${parsed.schema}.${parsed.table} does not exist.`, ...data }
+        }
+        return { success: true, ...data }
+      }
+      if (target === "function") {
+        const parsed = parseFunctionName(name)
+        if (!parsed) return { success: false, error: `Invalid function name: ${name}` }
+        const data = await describeFunction(project_id, parsed.schema, parsed.func, parsed.signature)
+        if (!data.overloads.length) {
+          return {
+            success: false,
+            error: parsed.signature
+              ? `No function ${parsed.schema}.${parsed.func}(${parsed.signature}) — signature not found.`
+              : `No function ${parsed.schema}.${parsed.func} exists.`,
+            hint: "Use introspect(target='schema', name='<schema>') to list functions.",
+          }
+        }
+        return { success: true, ...data }
+      }
+      return { success: false, error: `Unknown target: ${target}` }
+    } catch (e) {
+      return { success: false, error: e.message }
+    }
+  },
+}