@dotdo/postgres 0.1.1 → 0.1.3

package/src/mcp/index.ts

@@ -0,0 +1,122 @@
+/**
+ * MCP Server Module for PostgresDO
+ *
+ * Provides MCP (Model Context Protocol) server implementation for PostgreSQL
+ * databases running in Cloudflare Durable Objects.
+ *
+ * ## Overview
+ *
+ * This module implements the three core MCP primitives:
+ *
+ * 1. **search** - Query the database with SQL, list tables, or get schema
+ * 2. **fetch** - Get a specific row by table/id or table schema
+ * 3. **do** - Execute code with the `pg` binding for full database access
+ *
+ * ## Usage
+ *
+ * @example Basic MCP server setup
+ * ```typescript
+ * import { createMCPServer } from '@dotdo/postgres/mcp'
+ * import { PostgresDO } from '@dotdo/postgres/worker'
+ *
+ * // In your worker
+ * const stub = env.POSTGRES_DO.get(doId) as DurableObjectStub<PostgresDO>
+ * const mcpServer = createMCPServer(stub, { databaseId: 'mydb' })
+ *
+ * // Mount routes
+ * app.route('/mcp', mcpServer.routes())
+ * ```
+ *
+ * @example With auth context from oauth.do JWT
+ * ```typescript
+ * const mcpServer = createMCPServer(stub, {
+ *   databaseId: 'mydb',
+ *   authContext: {
+ *     userId: user.id,
+ *     email: user.email,
+ *     scopes: ['read', 'write'],
+ *   },
+ * })
+ * ```
+ *
+ * @example Using tools directly
+ * ```typescript
+ * // Search for tables
+ * const result = await mcpServer.handleRequest({
+ *   jsonrpc: '2.0',
+ *   id: 1,
+ *   method: 'tools/call',
+ *   params: {
+ *     name: 'search',
+ *     arguments: { query: 'tables' }
+ *   }
+ * })
+ *
+ * // Fetch a row
+ * const row = await mcpServer.handleRequest({
+ *   jsonrpc: '2.0',
+ *   id: 2,
+ *   method: 'tools/call',
+ *   params: {
+ *     name: 'fetch',
+ *     arguments: { resource: 'users/123' }
+ *   }
+ * })
+ *
+ * // Execute code
+ * const code = await mcpServer.handleRequest({
+ *   jsonrpc: '2.0',
+ *   id: 3,
+ *   method: 'tools/call',
+ *   params: {
+ *     name: 'do',
+ *     arguments: {
+ *       code: `
+ *         const users = await pg.query('SELECT * FROM users LIMIT 5')
+ *         return users.rows
+ *       `
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @module mcp
+ */
+
+// Types
+export type {
+  QueryResult,
+  TableInfo,
+  ColumnInfo,
+  MCPSearchResult,
+  MCPFetchResult,
+  PGBinding,
+  PGTransaction,
+  ToolResponse,
+  SearchInput,
+  FetchInput,
+  DoInput,
+  MCPAuthContext,
+  MCPServerConfig,
+} from './types.js'
+
+// Binding
+export { createPGBinding, PG_BINDING_TYPES } from './binding.js'
+export type { QueryExecutor } from './binding.js'
+
+// Tools
+export {
+  searchTool,
+  fetchTool,
+  doTool,
+  getToolDefinitions,
+  createToolHandlers,
+  createSearchHandler,
+  createFetchHandler,
+  createDoHandler,
+} from './tools.js'
+export type { Tool } from './tools.js'
+
+// Server
+export { createMCPServer, createMCPRoutes } from './server.js'
+export type { MCPServer } from './server.js'

package/src/mcp/server.ts

