@tryhamster/gerbil 1.0.0-rc.0

package/dist/integrations/mcp-client.d.mts

@@ -0,0 +1,206 @@
+//#region src/integrations/mcp-client.d.ts
+/**
+ * Gerbil MCP Client
+ *
+ * Connect to external MCP servers and use their tools.
+ * Uses the official @modelcontextprotocol/sdk for protocol compliance.
+ *
+ * @example
+ * ```typescript
+ * import { MCPClient, MCPHub } from "gerbil/mcp-client";
+ *
+ * // Connect to a single server
+ * const client = new MCPClient({
+ *   name: "filesystem",
+ *   command: "uvx",
+ *   args: ["mcp-server-filesystem", "/tmp"]
+ * });
+ * await client.connect();
+ * const tools = await client.listTools();
+ * const result = await client.callTool("read_file", { path: "/tmp/test.txt" });
+ *
+ * // Or use the hub for multiple servers
+ * const hub = new MCPHub();
+ * await hub.addServer("filesystem", { command: "uvx", args: ["mcp-server-filesystem", "/tmp"] });
+ * await hub.addServer("browser", { command: "npx", args: ["-y", "@anthropic/mcp-server-puppeteer"] });
+ *
+ * // All tools from all servers are available
+ * const allTools = hub.getAllTools();
+ * ```
+ */
+type MCPServerConfig = {
+  /** Command to run the MCP server */
+  command: string;
+  /** Arguments for the command */
+  args?: string[];
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Working directory */
+  cwd?: string;
+  /** Timeout for requests (ms, default: 30000) */
+  timeout?: number;
+};
+type MCPTool = {
+  name: string;
+  description?: string;
+  inputSchema?: {
+    type: string;
+    properties?: Record<string, any>;
+    required?: string[];
+  };
+};
+type MCPResource = {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+};
+/**
+ * Client for a single MCP server.
+ *
+ * Uses @modelcontextprotocol/sdk when available, falls back to
+ * a minimal stdio implementation otherwise.
+ */
+declare class MCPClient {
+  private readonly config;
+  private client;
+  private transport;
+  private connected;
+  private _tools;
+  private _resources;
+  private readonly serverName;
+  private useFallback;
+  private fallbackProcess;
+  private fallbackRequestId;
+  private readonly fallbackPending;
+  private fallbackBuffer;
+  constructor(config: MCPServerConfig & {
+    name?: string;
+  });
+  /**
+   * Connect to the MCP server
+   */
+  connect(): Promise<void>;
+  /**
+   * Try to load the official MCP SDK
+   * Uses dynamic import to avoid bundling issues when SDK is not installed
+   */
+  private loadSDK;
+  /**
+   * Connect using the official SDK
+   */
+  private connectWithSDK;
+  /**
+   * Fallback: Connect without SDK using raw stdio
+   */
+  private connectFallback;
+  private processFallbackBuffer;
+  private fallbackRequest;
+  private fallbackNotify;
+  /**
+   * Disconnect from the MCP server
+   */
+  disconnect(): Promise<void>;
+  /**
+   * Refresh tools and resources from the server
+   */
+  refreshCapabilities(): Promise<void>;
+  /**
+   * List available tools
+   */
+  listTools(): MCPTool[];
+  /**
+   * List available resources
+   */
+  listResources(): MCPResource[];
+  /**
+   * Call a tool
+   */
+  callTool(name: string, args?: Record<string, any>): Promise<any>;
+  /**
+   * Read a resource
+   */
+  readResource(uri: string): Promise<string>;
+  /**
+   * Check if connected
+   */
+  isConnected(): boolean;
+  /**
+   * Get server name
+   */
+  getName(): string;
+}
+/**
+ * Hub for managing multiple MCP server connections
+ */
+declare class MCPHub {
+  private readonly clients;
+  private readonly toolPrefix;
+  /**
+   * Add and connect to an MCP server
+   */
+  addServer(name: string, config: MCPServerConfig): Promise<MCPClient>;
+  /**
+   * Remove and disconnect an MCP server
+   */
+  removeServer(name: string): Promise<void>;
+  /**
+   * Get a specific client
+   */
+  getClient(name: string): MCPClient | undefined;
+  /**
+   * List connected servers
+   */
+  listServers(): string[];
+  /**
+   * Get all tools from all servers
+   */
+  getAllTools(): Array<{
+    server: string;
+    tool: MCPTool;
+  }>;
+  /**
+   * Call a tool from any connected server
+   * Tool name format: "server_name:tool_name" or just "tool_name" (searches all)
+   */
+  callTool(toolName: string, args?: Record<string, any>): Promise<any>;
+  /**
+   * Disconnect all servers
+   */
+  disconnectAll(): Promise<void>;
+  /**
+   * Register tools from an MCP server into Gerbil's tool registry
+   */
+  private registerServerTools;
+  /**
+   * Convert MCP JSON Schema to Zod schema (simplified)
+   */
+  private mcpSchemaToZod;
+}
+/**
+ * Get the default MCP hub (singleton)
+ */
+declare function getMCPHub(): MCPHub;
+/**
+ * Connect to an MCP server
+ */
+declare function connectMCP(name: string, config: MCPServerConfig): Promise<MCPClient>;
+/**
+ * Disconnect from an MCP server
+ */
+declare function disconnectMCP(name: string): Promise<void>;
+/**
+ * Call an MCP tool
+ */
+declare function callMCPTool(toolName: string, args?: Record<string, any>): Promise<any>;
+declare const _default: {
+  MCPClient: typeof MCPClient;
+  MCPHub: typeof MCPHub;
+  getMCPHub: typeof getMCPHub;
+  connectMCP: typeof connectMCP;
+  disconnectMCP: typeof disconnectMCP;
+  callMCPTool: typeof callMCPTool;
+};
+//#endregion
+export { MCPClient, MCPHub, MCPResource, MCPServerConfig, MCPTool, callMCPTool, connectMCP, _default as default, disconnectMCP, getMCPHub };
+//# sourceMappingURL=mcp-client.d.mts.map

