@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/mcp/manager.js

@@ -0,0 +1,328 @@
+/**
+ * MCPConnectionManager — brings up all configured servers in parallel,
+ * discovers their tools, and exposes ToolRegistryEntry[] for the agent.
+ *
+ * One failed server never blocks the others. Failures are captured in
+ * per-server state so /mcp can surface them to the user without taking the
+ * agent down.
+ */
+import { gateToolAction } from "../approval/tool-helper.js";
+import { MCPClient } from "./client.js";
+import { HttpTransport, StdioTransport } from "./transports.js";
+import { buildMcpToolName, normalizeNameForMCP } from "./name.js";
+export class McpManager {
+    options;
+    connections = new Map();
+    clientInfo;
+    onDiagnostic;
+    constructor(options) {
+        this.options = options;
+        this.clientInfo = options.clientInfo ?? { name: "bubble", version: "0.1.0" };
+        this.onDiagnostic = options.onDiagnostic ?? ((msg) => console.error(msg));
+        for (const server of options.servers) {
+            this.connections.set(server.name, {
+                state: { name: server.name, scope: server.scope, config: server.config, status: { kind: "disabled" } },
+            });
+        }
+    }
+    /** Connect all configured servers. Never throws — per-server errors are captured in state. */
+    async start() {
+        await Promise.all(this.options.servers.map(async (server) => {
+            await this.connectOne(server);
+        }));
+    }
+    async connectOne(server) {
+        const existing = this.connections.get(server.name);
+        try {
+            const client = await createClient(server.config, this.clientInfo);
+            const tools = await client.listTools();
+            const prompts = client.capabilities?.prompts
+                ? await client.listPrompts().catch((err) => {
+                    this.onDiagnostic(`[mcp:${server.name}] prompts/list failed: ${err.message}`);
+                    return [];
+                })
+                : [];
+            existing.client = client;
+            existing.state = {
+                name: server.name,
+                scope: server.scope,
+                config: server.config,
+                status: { kind: "connected", tools, prompts, serverInfo: client.serverInfo },
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            existing.state = {
+                name: server.name,
+                scope: server.scope,
+                config: server.config,
+                status: { kind: "failed", error: message },
+            };
+            this.onDiagnostic(`[mcp:${server.name}] failed to connect: ${message}`);
+        }
+    }
+    /** Disconnect and reconnect a single server. Returns the new state. */
+    async reconnect(name) {
+        const conn = this.connections.get(name);
+        if (!conn)
+            return null;
+        if (conn.client) {
+            try {
+                await conn.client.close();
+            }
+            catch {
+                // ignore
+            }
+            conn.client = undefined;
+        }
+        const server = {
+            name: conn.state.name,
+            scope: conn.state.scope,
+            config: conn.state.config,
+        };
+        await this.connectOne(server);
+        return conn.state;
+    }
+    /** Shutdown all connections. Best-effort; errors are ignored. */
+    async shutdown() {
+        await Promise.all([...this.connections.values()].map(async (conn) => {
+            if (!conn.client)
+                return;
+            try {
+                await conn.client.close();
+            }
+            catch {
+                // ignore
+            }
+            conn.client = undefined;
+        }));
+    }
+    getStates() {
+        return [...this.connections.values()].map((c) => c.state);
+    }
+    /**
+     * Produce ToolRegistryEntry[] for every tool from every connected server.
+     * Hosts must pass them through gateMcpTools before handing them to an agent.
+     */
+    getToolEntries() {
+        const entries = [];
+        for (const conn of this.connections.values()) {
+            if (conn.state.status.kind !== "connected" || !conn.client)
+                continue;
+            const serverName = conn.state.name;
+            for (const tool of conn.state.status.tools) {
+                entries.push(buildToolEntry(serverName, tool, () => conn.client));
+            }
+        }
+        return entries;
+    }
+    /**
+     * Produce UnifiedCommand[] for every prompt from every connected server.
+     * Each command, when invoked, calls `prompts/get` with positionally-parsed
+     * arguments and returns an `inject` payload that the harness hands back to
+     * the agent as the user's next turn.
+     *
+     * Naming: prompts are exposed as /<promptName> directly (flat namespace,
+     * matching opencode's convention). When two servers export the same prompt
+     * name, last-registered wins and a diagnostic is emitted so the user can
+     * see which server "shadowed" which. Server iteration order follows the
+     * Map insertion order (stable: servers are inserted once at constructor
+     * time from the config's declared order).
+     *
+     * Tools, in contrast, keep their `mcp__<server>__<tool>` names so existing
+     * Claude Code-style permission rules (e.g. `Bash(git status)` neighbours)
+     * continue to match. See src/mcp/name.ts.
+     */
+    getPromptCommands() {
+        const byName = new Map();
+        for (const conn of this.connections.values()) {
+            if (conn.state.status.kind !== "connected" || !conn.client)
+                continue;
+            const serverName = conn.state.name;
+            for (const prompt of conn.state.status.prompts) {
+                const displayName = normalizeNameForMCP(prompt.name);
+                const cmd = buildPromptCommand(serverName, displayName, prompt, () => conn.client);
+                const existing = byName.get(displayName);
+                if (existing) {
+                    this.onDiagnostic(`[mcp] prompt /${displayName} from server "${serverName}" shadows the same prompt from "${existing.sourceLabel ?? "unknown"}"`);
+                }
+                byName.set(displayName, cmd);
+            }
+        }
+        return [...byName.values()];
+    }
+}
+async function createClient(config, clientInfo) {
+    const transport = config.type === "stdio" ? new StdioTransport(config) : new HttpTransport(config);
+    const client = new MCPClient(transport, clientInfo);
+    await client.start();
+    return client;
+}
+function buildToolEntry(serverName, tool, getClient) {
+    const name = buildMcpToolName(serverName, tool.name);
+    const parameters = coerceSchema(tool.inputSchema);
+    const descriptionPrefix = `[MCP:${serverName}]`;
+    const description = [descriptionPrefix, tool.description?.trim() || tool.name].filter(Boolean).join(" ");
+    return {
+        name,
+        description,
+        parameters,
+        readOnly: false, // Conservative default; user can allow-list.
+        effect: "unknown",
+        deferred: true, // Load schema on demand via tool_search to keep context small.
+        async execute(args) {
+            const client = getClient();
+            if (!client) {
+                return {
+                    content: `Error: MCP server "${serverName}" is not connected.`,
+                    isError: true,
+                };
+            }
+            try {
+                const result = await client.callTool(tool.name, args);
+                const text = formatToolContent(result.content);
+                return { content: text || "(no content)", isError: result.isError === true };
+            }
+            catch (err) {
+                return {
+                    content: `Error calling ${serverName}.${tool.name}: ${err.message || String(err)}`,
+                    isError: true,
+                };
+            }
+        },
+    };
+}
+function coerceSchema(input) {
+    if (input && typeof input === "object" && !Array.isArray(input)) {
+        const s = input;
+        if (s.type === "object" && typeof s.properties === "object") {
+            return input;
+        }
+    }
+    // Fallback — some servers omit inputSchema or send something odd.
+    return { type: "object", properties: {} };
+}
+function buildPromptCommand(serverName, displayName, prompt, getClient) {
+    const argNames = (prompt.arguments ?? []).map((a) => a.name);
+    const argSig = argNames.length > 0 ? ` <${argNames.join("> <")}>` : "";
+    const description = `[MCP:${serverName}] ${prompt.description?.trim() || prompt.name}${argSig ? ` (args:${argSig})` : ""}`;
+    return {
+        name: displayName,
+        description,
+        source: "mcp",
+        sourceLabel: serverName,
+        async handler(args) {
+            const client = getClient();
+            if (!client) {
+                return `Error: MCP server "${serverName}" is not connected.`;
+            }
+            const values = parsePositionalArgs(args);
+            const mapped = {};
+            for (let i = 0; i < argNames.length; i++) {
+                mapped[argNames[i]] = values[i] ?? "";
+            }
+            const required = (prompt.arguments ?? []).filter((a) => a.required).map((a) => a.name);
+            const missing = required.filter((n) => !mapped[n]);
+            if (missing.length > 0) {
+                return `Error: /${displayName} is missing required arg${missing.length === 1 ? "" : "s"}: ${missing.join(", ")}`;
+            }
+            try {
+                const result = await client.getPrompt(prompt.name, mapped);
+                const text = flattenPromptMessages(result.messages);
+                if (!text.trim()) {
+                    return `Error: /${displayName} returned an empty prompt.`;
+                }
+                return { inject: text };
+            }
+            catch (err) {
+                return `Error calling ${serverName}.${prompt.name}: ${err.message || String(err)}`;
+            }
+        },
+    };
+}
+/**
+ * Split positional args on whitespace, honoring double-quoted phrases so an
+ * argument like `"attention is all you need"` stays intact. Backslash escaping
+ * is not supported — keeps v1 predictable.
+ */
+function parsePositionalArgs(raw) {
+    const out = [];
+    const re = /"([^"]*)"|(\S+)/g;
+    let m;
+    while ((m = re.exec(raw)) !== null) {
+        out.push(m[1] ?? m[2]);
+    }
+    return out;
+}
+/**
+ * Collapse `prompts/get` messages into a single user-input string for the
+ * agent. Text from every message is concatenated; non-text blocks are
+ * annotated. Role labels are preserved only when the prompt mixes roles, so
+ * simple single-user-message prompts pass through cleanly.
+ */
+function flattenPromptMessages(messages) {
+    const allUser = messages.every((m) => m.role === "user");
+    const parts = [];
+    for (const msg of messages) {
+        const blocks = Array.isArray(msg.content) ? msg.content : [msg.content];
+        const text = blocks.map(promptBlockToText).filter(Boolean).join("\n");
+        if (!text)
+            continue;
+        parts.push(allUser ? text : `[${msg.role}]\n${text}`);
+    }
+    return parts.join("\n\n");
+}
+function promptBlockToText(block) {
+    if (block.type === "text" && typeof block.text === "string")
+        return block.text;
+    if (block.type === "resource")
+        return `[resource: ${block.mimeType ?? "unknown"}]`;
+    if (block.type === "image")
+        return `[image: ${block.mimeType ?? "unknown"}]`;
+    return `[${block.type}]`;
+}
+function formatToolContent(content) {
+    const parts = [];
+    for (const item of content) {
+        if (item.type === "text" && typeof item.text === "string") {
+            parts.push(item.text);
+        }
+        else if (item.type === "image" && item.mimeType) {
+            parts.push(`[image: ${item.mimeType}, ${(item.data?.length ?? 0)} bytes base64]`);
+        }
+        else if (item.type === "resource") {
+            parts.push(`[resource: ${item.mimeType ?? "unknown"}]`);
+        }
+        else {
+            parts.push(`[${item.type}]`);
+        }
+    }
+    return parts.join("\n");
+}
+/**
+ * Puts MCP tools behind the approval controller. MCP servers can do anything
+ * (open PRs, post messages, write databases) and their read-only hints are
+ * self-reported, so each call is an `external_tool` request: allowed by rules
+ * (`mcp__server__tool`, or `mcp__server` for the whole server), a session
+ * grant, or bypassPermissions — otherwise the user is asked.
+ */
+export function gateMcpTools(tools, approval) {
+    if (!approval)
+        return tools;
+    return tools.map((tool) => ({
+        ...tool,
+        requiresApproval: true,
+        async execute(args, ctx) {
+            const gate = await gateToolAction(approval, {
+                type: "external_tool",
+                toolCallId: ctx?.toolCall?.id ?? "",
+                title: tool.name,
+                kind: "mcp",
+                rawInput: args,
+            });
+            if (!gate.approved)
+                return gate.result;
+            return tool.execute(args, ctx);
+        },
+    }));
+}

