@onmars/lunar-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 onMars Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @onmars/lunar-mcp
+
+MCP (Model Context Protocol) client for [Lunar](https://github.com/onmars-tech/lunar).
+
+This package is used internally by `@onmars/lunar-cli`. Install the CLI instead:
+
+```bash
+bun install -g @onmars/lunar-cli
+```
+
+## License
+
+MIT — [onMars Tech](https://github.com/onmars-tech)

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@onmars/lunar-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": ["src/", "LICENSE"],
+  "dependencies": {
+    "@onmars/lunar-core": "0.1.0"
+  },
+  "description": "MCP (Model Context Protocol) client for Lunar",
+  "author": "onMars Tech",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/onmars-tech/lunar",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/onmars-tech/lunar",
+  "bugs": "https://github.com/onmars-tech/lunar/issues",
+  "keywords": ["lunar", "mcp", "model-context-protocol", "bun"],
+  "publishConfig": {
+  "access": "public"
+},
+"engines": {
+"bun": ">=1.2"
+}
+}

package/src/__tests__/connection.test.ts

@@ -0,0 +1,351 @@
+/**
+ * MCPConnection + MCPRegistry test suite
+ *
+ * Mocks node:child_process.spawn to avoid spawning real subprocesses.
+ * The mock process implements the MCP protocol in-memory:
+ *   stdin.write() → parse JSON-RPC → emit response on stdout
+ *
+ * This makes tests fast, deterministic, and environment-independent.
+ */
+
+import { afterEach, describe, expect, mock, test } from 'bun:test'
+import { EventEmitter } from 'node:events'
+
+// ── In-memory MCP protocol simulator ─────────────────────────────────────────
+
+function createMockProcess() {
+  const stdout = new EventEmitter()
+  const stderr = new EventEmitter()
+  const exitListeners: Array<(code: number | null, signal: string | null) => void> = []
+  let exited = false
+
+  function emitExit(code: number | null, signal: string | null) {
+    if (!exited) {
+      exited = true
+      for (const fn of exitListeners) fn(code, signal)
+    }
+  }
+
+  const stdin = {
+    writable: true,
+    write(data: string | Buffer): boolean {
+      const line = (typeof data === 'string' ? data : data.toString()).trim()
+      if (!line) return true
+
+      let msg: Record<string, unknown>
+      try {
+        msg = JSON.parse(line)
+      } catch {
+        return true
+      }
+
+      // Notifications have no id — no response needed
+      if (!('id' in msg)) return true
+
+      const id = msg.id
+      const method = msg.method as string
+      const params = msg.params as Record<string, unknown> | undefined
+
+      let result: unknown
+      let error: { code: number; message: string } | undefined
+
+      if (method === 'initialize') {
+        result = {
+          protocolVersion: '2025-11-25',
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: 'mock-engram', version: '0.1.0' },
+        }
+      } else if (method === 'tools/list') {
+        result = {
+          tools: [
+            {
+              name: 'mem_search',
+              description: 'Search persistent memory',
+              inputSchema: {
+                type: 'object',
+                properties: { query: { type: 'string' }, limit: { type: 'number' } },
+                required: ['query'],
+              },
+            },
+            {
+              name: 'mem_save',
+              description: 'Save a memory observation',
+              inputSchema: {
+                type: 'object',
+                properties: { title: { type: 'string' }, content: { type: 'string' } },
+                required: ['title', 'content'],
+              },
+            },
+            {
+              name: 'mem_context',
+              description: 'Get recent context',
+              inputSchema: {
+                type: 'object',
+                properties: { project: { type: 'string' } },
+              },
+            },
+          ],
+        }
+      } else if (method === 'tools/call') {
+        const name = (params as any)?.name as string
+        if (name === 'mem_search') {
+          result = {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify([
+                  { id: 1, title: 'Auth middleware', content: 'JWT-based auth', score: 0.9 },
+                  { id: 2, title: 'Database schema', content: 'PostgreSQL setup', score: 0.7 },
+                ]),
+              },
+            ],
+          }
+        } else if (name === 'mem_save') {
+          result = {
+            content: [{ type: 'text', text: JSON.stringify({ id: 42, status: 'saved' }) }],
+          }
+        } else if (name === 'mem_context') {
+          result = {
+            content: [{ type: 'text', text: 'Session 2026-02-28: Worked on MCP integration' }],
+          }
+        } else {
+          error = { code: -32601, message: `Unknown tool: ${name}` }
+        }
+      } else if (method === 'ping') {
+        result = {}
+      } else {
+        error = { code: -32601, message: `Method not found: ${method}` }
+      }
+
+      // Respond asynchronously (realistic: network/process I/O is async)
+      setImmediate(() => {
+        const resp = error
+          ? JSON.stringify({ jsonrpc: '2.0', id, error })
+          : JSON.stringify({ jsonrpc: '2.0', id, result })
+        stdout.emit('data', Buffer.from(resp + '\n'))
+      })
+
+      return true
+    },
+    end() {
+      stdin.writable = false
+      setImmediate(() => emitExit(0, null))
+    },
+  }
+
+  return {
+    stdin,
+    stdout,
+    stderr,
+    pid: 12345,
+    on(event: string, listener: (...args: unknown[]) => void) {
+      if (event === 'exit') exitListeners.push(listener as any)
+      return this
+    },
+    kill(signal = 'SIGKILL') {
+      stdin.writable = false
+      setImmediate(() => emitExit(null, signal))
+      return true
+    },
+  }
+}
+
+// Mock spawn before any imports of modules that use it.
+// Bun hoists mock.module() calls above static imports (same as jest.mock hoisting).
+mock.module('node:child_process', () => ({
+  spawn: mock((_cmd: string, _args: string[], _opts: unknown) => createMockProcess()),
+}))
+
+import { MCPConnection } from '../lib/connection'
+import { MCPRegistry } from '../lib/registry'
+
+function mockConfig(id = 'test', overrides: Record<string, unknown> = {}) {
+  return {
+    id,
+    command: 'mock-mcp-server',
+    timeoutMs: 5000,
+    autoRestart: false,
+    ...overrides,
+  }
+}
+
+// ═══════════════════════════════════════════════════════════
+// MCPConnection
+// ═══════════════════════════════════════════════════════════
+
+describe('MCPConnection', () => {
+  let conn: MCPConnection | null = null
+
+  afterEach(async () => {
+    if (conn) {
+      conn.kill()
+      conn = null
+    }
+  })
+
+  test('connects and performs MCP handshake', async () => {
+    conn = new MCPConnection(mockConfig())
+    await conn.connect()
+    expect(conn.state).toBe('ready')
+    expect(conn.serverInfo?.name).toBe('mock-engram')
+    expect(conn.serverInfo?.version).toBe('0.1.0')
+  })
+
+  test('discovers tools after handshake', async () => {
+    conn = new MCPConnection(mockConfig())
+    await conn.connect()
+    expect(conn.tools.length).toBe(3)
+    expect(conn.tools.map((t) => t.name)).toEqual(['mem_search', 'mem_save', 'mem_context'])
+  })
+
+  test('hasTool returns true for existing tools', async () => {
+    conn = new MCPConnection(mockConfig())
+    await conn.connect()
+    expect(conn.hasTool('mem_search')).toBe(true)
+    expect(conn.hasTool('nonexistent')).toBe(false)
+  })
+
+  test('callTool executes a tool and returns result', async () => {
+    conn = new MCPConnection(mockConfig())
+    await conn.connect()
+    const result = await conn.callTool('mem_search', { query: 'auth' })
+    expect(result.content).toBeDefined()
+    expect(result.content[0].type).toBe('text')
+    const parsed = JSON.parse(result.content[0].text!)
+    expect(parsed).toHaveLength(2)
+    expect(parsed[0].title).toBe('Auth middleware')
+  })
+
+  test('callTool for mem_save returns saved status', async () => {
+    conn = new MCPConnection(mockConfig())
+    await conn.connect()
+    const result = await conn.callTool('mem_save', { title: 'Test', content: 'Content' })
+    const parsed = JSON.parse(result.content[0].text!)
+    expect(parsed.status).toBe('saved')
+    expect(parsed.id).toBe(42)
+  })
+
+  test('callTool throws when not connected', async () => {
+    conn = new MCPConnection(mockConfig())
+    // Don't call connect() — should reject immediately
+    await expect(conn.callTool('mem_search', { query: 'test' })).rejects.toThrow('not ready')
+  })
+
+  test('disconnect gracefully shuts down', async () => {
+    conn = new MCPConnection(mockConfig())
+    await conn.connect()
+    expect(conn.state).toBe('ready')
+    await conn.disconnect()
+    expect(conn.state).toBe('disconnected')
+    conn = null
+  })
+
+  test('tools returns a copy (immutable)', async () => {
+    conn = new MCPConnection(mockConfig())
+    await conn.connect()
+    const tools1 = conn.tools
+    const tools2 = conn.tools
+    expect(tools1).toEqual(tools2)
+    expect(tools1).not.toBe(tools2)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════
+// MCPRegistry
+// ═══════════════════════════════════════════════════════════
+
+describe('MCPRegistry', () => {
+  let registry: MCPRegistry | null = null
+
+  afterEach(async () => {
+    if (registry) {
+      await registry.disconnectAll()
+      registry = null
+    }
+  })
+
+  test('connects and registers a server', async () => {
+    registry = new MCPRegistry()
+    await registry.connect(mockConfig('server1'))
+    const status = registry.status()
+    expect(status).toHaveLength(1)
+    expect(status[0].id).toBe('server1')
+    expect(status[0].state).toBe('ready')
+    expect(status[0].serverName).toBe('mock-engram')
+    expect(status[0].toolCount).toBe(3)
+  })
+
+  test('lists tools from all connected servers', async () => {
+    registry = new MCPRegistry()
+    await registry.connect(mockConfig('server1'))
+    const tools = registry.listTools()
+    expect(tools.length).toBe(3)
+    expect(tools[0].serverId).toBe('server1')
+  })
+
+  test('connects multiple servers simultaneously', async () => {
+    registry = new MCPRegistry()
+    await registry.connect(mockConfig('server1'))
+    await registry.connect(mockConfig('server2'))
+    const status = registry.status()
+    expect(status).toHaveLength(2)
+    const tools = registry.listTools()
+    expect(tools.length).toBe(6)
+  })
+
+  test('routes callTool to the correct server', async () => {
+    registry = new MCPRegistry()
+    await registry.connect(mockConfig('server1'))
+    const result = await registry.callTool('mem_search', { query: 'test' })
+    expect(result).toBeDefined()
+  })
+
+  test('callTool throws for unknown tool', async () => {
+    registry = new MCPRegistry()
+    await registry.connect(mockConfig('server1'))
+    await expect(registry.callTool('nonexistent_tool')).rejects.toThrow('not found')
+  })
+
+  test('throws on duplicate connection id', async () => {
+    registry = new MCPRegistry()
+    await registry.connect(mockConfig('server1'))
+    await expect(registry.connect(mockConfig('server1'))).rejects.toThrow('already exists')
+  })
+
+  test('disconnect removes server and its tools', async () => {
+    registry = new MCPRegistry()
+    await registry.connect(mockConfig('server1'))
+    expect(registry.listTools().length).toBe(3)
+    await registry.disconnect('server1')
+    expect(registry.status()).toHaveLength(0)
+    expect(registry.listTools().length).toBe(0)
+  })
+
+  test('getByRole filters connections', async () => {
+    registry = new MCPRegistry()
+    await registry.connect(mockConfig('mem1', { role: 'memory' }))
+    await registry.connect(mockConfig('tool1', { role: 'tools' }))
+    const memoryConns = registry.getByRole('memory')
+    expect(memoryConns).toHaveLength(1)
+    expect(memoryConns[0].id).toBe('mem1')
+    const toolConns = registry.getByRole('tools')
+    expect(toolConns).toHaveLength(1)
+    expect(toolConns[0].id).toBe('tool1')
+  })
+
+  test('disconnectAll shuts down everything', async () => {
+    registry = new MCPRegistry()
+    await registry.connect(mockConfig('server1'))
+    await registry.connect(mockConfig('server2'))
+    await registry.disconnectAll()
+    expect(registry.status()).toHaveLength(0)
+    registry = null
+  })
+
+  test('get returns connection by id', async () => {
+    registry = new MCPRegistry()
+    await registry.connect(mockConfig('server1'))
+    expect(registry.get('server1')).toBeDefined()
+    expect(registry.get('nonexistent')).toBeUndefined()
+  })
+})

package/src/__tests__/mock-mcp-server.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * Mock MCP server for testing.
+ * Implements the minimum MCP protocol over stdio.
+ * Responds to: initialize, tools/list, tools/call
+ */
+
+import * as readline from 'node:readline'
+
+const TOOLS = [
+  {
+    name: 'mem_search',
+    description: 'Search persistent memory',
+    inputSchema: {
+      type: 'object' as const,
+      properties: { query: { type: 'string' }, limit: { type: 'number' } },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'mem_save',
+    description: 'Save a memory observation',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        title: { type: 'string' },
+        content: { type: 'string' },
+        type: { type: 'string' },
+      },
+      required: ['title', 'content'],
+    },
+  },
+  {
+    name: 'mem_context',
+    description: 'Get recent context',
+    inputSchema: {
+      type: 'object' as const,
+      properties: { project: { type: 'string' } },
+    },
+  },
+]
+
+function respond(id: number | string, result: unknown) {
+  const msg = JSON.stringify({ jsonrpc: '2.0', id, result })
+  process.stdout.write(msg + '\n')
+}
+
+function respondError(id: number | string, code: number, message: string) {
+  const msg = JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } })
+  process.stdout.write(msg + '\n')
+}
+
+const rl = readline.createInterface({ input: process.stdin })
+
+rl.on('line', (line) => {
+  try {
+    const msg = JSON.parse(line.trim())
+
+    if (msg.method === 'initialize') {
+      respond(msg.id, {
+        protocolVersion: '2025-11-25',
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'mock-engram', version: '0.1.0' },
+      })
+      return
+    }
+
+    if (msg.method === 'notifications/initialized') {
+      // Notification — no response needed
+      return
+    }
+
+    if (msg.method === 'tools/list') {
+      respond(msg.id, { tools: TOOLS })
+      return
+    }
+
+    if (msg.method === 'tools/call') {
+      const { name, arguments: args } = msg.params
+
+      if (name === 'mem_search') {
+        respond(msg.id, {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify([
+                { id: 1, title: 'Auth middleware', content: 'JWT-based auth', score: 0.9 },
+                { id: 2, title: 'Database schema', content: 'PostgreSQL setup', score: 0.7 },
+              ]),
+            },
+          ],
+        })
+        return
+      }
+
+      if (name === 'mem_save') {
+        respond(msg.id, {
+          content: [{ type: 'text', text: JSON.stringify({ id: 42, status: 'saved' }) }],
+        })
+        return
+      }
+
+      if (name === 'mem_context') {
+        respond(msg.id, {
+          content: [{ type: 'text', text: 'Session 2026-02-28: Worked on MCP integration' }],
+        })
+        return
+      }
+
+      if (name === 'mem_session_start') {
+        respond(msg.id, {
+          content: [{ type: 'text', text: JSON.stringify({ status: 'started', id: args.id }) }],
+        })
+        return
+      }
+
+      if (name === 'mem_session_end') {
+        respond(msg.id, {
+          content: [{ type: 'text', text: JSON.stringify({ status: 'ended' }) }],
+        })
+        return
+      }
+
+      if (name === 'mem_session_summary') {
+        respond(msg.id, {
+          content: [{ type: 'text', text: JSON.stringify({ status: 'saved' }) }],
+        })
+        return
+      }
+
+      respondError(msg.id, -32601, `Unknown tool: ${name}`)
+      return
+    }
+
+    if (msg.method === 'ping') {
+      respond(msg.id, {})
+      return
+    }
+
+    // Unknown method
+    if (msg.id) {
+      respondError(msg.id, -32601, `Method not found: ${msg.method}`)
+    }
+  } catch {
+    // Ignore parse errors
+  }
+})

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * @onmars/lunar-mcp — MCP client for the Lunar framework
+ *
+ * Manages multiple MCP server connections via stdio transport.
+ * Provides tool discovery, routing, and memory provider adapters.
+ *
+ * @example
+ * ```typescript
+ * import { MCPRegistry } from '@onmars/lunar-mcp'
+ *
+ * const registry = new MCPRegistry()
+ *
+ * // Connect to Engram
+ * await registry.connect({
+ *   id: 'engram',
+ *   command: 'engram mcp',
+ *   role: 'memory',
+ * })
+ *
+ * // List all tools
+ * const tools = registry.listTools()
+ *
+ * // Call a tool (auto-routes to correct server)
+ * await registry.callTool('mem_search', { query: 'auth middleware' })
+ * ```
+ */
+
+// Core
+export { type ConnectionState, MCPConnection } from './lib/connection'
+export { type MCPConnectionStatus, MCPRegistry } from './lib/registry'
+
+// Types
+export type {
+  ClientCapabilities,
+  ClientInfo,
+  InitializeParams,
+  InitializeResult,
+  JsonRpcError,
+  JsonRpcMessage,
+  JsonRpcNotification,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  MCPServerConfig,
+  MCPTool,
+  ServerCapabilities,
+  ServerInfo,
+  ToolCallParams,
+  ToolCallResult,
+  ToolContent,
+  ToolsListResult,
+} from './lib/types'
+
+export { JSON_RPC_ERRORS } from './lib/types'

