@revealui/mcp 0.1.0 → 0.1.3

package/src/config/index.ts

@@ -1,30 +0,0 @@
-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

@@ -1,221 +0,0 @@
-/**
- * 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)
-}

package/src/hypervisor.ts

@@ -1,464 +0,0 @@
-/**
- * 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
-    }
-  }
-}