@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/mcp/client.d.ts

@@ -0,0 +1,68 @@
+/**
+ * MCPClient — protocol layer over a transport.
+ *
+ * Handles JSON-RPC id correlation, the `initialize` handshake, and typed
+ * wrappers for `tools/list` / `tools/call`. Enough surface for the tool
+ * registry to plug MCP tools in; more methods can be added the same way.
+ */
+import type { McpPromptInfo, McpToolInfo, McpTransport } from "./types.js";
+export interface ClientInfo {
+    name: string;
+    version: string;
+}
+export interface ToolCallContent {
+    type: string;
+    text?: string;
+    data?: string;
+    mimeType?: string;
+    [extra: string]: unknown;
+}
+export interface ToolCallResult {
+    content: ToolCallContent[];
+    isError?: boolean;
+    structuredContent?: unknown;
+}
+/** One block from a prompt message. MCP content types mirror tools. */
+export interface PromptContentBlock {
+    type: string;
+    text?: string;
+    data?: string;
+    mimeType?: string;
+    [extra: string]: unknown;
+}
+export interface PromptMessage {
+    role: "user" | "assistant";
+    /** Per MCP spec `content` is a single block; some servers return an array. */
+    content: PromptContentBlock | PromptContentBlock[];
+}
+export interface PromptResult {
+    description?: string;
+    messages: PromptMessage[];
+}
+export declare class MCPClient {
+    private readonly transport;
+    private readonly clientInfo;
+    private readonly defaultTimeoutMs;
+    private nextId;
+    private pending;
+    private closed;
+    private _serverInfo?;
+    private _capabilities?;
+    private _instructions?;
+    constructor(transport: McpTransport, clientInfo: ClientInfo, defaultTimeoutMs?: number);
+    start(): Promise<void>;
+    private initialize;
+    get serverInfo(): {
+        name: string;
+        version: string;
+    } | undefined;
+    get capabilities(): Record<string, unknown> | undefined;
+    get instructions(): string | undefined;
+    listTools(): Promise<McpToolInfo[]>;
+    listPrompts(): Promise<McpPromptInfo[]>;
+    getPrompt(name: string, args: Record<string, string>, timeoutMs?: number): Promise<PromptResult>;
+    callTool(name: string, args: Record<string, unknown>, timeoutMs?: number): Promise<ToolCallResult>;
+    private request;
+    private onMessage;
+    close(): Promise<void>;
+}

package/dist/mcp/client.js

