bub-mcp 0.0.1__tar.gz

bub_mcp-0.0.1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.3
+Name: bub-mcp
+Version: 0.0.1
+Summary: Expose configured MCP servers as Bub tools
+Author: Frost Ming
+Author-email: Frost Ming <me@frostming.com>
+Requires-Dist: fastmcp>=3.2.0,<4
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# bub-mcp
+
+Expose configured MCP servers as Bub tools.
+
+## Configuration
+
+The plugin reads MCP server definitions from a dedicated JSON file under Bub home:
+
+- `~/.bub/mcp.json`
+- or `$BUB_HOME/mcp.json` when `BUB_HOME` is set
+
+The file must contain a top-level `mcpServers` mapping:
+
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "url": "https://weather.example.com/mcp",
+      "transport": "http"
+    },
+    "local": {
+      "command": "python",
+      "args": ["./server.py"]
+    }
+  }
+}
+```
+
+## CLI Usage
+
+Use the CLI to inspect and manage `mcp.json`:
+
+```bash
+bub mcp list
+```
+
+Add an HTTP server:
+
+```bash
+bub mcp add --transport http weather https://weather.example.com/mcp
+```
+
+Add an SSE server with headers:
+
+```bash
+bub mcp add \
+  --transport sse \
+  --header "Authorization: Bearer token" \
+  events \
+  https://events.example.com/mcp
+```
+
+Add a stdio server with environment variables:
+
+```bash
+bub mcp add \
+  --transport stdio \
+  --env API_KEY=secret \
+  filesystem \
+  -- npx -y @modelcontextprotocol/server-filesystem /tmp
+```
+
+Remove a server:
+
+```bash
+bub mcp remove weather
+```
+
+`bub mcp add` writes the server config into `mcp.json` and performs a connection test before exiting.

bub_mcp-0.0.1/README.md

@@ -0,0 +1,69 @@
+# bub-mcp
+
+Expose configured MCP servers as Bub tools.
+
+## Configuration
+
+The plugin reads MCP server definitions from a dedicated JSON file under Bub home:
+
+- `~/.bub/mcp.json`
+- or `$BUB_HOME/mcp.json` when `BUB_HOME` is set
+
+The file must contain a top-level `mcpServers` mapping:
+
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "url": "https://weather.example.com/mcp",
+      "transport": "http"
+    },
+    "local": {
+      "command": "python",
+      "args": ["./server.py"]
+    }
+  }
+}
+```
+
+## CLI Usage
+
+Use the CLI to inspect and manage `mcp.json`:
+
+```bash
+bub mcp list
+```
+
+Add an HTTP server:
+
+```bash
+bub mcp add --transport http weather https://weather.example.com/mcp
+```
+
+Add an SSE server with headers:
+
+```bash
+bub mcp add \
+  --transport sse \
+  --header "Authorization: Bearer token" \
+  events \
+  https://events.example.com/mcp
+```
+
+Add a stdio server with environment variables:
+
+```bash
+bub mcp add \
+  --transport stdio \
+  --env API_KEY=secret \
+  filesystem \
+  -- npx -y @modelcontextprotocol/server-filesystem /tmp
+```
+
+Remove a server:
+
+```bash
+bub mcp remove weather
+```
+
+`bub mcp add` writes the server config into `mcp.json` and performs a connection test before exiting.

bub_mcp-0.0.1/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "bub-mcp"
+version = "0.0.1"
+description = "Expose configured MCP servers as Bub tools"
+readme = "README.md"
+authors = [
+    { name = "Frost Ming", email = "me@frostming.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "fastmcp>=3.2.0,<4",
+    "pydantic-settings>=2.10.1",
+]
+
+[project.entry-points.bub]
+mcp = "bub_mcp.plugin:MCPPlugin"
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]

