ouroboros-ai 0.26.7.dev5__tar.gz → 0.26.7.dev6__tar.gz

{ouroboros_ai-0.26.7.dev5 → ouroboros_ai-0.26.7.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.26.7.dev5
+Version: 0.26.7.dev6
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

ouroboros_ai-0.26.7.dev6/docs/guides/mcp-bridge.md

@@ -0,0 +1,93 @@
+# MCP Bridge — Server-to-Server Communication
+
+## Overview
+
+The MCP Bridge module enables an MCP server (like Ouroboros) to connect to and
+consume tools from other MCP servers during execution. This solves the problem
+where `execute_seed` runs in isolation without access to external MCP tools.
+
+## Architecture
+
+```
+Claude Session (Host)
+    │
+    └── Ouroboros MCP Server
+            │
+            ├── MCPBridge
+            │     └── MCPClientManager
+            │           ├── openchrome MCP
+            │           ├── filesystem MCP
+            │           └── database MCP
+            │
+            └── ExecuteSeedHandler
+                  └── OrchestratorRunner (merged tools)
+                        └── Child Agent (native + external tools)
+```
+
+## Quick Start
+
+### 1. Create config file
+
+Create `~/.ouroboros/mcp_servers.yaml`:
+
+```yaml
+mcp_servers:
+  - name: openchrome
+    transport: stdio
+    command: npx
+    args: ["-y", "openchrome-mcp@latest", "serve", "--auto-launch"]
+
+connection:
+  timeout_seconds: 30
+  retry_attempts: 3
+```
+
+### 2. Start MCP server
+
+```bash
+ouroboros mcp serve
+# Output: MCP Bridge: 1/1 upstream server(s) connected
+```
+
+### 3. Execute seed with external tools
+
+The child agent now has access to all upstream MCP tools during execution.
+
+## Python API
+
+### MCPBridge
+
+```python
+from ouroboros.mcp.bridge import MCPBridge, MCPBridgeConfig
+
+# Async context manager
+async with MCPBridge.from_config_file(Path("mcp.yaml")) as bridge:
+    tools = await bridge.manager.list_all_tools()
+
+# Manual lifecycle
+bridge = MCPBridge.from_config(config)
+await bridge.connect()
+await bridge.disconnect()
+```
+
+### Factory Functions
+
+```python
+from ouroboros.mcp.bridge import create_bridge_from_env
+
+bridge = create_bridge_from_env()  # Auto-discovers config
+if bridge:
+    await bridge.connect()
+```
+
+## Config Discovery
+
+Checked in order:
+1. `$OUROBOROS_MCP_CONFIG` environment variable
+2. `~/.ouroboros/mcp_servers.yaml`
+3. `{cwd}/.ouroboros/mcp_servers.yaml`
+
+## Known Limitations
+
+- Evolution loop (`evolve_step`) does not yet pass the bridge manager
+- No dynamic server addition after initial connection

{ouroboros_ai-0.26.7.dev5 → ouroboros_ai-0.26.7.dev6}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.26.7.dev5'
-__version_tuple__ = version_tuple = (0, 26, 7, 'dev5')
+__version__ = version = '0.26.7.dev6'
+__version_tuple__ = version_tuple = (0, 26, 7, 'dev6')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.26.7.dev5 → ouroboros_ai-0.26.7.dev6}/src/ouroboros/cli/commands/mcp.py