package/dist/integrations/mcp-client.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.d.mts","names":[],"sources":["../../src/integrations/mcp-client.ts"],"sourcesContent":[],"mappings":";;AAqCA;AAiBA;AAUA;AAiBA;;;;;;;;;;;AAyUA;;;;;;;;;;;;AAmLA;AAUA;AAAuD,KAljB3C,eAAA,GAkjB2C;EAA0B;EAAR,OAAA,EAAA,MAAA;EAAO;EAO1D,IAAA,CAAA,EAAA,MAAA,EAAA;EAOA;EAErB,GAAA,CAAA,EA1jBO,MA0jBP,CAAA,MAAA,EAAA,MAAA,CAAA;;;;;;KAjjBW,OAAA;;;;;iBAKK;;;;KAKL,WAAA;;;;;;;;;;;;cAiBC,SAAA;;;;;;;;;;;;;sBAmBS;;;;;;aAWH;;;;;;;;;;;;;;;;;;;;gBAyKG;;;;yBAsBS;;;;eA6BhB;;;;mBAOI;;;;gCAOkB,sBAA2B;;;;6BAyB7B;;;;;;;;;;;;;cAwCtB,MAAA;;;;;;kCAO2B,kBAAkB,QAAQ;;;;8BAmB9B;;;;2BAWT;;;;;;;;iBAcV;;UAA8B;;;;;;oCAgBN,sBAA2B;;;;mBAyB3C;;;;;;;;;;;;;iBAuFT,SAAA,CAAA,GAAa;;;;iBAUP,UAAA,uBAAiC,kBAAkB,QAAQ;;;;iBAO3D,aAAA,gBAA6B;;;;iBAO7B,WAAA,0BAAqC,sBAAsB;cAEhF"}

package/dist/integrations/mcp-client.mjs

