@revealui/mcp 0.0.1-pre.0 → 0.1.0

package/src/adapters/db.ts

@@ -0,0 +1,180 @@
+/**
+ * DB adapter for MCP.
+ * - `connectPglite()` initializes ElectricSQL/pglite client with CRDT metadata.
+ * - `connectPostgres()` creates a standard Postgres client with Electric metadata.
+ * - `createMcpDbClient()` factory that selects adapter based on config.
+ *
+ * Uses @revealui/contracts as the single source of truth for CRDT operation types.
+ */
+
+import { mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import getMcpConfig from '@revealui/config/mcp'
+import type { CrdtOperationsInsert, CrdtOperationsRow } from '@revealui/contracts'
+import { getSSLConfig } from '@revealui/core/database/ssl-config'
+
+export interface QueryResult<T = Record<string, unknown>> {
+  rows: T[]
+  affectedRows?: number
+}
+
+export type McpDbClient = {
+  query: <T = Record<string, unknown>>(sql: string, params?: unknown[]) => Promise<QueryResult<T>>
+  close: () => Promise<void>
+}
+
+/** Re-export contracts CRDT types for consumers */
+export type { CrdtOperationsRow, CrdtOperationsInsert }
+
+// Type for PGlite instance (minimal interface to avoid import issues)
+interface PGliteInstance {
+  waitReady: Promise<void>
+  query<T = Record<string, unknown>>(
+    sql: string,
+    params?: unknown[],
+  ): Promise<{ rows: T[]; affectedRows?: number }>
+  exec(query: string): Promise<unknown>
+  close(): Promise<void>
+}
+
+// CRDT operations table schema for conflict-free replication
+const CRDT_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS crdt_operations (
+    id TEXT PRIMARY KEY,
+    document_id TEXT NOT NULL,
+    operation_type TEXT NOT NULL,
+    payload JSONB NOT NULL,
+    vector_clock JSONB NOT NULL,
+    node_id TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    applied_at TIMESTAMPTZ
+  );
+  CREATE INDEX IF NOT EXISTS idx_crdt_ops_document ON crdt_operations(document_id);
+  CREATE INDEX IF NOT EXISTS idx_crdt_ops_node ON crdt_operations(node_id);
+  CREATE INDEX IF NOT EXISTS idx_crdt_ops_created ON crdt_operations(created_at DESC);
+`
+
+/**
+ * Connect to PGlite (embedded PostgreSQL) for local development/testing.
+ * Uses dynamic import to avoid bundling @electric-sql/pglite when not needed.
+ *
+ * @param options - Optional connection options
+ * @param options.dataDir - Override the default data directory. Use ':memory:' for in-memory.
+ */
+export async function connectPglite(options?: { dataDir?: string }): Promise<McpDbClient> {
+  const cfg = getMcpConfig()
+
+  // Determine data directory from options, config, or default
+  // Use ':memory:' for in-memory database (useful for testing)
+  const dataDir = options?.dataDir || cfg.electricDatabaseUrl || '.revealui/mcp/pglite'
+
+  let db: PGliteInstance
+
+  try {
+    // Ensure directory exists if not in-memory
+    if (dataDir !== ':memory:') {
+      await mkdir(dirname(dataDir), { recursive: true })
+    }
+
+    const { PGlite } = await import('@electric-sql/pglite')
+    db = new PGlite(dataDir) as PGliteInstance
+    await db.waitReady
+  } catch (error) {
+    const err = error as Error
+    if (err.message?.includes('Cannot find module') || err.message?.includes('MODULE_NOT_FOUND')) {
+      throw new Error(
+        '@electric-sql/pglite is not installed. Run: pnpm add -D @electric-sql/pglite',
+      )
+    }
+    throw error
+  }
+
+  // Create CRDT operations table
+  await db.exec(CRDT_TABLE_SQL)
+
+  return {
+    async query<T = Record<string, unknown>>(
+      sql: string,
+      params?: unknown[],
+    ): Promise<QueryResult<T>> {
+      const result = await db.query(sql, params)
+      return {
+        rows: result.rows as T[],
+        affectedRows: result.affectedRows,
+      }
+    },
+    async close(): Promise<void> {
+      await db.close()
+    },
+  }
+}
+
+/**
+ * Connect to PostgreSQL for production use.
+ * Supports Neon, Supabase, and generic PostgreSQL with SSL.
+ */
+export async function connectPostgres(): Promise<McpDbClient> {
+  const cfg = getMcpConfig()
+
+  const connectionString =
+    cfg.electricDatabaseUrl ||
+    process.env.DATABASE_URL ||
+    process.env.POSTGRES_URL ||
+    process.env.SUPABASE_DATABASE_URI
+
+  if (!connectionString) {
+    throw new Error(
+      'Database connection string not found. Set ELECTRIC_DATABASE_URL, DATABASE_URL, POSTGRES_URL, or SUPABASE_DATABASE_URI.',
+    )
+  }
+
+  const { Pool } = await import('pg')
+  const pool = new Pool({
+    connectionString,
+    ssl: getSSLConfig(connectionString),
+  })
+
+  // Test connection
+  const client = await pool.connect()
+  try {
+    await client.query('SELECT 1')
+  } finally {
+    client.release()
+  }
+
+  // Create CRDT operations table
+  await pool.query(CRDT_TABLE_SQL)
+
+  return {
+    async query<T = Record<string, unknown>>(
+      sql: string,
+      params?: unknown[],
+    ): Promise<QueryResult<T>> {
+      const result = await pool.query(sql, params)
+      return {
+        rows: result.rows as T[],
+        affectedRows: result.rowCount ?? undefined,
+      }
+    },
+    async close(): Promise<void> {
+      await pool.end()
+    },
+  }
+}
+
+/**
+ * Factory function that creates an MCP database client based on configuration.
+ * Reads `persistenceDriver` from getMcpConfig() to determine which adapter to use.
+ */
+export async function createMcpDbClient(): Promise<McpDbClient> {
+  const cfg = getMcpConfig()
+
+  if (cfg.persistenceDriver === 'postgres') {
+    return connectPostgres()
+  }
+
+  // Default to pglite for local development
+  return connectPglite()
+}
+
+export default { connectPglite, connectPostgres, createMcpDbClient }

package/src/config/config.json

@@ -0,0 +1,49 @@
+{
+  "_comment": "MCP server configuration. This config is synchronized with .cursor/mcp-config.json (source of truth). All 6 servers are included for consistency.",
+  "_source_of_truth": ".cursor/mcp-config.json",
+  "_last_synced": "2025-01",
+  "mcpServers": {
+    "vercel": {
+      "command": "pnpm",
+      "args": ["mcp:vercel"],
+      "env": {
+        "VERCEL_API_KEY": "${VERCEL_API_KEY}",
+        "VERCEL_TOKEN": "${VERCEL_TOKEN}"
+      }
+    },
+    "stripe": {
+      "command": "pnpm",
+      "args": ["mcp:stripe"],
+      "env": {
+        "STRIPE_SECRET_KEY": "${STRIPE_SECRET_KEY}"
+      }
+    },
+    "neon": {
+      "command": "pnpm",
+      "args": ["mcp:neon"],
+      "env": {
+        "NEON_API_KEY": "${NEON_API_KEY}"
+      }
+    },
+    "supabase": {
+      "command": "pnpm",
+      "args": ["mcp:supabase"],
+      "env": {
+        "SUPABASE_URL": "${SUPABASE_URL}",
+        "SUPABASE_ANON_KEY": "${SUPABASE_ANON_KEY}",
+        "SUPABASE_SERVICE_ROLE_KEY": "${SUPABASE_SERVICE_ROLE_KEY}"
+      }
+    },
+    "playwright": {
+      "command": "pnpm",
+      "args": ["mcp:playwright"]
+    },
+    "next-devtools": {
+      "command": "pnpm",
+      "args": ["mcp:next-devtools"],
+      "env": {
+        "NEXT_TELEMETRY_DISABLED": "${NEXT_TELEMETRY_DISABLED:-0}"
+      }
+    }
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,30 @@
+export type McpMetricsMode = 'logs' | 'otel' | 'prometheus'
+
+export interface McpConfig {
+  persistenceDriver: 'pglite' | 'postgres'
+  electricDatabaseUrl: string | null
+  electricApiKey: string | null
+  metricsMode: McpMetricsMode
+  pgvectorEnabled: boolean
+}
+
+function boolFromEnv(v: string | undefined, fallback = false) {
+  if (v === undefined) return fallback
+  return ['1', 'true', 'yes'].includes(v.toLowerCase())
+}
+
+export function getMcpConfig(): McpConfig {
+  const persistenceDriver =
+    (process.env.MCP_PERSISTENCE_DRIVER as 'pglite' | 'postgres') || 'pglite'
+  const metricsMode = (process.env.MCP_METRICS_MODE as McpMetricsMode) || 'logs'
+
+  return {
+    persistenceDriver,
+    electricDatabaseUrl: process.env.ELECTRIC_DATABASE_URL || null,
+    electricApiKey: process.env.ELECTRIC_API_KEY || null,
+    metricsMode,
+    pgvectorEnabled: boolFromEnv(process.env.PGVECTOR_ENABLED, false),
+  }
+}
+
+export default getMcpConfig

package/src/contracts.ts

@@ -0,0 +1,221 @@
+/**
+ * MCP Contracts
+ *
+ * Zod schemas for MCP-specific types, built on top of @revealui/contracts.
+ * These provide runtime validation for MCP request/response payloads
+ * and bridge MCP SDK tool definitions to contracts ToolDefinition.
+ */
+
+import {
+  type A2AAgentCard,
+  type A2AAuth,
+  type AgentDefinition,
+  agentDefinitionToCard,
+  type ToolDefinition,
+  ToolDefinitionSchema,
+  type ToolParameter,
+  z,
+} from '@revealui/contracts'
+
+// =============================================================================
+// MCP Request / Response Schemas
+// =============================================================================
+
+/**
+ * Schema for MCP request options (idempotency, retry, dry-run)
+ */
+export const MCPRequestOptionsSchema = z.object({
+  timeout: z.number().positive().optional(),
+  retries: z.number().int().nonnegative().optional(),
+  dryRun: z.boolean().optional(),
+  idempotencyKey: z.string().optional(),
+  idempotencyTTL: z.number().positive().optional(),
+})
+
+export type MCPRequestOptions = z.infer<typeof MCPRequestOptionsSchema>
+
+/**
+ * Schema for an MCP request payload
+ */
+export const MCPRequestSchema = z.object({
+  action: z.string().min(1),
+  parameters: z.record(z.string(), z.unknown()).optional(),
+  options: MCPRequestOptionsSchema.optional(),
+})
+
+export type MCPRequest = z.infer<typeof MCPRequestSchema>
+
+/**
+ * Schema for MCP response metadata
+ */
+export const MCPResponseMetadataSchema = z.object({
+  duration: z.number().nonnegative(),
+  retries: z.number().int().nonnegative(),
+  service: z.string(),
+  cached: z.boolean().optional(),
+  idempotencyKey: z.string().optional(),
+})
+
+export type MCPResponseMetadata = z.infer<typeof MCPResponseMetadataSchema>
+
+/**
+ * Schema for an MCP response payload
+ */
+export const MCPResponseSchema = z.object({
+  success: z.boolean(),
+  data: z.unknown().optional(),
+  error: z.string().optional(),
+  metadata: MCPResponseMetadataSchema.optional(),
+})
+
+export type MCPResponse = z.infer<typeof MCPResponseSchema>
+
+/**
+ * Schema for MCP adapter configuration
+ */
+export const MCPAdapterConfigSchema = z.object({
+  apiKey: z.string().optional(),
+  baseUrl: z.string().url().optional(),
+  timeout: z.number().positive().optional(),
+  retries: z.number().int().nonnegative().optional(),
+  environment: z.enum(['development', 'production']).optional(),
+})
+
+export type MCPAdapterConfig = z.infer<typeof MCPAdapterConfigSchema>
+
+// =============================================================================
+// Tool Definition Bridge
+// =============================================================================
+
+/**
+ * Converts an MCP SDK tool definition (JSON Schema-based) to a contracts ToolDefinition.
+ *
+ * The MCP SDK uses JSON Schema for tool `inputSchema`, while contracts uses
+ * a structured ToolParameter format. This bridge maps between them.
+ */
+export function mcpToolToContractsToolDefinition(mcpTool: {
+  name: string
+  description?: string
+  inputSchema?: {
+    type: string
+    properties?: Record<
+      string,
+      { type?: string; description?: string; default?: unknown; enum?: string[] }
+    >
+    required?: string[]
+  }
+}): ToolDefinition {
+  const parameters: Record<string, ToolParameter> = {}
+
+  if (mcpTool.inputSchema?.properties) {
+    const required = new Set(mcpTool.inputSchema.required ?? [])
+
+    for (const [key, prop] of Object.entries(mcpTool.inputSchema.properties)) {
+      parameters[key] = {
+        type: (prop.type as ToolParameter['type']) ?? 'string',
+        description: prop.description ?? '',
+        required: required.has(key),
+        ...(prop.default !== undefined && { default: prop.default }),
+        ...(prop.enum && { enum: prop.enum }),
+      }
+    }
+  }
+
+  return ToolDefinitionSchema.parse({
+    name: mcpTool.name,
+    description: mcpTool.description ?? `MCP tool: ${mcpTool.name}`,
+    parameters,
+    destructive: false,
+  })
+}
+
+/**
+ * Converts a contracts ToolDefinition back to an MCP SDK-compatible tool shape.
+ * Useful for registering contracts-defined tools with MCP servers.
+ */
+export function contractsToolDefinitionToMcpTool(tool: ToolDefinition): {
+  name: string
+  description: string
+  inputSchema: {
+    type: 'object'
+    properties: Record<
+      string,
+      { type: string; description: string; default?: unknown; enum?: string[] }
+    >
+    required: string[]
+  }
+} {
+  const properties: Record<
+    string,
+    { type: string; description: string; default?: unknown; enum?: string[] }
+  > = {}
+  const required: string[] = []
+
+  for (const [key, param] of Object.entries(tool.parameters)) {
+    properties[key] = {
+      type: param.type,
+      description: param.description,
+      ...(param.default !== undefined && { default: param.default }),
+      ...(param.enum && { enum: param.enum }),
+    }
+
+    if (param.required) {
+      required.push(key)
+    }
+  }
+
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: {
+      type: 'object',
+      properties,
+      required,
+    },
+  }
+}
+
+// =============================================================================
+// Agent Card Bridge
+// =============================================================================
+
+/**
+ * Converts a RevealUI AgentDefinition to a Google A2A AgentCard.
+ * Wraps the contracts-level `agentDefinitionToCard` with optional MCP-specific overrides.
+ *
+ * @param agent - The agent definition (source of truth)
+ * @param baseUrl - The server base URL (e.g. https://api.revealui.com)
+ * @param opts - Optional overrides for auth scheme and streaming capability
+ */
+export function agentDefinitionToAgentCard(
+  agent: AgentDefinition,
+  baseUrl: string,
+  opts?: { authScheme?: A2AAuth; streaming?: boolean },
+): A2AAgentCard {
+  const card = agentDefinitionToCard(agent, baseUrl)
+  if (!opts) return card
+
+  const { authScheme, streaming } = opts
+  return {
+    ...card,
+    ...(authScheme !== undefined && { authentication: authScheme }),
+    capabilities: {
+      ...(card.capabilities ?? {
+        streaming: false,
+        pushNotifications: false,
+        stateTransitionHistory: false,
+      }),
+      streaming: streaming ?? card.capabilities?.streaming ?? false,
+    },
+  }
+}
+
+/**
+ * Converts all tools in a RevealUI AgentDefinition to MCP tool specs.
+ * Uses `contractsToolDefinitionToMcpTool` for each tool.
+ */
+export function agentDefinitionToMcpTools(
+  agent: AgentDefinition,
+): ReturnType<typeof contractsToolDefinitionToMcpTool>[] {
+  return agent.tools.map(contractsToolDefinitionToMcpTool)
+}