@dotdo/postgres 0.1.2 → 0.1.3

package/src/mcp/tools.ts

@@ -0,0 +1,464 @@
+/**
+ * MCP Tools for PostgresDO
+ *
+ * Implements the three core MCP tools: search, fetch, and do.
+ */
+
+import type {
+  MCPSearchResult,
+  MCPFetchResult,
+  ToolResponse,
+  SearchInput,
+  FetchInput,
+  DoInput,
+  MCPAuthContext,
+} from './types.js'
+import type { QueryExecutor } from './binding.js'
+import { createPGBinding, PG_BINDING_TYPES } from './binding.js'
+
+/**
+ * Tool definition for MCP protocol
+ */
+export interface Tool {
+  name: string
+  description: string
+  inputSchema: {
+    type: string
+    properties: Record<string, unknown>
+    required: string[]
+  }
+}
+
+/**
+ * Search tool definition
+ */
+export const searchTool: Tool = {
+  name: 'search',
+  description:
+    'Search the PostgreSQL database. Supports SQL queries, table listing, and schema introspection.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description:
+          'Search query. Can be: SQL query (SELECT ...), "tables" to list tables, or "schema:<table>" to get table schema',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of results to return',
+      },
+    },
+    required: ['query'],
+  },
+}
+
+/**
+ * Fetch tool definition
+ */
+export const fetchTool: Tool = {
+  name: 'fetch',
+  description:
+    'Fetch a specific resource from the database. Format: "table/id" or "schema/table/column"',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      resource: {
+        type: 'string',
+        description:
+          'Resource identifier. Format: "table/id" to get a row, or "schema/table" for table schema',
+      },
+    },
+    required: ['resource'],
+  },
+}
+
+/**
+ * Do tool definition
+ */
+export const doTool: Tool = {
+  name: 'do',
+  description: `Execute TypeScript/JavaScript code with access to the PostgreSQL database via the 'pg' binding.
+
+Available APIs:
+${PG_BINDING_TYPES}`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      code: {
+        type: 'string',
+        description: 'TypeScript/JavaScript code to execute',
+      },
+    },
+    required: ['code'],
+  },
+}
+
+/**
+ * Create the search tool handler
+ */
+export function createSearchHandler(
+  executor: QueryExecutor
+): (input: SearchInput) => Promise<ToolResponse> {
+  return async (input: SearchInput): Promise<ToolResponse> => {
+    try {
+      const { query, limit = 100 } = input
+
+      // Handle special commands
+      if (query.toLowerCase() === 'tables') {
+        const result = await executor.rpcQuery(`
+          SELECT
+            table_name as name,
+            table_schema as schema,
+            table_type as type
+          FROM information_schema.tables
+          WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
+          ORDER BY table_schema, table_name
+          LIMIT $1
+        `, [limit])
+
+        const results: MCPSearchResult[] = result.rows.map((row) => ({
+          id: `${row.schema}.${row.name}`,
+          title: row.name as string,
+          snippet: `${row.type} in schema ${row.schema}`,
+          metadata: { schema: row.schema, type: row.type },
+        }))
+
+        return {
+          content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+        }
+      }
+
+      // Handle schema introspection: "schema:tablename"
+      if (query.toLowerCase().startsWith('schema:')) {
+        const tableName = query.slice(7).trim()
+
+        // Validate table name
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) {
+          return {
+            content: [{ type: 'text', text: JSON.stringify({ error: 'Invalid table name' }) }],
+            isError: true,
+          }
+        }
+
+        const result = await executor.rpcQuery(
+          `
+          SELECT
+            column_name as name,
+            data_type as type,
+            is_nullable,
+            column_default
+          FROM information_schema.columns
+          WHERE table_name = $1
+            AND table_schema NOT IN ('pg_catalog', 'information_schema')
+          ORDER BY ordinal_position
+        `,
+          [tableName]
+        )
+
+        const results: MCPSearchResult[] = result.rows.map((row) => ({
+          id: `${tableName}.${row.name}`,
+          title: row.name as string,
+          snippet: `${row.type}${row.is_nullable === 'NO' ? ' NOT NULL' : ''}${row.column_default ? ` DEFAULT ${row.column_default}` : ''}`,
+          metadata: {
+            table: tableName,
+            type: row.type,
+            nullable: row.is_nullable === 'YES',
+            default: row.column_default,
+          },
+        }))
+
+        return {
+          content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+        }
+      }
+
+      // Execute SQL query
+      // Add LIMIT if not present and query is a SELECT
+      let sql = query.trim()
+      const isSelect = sql.toLowerCase().startsWith('select')
+
+      if (isSelect && !sql.toLowerCase().includes('limit')) {
+        sql = `${sql} LIMIT ${limit}`
+      }
+
+      const result = await executor.rpcQuery(sql)
+
+      const results: MCPSearchResult[] = result.rows.map((row, index) => {
+        // Try to find an id-like field
+        const idField = Object.keys(row).find(
+          (k) => k === 'id' || k.endsWith('_id') || k === 'uuid'
+        )
+        const id = idField ? String(row[idField]) : String(index)
+
+        // Create a title from the first non-id field
+        const titleField = Object.keys(row).find(
+          (k) => k !== idField && typeof row[k] === 'string'
+        )
+        const title = titleField ? String(row[titleField]) : `Row ${index + 1}`
+
+        return {
+          id,
+          title,
+          snippet: JSON.stringify(row),
+          metadata: row as Record<string, unknown>,
+        }
+      })
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error'
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
+        isError: true,
+      }
+    }
+  }
+}
+
+/**
+ * Create the fetch tool handler
+ */
+export function createFetchHandler(
+  executor: QueryExecutor
+): (input: FetchInput) => Promise<ToolResponse> {
+  return async (input: FetchInput): Promise<ToolResponse> => {
+    try {
+      const { resource } = input
+      const parts = resource.split('/')
+
+      // Handle schema fetch: "schema/tablename"
+      if (parts[0].toLowerCase() === 'schema' && parts.length === 2) {
+        const tableName = parts[1]
+
+        // Validate table name
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) {
+          return {
+            content: [{ type: 'text', text: JSON.stringify({ error: 'Invalid table name' }) }],
+            isError: true,
+          }
+        }
+
+        const result = await executor.rpcQuery(
+          `
+          SELECT
+            column_name as name,
+            data_type as type,
+            is_nullable = 'YES' as nullable,
+            column_default as "default"
+          FROM information_schema.columns
+          WHERE table_name = $1
+            AND table_schema NOT IN ('pg_catalog', 'information_schema')
+          ORDER BY ordinal_position
+        `,
+          [tableName]
+        )
+
+        const fetchResult: MCPFetchResult = {
+          content: JSON.stringify(result.rows, null, 2),
+          contentType: 'application/json',
+          metadata: {
+            table: tableName,
+            columnCount: result.rows.length,
+          },
+        }
+
+        return {
+          content: [{ type: 'text', text: JSON.stringify(fetchResult, null, 2) }],
+        }
+      }
+
+      // Handle row fetch: "tablename/id"
+      if (parts.length === 2) {
+        const [tableName, id] = parts
+
+        // Validate table name
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) {
+          return {
+            content: [{ type: 'text', text: JSON.stringify({ error: 'Invalid table name' }) }],
+            isError: true,
+          }
+        }
+
+        // Try to find the primary key column
+        const pkResult = await executor.rpcQuery(
+          `
+          SELECT kcu.column_name
+          FROM information_schema.key_column_usage kcu
+          JOIN information_schema.table_constraints tc
+            ON kcu.constraint_name = tc.constraint_name
+          WHERE tc.constraint_type = 'PRIMARY KEY'
+            AND kcu.table_name = $1
+          LIMIT 1
+        `,
+          [tableName]
+        )
+
+        const pkColumn =
+          pkResult.rows.length > 0 ? (pkResult.rows[0].column_name as string) : 'id'
+
+        // Fetch the row
+        const result = await executor.rpcQuery(
+          `SELECT * FROM "${tableName}" WHERE "${pkColumn}" = $1 LIMIT 1`,
+          [id]
+        )
+
+        if (result.rows.length === 0) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify({ error: `Row not found: ${resource}` }),
+              },
+            ],
+            isError: true,
+          }
+        }
+
+        const fetchResult: MCPFetchResult = {
+          content: JSON.stringify(result.rows[0], null, 2),
+          contentType: 'application/json',
+          metadata: {
+            table: tableName,
+            primaryKey: pkColumn,
+            id,
+          },
+        }
+
+        return {
+          content: [{ type: 'text', text: JSON.stringify(fetchResult, null, 2) }],
+        }
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              error:
+                'Invalid resource format. Use "table/id" for rows or "schema/table" for schema',
+            }),
+          },
+        ],
+        isError: true,
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error'
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
+        isError: true,
+      }
+    }
+  }
+}
+
+/**
+ * Create the do tool handler
+ */
+export function createDoHandler(
+  executor: QueryExecutor,
+  options: { timeout?: number; authContext?: MCPAuthContext } = {}
+): (input: DoInput) => Promise<ToolResponse> {
+  const { timeout = 5000 } = options
+
+  return async (input: DoInput): Promise<ToolResponse> => {
+    const startTime = Date.now()
+    const logs: Array<[string, string]> = []
+
+    try {
+      const { code } = input
+
+      // Create the pg binding
+      const pg = createPGBinding(executor)
+
+      // Create sandbox console that captures logs
+      const sandboxConsole = {
+        log: (...args: unknown[]) => logs.push(['log', args.map(String).join(' ')]),
+        error: (...args: unknown[]) => logs.push(['error', args.map(String).join(' ')]),
+        warn: (...args: unknown[]) => logs.push(['warn', args.map(String).join(' ')]),
+        info: (...args: unknown[]) => logs.push(['info', args.map(String).join(' ')]),
+      }
+
+      // Create and execute function with sandbox
+      // Note: In production, use ai-evaluate for proper V8 isolation
+      const fn = new Function('pg', 'console', `
+        return (async () => {
+          ${code}
+        })()
+      `)
+
+      // Execute with timeout
+      const result = await Promise.race([
+        fn(pg, sandboxConsole),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error('Execution timeout')), timeout)
+        ),
+      ])
+
+      const duration = Date.now() - startTime
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                success: true,
+                value: result,
+                logs: logs.map(([level, msg]) => ({ level, message: msg })),
+                duration,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      }
+    } catch (error) {
+      const duration = Date.now() - startTime
+      const message = error instanceof Error ? error.message : 'Unknown error'
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                success: false,
+                error: message,
+                logs: logs.map(([level, msg]) => ({ level, message: msg })),
+                duration,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+        isError: true,
+      }
+    }
+  }
+}
+
+/**
+ * Get all tool definitions
+ */
+export function getToolDefinitions(): Tool[] {
+  return [searchTool, fetchTool, doTool]
+}
+
+/**
+ * Create all tool handlers
+ */
+export function createToolHandlers(
+  executor: QueryExecutor,
+  options: { timeout?: number; authContext?: MCPAuthContext } = {}
+): Record<string, (input: unknown) => Promise<ToolResponse>> {
+  return {
+    search: createSearchHandler(executor) as (input: unknown) => Promise<ToolResponse>,
+    fetch: createFetchHandler(executor) as (input: unknown) => Promise<ToolResponse>,
+    do: createDoHandler(executor, options) as (input: unknown) => Promise<ToolResponse>,
+  }
+}

