@revealui/mcp 0.0.1-pre.0 → 0.1.0

package/src/hypervisor.ts

@@ -0,0 +1,464 @@
+/**
+ * MCP Hypervisor
+ *
+ * Manages N running MCP server processes, pings them for liveness, and
+ * dynamically exposes their tools at runtime. Inspired by the
+ * MCPCompatibilityLayer/MCPHypervisor pattern from AnythingLLM.
+ *
+ * Architecture:
+ *   - Singleton: one hypervisor per process manages all MCP servers
+ *   - Each server is spawned with piped stdio for JSON-RPC communication
+ *   - Tool names are namespaced: @@mcp_{serverName}_{toolName}
+ *   - Health check loop: every 60s, process.exitCode check + tools/list probe
+ *
+ * Wire format: newline-delimited JSON-RPC 2.0 (stdin/stdout)
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process'
+import { registerCleanupHandler } from '@revealui/core/monitoring'
+import { logger } from '@revealui/core/observability/logger'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface MCPServerConfig {
+  /** Unique name for this server (used in tool namespacing) */
+  name: string
+  /** Executable to run (e.g. 'node', 'pnpm') */
+  command: string
+  /** Arguments to the command */
+  args: string[]
+  /** Additional environment variables */
+  env?: Record<string, string>
+}
+
+export interface MCPTool {
+  name: string
+  description: string
+  inputSchema: {
+    type: 'object'
+    properties?: Record<string, unknown>
+    required?: string[]
+  }
+}
+
+export interface NamespacedTool {
+  /** Namespaced name: @@mcp_{serverName}_{toolName} */
+  namespacedName: string
+  serverName: string
+  tool: MCPTool
+}
+
+interface ServerEntry {
+  config: MCPServerConfig
+  process: ChildProcess | null
+  tools: MCPTool[]
+  healthy: boolean
+  lastPingAt: number | null
+}
+
+interface JsonRpcRequest {
+  jsonrpc: '2.0'
+  id: number
+  method: string
+  params?: unknown
+}
+
+interface JsonRpcResponse {
+  jsonrpc: '2.0'
+  id: number
+  result?: unknown
+  error?: { code: number; message: string }
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const HEALTH_CHECK_INTERVAL_MS = 60_000
+const REQUEST_TIMEOUT_MS = 5_000
+const MCP_TOOL_PREFIX = '@@mcp'
+
+// =============================================================================
+// MCPHypervisor
+// =============================================================================
+
+/**
+ * Singleton that manages MCP server processes and their tool registries.
+ *
+ * @example
+ * ```typescript
+ * const hypervisor = MCPHypervisor.getInstance()
+ *
+ * hypervisor.registerServer({
+ *   name: 'stripe',
+ *   command: 'pnpm',
+ *   args: ['dlx', '@stripe/mcp', '--tools=all', '--api-key=sk_...'],
+ * })
+ *
+ * await hypervisor.startServer('stripe')
+ * const tools = hypervisor.getAllTools()
+ * // tools[0].namespacedName === '@@mcp_stripe_create_payment_intent'
+ * ```
+ */
+export class MCPHypervisor {
+  private static instance: MCPHypervisor | null = null
+
+  private servers: Map<string, ServerEntry> = new Map()
+  private requestCounter = 0
+  private pendingRequests: Map<
+    number,
+    { resolve: (value: unknown) => void; reject: (error: Error) => void; timer: NodeJS.Timeout }
+  > = new Map()
+  private healthCheckTimer: NodeJS.Timeout | null = null
+
+  private constructor() {
+    registerCleanupHandler(
+      'mcp-hypervisor',
+      async () => this.stopAll(),
+      'Stop all MCP server processes',
+      85,
+    )
+    this.startHealthCheckLoop()
+  }
+
+  static getInstance(): MCPHypervisor {
+    if (!MCPHypervisor.instance) {
+      MCPHypervisor.instance = new MCPHypervisor()
+    }
+    return MCPHypervisor.instance
+  }
+
+  // ---------------------------------------------------------------------------
+  // Server registration
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Register an MCP server configuration without starting it.
+   */
+  registerServer(config: MCPServerConfig): void {
+    if (this.servers.has(config.name)) {
+      logger.warn(`[MCPHypervisor] Server "${config.name}" is already registered`)
+      return
+    }
+    this.servers.set(config.name, {
+      config,
+      process: null,
+      tools: [],
+      healthy: false,
+      lastPingAt: null,
+    })
+    logger.info(`[MCPHypervisor] Registered server: ${config.name}`)
+  }
+
+  /**
+   * Unregister a server (stops it first if running).
+   */
+  async unregisterServer(name: string): Promise<void> {
+    const entry = this.servers.get(name)
+    if (!entry) return
+    if (entry.process) await this.stopServer(name)
+    this.servers.delete(name)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Spawn the MCP server process with piped stdio.
+   * Tools are discovered via `listServerTools()` after startup.
+   */
+  async startServer(name: string): Promise<void> {
+    const entry = this.servers.get(name)
+    if (!entry) throw new Error(`[MCPHypervisor] Unknown server: "${name}"`)
+    if (entry.process && entry.process.exitCode === null) {
+      logger.info(`[MCPHypervisor] Server "${name}" is already running`)
+      return
+    }
+
+    const { config } = entry
+    const child = spawn(config.command, config.args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, ...config.env },
+    })
+
+    entry.process = child
+    entry.healthy = false
+    entry.tools = []
+
+    // Buffer incoming stdout for JSON-RPC response parsing
+    let buffer = ''
+    child.stdout?.on('data', (chunk: Buffer) => {
+      buffer += chunk.toString()
+      const lines = buffer.split('\n')
+      buffer = lines.pop() ?? '' // keep incomplete line in buffer
+      for (const line of lines) {
+        const trimmed = line.trim()
+        if (!trimmed) continue
+        try {
+          const msg = JSON.parse(trimmed) as JsonRpcResponse
+          this.handleResponse(msg)
+        } catch {
+          // Non-JSON output from server — ignore
+        }
+      }
+    })
+
+    child.stderr?.on('data', (chunk: Buffer) => {
+      logger.warn(`[MCPHypervisor] ${name} stderr: ${chunk.toString().trim()}`)
+    })
+
+    child.on('exit', (code) => {
+      logger.warn(`[MCPHypervisor] Server "${name}" exited with code ${code}`)
+      entry.healthy = false
+      // Reject all pending requests for this server
+      for (const [id, pending] of this.pendingRequests) {
+        pending.reject(new Error(`Server "${name}" exited`))
+        clearTimeout(pending.timer)
+        this.pendingRequests.delete(id)
+      }
+    })
+
+    // Allow a brief startup window, then probe tools
+    await new Promise<void>((resolve) => setTimeout(resolve, 500))
+
+    try {
+      await this.listServerTools(name)
+      entry.healthy = true
+      logger.info(`[MCPHypervisor] Server "${name}" started (${entry.tools.length} tools)`)
+    } catch (error) {
+      logger.warn(
+        `[MCPHypervisor] Server "${name}" started but tool discovery failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      )
+      // Still mark healthy if the process is alive (tools may not be supported)
+      entry.healthy = entry.process.exitCode === null
+    }
+  }
+
+  /**
+   * Stop a running MCP server process.
+   */
+  async stopServer(name: string): Promise<void> {
+    const entry = this.servers.get(name)
+    if (!entry?.process) return
+
+    entry.process.kill('SIGTERM')
+    await new Promise<void>((resolve) => setTimeout(resolve, 200))
+
+    if (entry.process.exitCode === null) {
+      entry.process.kill('SIGKILL')
+    }
+
+    entry.process = null
+    entry.healthy = false
+    entry.tools = []
+    logger.info(`[MCPHypervisor] Stopped server: ${name}`)
+  }
+
+  /**
+   * Stop all running servers.
+   */
+  async stopAll(): Promise<void> {
+    this.stopHealthCheckLoop()
+    await Promise.all(Array.from(this.servers.keys()).map((name) => this.stopServer(name)))
+  }
+
+  // ---------------------------------------------------------------------------
+  // JSON-RPC communication
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Send a JSON-RPC request to a running server and await the response.
+   */
+  private sendRequest(name: string, method: string, params?: unknown): Promise<unknown> {
+    const entry = this.servers.get(name)
+    if (!entry?.process || entry.process.exitCode !== null) {
+      return Promise.reject(new Error(`Server "${name}" is not running`))
+    }
+
+    const id = ++this.requestCounter
+    const request: JsonRpcRequest = {
+      jsonrpc: '2.0',
+      id,
+      method,
+      ...(params !== undefined && { params }),
+    }
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(id)
+        reject(new Error(`Request ${method} timed out after ${REQUEST_TIMEOUT_MS}ms`))
+      }, REQUEST_TIMEOUT_MS)
+
+      this.pendingRequests.set(id, { resolve, reject, timer })
+
+      try {
+        entry.process?.stdin?.write(`${JSON.stringify(request)}\n`)
+      } catch (error) {
+        clearTimeout(timer)
+        this.pendingRequests.delete(id)
+        reject(error)
+      }
+    })
+  }
+
+  private handleResponse(msg: JsonRpcResponse): void {
+    const pending = this.pendingRequests.get(msg.id)
+    if (!pending) return
+
+    clearTimeout(pending.timer)
+    this.pendingRequests.delete(msg.id)
+
+    if (msg.error) {
+      pending.reject(new Error(`JSON-RPC error ${msg.error.code}: ${msg.error.message}`))
+    } else {
+      pending.resolve(msg.result)
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Health checks
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Ping a server — checks process liveness and sends a JSON-RPC `ping`.
+   * Updates `entry.healthy`.
+   */
+  async pingServer(name: string): Promise<boolean> {
+    const entry = this.servers.get(name)
+    if (!entry) return false
+
+    // Process liveness check
+    if (!entry.process || entry.process.exitCode !== null) {
+      entry.healthy = false
+      return false
+    }
+
+    entry.lastPingAt = Date.now()
+
+    try {
+      await this.sendRequest(name, 'ping')
+      entry.healthy = true
+      return true
+    } catch {
+      // ping not supported by all servers — still healthy if process is alive
+      entry.healthy = entry.process.exitCode === null
+      return entry.healthy
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tool discovery
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Discover tools from a running server via JSON-RPC `tools/list`.
+   * Caches the result in the server entry.
+   */
+  async listServerTools(name: string): Promise<MCPTool[]> {
+    const entry = this.servers.get(name)
+    if (!entry) throw new Error(`Unknown server: "${name}"`)
+
+    const result = await this.sendRequest(name, 'tools/list')
+
+    const tools = (result as { tools?: MCPTool[] })?.tools ?? []
+    entry.tools = tools
+    return tools
+  }
+
+  /**
+   * Return all tools from all healthy servers, namespaced as
+   * `@@mcp_{serverName}_{toolName}` to avoid collisions.
+   */
+  getAllTools(): NamespacedTool[] {
+    const tools: NamespacedTool[] = []
+
+    for (const [serverName, entry] of this.servers) {
+      if (!entry.healthy) continue
+
+      for (const tool of entry.tools) {
+        tools.push({
+          namespacedName: `${MCP_TOOL_PREFIX}_${serverName}_${tool.name}`,
+          serverName,
+          tool,
+        })
+      }
+    }
+
+    return tools
+  }
+
+  /**
+   * Call a tool on a running MCP server via JSON-RPC `tools/call`.
+   *
+   * @param serverName - The registered server name
+   * @param toolName - The tool name (without namespace prefix)
+   * @param args - Arguments to pass to the tool
+   */
+  async callTool(serverName: string, toolName: string, args: unknown): Promise<unknown> {
+    return this.sendRequest(serverName, 'tools/call', {
+      name: toolName,
+      arguments: args,
+    })
+  }
+
+  /**
+   * Return the health status of all registered servers.
+   */
+  getStatus(): Record<string, { healthy: boolean; toolCount: number; pid: number | null }> {
+    const status: Record<string, { healthy: boolean; toolCount: number; pid: number | null }> = {}
+    for (const [name, entry] of this.servers) {
+      status[name] = {
+        healthy: entry.healthy,
+        toolCount: entry.tools.length,
+        pid: entry.process?.pid ?? null,
+      }
+    }
+    return status
+  }
+
+  // ---------------------------------------------------------------------------
+  // Health check loop
+  // ---------------------------------------------------------------------------
+
+  private startHealthCheckLoop(): void {
+    this.healthCheckTimer = setInterval(async () => {
+      for (const [name] of this.servers) {
+        try {
+          await this.pingServer(name)
+        } catch {
+          // Already handled inside pingServer
+        }
+      }
+    }, HEALTH_CHECK_INTERVAL_MS)
+
+    // Don't prevent process exit
+    this.healthCheckTimer.unref?.()
+  }
+
+  private stopHealthCheckLoop(): void {
+    if (this.healthCheckTimer) {
+      clearInterval(this.healthCheckTimer)
+      this.healthCheckTimer = null
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Testing utilities
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Reset the singleton (for testing only).
+   * @internal
+   */
+  static _resetForTests(): void {
+    if (MCPHypervisor.instance) {
+      MCPHypervisor.instance.stopHealthCheckLoop()
+      MCPHypervisor.instance = null
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,87 @@
+/**
+ * @revealui/mcp
+ *
+ * Model Context Protocol integrations for RevealUI.
+ *
+ * Provides:
+ * - MCP adapter framework (Vercel, Stripe, Neon)
+ * - Database adapter (PGlite / PostgreSQL) with CRDT support
+ * - MCP contracts (Zod schemas for request/response/tool bridging)
+ * - MCP server launchers (code-validator, stripe, neon, etc.)
+ *
+ * @packageDocumentation
+ */
+
+import { isFeatureEnabled } from '@revealui/core/features'
+import { initializeLicense } from '@revealui/core/license'
+import { logger } from '@revealui/core/observability/logger'
+
+/**
+ * Check if the MCP package is licensed for use.
+ * Initializes the license cache from environment variables, then checks the tier.
+ * Returns false with a warning log if no Pro/Enterprise license is active.
+ */
+export async function checkMcpLicense(): Promise<boolean> {
+  await initializeLicense()
+  if (!isFeatureEnabled('mcp')) {
+    logger.warn(
+      '[@revealui/mcp] MCP server integration requires a Pro or Enterprise license. ' +
+        'Visit https://revealui.com/pricing for details.',
+    )
+    return false
+  }
+  return true
+}
+
+// Database adapter
+export {
+  type CrdtOperationsInsert,
+  type CrdtOperationsRow,
+  connectPglite,
+  connectPostgres,
+  createMcpDbClient,
+  type McpDbClient,
+  type QueryResult,
+} from './adapters/db.js'
+// Configuration
+export {
+  getMcpConfig,
+  type McpConfig as McpEnvConfig,
+  type McpMetricsMode,
+} from './config/index.js'
+// Contracts (Zod schemas + tool bridging)
+export {
+  agentDefinitionToAgentCard,
+  agentDefinitionToMcpTools,
+  contractsToolDefinitionToMcpTool,
+  type MCPAdapterConfig,
+  MCPAdapterConfigSchema,
+  type MCPRequest,
+  type MCPRequestOptions,
+  MCPRequestOptionsSchema,
+  MCPRequestSchema,
+  type MCPResponse,
+  type MCPResponseMetadata,
+  MCPResponseMetadataSchema,
+  MCPResponseSchema,
+  mcpToolToContractsToolDefinition,
+} from './contracts.js'
+// Hypervisor: process management + dynamic tool discovery
+export {
+  MCPHypervisor,
+  type MCPServerConfig,
+  type MCPTool,
+  type NamespacedTool,
+} from './hypervisor.js'
+// Adapter framework
+export {
+  createMCPAdapter,
+  disposeAllAdapters,
+  generateIdempotencyKey,
+  generateUniqueIdempotencyKey,
+  MCPAdapter,
+  type MCPConfig,
+  NeonAdapter,
+  StripeAdapter,
+  VercelAdapter,
+} from './servers/adapter.js'