package/dist/mcp/name.d.ts

@@ -0,0 +1,26 @@
+/**
+ * MCP tool / server name normalization.
+ *
+ * Mirrors Claude Code's convention so that permission rules written for Claude
+ * Code-style `mcp__<server>__<tool>` names work the same here.
+ *
+ * The OpenAI tool name pattern is roughly /^[a-zA-Z0-9_-]{1,64}$/. We replace
+ * any character outside that set with an underscore. Server and tool names are
+ * normalized independently so a "." or " " in a server name can't collide with
+ * the "__" delimiter.
+ */
+export declare function normalizeNameForMCP(name: string): string;
+export declare function getMcpPrefix(serverName: string): string;
+export declare function buildMcpToolName(serverName: string, toolName: string): string;
+/**
+ * Parse a tool name back to its server + tool components.
+ *
+ * Known limitation (inherited from Claude Code): if a server name contains
+ * "__", the split is ambiguous. In that case we greedily take the first segment
+ * as the server. Since server names come from user config and typically don't
+ * contain double underscores, this is acceptable in v1.
+ */
+export declare function mcpInfoFromString(toolString: string): {
+    serverName: string;
+    toolName: string;
+} | null;

package/dist/mcp/name.js

@@ -0,0 +1,40 @@
+/**
+ * MCP tool / server name normalization.
+ *
+ * Mirrors Claude Code's convention so that permission rules written for Claude
+ * Code-style `mcp__<server>__<tool>` names work the same here.
+ *
+ * The OpenAI tool name pattern is roughly /^[a-zA-Z0-9_-]{1,64}$/. We replace
+ * any character outside that set with an underscore. Server and tool names are
+ * normalized independently so a "." or " " in a server name can't collide with
+ * the "__" delimiter.
+ */
+export function normalizeNameForMCP(name) {
+    return name.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+export function getMcpPrefix(serverName) {
+    return `mcp__${normalizeNameForMCP(serverName)}__`;
+}
+export function buildMcpToolName(serverName, toolName) {
+    return `${getMcpPrefix(serverName)}${normalizeNameForMCP(toolName)}`;
+}
+/**
+ * Parse a tool name back to its server + tool components.
+ *
+ * Known limitation (inherited from Claude Code): if a server name contains
+ * "__", the split is ambiguous. In that case we greedily take the first segment
+ * as the server. Since server names come from user config and typically don't
+ * contain double underscores, this is acceptable in v1.
+ */
+export function mcpInfoFromString(toolString) {
+    const parts = toolString.split("__");
+    if (parts.length < 3 || parts[0] !== "mcp")
+        return null;
+    const serverName = parts[1];
+    if (!serverName)
+        return null;
+    const toolName = parts.slice(2).join("__");
+    if (!toolName)
+        return null;
+    return { serverName, toolName };
+}

package/dist/mcp/transports.d.ts

@@ -0,0 +1,54 @@
+/**
+ * MCP transports — minimal, dependency-free JSON-RPC clients.
+ *
+ * Two transports in v1:
+ *   - StdioTransport: child process, line-delimited JSON on stdin/stdout
+ *   - HttpTransport: POST JSON-RPC over HTTP (Streamable HTTP), handle both
+ *     application/json and text/event-stream responses. Also used for `sse`
+ *     servers — the spec lets a server respond with either content-type.
+ *
+ * These deliberately do NOT depend on @modelcontextprotocol/sdk. The SDK pulls
+ * in zod + schema machinery we don't need. Our surface area here is small:
+ * initialize + tools/list + tools/call. Adding more methods is just more
+ * JSON-RPC calls on the same pipe.
+ */
+import type { HttpServerConfig, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, McpTransport, SseServerConfig, StdioServerConfig } from "./types.js";
+type IncomingHandler = (msg: JsonRpcResponse | JsonRpcNotification | JsonRpcRequest) => void;
+export declare const MCP_HTTP_CLOSE_TIMEOUT_MS = 750;
+export declare class StdioTransport implements McpTransport {
+    private readonly config;
+    private child?;
+    private buffer;
+    private stderrBuffer;
+    private messageHandler?;
+    private errorHandler?;
+    private closeHandler?;
+    private closed;
+    constructor(config: StdioServerConfig);
+    start(): Promise<void>;
+    private onStdout;
+    send(message: JsonRpcRequest | JsonRpcNotification | JsonRpcResponse): Promise<void>;
+    onMessage(handler: IncomingHandler): void;
+    onError(handler: (err: Error) => void): void;
+    onClose(handler: () => void): void;
+    close(): Promise<void>;
+    getStderr(): string;
+}
+export declare class HttpTransport implements McpTransport {
+    private messageHandler?;
+    private errorHandler?;
+    private closeHandler?;
+    private sessionId?;
+    private closed;
+    private readonly url;
+    private readonly baseHeaders;
+    constructor(config: HttpServerConfig | SseServerConfig);
+    start(): Promise<void>;
+    send(message: JsonRpcRequest | JsonRpcNotification | JsonRpcResponse): Promise<void>;
+    private parseSseBody;
+    onMessage(handler: IncomingHandler): void;
+    onError(handler: (err: Error) => void): void;
+    onClose(handler: () => void): void;
+    close(): Promise<void>;
+}
+export {};