package/src/mcp/types.ts

@@ -0,0 +1,148 @@
+/**
+ * MCP Server Types for PostgresDO
+ *
+ * Type definitions for the MCP (Model Context Protocol) server implementation.
+ */
+
+/**
+ * Query result from pg.query()
+ */
+export interface QueryResult<T = Record<string, unknown>> {
+  rows: T[]
+  rowCount: number
+  fields: Array<{
+    name: string
+    dataTypeID: number
+  }>
+}
+
+/**
+ * Table information from pg.tables()
+ */
+export interface TableInfo {
+  name: string
+  schema: string
+  type: 'table' | 'view' | 'materialized_view'
+  rowCount?: number
+}
+
+/**
+ * Column schema from pg.schema()
+ */
+export interface ColumnInfo {
+  name: string
+  type: string
+  nullable: boolean
+  default?: string
+  primaryKey: boolean
+}
+
+/**
+ * Search result for MCP search tool
+ */
+export interface MCPSearchResult {
+  id: string
+  title: string
+  snippet?: string
+  score?: number
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Fetch result for MCP fetch tool
+ */
+export interface MCPFetchResult {
+  content: string
+  contentType?: string
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * The pg binding exposed to the do tool
+ */
+export interface PGBinding {
+  /**
+   * Execute a SQL query with optional parameters
+   */
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResult<T>>
+
+  /**
+   * Execute a SQL statement (INSERT, UPDATE, DELETE)
+   */
+  execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }>
+
+  /**
+   * Execute multiple statements in a transaction
+   */
+  transaction<T>(fn: (tx: PGTransaction) => Promise<T>): Promise<T>
+
+  /**
+   * List all tables in the database
+   */
+  tables(): Promise<TableInfo[]>
+
+  /**
+   * Get schema information for a table
+   */
+  schema(tableName: string): Promise<ColumnInfo[]>
+}
+
+/**
+ * Transaction context for pg.transaction()
+ */
+export interface PGTransaction {
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResult<T>>
+  execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }>
+}
+
+/**
+ * MCP tool response format
+ */
+export interface ToolResponse {
+  content: Array<{ type: string; text: string }>
+  isError?: boolean
+}
+
+/**
+ * Search tool input
+ */
+export interface SearchInput {
+  query: string
+  limit?: number
+}
+
+/**
+ * Fetch tool input
+ */
+export interface FetchInput {
+  resource: string
+}
+
+/**
+ * Do tool input
+ */
+export interface DoInput {
+  code: string
+}
+
+/**
+ * Auth context from oauth.do JWT
+ */
+export interface MCPAuthContext {
+  userId: string
+  email?: string
+  scopes?: string[]
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * MCP Server configuration
+ */
+export interface MCPServerConfig {
+  /** Database ID for the PostgresDO instance */
+  databaseId: string
+  /** Optional auth context from JWT */
+  authContext?: MCPAuthContext
+  /** Timeout for code execution in ms (default: 5000) */
+  timeout?: number
+}