@@ -0,0 +1,177 @@
+/**
+ * MCPClient — protocol layer over a transport.
+ *
+ * Handles JSON-RPC id correlation, the `initialize` handshake, and typed
+ * wrappers for `tools/list` / `tools/call`. Enough surface for the tool
+ * registry to plug MCP tools in; more methods can be added the same way.
+ */
+const PROTOCOL_VERSION = "2025-06-18";
+const DEFAULT_TIMEOUT_MS = 30_000;
+export class MCPClient {
+    transport;
+    clientInfo;
+    defaultTimeoutMs;
+    nextId = 1;
+    pending = new Map();
+    closed = false;
+    _serverInfo;
+    _capabilities;
+    _instructions;
+    constructor(transport, clientInfo, defaultTimeoutMs = DEFAULT_TIMEOUT_MS) {
+        this.transport = transport;
+        this.clientInfo = clientInfo;
+        this.defaultTimeoutMs = defaultTimeoutMs;
+        transport.onMessage((msg) => this.onMessage(msg));
+        transport.onError((err) => {
+            // Fail all outstanding calls; the manager will surface this.
+            for (const [, pending] of this.pending) {
+                clearTimeout(pending.timer);
+                pending.reject(err);
+            }
+            this.pending.clear();
+        });
+        transport.onClose(() => {
+            this.closed = true;
+            for (const [, pending] of this.pending) {
+                clearTimeout(pending.timer);
+                pending.reject(new Error("MCP transport closed"));
+            }
+            this.pending.clear();
+        });
+    }
+    async start() {
+        await this.transport.start();
+        await this.initialize();
+    }
+    async initialize() {
+        const result = (await this.request("initialize", {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: this.clientInfo,
+        }));
+        this._serverInfo = result.serverInfo;
+        this._capabilities = result.capabilities;
+        this._instructions = result.instructions;
+        // Per spec, client must send `notifications/initialized` after the response.
+        await this.transport.send({
+            jsonrpc: "2.0",
+            method: "notifications/initialized",
+        });
+    }
+    get serverInfo() {
+        return this._serverInfo;
+    }
+    get capabilities() {
+        return this._capabilities;
+    }
+    get instructions() {
+        return this._instructions;
+    }
+    async listTools() {
+        const tools = [];
+        let cursor;
+        do {
+            const result = (await this.request("tools/list", cursor ? { cursor } : {}));
+            if (Array.isArray(result.tools)) {
+                for (const t of result.tools) {
+                    tools.push({
+                        name: t.name,
+                        description: t.description,
+                        inputSchema: t.inputSchema,
+                    });
+                }
+            }
+            cursor = result.nextCursor;
+        } while (cursor);
+        return tools;
+    }
+    async listPrompts() {
+        const prompts = [];
+        let cursor;
+        do {
+            const result = (await this.request("prompts/list", cursor ? { cursor } : {}));
+            if (Array.isArray(result.prompts)) {
+                for (const p of result.prompts) {
+                    prompts.push({
+                        name: p.name,
+                        description: p.description,
+                        arguments: p.arguments,
+                    });
+                }
+            }
+            cursor = result.nextCursor;
+        } while (cursor);
+        return prompts;
+    }
+    async getPrompt(name, args, timeoutMs) {
+        const result = (await this.request("prompts/get", { name, arguments: args }, timeoutMs));
+        return {
+            description: result.description,
+            messages: Array.isArray(result.messages) ? result.messages : [],
+        };
+    }
+    async callTool(name, args, timeoutMs) {
+        const result = (await this.request("tools/call", { name, arguments: args }, timeoutMs));
+        return {
+            content: Array.isArray(result.content) ? result.content : [],
+            isError: result.isError,
+            structuredContent: result.structuredContent,
+        };
+    }
+    request(method, params, timeoutMs) {
+        if (this.closed)
+            return Promise.reject(new Error("MCP client is closed"));
+        const id = this.nextId++;
+        const req = { jsonrpc: "2.0", id, method, params };
+        return new Promise((resolve, reject) => {
+            const ms = timeoutMs ?? this.defaultTimeoutMs;
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`MCP request "${method}" timed out after ${ms}ms`));
+            }, ms);
+            this.pending.set(id, { resolve, reject, timer });
+            this.transport.send(req).catch((err) => {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            });
+        });
+    }
+    onMessage(msg) {
+        // Response: has "id" plus "result" or "error".
+        if ("id" in msg && (("result" in msg) || ("error" in msg))) {
+            const id = typeof msg.id === "number" ? msg.id : Number(msg.id);
+            const pending = this.pending.get(id);
+            if (!pending)
+                return;
+            this.pending.delete(id);
+            clearTimeout(pending.timer);
+            if ("error" in msg && msg.error) {
+                pending.reject(new Error(`${msg.error.message} (code ${msg.error.code})`));
+            }
+            else {
+                pending.resolve(msg.result);
+            }
+            return;
+        }
+        // Ping is a core MCP request and requires no advertised capability. Long-lived
+        // servers (including Playwright) close healthy sessions when it is ignored.
+        if ("id" in msg && "method" in msg) {
+            const response = msg.method === "ping"
+                ? { jsonrpc: "2.0", id: msg.id, result: {} }
+                : { jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: `Unsupported client method: ${msg.method}` } };
+            void this.transport.send(response).catch((error) => {
+                for (const pending of this.pending.values()) {
+                    clearTimeout(pending.timer);
+                    pending.reject(error instanceof Error ? error : new Error(String(error)));
+                }
+                this.pending.clear();
+            });
+        }
+        // Notifications need no response; sampling and roots are not advertised.
+    }
+    async close() {
+        this.closed = true;
+        await this.transport.close();
+    }
+}