@@ -0,0 +1,361 @@
+/**
+ * MCP Server for PostgresDO
+ *
+ * Creates an MCP (Model Context Protocol) server that exposes PostgreSQL
+ * functionality through the search/fetch/do pattern.
+ */
+
+import { Hono } from 'hono'
+import type { Context as HonoContext } from 'hono'
+import type { MCPServerConfig, MCPAuthContext, ToolResponse } from './types.js'
+import type { QueryExecutor } from './binding.js'
+import {
+  getToolDefinitions,
+  createToolHandlers,
+} from './tools.js'
+
+/**
+ * MCP Protocol Message Types
+ */
+interface MCPMessage {
+  jsonrpc: '2.0'
+  id?: string | number
+  method?: string
+  params?: Record<string, unknown>
+  result?: unknown
+  error?: {
+    code: number
+    message: string
+    data?: unknown
+  }
+}
+
+/**
+ * MCP Server implementation
+ */
+export interface MCPServer {
+  /** Handle an MCP request */
+  handleRequest(request: MCPMessage): Promise<MCPMessage>
+  /** Get the Hono routes for HTTP transport */
+  routes(): Hono
+}
+
+/**
+ * MCP Error codes
+ */
+const MCP_ERRORS = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+} as const
+
+/**
+ * Create an MCP server for PostgresDO
+ *
+ * @param executor - Query executor (PostgresDO stub)
+ * @param config - Server configuration
+ * @returns MCP server instance
+ */
+export function createMCPServer(
+  executor: QueryExecutor,
+  config: MCPServerConfig = { databaseId: 'default' }
+): MCPServer {
+  const { timeout = 5000, authContext } = config
+  const handlers = createToolHandlers(executor, { timeout, authContext })
+  const tools = getToolDefinitions()
+
+  /**
+   * Handle tools/list request
+   */
+  function handleToolsList(): MCPMessage {
+    return {
+      jsonrpc: '2.0',
+      result: {
+        tools: tools.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        })),
+      },
+    }
+  }
+
+  /**
+   * Handle tools/call request
+   */
+  async function handleToolsCall(
+    params: Record<string, unknown>
+  ): Promise<MCPMessage> {
+    const toolName = params.name as string
+    const toolArgs = (params.arguments || {}) as Record<string, unknown>
+
+    const handler = handlers[toolName]
+    if (!handler) {
+      return {
+        jsonrpc: '2.0',
+        error: {
+          code: MCP_ERRORS.METHOD_NOT_FOUND,
+          message: `Unknown tool: ${toolName}`,
+        },
+      }
+    }
+
+    try {
+      const result = await handler(toolArgs)
+      return {
+        jsonrpc: '2.0',
+        result,
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error'
+      return {
+        jsonrpc: '2.0',
+        error: {
+          code: MCP_ERRORS.INTERNAL_ERROR,
+          message,
+        },
+      }
+    }
+  }
+
+  /**
+   * Handle initialize request
+   */
+  function handleInitialize(_params: Record<string, unknown>): MCPMessage {
+    return {
+      jsonrpc: '2.0',
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: {
+          tools: {},
+        },
+        serverInfo: {
+          name: 'postgres-mcp',
+          version: '0.1.0',
+        },
+      },
+    }
+  }
+
+  /**
+   * Handle ping request
+   */
+  function handlePing(): MCPMessage {
+    return {
+      jsonrpc: '2.0',
+      result: {},
+    }
+  }
+
+  /**
+   * Main request handler
+   */
+  async function handleRequest(request: MCPMessage): Promise<MCPMessage> {
+    const { method, params = {}, id } = request
+
+    let response: MCPMessage
+
+    switch (method) {
+      case 'initialize':
+        response = handleInitialize(params)
+        break
+      case 'ping':
+        response = handlePing()
+        break
+      case 'tools/list':
+        response = handleToolsList()
+        break
+      case 'tools/call':
+        response = await handleToolsCall(params)
+        break
+      default:
+        response = {
+          jsonrpc: '2.0',
+          error: {
+            code: MCP_ERRORS.METHOD_NOT_FOUND,
+            message: `Unknown method: ${method}`,
+          },
+        }
+    }
+
+    // Add request ID to response
+    if (id !== undefined) {
+      response.id = id
+    }
+
+    return response
+  }
+
+  /**
+   * Create Hono routes for HTTP transport
+   */
+  function routes(): Hono {
+    const app = new Hono()
+
+    // MCP protocol endpoint (JSON-RPC over HTTP)
+    app.post('/mcp', async (c) => {
+      try {
+        const request = await c.req.json<MCPMessage>()
+
+        if (request.jsonrpc !== '2.0') {
+          return c.json(
+            {
+              jsonrpc: '2.0',
+              error: {
+                code: MCP_ERRORS.INVALID_REQUEST,
+                message: 'Invalid JSON-RPC version',
+              },
+            },
+            400
+          )
+        }
+
+        const response = await handleRequest(request)
+        return c.json(response)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Parse error'
+        return c.json(
+          {
+            jsonrpc: '2.0',
+            error: {
+              code: MCP_ERRORS.PARSE_ERROR,
+              message,
+            },
+          },
+          400
+        )
+      }
+    })
+
+    // Well-known MCP discovery endpoint
+    app.get('/.well-known/mcp', (c) => {
+      return c.json({
+        name: 'postgres-mcp',
+        version: '0.1.0',
+        protocol_version: '2024-11-05',
+        capabilities: {
+          tools: true,
+        },
+        endpoints: {
+          mcp: '/mcp',
+          sse: '/mcp/sse',
+        },
+      })
+    })
+
+    // SSE endpoint for streaming transport
+    app.get('/mcp/sse', async (c) => {
+      // SSE transport - to be implemented
+      return c.text('SSE transport not yet implemented', 501)
+    })
+
+    // Direct tool endpoints for convenience
+    app.post('/mcp/search', async (c) => {
+      try {
+        const input = await c.req.json()
+        const result = await handlers.search(input)
+        return c.json(result)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error'
+        return c.json({ error: message }, 500)
+      }
+    })
+
+    app.post('/mcp/fetch', async (c) => {
+      try {
+        const input = await c.req.json()
+        const result = await handlers.fetch(input)
+        return c.json(result)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error'
+        return c.json({ error: message }, 500)
+      }
+    })
+
+    app.post('/mcp/do', async (c) => {
+      try {
+        const input = await c.req.json()
+        const result = await handlers.do(input)
+        return c.json(result)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error'
+        return c.json({ error: message }, 500)
+      }
+    })
+
+    // Tool definitions endpoint
+    app.get('/mcp/tools', (c) => {
+      return c.json({
+        tools: tools.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        })),
+      })
+    })
+
+    // Health check
+    app.get('/mcp/health', (c) => {
+      return c.json({
+        status: 'healthy',
+        server: 'postgres-mcp',
+        version: '0.1.0',
+        timestamp: new Date().toISOString(),
+      })
+    })
+
+    return app
+  }
+
+  return {
+    handleRequest,
+    routes,
+  }
+}
+
+/**
+ * Variables stored in Hono context for MCP routes
+ */
+interface MCPVariables {
+  mcpServer: MCPServer
+}
+
+/**
+ * Create MCP routes for integration with PostgresDO worker
+ */
+export function createMCPRoutes(
+  getExecutor: (c: HonoContext) => QueryExecutor,
+  getConfig?: (c: HonoContext) => MCPServerConfig
+): Hono<{ Variables: MCPVariables }> {
+  const app = new Hono<{ Variables: MCPVariables }>()
+
+  // Middleware to create MCP server per request
+  app.use('*', async (c, next) => {
+    const executor = getExecutor(c as unknown as HonoContext)
+    const config = getConfig?.(c as unknown as HonoContext) || { databaseId: 'default' }
+    const mcpServer = createMCPServer(executor, config)
+
+    // Store in context
+    c.set('mcpServer', mcpServer)
+
+    await next()
+  })
+
+  // Forward to MCP server routes
+  app.all('*', async (c) => {
+    const mcpServer = c.get('mcpServer')
+    const routes = mcpServer.routes()
+    return routes.fetch(c.req.raw)
+  })
+
+  return app
+}
+
+/**
+ * Re-export types and tools
+ */
+export { getToolDefinitions, createToolHandlers }
+export type { Tool } from './tools.js'
+export type { MCPServerConfig, MCPAuthContext, ToolResponse }