package/src/lib/connection.ts

@@ -0,0 +1,344 @@
+/**
+ * MCPConnection — Single connection to an MCP server via stdio
+ *
+ * Manages:
+ * - Subprocess lifecycle (spawn, restart, shutdown)
+ * - JSON-RPC 2.0 protocol over stdin/stdout
+ * - MCP handshake (initialize → initialized)
+ * - Tool discovery and invocation
+ * - Request/response correlation via message IDs
+ * - Newline-delimited JSON framing
+ *
+ * Each MCPConnection wraps exactly one subprocess running an MCP server.
+ * The MCPRegistry manages multiple connections.
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process'
+import { EventEmitter } from 'node:events'
+import type {
+  InitializeResult,
+  JsonRpcNotification,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  MCPServerConfig,
+  MCPTool,
+  ServerCapabilities,
+  ServerInfo,
+  ToolCallResult,
+} from './types'
+
+export type ConnectionState = 'disconnected' | 'connecting' | 'ready' | 'error'
+
+export class MCPConnection extends EventEmitter {
+  readonly id: string
+  private config: MCPServerConfig
+  private process: ChildProcess | null = null
+  private nextId = 1
+  private pending = new Map<
+    number | string,
+    {
+      resolve: (value: unknown) => void
+      reject: (error: Error) => void
+      timer: ReturnType<typeof setTimeout>
+    }
+  >()
+  private buffer = ''
+  private _state: ConnectionState = 'disconnected'
+  private _tools: MCPTool[] = []
+  private _serverInfo: ServerInfo | null = null
+  private _capabilities: ServerCapabilities | null = null
+
+  get state(): ConnectionState {
+    return this._state
+  }
+  get tools(): MCPTool[] {
+    return [...this._tools]
+  }
+  get serverInfo(): ServerInfo | null {
+    return this._serverInfo
+  }
+  get capabilities(): ServerCapabilities | null {
+    return this._capabilities
+  }
+
+  constructor(config: MCPServerConfig) {
+    super()
+    this.id = config.id
+    this.config = config
+  }
+
+  /**
+   * Spawn the MCP server subprocess and perform the MCP handshake.
+   * After this resolves, the connection is ready for tool calls.
+   */
+  async connect(): Promise<void> {
+    if (this._state === 'ready') return
+    this._state = 'connecting'
+
+    try {
+      // 1. Spawn subprocess
+      const [cmd, ...defaultArgs] = this.config.command.split(' ')
+      const args = [...defaultArgs, ...(this.config.args || [])]
+
+      try {
+        this.process = spawn(cmd, args, {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          cwd: this.config.cwd,
+          env: { ...process.env, ...this.config.env },
+        })
+      } catch (spawnError) {
+        this._state = 'error'
+        throw spawnError
+      }
+
+      // Handle subprocess events
+      this.process.on('exit', (code, signal) => {
+        this._state = 'disconnected'
+        this.rejectAllPending(new Error(`MCP server exited (code=${code}, signal=${signal})`))
+        this.emit('exit', { code, signal })
+      })
+
+      this.process.on('error', (err) => {
+        this._state = 'error'
+        this.rejectAllPending(err)
+        this.emit('error', err)
+      })
+
+      // stderr → log (MCP servers may emit logs on stderr)
+      this.process.stderr?.on('data', (chunk: Buffer) => {
+        this.emit('log', chunk.toString())
+      })
+
+      // stdout → JSON-RPC message parsing
+      this.process.stdout?.on('data', (chunk: Buffer) => {
+        this.buffer += chunk.toString()
+        this.processBuffer()
+      })
+
+      // 2. MCP handshake: initialize
+      const initResult = (await this.request(
+        'initialize',
+        {
+          protocolVersion: '2025-11-25',
+          capabilities: {},
+          clientInfo: {
+            name: 'lunar',
+            version: '0.2.0',
+          },
+        },
+        this.config.timeoutMs || 10000,
+      )) as InitializeResult
+
+      this._serverInfo = initResult.serverInfo
+      this._capabilities = initResult.capabilities
+
+      // 3. Send initialized notification
+      this.notify('notifications/initialized')
+
+      // 4. Discover tools
+      if (initResult.capabilities?.tools) {
+        const toolsResult = (await this.request('tools/list', {})) as { tools: MCPTool[] }
+        this._tools = toolsResult.tools || []
+      }
+
+      this._state = 'ready'
+      this.emit('ready', {
+        serverInfo: this._serverInfo,
+        tools: this._tools.length,
+      })
+    } catch (err) {
+      this._state = 'error'
+      this.kill()
+      throw err
+    }
+  }
+
+  /**
+   * Call an MCP tool by name. Returns the tool result.
+   */
+  async callTool(name: string, args?: Record<string, unknown>): Promise<ToolCallResult> {
+    if (this._state !== 'ready') {
+      throw new Error(`MCP connection "${this.id}" is not ready (state: ${this._state})`)
+    }
+    return this.request('tools/call', {
+      name,
+      arguments: args || {},
+    }) as Promise<ToolCallResult>
+  }
+
+  /**
+   * Check if this connection has a specific tool.
+   */
+  hasTool(name: string): boolean {
+    return this._tools.some((t) => t.name === name)
+  }
+
+  /**
+   * Send a JSON-RPC request and wait for the response.
+   */
+  private request(
+    method: string,
+    params: Record<string, unknown>,
+    timeoutMs = 30000,
+  ): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const id = this.nextId++
+
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error(`MCP request "${method}" timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+
+      this.pending.set(id, { resolve, reject, timer })
+
+      const message: JsonRpcRequest = {
+        jsonrpc: '2.0',
+        id,
+        method,
+        params,
+      }
+
+      this.send(message)
+    })
+  }
+
+  /**
+   * Send a JSON-RPC notification (no response expected).
+   */
+  private notify(method: string, params?: Record<string, unknown>): void {
+    const message: JsonRpcNotification = {
+      jsonrpc: '2.0',
+      method,
+      ...(params && { params }),
+    }
+    this.send(message)
+  }
+
+  /**
+   * Write a JSON-RPC message to the subprocess stdin.
+   * MCP uses newline-delimited JSON over stdio.
+   */
+  private send(message: JsonRpcRequest | JsonRpcNotification): void {
+    if (!this.process?.stdin?.writable) {
+      throw new Error(`MCP connection "${this.id}" stdin not writable`)
+    }
+    const json = JSON.stringify(message)
+    this.process.stdin.write(json + '\n')
+  }
+
+  /**
+   * Process buffered stdout data, extracting complete JSON-RPC messages.
+   * MCP uses newline-delimited JSON (one message per line).
+   */
+  private processBuffer(): void {
+    const lines = this.buffer.split('\n')
+    // Keep the last incomplete line in the buffer
+    this.buffer = lines.pop() || ''
+
+    for (const line of lines) {
+      const trimmed = line.trim()
+      if (!trimmed) continue
+
+      try {
+        const message = JSON.parse(trimmed)
+        this.handleMessage(message)
+      } catch {
+        // Non-JSON output (e.g., startup messages) — ignore
+        this.emit('log', `[non-json] ${trimmed}`)
+      }
+    }
+  }
+
+  /**
+   * Handle an incoming JSON-RPC message (response or server notification).
+   */
+  private handleMessage(message: JsonRpcResponse | JsonRpcNotification): void {
+    // Response to a pending request
+    if ('id' in message && message.id != null) {
+      const pending = this.pending.get(message.id)
+      if (pending) {
+        this.pending.delete(message.id)
+        clearTimeout(pending.timer)
+
+        if (message.error) {
+          pending.reject(new Error(`MCP error [${message.error.code}]: ${message.error.message}`))
+        } else {
+          pending.resolve(message.result)
+        }
+      }
+      return
+    }
+
+    // Server-initiated notification
+    if ('method' in message) {
+      this.emit('notification', {
+        method: message.method,
+        params: message.params,
+      })
+    }
+  }
+
+  /**
+   * Reject all pending requests (used on disconnect/error).
+   */
+  private rejectAllPending(error: Error): void {
+    for (const [id, pending] of this.pending) {
+      clearTimeout(pending.timer)
+      pending.reject(error)
+    }
+    this.pending.clear()
+  }
+
+  /**
+   * Graceful shutdown: close stdin, wait, SIGTERM, SIGKILL.
+   */
+  async disconnect(): Promise<void> {
+    if (!this.process) return
+
+    return new Promise<void>((resolve) => {
+      const proc = this.process!
+      let resolved = false
+
+      const done = () => {
+        if (!resolved) {
+          resolved = true
+          this.process = null
+          this._state = 'disconnected'
+          this._tools = []
+          resolve()
+        }
+      }
+
+      proc.on('exit', done)
+
+      // Step 1: Close stdin
+      proc.stdin?.end()
+
+      // Step 2: SIGTERM after 2s
+      setTimeout(() => {
+        if (!resolved) proc.kill('SIGTERM')
+      }, 2000)
+
+      // Step 3: SIGKILL after 5s
+      setTimeout(() => {
+        if (!resolved) {
+          proc.kill('SIGKILL')
+          done()
+        }
+      }, 5000)
+    })
+  }
+
+  /**
+   * Force kill the subprocess immediately.
+   */
+  kill(): void {
+    if (this.process) {
+      this.process.kill('SIGKILL')
+      this.process = null
+      this._state = 'disconnected'
+      this._tools = []
+      this.rejectAllPending(new Error('Connection killed'))
+    }
+  }
+}

package/src/lib/registry.ts

@@ -0,0 +1,212 @@
+/**
+ * MCPRegistry — Manages multiple MCP server connections
+ *
+ * Features:
+ * - Connect/disconnect multiple MCP servers
+ * - Aggregate tools from all connections
+ * - Route tool calls to the correct server
+ * - Filter connections by role (memory, tools, both)
+ * - Health check all connections
+ * - Graceful shutdown of all connections
+ */
+
+import { EventEmitter } from 'node:events'
+import { type ConnectionState, MCPConnection } from './connection'
+import type { MCPServerConfig, MCPTool } from './types'
+
+export interface MCPConnectionStatus {
+  id: string
+  state: ConnectionState
+  serverName?: string
+  serverVersion?: string
+  toolCount: number
+  role: string
+}
+
+export class MCPRegistry extends EventEmitter {
+  private connections = new Map<string, MCPConnection>()
+  private configs = new Map<string, MCPServerConfig>()
+  /** Maps tool name → connection id for routing */
+  private toolIndex = new Map<string, string>()
+
+  /**
+   * Connect to an MCP server. Spawns the subprocess and performs handshake.
+   *
+   * @throws if connection fails (timeout, crash, handshake error)
+   */
+  async connect(config: MCPServerConfig): Promise<MCPConnection> {
+    if (this.connections.has(config.id)) {
+      throw new Error(`MCP connection "${config.id}" already exists`)
+    }
+
+    const conn = new MCPConnection(config)
+    this.connections.set(config.id, conn)
+    this.configs.set(config.id, config)
+
+    // Forward events
+    conn.on('ready', (info) => this.emit('server:ready', { id: config.id, ...info }))
+    conn.on('exit', (info) => {
+      this.emit('server:exit', { id: config.id, ...info })
+      this.removeToolsForConnection(config.id)
+
+      // Auto-restart if configured
+      if (config.autoRestart !== false) {
+        this.emit('server:restarting', { id: config.id })
+        setTimeout(() => this.reconnect(config.id).catch(() => {}), 2000)
+      }
+    })
+    conn.on('error', (err) => this.emit('server:error', { id: config.id, error: err }))
+
+    await conn.connect()
+
+    // Index tools for routing
+    for (const tool of conn.tools) {
+      this.toolIndex.set(tool.name, config.id)
+    }
+
+    return conn
+  }
+
+  /**
+   * Disconnect and remove an MCP server.
+   */
+  async disconnect(id: string): Promise<void> {
+    const conn = this.connections.get(id)
+    if (!conn) return
+
+    this.removeToolsForConnection(id)
+    await conn.disconnect()
+    this.connections.delete(id)
+    this.configs.delete(id)
+  }
+
+  /**
+   * Reconnect a previously configured server.
+   */
+  private async reconnect(id: string): Promise<void> {
+    const config = this.configs.get(id)
+    if (!config) return
+
+    const existing = this.connections.get(id)
+    if (existing) {
+      existing.kill()
+      this.connections.delete(id)
+    }
+
+    const conn = new MCPConnection(config)
+    this.connections.set(id, conn)
+
+    conn.on('exit', (info) => {
+      this.emit('server:exit', { id, ...info })
+      this.removeToolsForConnection(id)
+    })
+
+    try {
+      await conn.connect()
+      for (const tool of conn.tools) {
+        this.toolIndex.set(tool.name, id)
+      }
+      this.emit('server:reconnected', { id })
+    } catch {
+      this.emit('server:reconnect-failed', { id })
+    }
+  }
+
+  /**
+   * Get a specific connection by ID.
+   */
+  get(id: string): MCPConnection | undefined {
+    return this.connections.get(id)
+  }
+
+  /**
+   * List all tools from all connected servers.
+   * Each tool includes which server it belongs to.
+   */
+  listTools(): Array<MCPTool & { serverId: string }> {
+    const tools: Array<MCPTool & { serverId: string }> = []
+    for (const [id, conn] of this.connections) {
+      if (conn.state !== 'ready') continue
+      for (const tool of conn.tools) {
+        tools.push({ ...tool, serverId: id })
+      }
+    }
+    return tools
+  }
+
+  /**
+   * Call a tool. Automatically routes to the correct MCP server.
+   *
+   * @throws if the tool is not found in any connected server
+   */
+  async callTool(name: string, args?: Record<string, unknown>): Promise<unknown> {
+    const connId = this.toolIndex.get(name)
+    if (!connId) {
+      throw new Error(`MCP tool "${name}" not found in any connected server`)
+    }
+
+    const conn = this.connections.get(connId)
+    if (!conn || conn.state !== 'ready') {
+      throw new Error(`MCP server "${connId}" not ready for tool "${name}"`)
+    }
+
+    const result = await conn.callTool(name, args)
+
+    // Extract text content for convenience
+    if (result.isError) {
+      const errorText = result.content
+        .filter((c) => c.type === 'text')
+        .map((c) => c.text)
+        .join('\n')
+      throw new Error(`MCP tool "${name}" error: ${errorText}`)
+    }
+
+    return result
+  }
+
+  /**
+   * Get connections with a specific role (for adapter creation).
+   */
+  getByRole(role: 'memory' | 'tools' | 'both'): MCPConnection[] {
+    const result: MCPConnection[] = []
+    for (const [id, conn] of this.connections) {
+      const config = this.configs.get(id)
+      if (!config) continue
+      if (config.role === role || config.role === 'both' || role === 'both') {
+        result.push(conn)
+      }
+    }
+    return result
+  }
+
+  /**
+   * Status of all connections.
+   */
+  status(): MCPConnectionStatus[] {
+    return Array.from(this.connections.entries()).map(([id, conn]) => ({
+      id,
+      state: conn.state,
+      serverName: conn.serverInfo?.name,
+      serverVersion: conn.serverInfo?.version,
+      toolCount: conn.tools.length,
+      role: this.configs.get(id)?.role || 'tools',
+    }))
+  }
+
+  /**
+   * Gracefully disconnect all servers.
+   */
+  async disconnectAll(): Promise<void> {
+    const promises = Array.from(this.connections.keys()).map((id) => this.disconnect(id))
+    await Promise.allSettled(promises)
+  }
+
+  /**
+   * Remove tool index entries for a disconnected server.
+   */
+  private removeToolsForConnection(id: string): void {
+    for (const [toolName, connId] of this.toolIndex) {
+      if (connId === id) this.toolIndex.delete(toolName)
+    }
+  }
+}

package/src/lib/types.ts

@@ -0,0 +1,147 @@
+/**
+ * MCP Protocol types — JSON-RPC 2.0 + MCP extensions
+ *
+ * Based on: https://modelcontextprotocol.io/specification/2025-11-25
+ * Protocol version: 2025-11-25
+ */
+
+// ════════════════════════════════════════════════════════════
+// JSON-RPC 2.0 base types
+// ════════════════════════════════════════════════════════════
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0'
+  id: number | string
+  method: string
+  params?: Record<string, unknown>
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0'
+  id: number | string
+  result?: unknown
+  error?: JsonRpcError
+}
+
+export interface JsonRpcNotification {
+  jsonrpc: '2.0'
+  method: string
+  params?: Record<string, unknown>
+}
+
+export interface JsonRpcError {
+  code: number
+  message: string
+  data?: unknown
+}
+
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | JsonRpcNotification
+
+// ════════════════════════════════════════════════════════════
+// MCP initialization
+// ════════════════════════════════════════════════════════════
+
+export interface ClientInfo {
+  name: string
+  version: string
+}
+
+export interface ServerInfo {
+  name: string
+  version: string
+}
+
+export interface ClientCapabilities {
+  roots?: { listChanged?: boolean }
+  sampling?: Record<string, unknown>
+}
+
+export interface ServerCapabilities {
+  tools?: { listChanged?: boolean }
+  resources?: { subscribe?: boolean; listChanged?: boolean }
+  prompts?: { listChanged?: boolean }
+  logging?: Record<string, unknown>
+}
+
+export interface InitializeParams {
+  protocolVersion: string
+  capabilities: ClientCapabilities
+  clientInfo: ClientInfo
+}
+
+export interface InitializeResult {
+  protocolVersion: string
+  capabilities: ServerCapabilities
+  serverInfo: ServerInfo
+  instructions?: string
+}
+
+// ════════════════════════════════════════════════════════════
+// MCP Tools
+// ════════════════════════════════════════════════════════════
+
+export interface MCPTool {
+  name: string
+  description?: string
+  inputSchema: {
+    type: 'object'
+    properties?: Record<string, unknown>
+    required?: string[]
+  }
+}
+
+export interface ToolsListResult {
+  tools: MCPTool[]
+}
+
+export interface ToolCallParams {
+  name: string
+  arguments?: Record<string, unknown>
+}
+
+export interface ToolContent {
+  type: 'text' | 'image' | 'resource'
+  text?: string
+  data?: string
+  mimeType?: string
+}
+
+export interface ToolCallResult {
+  content: ToolContent[]
+  isError?: boolean
+}
+
+// ════════════════════════════════════════════════════════════
+// MCP Connection config
+// ════════════════════════════════════════════════════════════
+
+export interface MCPServerConfig {
+  /** Unique identifier for this connection */
+  id: string
+  /** Command to spawn the MCP server */
+  command: string
+  /** Command arguments */
+  args?: string[]
+  /** Working directory for the subprocess */
+  cwd?: string
+  /** Environment variables for the subprocess */
+  env?: Record<string, string>
+  /** Role: 'memory' creates a MemoryProvider adapter, 'tools' exposes tools to agent */
+  role?: 'memory' | 'tools' | 'both'
+  /** Connection timeout in ms. Default: 10000 */
+  timeoutMs?: number
+  /** Auto-restart on crash. Default: true */
+  autoRestart?: boolean
+}
+
+// ════════════════════════════════════════════════════════════
+// Standard JSON-RPC error codes
+// ════════════════════════════════════════════════════════════
+
+export const JSON_RPC_ERRORS = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+} as const