package/dist/mcp/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Load and validate mcpServers from user / project / local settings files.
+ *
+ * Precedence: later scope wins (user → project → local). Each server is
+ * identified by its key in mcpServers; if the same name appears in multiple
+ * scopes, the higher-precedence scope overwrites, and we record a diagnostic.
+ *
+ * Servers from the project and local files arrive with the repository and
+ * Bubble would spawn their commands at startup, so they are skipped until the
+ * user trusts the folder (asked at startup, trust.ts).
+ *
+ * Env expansion: ${VAR} in command, args, env values, url, or header values
+ * is replaced with the matching process.env entry. Missing vars become empty
+ * strings and yield a diagnostic (non-fatal).
+ */
+import type { ScopedMcpServerConfig } from "./types.js";
+export interface McpConfigDiagnostic {
+    scope: "user" | "project" | "local";
+    path: string;
+    message: string;
+}
+export interface LoadedMcpConfig {
+    servers: ScopedMcpServerConfig[];
+    diagnostics: McpConfigDiagnostic[];
+}
+export interface LoadMcpConfigOptions {
+    cwd: string;
+    bubbleHome?: string;
+}
+export declare function loadMcpConfig(options: LoadMcpConfigOptions): LoadedMcpConfig;

package/dist/mcp/config.js

