@bubblebrain-ai/bubble 0.0.1

package/dist/mcp/config.js

@@ -0,0 +1,127 @@
+/**
+ * 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.
+ *
+ * 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";
+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();
+    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;
+        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,55 @@
+/**
+ * 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 { 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. */
+    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[];
+}

package/dist/mcp/manager.js

@@ -0,0 +1,296 @@
+/**
+ * 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 { 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. */
+    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.
+        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");
+}

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,53 @@
+/**
+ * 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 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): 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): Promise<void>;
+    private parseSseBody;
+    onMessage(handler: IncomingHandler): void;
+    onError(handler: (err: Error) => void): void;
+    onClose(handler: () => void): void;
+    close(): Promise<void>;
+}
+export {};