bub_mcp-0.0.1/src/bub_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""Bub MCP plugin package."""
+

bub_mcp-0.0.1/src/bub_mcp/cli.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import asyncio
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+import typer
+
+if TYPE_CHECKING:
+    from bub_mcp.plugin import MCPChannel, MCPServerState
+
+
+class MCPTransport(StrEnum):
+    HTTP = "http"
+    SSE = "sse"
+    STDIO = "stdio"
+
+
+def _format_server_list(servers: dict[str, MCPServerState]) -> str:
+    lines: list[str] = []
+    lines.append(typer.style("🔌 MCP Tools", bold=True))
+    for name, server in servers.items():
+        lines.append(f"- {name}")
+        if server.connected:
+            lines.append("  Status: Connected")
+            lines.append(
+                f"  Tools: {', '.join(tool.name for tool in server.tools) if server.tools else 'No tools'}"
+            )
+        else:
+            lines.append("  Status: Not connected")
+            if server.error:
+                lines.append(f"  Error: {server.error}")
+    return "\n".join(lines)
+
+
+def _parse_key_value(option_name: str, item: str, separator: str) -> tuple[str, str]:
+    if separator not in item:
+        raise typer.BadParameter(f"{option_name} must be in KEY{separator}VALUE format")
+    key, value = item.split(separator, 1)
+    key = key.strip()
+    value = value.strip()
+    if not key:
+        raise typer.BadParameter(f"{option_name} key must not be blank")
+    return key, value
+
+
+def _build_stdio_server_config(
+    command_args: list[str], env_items: list[str], header_items: list[str]
+) -> dict[str, object]:
+    if not command_args:
+        raise typer.BadParameter("stdio transport requires a command after '--'")
+    if header_items:
+        raise typer.BadParameter("--header is only supported for http or sse transport")
+
+    command, *args = command_args
+    config: dict[str, object] = {"command": command}
+    if args:
+        config["args"] = args
+    if env_items:
+        config["env"] = {
+            key: value
+            for key, value in (
+                _parse_key_value("--env", item, "=") for item in env_items
+            )
+        }
+    return config
+
+
+def _build_remote_server_config(
+    transport: MCPTransport,
+    targets: list[str],
+    env_items: list[str],
+    header_items: list[str],
+) -> dict[str, object]:
+    if env_items:
+        raise typer.BadParameter("--env is only supported for stdio transport")
+    if len(targets) != 1:
+        raise typer.BadParameter(
+            f"{transport.value} transport requires exactly one URL argument"
+        )
+
+    config: dict[str, object] = {"url": targets[0], "transport": transport.value}
+    if header_items:
+        config["headers"] = {
+            key: value
+            for key, value in (
+                _parse_key_value("--header", item, ":") for item in header_items
+            )
+        }
+    return config
+
+
+def _build_server_config(
+    transport: MCPTransport,
+    targets: list[str],
+    env_items: list[str],
+    header_items: list[str],
+) -> dict[str, object]:
+    if transport is MCPTransport.STDIO:
+        return _build_stdio_server_config(targets, env_items, header_items)
+    return _build_remote_server_config(transport, targets, env_items, header_items)
+
+
+def _probe_server(manager: MCPChannel, name: str) -> tuple[bool, str]:
+    try:
+        manager.bootstrap()
+        server = manager.list().get(name)
+        if server is None:
+            return False, f"MCP server '{name}' is missing after bootstrap."
+        rendered = _format_server_list({name: server})
+        if not server.connected:
+            error_message = server.error or "unknown connection error"
+            return False, f"{rendered}\nConnection test failed: {error_message}"
+        return True, rendered
+    finally:
+        asyncio.run(manager.stop())
+
+
+def make_mcp_command(manager: MCPChannel) -> typer.Typer:
+    app = typer.Typer()
+
+    @app.command("list")
+    def list_tools() -> None:
+        """List registered MCP tools."""
+        manager.bootstrap()
+        mcp_tools = manager.list()
+        if not mcp_tools:
+            typer.echo("No MCP tools registered.")
+            return
+        typer.echo(_format_server_list(mcp_tools))
+
+    @app.command("add")
+    def add_server(
+        transport: MCPTransport = typer.Option(
+            ..., "--transport", help="MCP transport: http, sse, or stdio."
+        ),
+        env: list[str] | None = typer.Option(
+            None,
+            "--env",
+            help="Environment variable in KEY=VALUE format for stdio servers.",
+        ),
+        header: list[str] | None = typer.Option(
+            None,
+            "--header",
+            help="Header in 'Name: Value' format for http or sse servers.",
+        ),
+        name: str = typer.Argument(..., help="Server name."),
+        target: list[str] = typer.Argument(
+            ..., help="URL for remote servers, or '-- <command> [args...]' for stdio."
+        ),
+    ) -> None:
+        """Add an MCP server configuration."""
+        server_config = _build_server_config(
+            transport,
+            target,
+            env or [],
+            header or [],
+        )
+        try:
+            asyncio.run(manager.add(name, server_config))
+        except ValueError as exc:
+            raise typer.BadParameter(str(exc)) from exc
+
+        typer.echo(f"Added MCP server '{name}'.")
+        typer.echo(f"Config: {manager.settings.config_path}")
+        connected, output = _probe_server(manager, name)
+        typer.echo("Connection test: ok" if connected else "Connection test: failed")
+        typer.echo(output, err=not connected)
+        if not connected:
+            raise typer.Exit(code=1)
+
+    @app.command("remove")
+    def remove_server(
+        name: str = typer.Argument(..., help="Server name."),
+    ) -> None:
+        """Remove an MCP server configuration."""
+        try:
+            asyncio.run(manager.remove(name))
+        except KeyError as exc:
+            typer.echo(f"MCP server '{name}' does not exist.", err=True)
+            raise typer.Exit(code=1) from exc
+        except ValueError as exc:
+            raise typer.BadParameter(str(exc)) from exc
+
+        typer.echo(f"Removed MCP server '{name}'.")
+        typer.echo(f"Config: {manager.settings.config_path}")
+
+    return app

bub_mcp-0.0.1/src/bub_mcp/config.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import bub
+from pydantic import Field
+from pydantic_settings import SettingsConfigDict
+
+
+def default_config_path() -> Path:
+    return bub.home / "mcp.json"
+
+
+def read_config(config_file: Path) -> dict[str, Any]:
+    if not config_file.exists():
+        return {}
+    loaded = json.loads(config_file.read_text(encoding="utf-8"))
+    if not isinstance(loaded, dict):
+        raise RuntimeError("MCP config file must contain a top-level mapping")
+    return loaded.get("mcpServers", {})
+
+
+@bub.config(name="mcp")
+class MCPSettings(bub.Settings):
+    model_config = SettingsConfigDict(env_prefix="BUB_MCP_", extra="ignore")
+
+    config_path: Path = Field(default_factory=default_config_path)
+    init_timeout_seconds: float | None = 20.0
+
+    def read_mcp_servers(self) -> dict[str, Any]:
+        return read_config(self.config_path)
+
+    def write_mcp_servers(self, mcp_servers: dict[str, Any]) -> None:
+        config = {"mcpServers": mcp_servers}
+        self.config_path.write_text(json.dumps(config, indent=2), encoding="utf-8")

bub_mcp-0.0.1/src/bub_mcp/plugin.py

@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+import fastmcp
+import mcp.types
+import typer
+import bub
+from bub import hookimpl, tool
+from bub.channels import Channel, Lifecycle
+from bub.tools import REGISTRY
+from bub.types import Envelope, MessageHandler, State
+from loguru import logger
+from republic import Tool, ToolContext
+
+from bub_mcp.config import MCPSettings
+
+TOOL_PREFIX = "mcp."
+LIFECYCLE_CHANNEL_NAME = "mcp.lifecycle"
+
+
+def _create_fastmcp_client(
+    config: dict[str, Any], *, init_timeout_seconds: float | None
+) -> fastmcp.Client[Any]:
+
+    kwargs: dict[str, Any] = {}
+    if init_timeout_seconds is not None:
+        kwargs["init_timeout"] = init_timeout_seconds
+    return fastmcp.Client(config, **kwargs)
+
+
+def _tool_name(server_name: str, remote_name: str) -> str:
+    normalized_name = remote_name
+    if not remote_name.startswith(f"{server_name}_"):
+        normalized_name = f"{server_name}_{remote_name}"
+    return f"{TOOL_PREFIX}{normalized_name}"
+
+
+def _tool_parameters(remote_tool: mcp.types.Tool) -> dict[str, Any]:
+    schema = remote_tool.inputSchema
+    if isinstance(schema, dict) and schema.get("type") == "object":
+        return schema
+    return {"type": "object", "properties": {}}
+
+
+def _render_binary_placeholder(kind: str, item: Any) -> str:
+    mime_type = getattr(item, "mimeType", "application/octet-stream")
+    return f"[Binary content: {kind} {mime_type}]"
+
+
+def _format_tool_result(result: Any) -> str:
+    content = getattr(result, "content", []) or []
+    blocks: list[str] = []
+
+    for item in content:
+        item_type = getattr(item, "type", None)
+        if item_type == "text":
+            text = getattr(item, "text", "")
+            if isinstance(text, str) and text:
+                blocks.append(text)
+            continue
+        if item_type == "resource":
+            resource = getattr(item, "resource", None)
+            text = getattr(resource, "text", None)
+            if isinstance(text, str) and text:
+                blocks.append(text)
+                continue
+            uri = getattr(resource, "uri", "unknown")
+            mime_type = getattr(resource, "mimeType", "application/octet-stream")
+            blocks.append(f"[Resource content: {uri} ({mime_type})]")
+            continue
+        if item_type == "image":
+            blocks.append(_render_binary_placeholder("image", item))
+            continue
+        if item_type == "audio":
+            blocks.append(_render_binary_placeholder("audio", item))
+            continue
+
+    structured = getattr(result, "structuredContent", None)
+    if not blocks and structured is not None:
+        return json.dumps(structured, ensure_ascii=False, indent=2, sort_keys=True)
+
+    rendered = "\n".join(blocks).strip()
+    if rendered:
+        return rendered
+
+    is_error = bool(getattr(result, "isError", False))
+    return "error: remote MCP tool returned no content" if is_error else "ok"
+
+
+@dataclass
+class MCPServerState:
+    client: Any | None = None
+    tools: list[Tool] = field(default_factory=list)
+    connected: bool = False
+    error: str | None = None
+
+
+class MCPChannel(Lifecycle):
+    name = LIFECYCLE_CHANNEL_NAME
+
+    def __init__(self) -> None:
+        self.settings = bub.ensure_config(MCPSettings)
+        self._lock = asyncio.Lock()
+        self._bootstrap_task: asyncio.Task[None] | None = None
+        self._servers: dict[str, MCPServerState] = {}
+        self._stop_event: asyncio.Event | None = None
+
+    async def start(self, stop_event: asyncio.Event) -> None:
+        self._stop_event = stop_event
+        if any(server.connected for server in self._servers.values()):
+            return
+        if self._bootstrap_task is not None and not self._bootstrap_task.done():
+            return
+        self._bootstrap_task = asyncio.create_task(
+            self._bootstrap(stop_event), name="bub-mcp.bootstrap"
+        )
+
+    async def stop(self) -> None:
+        task = self._bootstrap_task
+        self._bootstrap_task = None
+        self._stop_event = None
+        if task is not None and not task.done():
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+
+        async with self._lock:
+            clients = [
+                server.client
+                for server in self._servers.values()
+                if server.client is not None
+            ]
+            for server in self._servers.values():
+                server.client = None
+                server.connected = False
+
+        for client in clients:
+            await self._close_client(client)
+
+    def list(self) -> dict[str, MCPServerState]:
+        return self._servers.copy()
+
+    async def add(self, name: str, server: dict[str, Any]) -> dict[str, dict[str, Any]]:
+        server_name = name.strip()
+        if not server_name:
+            raise ValueError("server name must not be blank")
+        if not isinstance(server, dict) or not server:
+            raise ValueError("server config must be a non-empty mapping")
+
+        mcp_servers = self.settings.read_mcp_servers()
+
+        if server_name in mcp_servers:
+            raise ValueError(f"MCP server '{server_name}' already exists")
+        mcp_servers[server_name] = server
+        self.settings.write_mcp_servers(mcp_servers)
+        return mcp_servers
+
+    async def remove(self, name: str) -> dict[str, dict[str, Any]]:
+        server_name = name.strip()
+        if not server_name:
+            raise ValueError("server name must not be blank")
+
+        mcp_servers = self.settings.read_mcp_servers()
+
+        if server_name not in mcp_servers:
+            raise KeyError(server_name)
+        mcp_servers.pop(server_name)
+        self.settings.write_mcp_servers(mcp_servers)
+        return mcp_servers
+
+    async def call_tool(
+        self, server_name: str, remote_name: str, arguments: dict[str, Any]
+    ) -> str:
+        server = self._servers.get(server_name)
+        if server is None or server.client is None:
+            raise RuntimeError(
+                f"MCP client for server '{server_name}' is not connected"
+            )
+        result = await server.client.call_tool(remote_name, arguments or {})
+        return _format_tool_result(result)
+
+    def bootstrap(self) -> None:
+        async def main() -> None:
+            stop_event = asyncio.Event()
+            await self._bootstrap(stop_event)
+
+        asyncio.run(main())
+
+    async def _bootstrap(self, stop_event: asyncio.Event) -> None:
+        async with self._lock:
+            try:
+                config = self.settings.read_mcp_servers()
+                if not config:
+                    self._servers = {}
+                    return
+
+                config_items = list(config.items())
+                server_states = await asyncio.gather(
+                    *[
+                        self._connect_server(server_name, server_config)
+                        for server_name, server_config in config_items
+                    ]
+                )
+
+                self._servers = {
+                    server_name: server_state
+                    for (server_name, _server_config), server_state in zip(
+                        config_items, server_states, strict=False
+                    )
+                }
+
+                for server_name, server in self._servers.items():
+                    for tool in server.tools:
+                        REGISTRY[tool.name] = tool
+
+                if self._servers and not any(
+                    server.connected for server in self._servers.values()
+                ):
+                    stop_event.set()
+            except asyncio.CancelledError:
+                for server in self._servers.values():
+                    if server.client is not None:
+                        await self._close_client(server.client)
+                        server.client = None
+                    server.connected = False
+                raise
+            except Exception as exc:
+                for server in self._servers.values():
+                    if server.client is not None:
+                        await self._close_client(server.client)
+                        server.client = None
+                    server.connected = False
+                logger.warning("bub-mcp bootstrap failed: {}", exc)
+                stop_event.set()
+
+    async def _connect_server(
+        self, server_name: str, server_config: dict[str, Any]
+    ) -> MCPServerState:
+        server = MCPServerState()
+        client: Any | None = None
+        try:
+            client = _create_fastmcp_client(
+                {server_name: server_config},
+                init_timeout_seconds=self.settings.init_timeout_seconds,
+            )
+            await client.__aenter__()
+            remote_tools = await client.list_tools()
+            server.client = client
+            server.connected = True
+            server.error = None
+
+            for remote_tool in remote_tools:
+                tool = self._build_tool(server_name, remote_tool)
+                if tool is not None:
+                    server.tools.append(tool)
+        except asyncio.CancelledError:
+            if client is not None:
+                await self._close_client(client)
+            raise
+        except Exception as exc:
+            if client is not None:
+                await self._close_client(client)
+            self._record_failed_server(server_name, server, exc)
+        return server
+
+    def _build_tool(self, server_name: str, remote_tool: mcp.types.Tool) -> Tool | None:
+        remote_name = remote_tool.name.strip()
+        if not remote_name:
+            return None
+        bub_name = _tool_name(server_name, remote_name)
+        return Tool(
+            name=bub_name,
+            description=str(remote_tool.description or f"MCP tool {remote_name}"),
+            parameters=_tool_parameters(remote_tool),
+            handler=self._make_handler(server_name, remote_name),
+        )
+
+    def _record_failed_server(
+        self, server_name: str, server: MCPServerState, exc: Exception
+    ) -> None:
+        error_message = str(exc) or exc.__class__.__name__
+        server.client = None
+        server.connected = False
+        server.error = error_message
+        logger.warning(
+            "bub-mcp failed to connect MCP server '{}': {}", server_name, error_message
+        )
+
+    def _make_handler(self, server_name: str, remote_name: str):
+        async def _handler(**payload: Any) -> str:
+            return await self.call_tool(server_name, remote_name, payload)
+
+        return _handler
+
+    @staticmethod
+    async def _close_client(client: Any) -> None:
+        with contextlib.suppress(Exception):
+            await client.__aexit__(None, None, None)
+
+
+class MCPPlugin:
+    def __init__(self, framework: Any) -> None:
+        del framework
+        self._manager = MCPChannel()
+
+    @hookimpl
+    def load_state(self, message: Envelope, session_id: str) -> State:
+        return {"mcp": self._manager}
+
+    @hookimpl
+    def provide_channels(self, message_handler: MessageHandler) -> list[Channel]:
+        del message_handler
+        return [self._manager]
+
+    @hookimpl
+    def register_cli_commands(self, app: typer.Typer) -> None:
+        from bub_mcp.cli import make_mcp_command
+
+        app.add_typer(
+            make_mcp_command(self._manager), name="mcp", help="Manage MCP servers"
+        )
+
+
+@tool(name="mcp", context=True)
+def mcp_list(*, context: ToolContext) -> str:
+    """List configured MCP servers."""
+    manager = context.state.get("mcp")
+    if not isinstance(manager, MCPChannel):
+        raise RuntimeError("MCP channel is not available in state")
+    servers = manager.list()
+    if not servers:
+        return "No MCP servers configured."
+    lines: list[str] = []
+    lines.append("🔌 MCP Servers:")
+    for name, server in servers.items():
+        lines.append(f"- {name}")
+        if server.connected:
+            lines.append("  Status: Connected")
+            lines.append(
+                f"  Tools: {', '.join(tool.name for tool in server.tools) if server.tools else 'No tools'}"
+            )
+        else:
+            lines.append("  Status: Not connected")
+            if server.error:
+                lines.append(f"  Error: {server.error}")
+    return "\n".join(lines)

bub_mcp-0.0.1/src/bub_mcp/py.typed

@@ -0,0 +1 @@
+