autohand-cli 0.7.14 → 0.8.2

package/dist/chunk-S52YW5ZQ.js

@@ -0,0 +1,844 @@
+import {
+  buildNpxIsolatedCacheEnv,
+  isNpxCommand,
+  isRetriableNpxInstallError,
+  normalizeMcpCommandForSpawn
+} from "./chunk-WQ3VJXZB.js";
+
+// src/mcp/McpClientManager.ts
+import { spawn } from "child_process";
+import { EventEmitter } from "events";
+
+// src/mcp/types.ts
+var VALID_TRANSPORTS = ["stdio", "sse", "http"];
+function validateMcpServerConfig(config) {
+  if (!config.name || typeof config.name !== "string" || config.name.trim() === "") {
+    throw new Error('MCP server config requires a non-empty "name" field');
+  }
+  if (!VALID_TRANSPORTS.includes(config.transport)) {
+    throw new Error(
+      `MCP server config has invalid "transport" type: "${config.transport}". Must be one of: ${VALID_TRANSPORTS.join(", ")}`
+    );
+  }
+  if (config.transport === "stdio") {
+    if (!config.command || typeof config.command !== "string") {
+      throw new Error(
+        `MCP stdio server "${config.name}" requires a "command" field`
+      );
+    }
+  }
+  if (config.transport === "sse" || config.transport === "http") {
+    if (!config.url || typeof config.url !== "string") {
+      throw new Error(
+        `MCP ${config.transport} server "${config.name}" requires a "url" field`
+      );
+    }
+  }
+}
+function convertMcpToolToAutohand(mcpTool, serverName) {
+  const prefixedName = `mcp__${serverName}__${mcpTool.name}`;
+  return {
+    name: prefixedName,
+    description: mcpTool.description ?? "",
+    parameters: {
+      type: "object",
+      properties: mcpTool.inputSchema.properties ?? {},
+      ...mcpTool.inputSchema.required && mcpTool.inputSchema.required.length > 0 ? { required: mcpTool.inputSchema.required } : {}
+    },
+    serverName
+  };
+}
+
+// src/mcp/McpClientManager.ts
+var McpStdioConnection = class _McpStdioConnection extends EventEmitter {
+  constructor(config, framing) {
+    super();
+    this.config = config;
+    this.framing = framing;
+    this.process = null;
+    this.lineBuffer = "";
+    this.frameBuffer = Buffer.alloc(0);
+    this.nextId = 1;
+    this.pendingRequests = /* @__PURE__ */ new Map();
+  }
+  static {
+    /** Default timeout for RPC requests in milliseconds */
+    this.REQUEST_TIMEOUT_MS = 3e4;
+  }
+  /**
+   * Spawns the server process and sets up communication channels.
+   */
+  async start() {
+    if (!this.config.command) {
+      throw new Error(`Cannot start stdio connection: no command specified for server "${this.config.name}"`);
+    }
+    return new Promise((resolve, reject) => {
+      try {
+        const normalized = normalizeMcpCommandForSpawn(this.config.command, this.config.args);
+        this.process = spawn(normalized.command, normalized.args ?? [], {
+          stdio: ["pipe", "pipe", "pipe"],
+          env: {
+            ...process.env,
+            ...this.config.env
+          }
+        });
+        this.process.stdout?.on("data", (data) => {
+          this.handleStdoutData(data);
+        });
+        this.process.stderr?.on("data", (data) => {
+          this.emit("stderr", data.toString());
+        });
+        this.process.on("error", (err) => {
+          this.emit("error", err);
+          reject(err);
+        });
+        this.process.on("close", (code) => {
+          this.cleanup();
+          this.emit("close", code);
+        });
+        setTimeout(() => resolve(), 100);
+      } catch (err) {
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+  }
+  /**
+   * Sends a JSON-RPC 2.0 request and waits for the response.
+   */
+  async request(method, params) {
+    if (!this.process?.stdin?.writable) {
+      throw new Error(`MCP server "${this.config.name}" is not connected`);
+    }
+    const id = this.nextId++;
+    const request = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      ...params !== void 0 ? { params } : {}
+    };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`MCP request "${method}" timed out after ${_McpStdioConnection.REQUEST_TIMEOUT_MS}ms`));
+      }, _McpStdioConnection.REQUEST_TIMEOUT_MS);
+      this.pendingRequests.set(id, { resolve, reject, timer });
+      const message = this.serializeMessage(request);
+      this.process.stdin.write(message);
+    });
+  }
+  /**
+   * Sends a JSON-RPC 2.0 notification (no response expected).
+   */
+  notify(method, params) {
+    if (!this.process?.stdin?.writable) {
+      return;
+    }
+    const notification = {
+      jsonrpc: "2.0",
+      method,
+      ...params !== void 0 ? { params } : {}
+    };
+    const message = this.serializeMessage(notification);
+    this.process.stdin.write(message);
+  }
+  /**
+   * Stops the server process and cleans up resources.
+   */
+  async stop() {
+    if (this.process) {
+      this.process.stdin?.end();
+      this.process.kill("SIGTERM");
+      const forceKillTimer = setTimeout(() => {
+        if (this.process && !this.process.killed) {
+          this.process.kill("SIGKILL");
+        }
+      }, 5e3);
+      await new Promise((resolve) => {
+        if (this.process) {
+          this.process.on("close", () => {
+            clearTimeout(forceKillTimer);
+            resolve();
+          });
+        } else {
+          clearTimeout(forceKillTimer);
+          resolve();
+        }
+      });
+    }
+    this.cleanup();
+  }
+  /**
+   * Parses incoming stdout data as newline-delimited JSON-RPC messages.
+   */
+  handleStdoutData(data) {
+    if (this.framing === "newline") {
+      this.parseLineDelimitedData(data);
+      return;
+    }
+    this.parseContentLengthData(data);
+  }
+  /**
+   * Routes incoming JSON-RPC responses to their pending request handlers.
+   */
+  handleMessage(message) {
+    if (message.id !== void 0 && this.pendingRequests.has(message.id)) {
+      const pending = this.pendingRequests.get(message.id);
+      this.pendingRequests.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);
+      }
+    } else {
+      this.emit("notification", message);
+    }
+  }
+  /**
+   * Cleans up all pending requests and resets state.
+   */
+  cleanup() {
+    for (const [id, pending] of this.pendingRequests) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("MCP connection closed"));
+      this.pendingRequests.delete(id);
+    }
+    this.process = null;
+    this.lineBuffer = "";
+    this.frameBuffer = Buffer.alloc(0);
+  }
+  /**
+   * Serializes JSON-RPC payload according to configured stdio framing mode.
+   */
+  serializeMessage(payload) {
+    const json = JSON.stringify(payload);
+    if (this.framing === "newline") {
+      return `${json}
+`;
+    }
+    const contentLength = Buffer.byteLength(json, "utf8");
+    return `Content-Length: ${contentLength}\r
+\r
+${json}`;
+  }
+  /**
+   * Parses newline-delimited JSON-RPC messages (legacy mode).
+   */
+  parseLineDelimitedData(data) {
+    this.lineBuffer += data.toString();
+    let newlineIndex;
+    while ((newlineIndex = this.lineBuffer.indexOf("\n")) !== -1) {
+      const line = this.lineBuffer.slice(0, newlineIndex).trim();
+      this.lineBuffer = this.lineBuffer.slice(newlineIndex + 1);
+      if (line.length === 0) continue;
+      this.handleJsonPayload(line);
+    }
+  }
+  /**
+   * Parses Content-Length framed JSON-RPC messages (MCP stdio spec).
+   */
+  parseContentLengthData(data) {
+    this.frameBuffer = Buffer.concat([this.frameBuffer, data]);
+    while (this.frameBuffer.length > 0) {
+      const header = this.findHeaderEnd(this.frameBuffer);
+      if (!header) {
+        const preview = this.frameBuffer.toString("utf8", 0, Math.min(this.frameBuffer.length, 256));
+        const trimmed = preview.trimStart();
+        const looksLikeJsonLine = trimmed.startsWith("{") || trimmed.startsWith("[");
+        if (looksLikeJsonLine && this.frameBuffer.includes(10)) {
+          this.parseLineDelimitedData(this.frameBuffer);
+          this.frameBuffer = Buffer.alloc(0);
+        }
+        return;
+      }
+      const headersText = this.frameBuffer.subarray(0, header.index).toString("utf8");
+      const contentLength = this.extractContentLength(headersText);
+      if (contentLength === null) {
+        const newlineIndex = this.frameBuffer.indexOf("\n");
+        if (newlineIndex === -1) return;
+        const line = this.frameBuffer.subarray(0, newlineIndex).toString("utf8").trim();
+        this.frameBuffer = this.frameBuffer.subarray(newlineIndex + 1);
+        if (line.length > 0) {
+          this.handleJsonPayload(line);
+        }
+        continue;
+      }
+      const payloadStart = header.index + header.separatorLength;
+      const payloadEnd = payloadStart + contentLength;
+      if (this.frameBuffer.length < payloadEnd) {
+        return;
+      }
+      const json = this.frameBuffer.subarray(payloadStart, payloadEnd).toString("utf8").trim();
+      this.frameBuffer = this.frameBuffer.subarray(payloadEnd);
+      if (json.length > 0) {
+        this.handleJsonPayload(json);
+      }
+    }
+  }
+  /**
+   * Finds the end of a stdio frame header block.
+   */
+  findHeaderEnd(buffer) {
+    const crlfIndex = buffer.indexOf("\r\n\r\n");
+    const lfIndex = buffer.indexOf("\n\n");
+    if (crlfIndex === -1 && lfIndex === -1) return null;
+    if (crlfIndex !== -1 && (lfIndex === -1 || crlfIndex < lfIndex)) {
+      return { index: crlfIndex, separatorLength: 4 };
+    }
+    return { index: lfIndex, separatorLength: 2 };
+  }
+  /**
+   * Extracts Content-Length header value from frame headers.
+   */
+  extractContentLength(headers) {
+    const lines = headers.split(/\r?\n/);
+    for (const line of lines) {
+      const match = /^content-length\s*:\s*(\d+)\s*$/i.exec(line.trim());
+      if (!match) continue;
+      const parsed = Number.parseInt(match[1], 10);
+      if (Number.isNaN(parsed) || parsed < 0) return null;
+      return parsed;
+    }
+    return null;
+  }
+  /**
+   * Parses and routes a single JSON-RPC payload.
+   */
+  handleJsonPayload(json) {
+    try {
+      const message = JSON.parse(json);
+      this.handleMessage(message);
+    } catch {
+      this.emit("stderr", `Non-JSON output: ${json}`);
+    }
+  }
+};
+var McpHttpConnection = class _McpHttpConnection extends EventEmitter {
+  constructor(config) {
+    super();
+    this.config = config;
+    this.nextId = 1;
+    this.sessionId = null;
+  }
+  static {
+    /** Default timeout for HTTP requests in milliseconds */
+    this.REQUEST_TIMEOUT_MS = 3e4;
+  }
+  /**
+   * No-op for HTTP transport (no persistent process to start).
+   */
+  async start() {
+  }
+  /**
+   * Sends a JSON-RPC 2.0 request via HTTP POST and returns the response.
+   */
+  async request(method, params) {
+    if (!this.config.url) {
+      throw new Error(`MCP HTTP server "${this.config.name}" has no URL configured`);
+    }
+    const id = this.nextId++;
+    const body = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      ...params !== void 0 ? { params } : {}
+    };
+    const headers = {
+      "Content-Type": "application/json",
+      "Accept": "application/json, text/event-stream",
+      ...this.config.headers ?? {}
+    };
+    if (this.sessionId) {
+      headers["Mcp-Session-Id"] = this.sessionId;
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), _McpHttpConnection.REQUEST_TIMEOUT_MS);
+    try {
+      const response = await fetch(this.config.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      clearTimeout(timeout);
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new Error(
+          `MCP HTTP request "${method}" failed: ${response.status} ${response.statusText}${text ? ` - ${text}` : ""}`
+        );
+      }
+      const newSessionId = response.headers.get("mcp-session-id");
+      if (newSessionId) {
+        this.sessionId = newSessionId;
+      }
+      const contentType = response.headers.get("content-type") ?? "";
+      if (contentType.includes("text/event-stream")) {
+        const text = await response.text();
+        return this.parseSSEResponse(text, id);
+      }
+      const result = await response.json();
+      if (result.error) {
+        throw new Error(
+          `MCP error (${result.error.code}): ${result.error.message}`
+        );
+      }
+      return result.result;
+    } catch (error) {
+      clearTimeout(timeout);
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new Error(`MCP HTTP request "${method}" timed out after ${_McpHttpConnection.REQUEST_TIMEOUT_MS}ms`);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Sends a JSON-RPC 2.0 notification via HTTP POST (fire-and-forget).
+   */
+  notify(method, params) {
+    if (!this.config.url) return;
+    const body = {
+      jsonrpc: "2.0",
+      method,
+      ...params !== void 0 ? { params } : {}
+    };
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.config.headers ?? {}
+    };
+    if (this.sessionId) {
+      headers["Mcp-Session-Id"] = this.sessionId;
+    }
+    fetch(this.config.url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    }).catch(() => {
+    });
+  }
+  /**
+   * No persistent process to stop for HTTP transport.
+   */
+  async stop() {
+    this.sessionId = null;
+  }
+  /**
+   * Parses an SSE (text/event-stream) response to extract the JSON-RPC result.
+   */
+  parseSSEResponse(text, _expectedId) {
+    const lines = text.split("\n");
+    let lastData = "";
+    for (const line of lines) {
+      if (line.startsWith("data: ")) {
+        lastData = line.slice(6);
+      }
+    }
+    if (!lastData) {
+      throw new Error("No data found in SSE response");
+    }
+    try {
+      const parsed = JSON.parse(lastData);
+      if (parsed.error) {
+        throw new Error(`MCP error (${parsed.error.code}): ${parsed.error.message}`);
+      }
+      return parsed.result;
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw new Error(`Invalid JSON in SSE response: ${lastData.slice(0, 100)}`);
+      }
+      throw error;
+    }
+  }
+};
+var McpClientManager = class {
+  constructor() {
+    this.servers = /* @__PURE__ */ new Map();
+    this.connections = /* @__PURE__ */ new Map();
+  }
+  // ============================================================================
+  // Static Helper Methods
+  // ============================================================================
+  /**
+   * Checks if a tool name belongs to MCP (starts with mcp__ prefix).
+   * @param toolName - The tool name to check
+   * @returns true if the tool is an MCP tool
+   */
+  static isMcpTool(toolName) {
+    return toolName.startsWith("mcp__");
+  }
+  /**
+   * Extracts the server name and tool name from a prefixed MCP tool name.
+   * The expected format is `mcp__<serverName>__<toolName>`.
+   *
+   * @param prefixedName - The full prefixed tool name
+   * @returns Object with serverName and toolName, or null if invalid format
+   */
+  static parseMcpToolName(prefixedName) {
+    if (!prefixedName.startsWith("mcp__")) return null;
+    const withoutPrefix = prefixedName.slice(5);
+    const separatorIndex = withoutPrefix.indexOf("__");
+    if (separatorIndex <= 0) return null;
+    const serverName = withoutPrefix.slice(0, separatorIndex);
+    const toolName = withoutPrefix.slice(separatorIndex + 2);
+    if (!serverName || !toolName) return null;
+    return { serverName, toolName };
+  }
+  // ============================================================================
+  // Connection Management
+  // ============================================================================
+  /**
+   * Connects to all configured MCP servers.
+   * Servers with `autoConnect: false` are skipped.
+   * Connection failures for individual servers are caught and logged
+   * but do not prevent other servers from connecting.
+   *
+   * @param configs - Array of server configurations
+   */
+  async connectAll(configs) {
+    const connectPromises = configs.filter((config) => config.autoConnect !== false).map(async (config) => {
+      try {
+        await this.connect(config);
+      } catch (error) {
+        this.servers.set(config.name, {
+          config,
+          status: "error",
+          tools: [],
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    });
+    await Promise.all(connectPromises);
+  }
+  /**
+   * Connects to a single MCP server. Performs the MCP initialize handshake,
+   * discovers available tools, and registers them.
+   *
+   * @param config - Server configuration
+   * @throws {Error} If the configuration is invalid or connection fails
+   */
+  async connect(config) {
+    validateMcpServerConfig(config);
+    if (this.servers.has(config.name)) {
+      await this.disconnect(config.name);
+    }
+    if (config.transport === "stdio") {
+      await this.connectStdio(config);
+    } else if (config.transport === "http") {
+      await this.connectHttp(config);
+    } else if (config.transport === "sse") {
+      await this.connectSse(config);
+    }
+  }
+  /**
+   * Disconnects from a specific MCP server.
+   *
+   * @param serverName - Name of the server to disconnect
+   * @throws {Error} If the server is not found
+   */
+  async disconnect(serverName) {
+    const connection = this.connections.get(serverName);
+    if (!connection && !this.servers.has(serverName)) {
+      throw new Error(`MCP server not found: "${serverName}"`);
+    }
+    if (connection) {
+      await connection.stop();
+      this.connections.delete(serverName);
+    }
+    this.servers.delete(serverName);
+  }
+  /**
+   * Disconnects from all connected MCP servers.
+   */
+  async disconnectAll() {
+    const disconnectPromises = Array.from(this.servers.keys()).map(
+      (name) => this.disconnect(name).catch(() => {
+      })
+    );
+    await Promise.all(disconnectPromises);
+  }
+  // ============================================================================
+  // Tool Discovery
+  // ============================================================================
+  /**
+   * Returns all known servers with their status and tool count.
+   * @returns Array of server summaries
+   */
+  getServers() {
+    const result = [];
+    for (const [name, state] of this.servers) {
+      result.push({
+        name,
+        status: state.status,
+        toolCount: state.tools.length
+      });
+    }
+    return result;
+  }
+  /**
+   * Returns all available tools from all connected servers.
+   * @returns Array of tool definitions
+   */
+  getAllTools() {
+    const allTools = [];
+    for (const state of this.servers.values()) {
+      if (state.status === "connected") {
+        allTools.push(...state.tools);
+      }
+    }
+    return allTools;
+  }
+  /**
+   * Returns tools from a specific server.
+   * @param serverName - Name of the server
+   * @returns Array of tool definitions from that server
+   */
+  getToolsForServer(serverName) {
+    const state = this.servers.get(serverName);
+    if (!state || state.status !== "connected") return [];
+    return state.tools;
+  }
+  // ============================================================================
+  // Tool Execution
+  // ============================================================================
+  /**
+   * Calls a tool on a specific MCP server.
+   *
+   * @param serverName - Name of the server providing the tool
+   * @param toolName - Name of the tool (without mcp__ prefix)
+   * @param args - Arguments to pass to the tool
+   * @returns The tool's result
+   * @throws {Error} If the server is not connected or the tool call fails
+   */
+  async callTool(serverName, toolName, args) {
+    const connection = this.connections.get(serverName);
+    const state = this.servers.get(serverName);
+    if (!connection || !state || state.status !== "connected") {
+      throw new Error(`MCP server not found or not connected: "${serverName}"`);
+    }
+    const toolArgs = { ...args };
+    delete toolArgs.type;
+    const result = await connection.request("tools/call", {
+      name: toolName,
+      arguments: toolArgs
+    });
+    return result;
+  }
+  // ============================================================================
+  // Server Status
+  // ============================================================================
+  /**
+   * Lists all known servers with their connection status and tool count.
+   * @returns Array of server status objects
+   */
+  listServers() {
+    return Array.from(this.servers.values()).map((state) => ({
+      name: state.config.name,
+      status: state.status,
+      toolCount: state.tools.length,
+      error: state.error
+    }));
+  }
+  // ============================================================================
+  // Private: Transport-Specific Connection Logic
+  // ============================================================================
+  /**
+   * Connects to an MCP server via stdio transport.
+   * Spawns the server process, performs the MCP initialize handshake,
+   * and discovers available tools.
+   */
+  async connectStdio(config) {
+    try {
+      const connected = await this.connectStdioWithFallbackFraming(config);
+      this.registerConnectedStdioServer(config, connected.connection, connected.tools);
+    } catch (error) {
+      if (!this.shouldRetryNpxWithIsolatedCache(config, error)) {
+        throw error;
+      }
+      const retryConfig = {
+        ...config,
+        env: buildNpxIsolatedCacheEnv(config.env, config.name)
+      };
+      try {
+        const connected = await this.connectStdioWithFallbackFraming(retryConfig);
+        this.registerConnectedStdioServer(config, connected.connection, connected.tools);
+      } catch (retryError) {
+        const initialMessage = error instanceof Error ? error.message : String(error);
+        const retryMessage = retryError instanceof Error ? retryError.message : String(retryError);
+        throw new Error(`${initialMessage}
+Retry with isolated npm cache failed: ${retryMessage}`);
+      }
+    }
+  }
+  shouldRetryNpxWithIsolatedCache(config, error) {
+    if (!config.command || !isNpxCommand(config.command)) {
+      return false;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return isRetriableNpxInstallError(message);
+  }
+  /**
+   * Some MCP servers still use newline-delimited JSON-RPC over stdio.
+   * Start with Content-Length framing (spec), then fallback to newline when
+   * initialize stalls/closes without a successful handshake.
+   */
+  shouldRetryWithNewlineFraming(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes('MCP request "initialize" timed out') || message.includes("MCP connection closed before initialization completed") || message.includes("MCP connection closed (server exited with code");
+  }
+  async connectStdioWithFallbackFraming(config) {
+    try {
+      return await this.connectStdioWithFraming(config, "content-length");
+    } catch (contentLengthError) {
+      if (!this.shouldRetryWithNewlineFraming(contentLengthError)) {
+        throw contentLengthError;
+      }
+      try {
+        return await this.connectStdioWithFraming(config, "newline");
+      } catch (newlineError) {
+        const first = contentLengthError instanceof Error ? contentLengthError.message : String(contentLengthError);
+        const second = newlineError instanceof Error ? newlineError.message : String(newlineError);
+        throw new Error(`${first}
+Retry with newline framing failed: ${second}`);
+      }
+    }
+  }
+  /**
+   * Tries to establish a stdio MCP connection with a specific framing mode.
+   */
+  async connectStdioWithFraming(config, framing) {
+    const connection = new McpStdioConnection(config, framing);
+    let connectionError = null;
+    let stderrOutput = "";
+    let closeCode;
+    let handshakeComplete = false;
+    connection.on("error", (err) => {
+      connectionError = err;
+      const state = this.servers.get(config.name);
+      if (state) {
+        state.status = "error";
+        state.error = err.message;
+      }
+    });
+    connection.on("close", (code) => {
+      closeCode = code;
+      if (handshakeComplete || connectionError) return;
+      connectionError = new Error(
+        typeof code === "number" ? `MCP server process exited with code ${code}` : "MCP server process exited before completing initialization"
+      );
+    });
+    connection.on("stderr", (data) => {
+      stderrOutput += data;
+    });
+    try {
+      await connection.start();
+      if (connectionError) {
+        throw connectionError;
+      }
+      await connection.request("initialize", {
+        protocolVersion: "2024-11-05",
+        capabilities: {
+          tools: {}
+        },
+        clientInfo: {
+          name: "autohand",
+          version: "1.0.0"
+        }
+      });
+      connection.notify("notifications/initialized");
+      const toolsResult = await connection.request("tools/list", {});
+      const tools = (toolsResult?.tools ?? []).map(
+        (rawTool) => convertMcpToolToAutohand(rawTool, config.name)
+      );
+      handshakeComplete = true;
+      return { connection, tools };
+    } catch (error) {
+      await connection.stop().catch(() => {
+      });
+      let errMsg = error instanceof Error ? error.message : String(error);
+      if (errMsg === "MCP connection closed") {
+        errMsg = typeof closeCode === "number" ? `MCP connection closed (server exited with code ${closeCode})` : "MCP connection closed before initialization completed";
+      }
+      const detail = stderrOutput.trim();
+      if (detail) {
+        const stderrSnippet = detail.length > 500 ? detail.slice(-500) : detail;
+        throw new Error(`${errMsg}
+  Server stderr (tail): ${stderrSnippet}`);
+      }
+      throw new Error(errMsg);
+    }
+  }
+  /**
+   * Stores connected server state and attaches lifecycle listeners.
+   */
+  registerConnectedStdioServer(config, connection, tools) {
+    connection.on("close", (code) => {
+      const state = this.servers.get(config.name);
+      if (state && state.status === "connected") {
+        state.status = "error";
+        state.error = typeof code === "number" ? `MCP server process exited with code ${code}` : "MCP server disconnected unexpectedly";
+      }
+    });
+    this.servers.set(config.name, {
+      config,
+      status: "connected",
+      tools
+    });
+    this.connections.set(config.name, connection);
+  }
+  /**
+   * Connects to an MCP server via HTTP (Streamable HTTP) transport.
+   * Sends JSON-RPC requests as HTTP POST to the configured URL.
+   */
+  async connectHttp(config) {
+    const connection = new McpHttpConnection(config);
+    try {
+      await connection.start();
+      await connection.request("initialize", {
+        protocolVersion: "2024-11-05",
+        capabilities: {
+          tools: {}
+        },
+        clientInfo: {
+          name: "autohand",
+          version: "1.0.0"
+        }
+      });
+      connection.notify("notifications/initialized");
+      const toolsResult = await connection.request("tools/list", {});
+      const tools = (toolsResult?.tools ?? []).map(
+        (rawTool) => convertMcpToolToAutohand(rawTool, config.name)
+      );
+      this.servers.set(config.name, {
+        config,
+        status: "connected",
+        tools
+      });
+      this.connections.set(config.name, connection);
+    } catch (error) {
+      await connection.stop().catch(() => {
+      });
+      throw error;
+    }
+  }
+  /**
+   * Connects to an MCP server via SSE transport.
+   * Currently a placeholder -- SSE transport requires an HTTP client
+   * with SSE support which will be added in a future iteration.
+   */
+  async connectSse(config) {
+    this.servers.set(config.name, {
+      config,
+      status: "error",
+      tools: [],
+      error: "SSE transport is not yet implemented. Use stdio or http transport instead."
+    });
+    throw new Error(
+      `SSE transport for MCP server "${config.name}" is not yet implemented. Use stdio or http transport instead.`
+    );
+  }
+};
+
+export {
+  McpClientManager
+};