DocsRuntimemcpMCPClient
Package: @hexos/runtime

MCP client implementation using STDIO transport for process-based communication.

Spawns an MCP server as a child process and communicates via JSON-RPC messages over standard input/output streams. Handles the MCP protocol handshake, request/response correlation, and protocol-compliant message formatting.

Messages are newline-delimited JSON-RPC 2.0 format. Supports both requests (with ID, expecting responses) and notifications (no ID, no response expected).

Implements IMCPClient interface and is managed by MCPManager. Configuration provided via MCPStdioServerConfig.

class MCPClient extends EventEmitter implements IMCPClient {
    constructor(serverName: string, config: MCPStdioServerConfig)
    connect() => Promise<void>;
    listTools() => Promise<MCPToolInfo[]>;
    callTool(name: string, args: unknown) => Promise<unknown>;
    disconnect() => void;
    isConnected() => boolean;
}

constructor

(serverName: string, config: MCPStdioServerConfig) => MCPClient

Create a new STDIO MCP client instance.

connect

() => Promise

Connect to the MCP server by spawning the configured child process.

Spawns the process with the configured command, args, and environment. Sets up event listeners for process lifecycle (error, exit) and stdio streams. Performs the MCP handshake by sending initialize request followed by initialized notification.

Idempotent - returns immediately if already connected.

listTools

() => Promise<MCPToolInfo[]>

Retrieve all tools available from the MCP server.

Sends a tools/list JSON-RPC request and parses the response to extract tool metadata. Returns empty array if no tools are available.

callTool

(name: string, args: unknown) => Promise

Execute a tool on the MCP server with the provided arguments.

Sends a tools/call request with tool name and arguments. Extracts text content from the MCP response (which returns content arrays) and attempts JSON parsing if the result looks like JSON.

disconnect

() => void

Disconnect from the MCP server and clean up all resources.

Sends SIGTERM to the child process, clears pending request map and input buffer, and resets connection state. All pending requests will be rejected implicitly when the process exits.

isConnected

() => boolean

Check whether the client is currently connected to the MCP server.

McpMCPManager