@@ -0,0 +1,144 @@
+/**
+ * Load and validate mcpServers from user / project / local settings files.
+ *
+ * Precedence: later scope wins (user → project → local). Each server is
+ * identified by its key in mcpServers; if the same name appears in multiple
+ * scopes, the higher-precedence scope overwrites, and we record a diagnostic.
+ *
+ * Servers from the project and local files arrive with the repository and
+ * Bubble would spawn their commands at startup, so they are skipped until the
+ * user trusts the folder (asked at startup, trust.ts).
+ *
+ * Env expansion: ${VAR} in command, args, env values, url, or header values
+ * is replaced with the matching process.env entry. Missing vars become empty
+ * strings and yield a diagnostic (non-fatal).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getBubbleHome } from "../bubble-home.js";
+import { isRepoConfigTrusted, readRepoSettings } from "../permissions/trust.js";
+export function loadMcpConfig(options) {
+    const bubbleHome = options.bubbleHome ?? getBubbleHome();
+    const paths = {
+        user: join(bubbleHome, "settings.json"),
+        project: join(options.cwd, ".bubble", "settings.json"),
+        local: join(options.cwd, ".bubble", "settings.local.json"),
+    };
+    const diagnostics = [];
+    const merged = new Map();
+    const repoTrusted = isRepoConfigTrusted(options.cwd, readRepoSettings(options.cwd), { bubbleHome });
+    for (const scope of ["user", "project", "local"]) {
+        const path = paths[scope];
+        if (!existsSync(path))
+            continue;
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(path, "utf-8"));
+        }
+        catch (err) {
+            diagnostics.push({ scope, path, message: `Failed to parse: ${err.message}` });
+            continue;
+        }
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const mcpServers = raw.mcpServers;
+        if (!mcpServers || typeof mcpServers !== "object" || Array.isArray(mcpServers))
+            continue;
+        if (scope !== "user" && !repoTrusted) {
+            const names = Object.keys(mcpServers);
+            if (names.length > 0) {
+                diagnostics.push({
+                    scope,
+                    path,
+                    message: `Skipped MCP server${names.length === 1 ? "" : "s"} ${names.join(", ")} from this repository: the folder is not trusted (Bubble asks at startup).`,
+                });
+            }
+            continue;
+        }
+        for (const [name, value] of Object.entries(mcpServers)) {
+            const validated = validateServerConfig(value, (msg) => {
+                diagnostics.push({ scope, path, message: `mcpServers.${name}: ${msg}` });
+            });
+            if (!validated)
+                continue;
+            const expanded = expandConfigEnv(validated, (missing) => {
+                diagnostics.push({
+                    scope,
+                    path,
+                    message: `mcpServers.${name}: env var "${missing}" is not set; expanded to empty string.`,
+                });
+            });
+            if (merged.has(name)) {
+                diagnostics.push({
+                    scope,
+                    path,
+                    message: `mcpServers.${name}: overrides entry from ${merged.get(name).scope} scope.`,
+                });
+            }
+            merged.set(name, { name, scope, config: expanded });
+        }
+    }
+    return { servers: [...merged.values()], diagnostics };
+}
+function validateServerConfig(value, report) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        report("expected an object");
+        return null;
+    }
+    const v = value;
+    const type = typeof v.type === "string" ? v.type : v.command ? "stdio" : undefined;
+    if (type === "stdio") {
+        if (typeof v.command !== "string" || !v.command.trim()) {
+            report('stdio server requires a non-empty "command"');
+            return null;
+        }
+        const args = Array.isArray(v.args) ? v.args.filter((a) => typeof a === "string") : [];
+        const env = v.env && typeof v.env === "object" && !Array.isArray(v.env)
+            ? Object.fromEntries(Object.entries(v.env).filter(([, val]) => typeof val === "string"))
+            : undefined;
+        const cwd = typeof v.cwd === "string" ? v.cwd : undefined;
+        return { type: "stdio", command: v.command, args, env, cwd };
+    }
+    if (type === "http" || type === "sse") {
+        if (typeof v.url !== "string" || !v.url.trim()) {
+            report(`${type} server requires a non-empty "url"`);
+            return null;
+        }
+        const headers = v.headers && typeof v.headers === "object" && !Array.isArray(v.headers)
+            ? Object.fromEntries(Object.entries(v.headers).filter(([, val]) => typeof val === "string"))
+            : undefined;
+        return { type, url: v.url, headers };
+    }
+    report(`unsupported transport type "${String(v.type)}" (expected "stdio", "http", or "sse")`);
+    return null;
+}
+function expandEnv(input, onMissing) {
+    return input.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => {
+        const value = process.env[name];
+        if (value === undefined) {
+            onMissing(name);
+            return "";
+        }
+        return value;
+    });
+}
+function expandConfigEnv(config, onMissing) {
+    if (config.type === "stdio") {
+        return {
+            type: "stdio",
+            command: expandEnv(config.command, onMissing),
+            args: config.args?.map((a) => expandEnv(a, onMissing)),
+            env: config.env
+                ? Object.fromEntries(Object.entries(config.env).map(([k, v]) => [k, expandEnv(v, onMissing)]))
+                : undefined,
+            cwd: config.cwd ? expandEnv(config.cwd, onMissing) : undefined,
+        };
+    }
+    return {
+        type: config.type,
+        url: expandEnv(config.url, onMissing),
+        headers: config.headers
+            ? Object.fromEntries(Object.entries(config.headers).map(([k, v]) => [k, expandEnv(v, onMissing)]))
+            : undefined,
+    };
+}

package/dist/mcp/manager.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 type { ToolRegistryEntry } from "../types.js";
+import type { ApprovalController } from "../approval/types.js";
+import type { UnifiedCommand } from "../slash-commands/unified.js";
+import type { McpServerState, ScopedMcpServerConfig } from "./types.js";
+export interface McpManagerOptions {
+    servers: ScopedMcpServerConfig[];
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** Log callback for non-fatal issues. Defaults to stderr. */
+    onDiagnostic?: (message: string) => void;
+}
+export declare class McpManager {
+    private readonly options;
+    private connections;
+    private readonly clientInfo;
+    private readonly onDiagnostic;
+    constructor(options: McpManagerOptions);
+    /** Connect all configured servers. Never throws — per-server errors are captured in state. */
+    start(): Promise<void>;
+    private connectOne;
+    /** Disconnect and reconnect a single server. Returns the new state. */
+    reconnect(name: string): Promise<McpServerState | null>;
+    /** Shutdown all connections. Best-effort; errors are ignored. */
+    shutdown(): Promise<void>;
+    getStates(): McpServerState[];
+    /**
+     * Produce ToolRegistryEntry[] for every tool from every connected server.
+     * Hosts must pass them through gateMcpTools before handing them to an agent.
+     */
+    getToolEntries(): ToolRegistryEntry[];
+    /**
+     * 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(): UnifiedCommand[];
+}
+/**
+ * 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 declare function gateMcpTools(tools: ToolRegistryEntry[], approval: ApprovalController | undefined): ToolRegistryEntry[];