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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.26.7.dev4
+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.dev4 → 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.dev4'
-__version_tuple__ = version_tuple = (0, 26, 7, 'dev4')
+__version__ = version = '0.26.7.dev6'
+__version_tuple__ = version_tuple = (0, 26, 7, 'dev6')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.26.7.dev4 → 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.dev4 → ouroboros_ai-0.26.7.dev6}/src/ouroboros/mcp/server/adapter.py

@@ -569,6 +569,7 @@ def create_ouroboros_server(
     state_dir: Any | None = None,
     runtime_backend: str | None = None,
     llm_backend: str | None = None,
+    mcp_bridge: Any | None = None,
 ) -> MCPServerAdapter:
     """Create an Ouroboros MCP server with all tools and dependencies wired.
 
@@ -1239,6 +1240,15 @@ def create_ouroboros_server(
     # The server owns the shared event store lifecycle
     server.register_owned_resource(event_store)
 
+    # Inject bridge into all BridgeAwareMixin handlers (loop-based auto-discovery)
+    if mcp_bridge is not None:
+        from ouroboros.mcp.tools.bridge_mixin import inject_bridge
+
+        injected = [type(h).__name__ for h in tool_handlers if inject_bridge(h, mcp_bridge)]
+        if injected:
+            log.info("mcp.bridge.injected", handlers=injected)
+        server.register_owned_resource(mcp_bridge)
+
     # Register all tools with the server
     for handler in tool_handlers:
         server.register_tool(handler)

ouroboros_ai-0.26.7.dev6/src/ouroboros/mcp/tools/bridge_mixin.py

@@ -0,0 +1,52 @@
+"""BridgeAwareMixin for MCP tool handlers that need external MCP access.
+
+Handlers that inherit from this mixin will automatically receive
+an MCPClientManager reference when an MCPBridge is configured,
+via loop-based injection in the composition root.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class BridgeAwareMixin:
+    """Mixin for handlers that need access to external MCP servers.
+
+    Provides ``mcp_manager`` and ``mcp_tool_prefix`` fields that are
+    injected by the composition root when an MCPBridge is configured.
+    Both fields default to None/"" so handlers work without a bridge.
+
+    Usage::
+
+        @dataclass
+        class MyHandler(BridgeAwareMixin):
+            other_field: str = ""
+
+            async def handle(self, arguments):
+                if self.mcp_manager:
+                    tools = await self.mcp_manager.list_all_tools()
+    """
+
+    mcp_manager: Any | None = field(default=None, repr=False)
+    mcp_tool_prefix: str = ""
+
+
+def inject_bridge(handler: object, bridge: object | None) -> bool:
+    """Inject bridge manager into a BridgeAwareMixin handler.
+
+    Args:
+        handler: A tool handler, possibly BridgeAwareMixin.
+        bridge: An MCPBridge instance (must have .manager and .tool_prefix).
+
+    Returns:
+        True if injection was performed, False otherwise.
+    """
+    if bridge is None or not isinstance(handler, BridgeAwareMixin):
+        return False
+
+    handler.mcp_manager = getattr(bridge, "manager", None)
+    handler.mcp_tool_prefix = getattr(bridge, "tool_prefix", "")
+    return True

{ouroboros_ai-0.26.7.dev4 → 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.dev4 → ouroboros_ai-0.26.7.dev6}/src/ouroboros/mcp/tools/execution_handlers.py

@@ -32,6 +32,7 @@ from ouroboros.core.worktree import (
 from ouroboros.evaluation.verification_artifacts import build_verification_artifacts
 from ouroboros.mcp.errors import MCPServerError, MCPToolError
 from ouroboros.mcp.job_manager import JobLinks, JobManager
+from ouroboros.mcp.tools.bridge_mixin import BridgeAwareMixin
 from ouroboros.mcp.types import (
     ContentType,
     MCPContentItem,
@@ -97,7 +98,7 @@ def _extract_inherited_effective_tools(arguments: dict[str, Any]) -> list[str] |
 
 
 @dataclass
-class ExecuteSeedHandler:
+class ExecuteSeedHandler(BridgeAwareMixin):
     """Handler for the execute_seed tool.
 
     Executes a seed (task specification) in the Ouroboros system.
@@ -394,6 +395,8 @@ class ExecuteSeedHandler:
                     adapter=agent_adapter,
                     event_store=event_store,
                     console=console,
+                    mcp_manager=self.mcp_manager,
+                    mcp_tool_prefix=self.mcp_tool_prefix,
                     debug=False,
                     enable_decomposition=True,
                     inherited_runtime_handle=inherited_runtime_handle,

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_"