@@ -0,0 +1,507 @@
+import "../utils-7vXqtq2Q.mjs";
+import { t as defineTool } from "../tools-BsiEE6f2.mjs";
+import { z } from "zod";
+
+//#region src/integrations/mcp-client.ts
+/**
+* Gerbil MCP Client
+*
+* Connect to external MCP servers and use their tools.
+* Uses the official @modelcontextprotocol/sdk for protocol compliance.
+*
+* @example
+* ```typescript
+* import { MCPClient, MCPHub } from "gerbil/mcp-client";
+*
+* // Connect to a single server
+* const client = new MCPClient({
+*   name: "filesystem",
+*   command: "uvx",
+*   args: ["mcp-server-filesystem", "/tmp"]
+* });
+* await client.connect();
+* const tools = await client.listTools();
+* const result = await client.callTool("read_file", { path: "/tmp/test.txt" });
+*
+* // Or use the hub for multiple servers
+* const hub = new MCPHub();
+* await hub.addServer("filesystem", { command: "uvx", args: ["mcp-server-filesystem", "/tmp"] });
+* await hub.addServer("browser", { command: "npx", args: ["-y", "@anthropic/mcp-server-puppeteer"] });
+*
+* // All tools from all servers are available
+* const allTools = hub.getAllTools();
+* ```
+*/
+/**
+* Client for a single MCP server.
+*
+* Uses @modelcontextprotocol/sdk when available, falls back to
+* a minimal stdio implementation otherwise.
+*/
+var MCPClient = class {
+	config;
+	client = null;
+	transport = null;
+	connected = false;
+	_tools = [];
+	_resources = [];
+	serverName;
+	useFallback = false;
+	fallbackProcess = null;
+	fallbackRequestId = 0;
+	fallbackPending = /* @__PURE__ */ new Map();
+	fallbackBuffer = "";
+	constructor(config) {
+		this.config = {
+			timeout: 3e4,
+			...config
+		};
+		this.serverName = config.name || "mcp";
+	}
+	/**
+	* Connect to the MCP server
+	*/
+	async connect() {
+		if (this.connected) return;
+		try {
+			const sdk = await this.loadSDK();
+			if (sdk) await this.connectWithSDK(sdk);
+			else await this.connectFallback();
+			this.connected = true;
+			await this.refreshCapabilities();
+		} catch (e) {
+			this.connected = false;
+			throw e;
+		}
+	}
+	/**
+	* Try to load the official MCP SDK
+	* Uses dynamic import to avoid bundling issues when SDK is not installed
+	*/
+	async loadSDK() {
+		try {
+			const importDynamic = new Function("modulePath", "return import(modulePath)");
+			const clientModule = await importDynamic("@modelcontextprotocol/sdk/client");
+			const stdioModule = await importDynamic("@modelcontextprotocol/sdk/client/stdio");
+			return {
+				Client: clientModule.Client,
+				StdioClientTransport: stdioModule.StdioClientTransport
+			};
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Connect using the official SDK
+	*/
+	async connectWithSDK(sdk) {
+		const { Client, StdioClientTransport } = sdk;
+		this.transport = new StdioClientTransport({
+			command: this.config.command,
+			args: this.config.args || [],
+			env: this.config.env
+		});
+		this.client = new Client({
+			name: "gerbil",
+			version: "1.0.0"
+		}, { capabilities: {} });
+		await this.client.connect(this.transport);
+	}
+	/**
+	* Fallback: Connect without SDK using raw stdio
+	*/
+	async connectFallback() {
+		this.useFallback = true;
+		const { spawn } = await import("child_process");
+		this.fallbackProcess = spawn(this.config.command, this.config.args || [], {
+			cwd: this.config.cwd,
+			env: {
+				...process.env,
+				...this.config.env
+			},
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		this.fallbackProcess.stdout?.on("data", (data) => {
+			this.fallbackBuffer += data.toString();
+			this.processFallbackBuffer();
+		});
+		this.fallbackProcess.on("error", (err) => {
+			this.connected = false;
+			throw new Error(`MCP server error: ${err.message}`);
+		});
+		this.fallbackProcess.on("exit", (code) => {
+			this.connected = false;
+			for (const [_, req] of this.fallbackPending) req.reject(/* @__PURE__ */ new Error(`MCP server exited with code ${code}`));
+			this.fallbackPending.clear();
+		});
+		await this.fallbackRequest("initialize", {
+			protocolVersion: "2024-11-05",
+			capabilities: {},
+			clientInfo: {
+				name: "gerbil",
+				version: "0.1.0"
+			}
+		});
+		this.fallbackNotify("notifications/initialized", {});
+	}
+	processFallbackBuffer() {
+		const lines = this.fallbackBuffer.split("\n");
+		this.fallbackBuffer = lines.pop() || "";
+		for (const line of lines) {
+			if (!line.trim()) continue;
+			try {
+				const response = JSON.parse(line);
+				if (response.id !== void 0) {
+					const pending = this.fallbackPending.get(response.id);
+					if (pending) {
+						this.fallbackPending.delete(response.id);
+						if (response.error) pending.reject(new Error(response.error.message));
+						else pending.resolve(response.result);
+					}
+				}
+			} catch {}
+		}
+	}
+	fallbackRequest(method, params) {
+		return new Promise((resolve, reject) => {
+			if (!this.fallbackProcess?.stdin) {
+				reject(/* @__PURE__ */ new Error("Not connected"));
+				return;
+			}
+			const id = ++this.fallbackRequestId;
+			const request = {
+				jsonrpc: "2.0",
+				id,
+				method,
+				params
+			};
+			const timeout = setTimeout(() => {
+				this.fallbackPending.delete(id);
+				reject(/* @__PURE__ */ new Error(`Request timeout: ${method}`));
+			}, this.config.timeout);
+			this.fallbackPending.set(id, {
+				resolve: (v) => {
+					clearTimeout(timeout);
+					resolve(v);
+				},
+				reject: (e) => {
+					clearTimeout(timeout);
+					reject(e);
+				}
+			});
+			this.fallbackProcess.stdin.write(`${JSON.stringify(request)}\n`);
+		});
+	}
+	fallbackNotify(method, params) {
+		if (!this.fallbackProcess?.stdin) return;
+		this.fallbackProcess.stdin.write(`${JSON.stringify({
+			jsonrpc: "2.0",
+			method,
+			params
+		})}\n`);
+	}
+	/**
+	* Disconnect from the MCP server
+	*/
+	async disconnect() {
+		if (!this.connected) return;
+		if (this.useFallback && this.fallbackProcess) {
+			this.fallbackProcess.kill("SIGTERM");
+			this.fallbackProcess = null;
+		} else if (this.client) {
+			await this.client.close();
+			this.client = null;
+			this.transport = null;
+		}
+		this.connected = false;
+		this._tools = [];
+		this._resources = [];
+	}
+	/**
+	* Refresh tools and resources from the server
+	*/
+	async refreshCapabilities() {
+		try {
+			if (this.useFallback) this._tools = (await this.fallbackRequest("tools/list", {})).tools || [];
+			else if (this.client) this._tools = (await this.client.listTools()).tools || [];
+		} catch {
+			this._tools = [];
+		}
+		try {
+			if (this.useFallback) this._resources = (await this.fallbackRequest("resources/list", {})).resources || [];
+			else if (this.client) this._resources = (await this.client.listResources()).resources || [];
+		} catch {
+			this._resources = [];
+		}
+	}
+	/**
+	* List available tools
+	*/
+	listTools() {
+		return this._tools;
+	}
+	/**
+	* List available resources
+	*/
+	listResources() {
+		return this._resources;
+	}
+	/**
+	* Call a tool
+	*/
+	async callTool(name, args = {}) {
+		let result;
+		if (this.useFallback) result = await this.fallbackRequest("tools/call", {
+			name,
+			arguments: args
+		});
+		else if (this.client) result = await this.client.callTool({
+			name,
+			arguments: args
+		});
+		else throw new Error("Not connected");
+		if (result.content && Array.isArray(result.content)) return result.content.map((c) => c.text || JSON.stringify(c)).join("\n");
+		return result;
+	}
+	/**
+	* Read a resource
+	*/
+	async readResource(uri) {
+		let result;
+		if (this.useFallback) result = await this.fallbackRequest("resources/read", { uri });
+		else if (this.client) result = await this.client.readResource({ uri });
+		else throw new Error("Not connected");
+		if (result.contents && Array.isArray(result.contents)) return result.contents.map((c) => c.text || c.blob || "").join("\n");
+		return typeof result === "string" ? result : JSON.stringify(result);
+	}
+	/**
+	* Check if connected
+	*/
+	isConnected() {
+		return this.connected;
+	}
+	/**
+	* Get server name
+	*/
+	getName() {
+		return this.serverName;
+	}
+};
+/**
+* Hub for managing multiple MCP server connections
+*/
+var MCPHub = class {
+	clients = /* @__PURE__ */ new Map();
+	toolPrefix = "mcp";
+	/**
+	* Add and connect to an MCP server
+	*/
+	async addServer(name, config) {
+		if (this.clients.has(name)) await this.removeServer(name);
+		const client = new MCPClient({
+			...config,
+			name
+		});
+		await client.connect();
+		this.clients.set(name, client);
+		this.registerServerTools(name, client);
+		return client;
+	}
+	/**
+	* Remove and disconnect an MCP server
+	*/
+	async removeServer(name) {
+		const client = this.clients.get(name);
+		if (client) {
+			await client.disconnect();
+			this.clients.delete(name);
+		}
+	}
+	/**
+	* Get a specific client
+	*/
+	getClient(name) {
+		return this.clients.get(name);
+	}
+	/**
+	* List connected servers
+	*/
+	listServers() {
+		return Array.from(this.clients.keys());
+	}
+	/**
+	* Get all tools from all servers
+	*/
+	getAllTools() {
+		const tools = [];
+		for (const [serverName, client] of this.clients) for (const tool of client.listTools()) tools.push({
+			server: serverName,
+			tool
+		});
+		return tools;
+	}
+	/**
+	* Call a tool from any connected server
+	* Tool name format: "server_name:tool_name" or just "tool_name" (searches all)
+	*/
+	async callTool(toolName, args = {}) {
+		if (toolName.includes(":")) {
+			const [serverName, actualToolName] = toolName.split(":", 2);
+			const client = this.clients.get(serverName);
+			if (!client) throw new Error(`MCP server "${serverName}" not connected`);
+			return client.callTool(actualToolName, args);
+		}
+		for (const [_, client] of this.clients) if (client.listTools().some((t) => t.name === toolName)) return client.callTool(toolName, args);
+		throw new Error(`Tool "${toolName}" not found in any connected MCP server`);
+	}
+	/**
+	* Disconnect all servers
+	*/
+	async disconnectAll() {
+		for (const [name] of this.clients) await this.removeServer(name);
+	}
+	/**
+	* Register tools from an MCP server into Gerbil's tool registry
+	*/
+	registerServerTools(serverName, client) {
+		const tools = client.listTools();
+		for (const tool of tools) {
+			const gerbilToolName = `${this.toolPrefix}_${serverName}_${tool.name}`;
+			const zodSchema = this.mcpSchemaToZod(tool.inputSchema);
+			defineTool({
+				name: gerbilToolName,
+				description: `[MCP:${serverName}] ${tool.description || tool.name}`,
+				parameters: zodSchema,
+				execute: async (params) => {
+					const result = await client.callTool(tool.name, params);
+					return typeof result === "string" ? result : JSON.stringify(result);
+				}
+			});
+		}
+	}
+	/**
+	* Convert MCP JSON Schema to Zod schema (simplified)
+	*/
+	mcpSchemaToZod(schema) {
+		if (!schema || schema.type !== "object") return z.object({}).passthrough();
+		const shape = {};
+		const properties = schema.properties || {};
+		const required = new Set(schema.required || []);
+		for (const [key, prop] of Object.entries(properties)) {
+			let zodType;
+			switch (prop.type) {
+				case "string":
+					zodType = z.string();
+					if (prop.description) zodType = zodType.describe(prop.description);
+					break;
+				case "number":
+				case "integer":
+					zodType = z.number();
+					break;
+				case "boolean":
+					zodType = z.boolean();
+					break;
+				case "array":
+					zodType = z.array(z.any());
+					break;
+				default: zodType = z.any();
+			}
+			if (!required.has(key)) zodType = zodType.optional();
+			shape[key] = zodType;
+		}
+		return z.object(shape).passthrough();
+	}
+};
+let defaultHub = null;
+/**
+* Get the default MCP hub (singleton)
+*/
+function getMCPHub() {
+	if (!defaultHub) defaultHub = new MCPHub();
+	return defaultHub;
+}
+/**
+* Connect to an MCP server
+*/
+async function connectMCP(name, config) {
+	return getMCPHub().addServer(name, config);
+}
+/**
+* Disconnect from an MCP server
+*/
+async function disconnectMCP(name) {
+	return getMCPHub().removeServer(name);
+}
+/**
+* Call an MCP tool
+*/
+async function callMCPTool(toolName, args) {
+	return getMCPHub().callTool(toolName, args);
+}
+/**
+* Tool for the LLM to call MCP tools
+*/
+defineTool({
+	name: "mcp_call",
+	description: "Call a tool from a connected MCP server. Use this when you need to interact with external tools like file systems, browsers, databases, etc.",
+	parameters: z.object({
+		server: z.string().describe("The MCP server name (e.g., 'filesystem', 'browser')"),
+		tool: z.string().describe("The tool name to call"),
+		args: z.record(z.any()).optional().describe("Arguments to pass to the tool")
+	}),
+	execute: async ({ server, tool, args }) => {
+		const hub = getMCPHub();
+		const client = hub.getClient(server);
+		if (!client) {
+			const servers = hub.listServers();
+			if (servers.length === 0) return "No MCP servers are connected. Use the MCP settings to connect to servers first.";
+			return `Server "${server}" not found. Available servers: ${servers.join(", ")}`;
+		}
+		try {
+			const result = await client.callTool(tool, args || {});
+			return typeof result === "string" ? result : JSON.stringify(result, null, 2);
+		} catch (e) {
+			return `Error calling ${server}:${tool}: ${e}`;
+		}
+	}
+});
+/**
+* Tool to list available MCP tools
+*/
+defineTool({
+	name: "mcp_list",
+	description: "List all tools available from connected MCP servers",
+	parameters: z.object({ server: z.string().optional().describe("Filter by server name (optional)") }),
+	execute: async ({ server }) => {
+		const hub = getMCPHub();
+		if (server) {
+			const client = hub.getClient(server);
+			if (!client) return `Server "${server}" not connected`;
+			return client.listTools().map((t) => `- ${t.name}: ${t.description || "(no description)"}`).join("\n");
+		}
+		const allTools = hub.getAllTools();
+		if (allTools.length === 0) return "No MCP servers connected. Connect to MCP servers to use external tools.";
+		const byServer = {};
+		for (const { server: s, tool } of allTools) {
+			if (!byServer[s]) byServer[s] = [];
+			byServer[s].push(`  - ${tool.name}: ${tool.description || "(no description)"}`);
+		}
+		return Object.entries(byServer).map(([s, tools]) => `[${s}]\n${tools.join("\n")}`).join("\n\n");
+	}
+});
+var mcp_client_default = {
+	MCPClient,
+	MCPHub,
+	getMCPHub,
+	connectMCP,
+	disconnectMCP,
+	callMCPTool
+};
+
+//#endregion
+export { MCPClient, MCPHub, callMCPTool, connectMCP, mcp_client_default as default, disconnectMCP, getMCPHub };
+//# sourceMappingURL=mcp-client.mjs.map