@@ -155,6 +155,21 @@ async def _run_mcp_server(
         # Auto-cleanup is best-effort — don't prevent server from starting
         _stderr_console.print(f"[yellow]Warning: auto-cleanup failed: {e}[/yellow]")
 
+    # Auto-discover and connect MCP bridge for server-to-server communication
+    from ouroboros.mcp.bridge import create_bridge_from_env
+
+    mcp_bridge = create_bridge_from_env(cwd=Path.cwd())
+    if mcp_bridge is not None:
+        try:
+            results = await mcp_bridge.connect()
+            connected = sum(1 for r in results.values() if r.is_ok)
+            _stderr_console.print(
+                f"[blue]MCP Bridge: {connected}/{len(results)} upstream server(s) connected[/blue]"
+            )
+        except Exception as e:
+            _stderr_console.print(f"[yellow]MCP Bridge connection failed: {e}[/yellow]")
+            mcp_bridge = None
+
     # Create server with all tools pre-registered via dependency injection.
     # Do NOT re-register OUROBOROS_TOOLS here — create_ouroboros_server already
     # registers handlers with proper dependencies (event_store, llm_adapter, etc.).
@@ -164,6 +179,7 @@ async def _run_mcp_server(
         event_store=event_store,
         runtime_backend=runtime_backend,
         llm_backend=llm_backend,
+        mcp_bridge=mcp_bridge,
     )
 
     tool_count = len(server.info.tools)

ouroboros_ai-0.26.7.dev6/src/ouroboros/mcp/bridge/__init__.py

@@ -0,0 +1,22 @@
+"""MCP Bridge — Reusable server-to-server communication layer.
+
+This module provides a lifecycle-managed bridge that allows an MCP server
+to connect to and consume tools from other MCP servers during execution.
+"""
+
+from ouroboros.mcp.bridge.bridge import MCPBridge
+from ouroboros.mcp.bridge.config import MCPBridgeConfig, load_bridge_config
+from ouroboros.mcp.bridge.factory import (
+    create_bridge,
+    create_bridge_from_config_file,
+    create_bridge_from_env,
+)
+
+__all__ = [
+    "MCPBridge",
+    "MCPBridgeConfig",
+    "create_bridge",
+    "create_bridge_from_config_file",
+    "create_bridge_from_env",
+    "load_bridge_config",
+]

ouroboros_ai-0.26.7.dev6/src/ouroboros/mcp/bridge/bridge.py

@@ -0,0 +1,88 @@
+"""MCPBridge — lifecycle-managed server-to-server MCP connections."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ouroboros.core.types import Result
+from ouroboros.mcp.bridge.config import MCPBridgeConfig, load_bridge_config
+from ouroboros.mcp.client.manager import MCPClientManager
+from ouroboros.mcp.types import MCPServerInfo
+from ouroboros.observability.logging import get_logger
+
+log = get_logger(__name__)
+
+
+@dataclass
+class MCPBridge:
+    """Manages the lifecycle of server-to-server MCP connections."""
+
+    config: MCPBridgeConfig
+    _manager: MCPClientManager = field(init=False, repr=False)
+    _connected: bool = field(default=False, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._manager = MCPClientManager(
+            max_retries=self.config.retry_attempts,
+            health_check_interval=self.config.health_check_interval,
+            default_timeout=self.config.timeout_seconds,
+        )
+
+    @classmethod
+    def from_config(cls, config: MCPBridgeConfig) -> MCPBridge:
+        return cls(config=config)
+
+    @classmethod
+    def from_config_file(cls, path: Path) -> MCPBridge:
+        result = load_bridge_config(path)
+        if result.is_err:
+            raise ValueError(f"Failed to load bridge config from {path}: {result.error}")
+        return cls(config=result.value)
+
+    @property
+    def manager(self) -> MCPClientManager:
+        return self._manager
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+    @property
+    def tool_prefix(self) -> str:
+        return self.config.tool_prefix
+
+    async def connect(self) -> dict[str, Result[MCPServerInfo, Any]]:
+        if self._connected:
+            log.warning("bridge.already_connected")
+            return {}
+        for server_config in self.config.servers:
+            await self._manager.add_server(server_config)
+        results = await self._manager.connect_all()
+        connected_count = sum(1 for r in results.values() if r.is_ok)
+        log.info(
+            "bridge.connected",
+            connected=connected_count,
+            total=len(results),
+            servers=list(results.keys()),
+        )
+        self._connected = True
+        return results
+
+    async def disconnect(self) -> None:
+        if not self._connected:
+            return
+        await self._manager.disconnect_all()
+        self._connected = False
+        log.info("bridge.disconnected")
+
+    async def close(self) -> None:
+        await self.disconnect()
+
+    async def __aenter__(self) -> MCPBridge:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.disconnect()

ouroboros_ai-0.26.7.dev6/src/ouroboros/mcp/bridge/config.py

@@ -0,0 +1,70 @@
+"""Bridge configuration for MCP server-to-server communication."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import os
+from pathlib import Path
+
+from ouroboros.core.types import Result
+from ouroboros.mcp.errors import MCPClientError
+from ouroboros.mcp.types import MCPServerConfig
+from ouroboros.observability.logging import get_logger
+
+log = get_logger(__name__)
+
+_ENV_VAR = "OUROBOROS_MCP_CONFIG"
+_HOME_CONFIG = Path.home() / ".ouroboros" / "mcp_servers.yaml"
+
+
+@dataclass(frozen=True, slots=True)
+class MCPBridgeConfig:
+    """Configuration for an MCP bridge."""
+
+    servers: tuple[MCPServerConfig, ...] = field(default_factory=tuple)
+    timeout_seconds: float = 30.0
+    retry_attempts: int = 3
+    health_check_interval: float = 60.0
+    tool_prefix: str = ""
+
+
+def discover_config(cwd: Path | None = None) -> Path | None:
+    """Auto-discover bridge configuration file."""
+    env_path = os.environ.get(_ENV_VAR)
+    if env_path:
+        p = Path(env_path)
+        if p.is_file():
+            log.info("bridge.config.discovered", source="env", path=str(p))
+            return p
+
+    if _HOME_CONFIG.is_file():
+        log.info("bridge.config.discovered", source="home", path=str(_HOME_CONFIG))
+        return _HOME_CONFIG
+
+    if cwd is not None:
+        cwd_config = cwd / ".ouroboros" / "mcp_servers.yaml"
+        if cwd_config.is_file():
+            log.info("bridge.config.discovered", source="cwd", path=str(cwd_config))
+            return cwd_config
+
+    return None
+
+
+def load_bridge_config(config_path: Path) -> Result[MCPBridgeConfig, MCPClientError]:
+    """Load bridge configuration from a YAML file."""
+    from ouroboros.orchestrator.mcp_config import load_mcp_config
+
+    result = load_mcp_config(config_path)
+    if result.is_err:
+        return Result.err(MCPClientError(f"Failed to load bridge config: {result.error}"))
+
+    client_config = result.value
+    return Result.ok(
+        MCPBridgeConfig(
+            servers=client_config.servers,
+            timeout_seconds=client_config.connection.timeout_seconds,
+            retry_attempts=client_config.connection.retry_attempts,
+            health_check_interval=client_config.connection.health_check_interval,
+            tool_prefix=client_config.tool_prefix,
+        )
+    )

ouroboros_ai-0.26.7.dev6/src/ouroboros/mcp/bridge/factory.py

@@ -0,0 +1,37 @@
+"""Convenience factories for creating MCP bridges."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ouroboros.mcp.bridge.bridge import MCPBridge
+from ouroboros.mcp.bridge.config import MCPBridgeConfig, discover_config, load_bridge_config
+from ouroboros.observability.logging import get_logger
+
+log = get_logger(__name__)
+
+
+async def create_bridge(config: MCPBridgeConfig) -> MCPBridge:
+    bridge = MCPBridge.from_config(config)
+    await bridge.connect()
+    return bridge
+
+
+async def create_bridge_from_config_file(path: Path) -> MCPBridge:
+    bridge = MCPBridge.from_config_file(path)
+    await bridge.connect()
+    return bridge
+
+
+def create_bridge_from_env(cwd: Path | None = None) -> MCPBridge | None:
+    config_path = discover_config(cwd)
+    if config_path is None:
+        return None
+    result = load_bridge_config(config_path)
+    if result.is_err:
+        log.warning(
+            "bridge.factory.config_load_failed", path=str(config_path), error=str(result.error)
+        )
+        return None
+    log.info("bridge.factory.created_from_env", config_path=str(config_path))
+    return MCPBridge.from_config(result.value)

{ouroboros_ai-0.26.7.dev5 → ouroboros_ai-0.26.7.dev6}/src/ouroboros/mcp/tools/definitions.py

@@ -4,6 +4,7 @@ This module re-exports all handler classes from their dedicated modules
 and provides the :func:`get_ouroboros_tools` factory that assembles
 the default handler tuple for MCP registration.
 
+
 Handler modules:
 - execution_handlers: ExecuteSeedHandler, StartExecuteSeedHandler
 - query_handlers: SessionStatusHandler, QueryEventsHandler, ACDashboardHandler
@@ -60,11 +61,15 @@ def execute_seed_handler(
     *,
     runtime_backend: str | None = None,
     llm_backend: str | None = None,
+    mcp_manager: object | None = None,
+    mcp_tool_prefix: str = "",
 ) -> ExecuteSeedHandler:
     """Create an ExecuteSeedHandler instance."""
     return ExecuteSeedHandler(
         agent_runtime_backend=runtime_backend,
         llm_backend=llm_backend,
+        mcp_manager=mcp_manager,
+        mcp_tool_prefix=mcp_tool_prefix,
     )
 
 
@@ -72,11 +77,15 @@ def start_execute_seed_handler(
     *,
     runtime_backend: str | None = None,
     llm_backend: str | None = None,
+    mcp_manager: object | None = None,
+    mcp_tool_prefix: str = "",
 ) -> StartExecuteSeedHandler:
     """Create a StartExecuteSeedHandler instance."""
     execute_handler = ExecuteSeedHandler(
         agent_runtime_backend=runtime_backend,
         llm_backend=llm_backend,
+        mcp_manager=mcp_manager,
+        mcp_tool_prefix=mcp_tool_prefix,
     )
     return StartExecuteSeedHandler(execute_handler=execute_handler)
 
@@ -192,11 +201,15 @@ def get_ouroboros_tools(
     *,
     runtime_backend: str | None = None,
     llm_backend: str | None = None,
+    mcp_manager: object | None = None,
+    mcp_tool_prefix: str = "",
 ) -> OuroborosToolHandlers:
     """Create the default set of Ouroboros MCP tool handlers."""
     execute_seed = ExecuteSeedHandler(
         agent_runtime_backend=runtime_backend,
         llm_backend=llm_backend,
+        mcp_manager=mcp_manager,
+        mcp_tool_prefix=mcp_tool_prefix,
     )
     return (
         execute_seed,

ouroboros_ai-0.26.7.dev6/tests/e2e/mcp_bridge_test_config.yaml

@@ -0,0 +1,9 @@
+mcp_servers:
+  - name: openchrome
+    transport: stdio
+    command: npx
+    args: ["--prefer-online", "-y", "openchrome-mcp@latest", "serve", "--auto-launch"]
+
+connection:
+  timeout_seconds: 30
+  retry_attempts: 2

ouroboros_ai-0.26.7.dev6/tests/integration/mcp/bridge/test_bridge_server_to_server.py

@@ -0,0 +1,82 @@
+"""Integration tests for MCP server-to-server communication via bridge."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from ouroboros.core.types import Result
+from ouroboros.mcp.bridge.bridge import MCPBridge
+from ouroboros.mcp.bridge.config import MCPBridgeConfig
+from ouroboros.mcp.client.manager import MCPClientManager
+from ouroboros.mcp.types import MCPServerConfig, TransportType
+
+
+class TestMCPBridgeReusability:
+    def test_bridge_config_accepts_multiple_servers(self):
+        config = MCPBridgeConfig(
+            servers=(
+                MCPServerConfig(
+                    name="calc", transport=TransportType.STDIO, command="echo", args=("1",)
+                ),
+                MCPServerConfig(
+                    name="greet", transport=TransportType.STDIO, command="echo", args=("2",)
+                ),
+            ),
+            tool_prefix="upstream_",
+        )
+        assert len(config.servers) == 2
+
+    def test_bridge_creates_manager(self):
+        config = MCPBridgeConfig(
+            servers=(
+                MCPServerConfig(name="a", transport=TransportType.STDIO, command="echo", args=()),
+            ),
+        )
+        bridge = MCPBridge.from_config(config)
+        assert isinstance(bridge.manager, MCPClientManager)
+
+    @pytest.mark.asyncio
+    async def test_lifecycle_with_multiple_configs(self):
+        config = MCPBridgeConfig(
+            servers=(
+                MCPServerConfig(
+                    name="s1", transport=TransportType.STDIO, command="echo", args=("1",)
+                ),
+                MCPServerConfig(
+                    name="s2", transport=TransportType.STDIO, command="echo", args=("2",)
+                ),
+            ),
+        )
+        bridge = MCPBridge.from_config(config)
+        with (
+            patch.object(bridge._manager, "add_server", new_callable=AsyncMock) as ma,
+            patch.object(
+                bridge._manager,
+                "connect_all",
+                new_callable=AsyncMock,
+                return_value={"s1": Result.ok(None), "s2": Result.ok(None)},
+            ),
+        ):
+            results = await bridge.connect()
+            assert len(results) == 2
+            assert ma.call_count == 2
+        with patch.object(bridge._manager, "disconnect_all", new_callable=AsyncMock):
+            await bridge.disconnect()
+
+
+class TestBridgeToProviderIntegration:
+    def test_manager_compatible_with_tool_provider(self):
+        from ouroboros.orchestrator.mcp_tools import MCPToolProvider
+
+        bridge = MCPBridge.from_config(MCPBridgeConfig())
+        provider = MCPToolProvider(bridge.manager)
+        assert provider is not None
+
+    def test_manager_with_prefix(self):
+        from ouroboros.orchestrator.mcp_tools import MCPToolProvider
+
+        bridge = MCPBridge.from_config(MCPBridgeConfig(tool_prefix="ext_"))
+        provider = MCPToolProvider(bridge.manager, tool_prefix=bridge.tool_prefix)
+        assert provider._tool_prefix == "ext_"

ouroboros_ai-0.26.7.dev6/tests/unit/mcp/bridge/test_bridge.py

@@ -0,0 +1,72 @@
+"""Tests for MCPBridge lifecycle management."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from ouroboros.mcp.bridge.bridge import MCPBridge
+from ouroboros.mcp.bridge.config import MCPBridgeConfig
+from ouroboros.mcp.types import MCPServerConfig, TransportType
+
+
+@pytest.fixture
+def sample_config() -> MCPBridgeConfig:
+    return MCPBridgeConfig(
+        servers=(
+            MCPServerConfig(
+                name="test-server", transport=TransportType.STDIO, command="echo", args=("hello",)
+            ),
+        ),
+        timeout_seconds=5.0,
+        retry_attempts=1,
+        tool_prefix="test_",
+    )
+
+
+class TestMCPBridge:
+    def test_from_config(self, sample_config):
+        bridge = MCPBridge.from_config(sample_config)
+        assert bridge.config is sample_config
+        assert not bridge.is_connected
+        assert bridge.tool_prefix == "test_"
+
+    @pytest.mark.asyncio
+    async def test_connect_disconnect(self, sample_config):
+        bridge = MCPBridge.from_config(sample_config)
+        with (
+            patch.object(bridge._manager, "add_server", new_callable=AsyncMock),
+            patch.object(bridge._manager, "connect_all", new_callable=AsyncMock, return_value={}),
+        ):
+            await bridge.connect()
+            assert bridge.is_connected
+        with patch.object(bridge._manager, "disconnect_all", new_callable=AsyncMock):
+            await bridge.disconnect()
+            assert not bridge.is_connected
+
+    @pytest.mark.asyncio
+    async def test_double_connect_warns(self, sample_config):
+        bridge = MCPBridge.from_config(sample_config)
+        bridge._connected = True
+        assert await bridge.connect() == {}
+
+    @pytest.mark.asyncio
+    async def test_context_manager(self, sample_config):
+        bridge = MCPBridge.from_config(sample_config)
+        with (
+            patch.object(bridge, "connect", new_callable=AsyncMock) as mc,
+            patch.object(bridge, "disconnect", new_callable=AsyncMock) as md,
+        ):
+            async with bridge as b:
+                assert b is bridge
+            mc.assert_called_once()
+            md.assert_called_once()
+
+    def test_from_config_file_valid(self, tmp_path):
+        f = tmp_path / "mcp.yaml"
+        f.write_text(
+            "mcp_servers:\n  - name: fs\n    transport: stdio\n    command: echo\n    args: ['test']\n"
+        )
+        bridge = MCPBridge.from_config_file(f)
+        assert len(bridge.config.servers) == 1

ouroboros_ai-0.26.7.dev6/tests/unit/mcp/bridge/test_config.py

@@ -0,0 +1,79 @@
+"""Tests for MCPBridgeConfig and config discovery."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from ouroboros.mcp.bridge.config import MCPBridgeConfig, discover_config, load_bridge_config
+
+
+class TestMCPBridgeConfig:
+    def test_default_values(self):
+        config = MCPBridgeConfig()
+        assert config.servers == ()
+        assert config.timeout_seconds == 30.0
+        assert config.retry_attempts == 3
+        assert config.tool_prefix == ""
+
+    def test_frozen(self):
+        config = MCPBridgeConfig()
+        with pytest.raises(AttributeError):
+            config.timeout_seconds = 10.0
+
+    def test_custom_values(self):
+        config = MCPBridgeConfig(timeout_seconds=10.0, retry_attempts=5, tool_prefix="upstream_")
+        assert config.timeout_seconds == 10.0
+        assert config.retry_attempts == 5
+        assert config.tool_prefix == "upstream_"
+
+
+class TestDiscoverConfig:
+    def test_env_var_takes_precedence(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        config_file = tmp_path / "custom.yaml"
+        config_file.write_text("mcp_servers: []")
+        monkeypatch.setenv("OUROBOROS_MCP_CONFIG", str(config_file))
+        assert discover_config() == config_file
+
+    def test_cwd_config(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.delenv("OUROBOROS_MCP_CONFIG", raising=False)
+        cwd_config = tmp_path / ".ouroboros" / "mcp_servers.yaml"
+        cwd_config.parent.mkdir(parents=True)
+        cwd_config.write_text("mcp_servers: []")
+        assert discover_config(cwd=tmp_path) == cwd_config
+
+
+class TestLoadBridgeConfig:
+    def test_load_valid_config(self, tmp_path: Path):
+        config_file = tmp_path / "mcp.yaml"
+        config_file.write_text(
+            "mcp_servers:\n  - name: test\n    transport: stdio\n    command: echo\n    args: ['hi']\nconnection:\n  timeout_seconds: 15\n  retry_attempts: 2\n"
+        )
+        result = load_bridge_config(config_file)
+        assert result.is_ok
+        assert len(result.value.servers) == 1
+        assert result.value.timeout_seconds == 15.0
+
+    def test_load_preserves_tool_prefix_and_health_check(self, tmp_path: Path):
+        config_file = tmp_path / "mcp.yaml"
+        config_file.write_text(
+            "mcp_servers:\n"
+            "  - name: test\n"
+            "    transport: stdio\n"
+            "    command: echo\n"
+            "    args: ['hi']\n"
+            "tool_prefix: upstream_\n"
+            "connection:\n"
+            "  timeout_seconds: 10\n"
+            "  retry_attempts: 1\n"
+            "  health_check_interval: 45.0\n"
+        )
+        result = load_bridge_config(config_file)
+        assert result.is_ok
+        assert result.value.tool_prefix == "upstream_"
+        assert result.value.health_check_interval == 45.0
+
+    def test_load_nonexistent_file(self, tmp_path: Path):
+        result = load_bridge_config(tmp_path / "nonexistent.yaml")
+        assert result.is_err