chora-mcp-orchestration 0.1.0__tar.gz

chora_mcp_orchestration-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: chora-mcp-orchestration
+Version: 0.1.0
+Summary: MCP server orchestration CLI and HTTP server for managing Docker-based MCP services
+License: MIT
+Keywords: mcp,orchestration,docker,deployment
+Author: Liminal Commons
+Author-email: team@liminalcommons.org
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: click (>=8.1.0,<9.0.0)
+Requires-Dist: docker (>=7.0.0,<8.0.0)
+Requires-Dist: fastapi (>=0.109.0,<0.110.0)
+Requires-Dist: httpx (>=0.26.0,<0.27.0)
+Requires-Dist: pydantic (>=2.5.0,<3.0.0)
+Requires-Dist: pyyaml (>=6.0,<7.0)
+Requires-Dist: uvicorn (>=0.27.0,<0.28.0)
+Project-URL: Bug Tracker, https://github.com/liminalcommons/chora-mcp-orchestration/issues
+Project-URL: Homepage, https://github.com/liminalcommons/chora-mcp-orchestration
+Project-URL: Repository, https://github.com/liminalcommons/chora-mcp-orchestration
+Description-Content-Type: text/markdown
+
+# chora-mcp-orchestration
+
+MCP server orchestration CLI and HTTP server for managing Docker-based MCP services.
+
+## Features
+
+- **Dual Mode Operation**: CLI commands + MCP HTTP server
+- **Docker Integration**: Manages containers via Docker SDK
+- **Auto-Discovery**: Reads registry.yaml for server definitions
+- **Health Monitoring**: Tracks container and endpoint health
+- **Log Access**: View container logs for debugging
+
+## Installation
+
+```bash
+poetry install
+```
+
+## Usage
+
+### CLI Mode
+
+```bash
+# Initialize ecosystem
+chora-orch init
+
+# Deploy server
+chora-orch deploy n8n
+
+# List servers
+chora-orch list
+
+# Check health
+chora-orch health manifest
+
+# View logs
+chora-orch logs n8n --tail 50
+
+# Stop server
+chora-orch stop n8n
+
+# Get status
+chora-orch status
+```
+
+### MCP Server Mode
+
+```bash
+# Start MCP HTTP server
+chora-orch-serve --port 8090
+```
+
+Then access tools via HTTP:
+- `POST /tools/init`
+- `POST /tools/deploy`
+- `POST /tools/list`
+- `POST /tools/health`
+- `POST /tools/logs`
+- `POST /tools/stop`
+- `POST /tools/status`
+
+## Development
+
+```bash
+# Run tests
+poetry run pytest -v
+
+# Run with coverage
+poetry run pytest --cov=chora_mcp_orchestration --cov-report=term-missing
+
+# Type check (if mypy added)
+poetry run mypy src/
+```
+
+## Documentation
+
+- [Requirements](docs/ORCHESTRATION-REQUIREMENTS.md) - Full specification
+- [CLI Scenarios](tests/features/orchestration_cli.feature) - BDD scenarios
+- [MCP Server Scenarios](tests/features/orchestration_mcp_server.feature) - HTTP tool scenarios
+
+## License
+
+MIT
+

chora_mcp_orchestration-0.1.0/README.md

@@ -0,0 +1,83 @@
+# chora-mcp-orchestration
+
+MCP server orchestration CLI and HTTP server for managing Docker-based MCP services.
+
+## Features
+
+- **Dual Mode Operation**: CLI commands + MCP HTTP server
+- **Docker Integration**: Manages containers via Docker SDK
+- **Auto-Discovery**: Reads registry.yaml for server definitions
+- **Health Monitoring**: Tracks container and endpoint health
+- **Log Access**: View container logs for debugging
+
+## Installation
+
+```bash
+poetry install
+```
+
+## Usage
+
+### CLI Mode
+
+```bash
+# Initialize ecosystem
+chora-orch init
+
+# Deploy server
+chora-orch deploy n8n
+
+# List servers
+chora-orch list
+
+# Check health
+chora-orch health manifest
+
+# View logs
+chora-orch logs n8n --tail 50
+
+# Stop server
+chora-orch stop n8n
+
+# Get status
+chora-orch status
+```
+
+### MCP Server Mode
+
+```bash
+# Start MCP HTTP server
+chora-orch-serve --port 8090
+```
+
+Then access tools via HTTP:
+- `POST /tools/init`
+- `POST /tools/deploy`
+- `POST /tools/list`
+- `POST /tools/health`
+- `POST /tools/logs`
+- `POST /tools/stop`
+- `POST /tools/status`
+
+## Development
+
+```bash
+# Run tests
+poetry run pytest -v
+
+# Run with coverage
+poetry run pytest --cov=chora_mcp_orchestration --cov-report=term-missing
+
+# Type check (if mypy added)
+poetry run mypy src/
+```
+
+## Documentation
+
+- [Requirements](docs/ORCHESTRATION-REQUIREMENTS.md) - Full specification
+- [CLI Scenarios](tests/features/orchestration_cli.feature) - BDD scenarios
+- [MCP Server Scenarios](tests/features/orchestration_mcp_server.feature) - HTTP tool scenarios
+
+## License
+
+MIT

chora_mcp_orchestration-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[tool.poetry]
+name = "chora-mcp-orchestration"
+version = "0.1.0"
+description = "MCP server orchestration CLI and HTTP server for managing Docker-based MCP services"
+authors = ["Liminal Commons <team@liminalcommons.org>"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://github.com/liminalcommons/chora-mcp-orchestration"
+repository = "https://github.com/liminalcommons/chora-mcp-orchestration"
+keywords = ["mcp", "orchestration", "docker", "deployment"]
+packages = [{include = "chora_mcp_orchestration", from = "src"}]
+
+[tool.poetry.urls]
+"Bug Tracker" = "https://github.com/liminalcommons/chora-mcp-orchestration/issues"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+docker = "^7.0.0"
+pyyaml = "^6.0"
+httpx = "^0.26.0"
+fastapi = "^0.109.0"
+uvicorn = "^0.27.0"
+pydantic = "^2.5.0"
+click = "^8.1.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.0"
+pytest-asyncio = "^0.21.0"
+pytest-cov = "^4.1.0"
+pytest-mock = "^3.12.0"
+
+[tool.poetry.scripts]
+chora-orch = "chora_mcp_orchestration.cli:main"
+chora-orch-serve = "chora_mcp_orchestration.server_main:main"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+addopts = "-v --strict-markers"
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]

chora_mcp_orchestration-0.1.0/src/chora_mcp_orchestration/__init__.py

@@ -0,0 +1,7 @@
+"""Chora MCP Orchestration - Docker-based MCP server management."""
+
+__version__ = "0.1.0"
+
+from .orchestrator import DockerOrchestrator, ServerDefinition
+
+__all__ = ["DockerOrchestrator", "ServerDefinition"]

chora_mcp_orchestration-0.1.0/src/chora_mcp_orchestration/cli.py

@@ -0,0 +1,152 @@
+"""CLI commands for chora-mcp-orchestration."""
+
+import click
+import json
+from .orchestrator import DockerOrchestrator
+
+
+@click.group()
+@click.option('--registry', default=None, help='Path to registry.yaml')
+@click.pass_context
+def cli(ctx, registry):
+    """Chora MCP Orchestration CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj['registry'] = registry
+
+
+@cli.command()
+@click.pass_context
+def init(ctx):
+    """Initialize MCP ecosystem with gateway and manifest."""
+    try:
+        orch = DockerOrchestrator(registry_path=ctx.obj.get('registry'))
+        result = orch.init()
+        
+        click.echo(f"Status: {result['status']}")
+        click.echo(f"Network: {result['network']}")
+        click.echo("Services:")
+        for svc in result['services']:
+            click.echo(f"  {svc['name']}: {svc['status']}")
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+
+@cli.command()
+@click.argument('namespace')
+@click.pass_context
+def deploy(ctx, namespace):
+    """Deploy MCP server by namespace."""
+    try:
+        orch = DockerOrchestrator(registry_path=ctx.obj.get('registry'))
+        result = orch.deploy(namespace)
+        
+        click.echo(f"Status: {result['status']}")
+        click.echo(f"Namespace: {result['namespace']}")
+    except ValueError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+
+@cli.command(name='list')
+@click.option('--format', type=click.Choice(['table', 'json']), default='table')
+@click.pass_context
+def list_servers(ctx, format):
+    """List all running MCP servers."""
+    try:
+        orch = DockerOrchestrator(registry_path=ctx.obj.get('registry'))
+        result = orch.list()
+        
+        if format == 'json':
+            click.echo(json.dumps(result, indent=2))
+        else:
+            for server in result['servers']:
+                click.echo(f"{server['namespace']} - {server.get('status', 'unknown')}")
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+
+@cli.command()
+@click.argument('namespace')
+@click.pass_context
+def health(ctx, namespace):
+    """Get health status for a server."""
+    try:
+        orch = DockerOrchestrator(registry_path=ctx.obj.get('registry'))
+        result = orch.health(namespace)
+        
+        click.echo(f"Namespace: {result['namespace']}")
+        click.echo(f"Docker Status: {result['docker_status']}")
+    except ValueError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+
+@cli.command()
+@click.argument('namespace')
+@click.option('--tail', default=100, help='Number of lines to show')
+@click.pass_context
+def logs(ctx, namespace, tail):
+    """Get logs from a server container."""
+    try:
+        orch = DockerOrchestrator(registry_path=ctx.obj.get('registry'))
+        result = orch.logs(namespace, tail=tail)
+        
+        for line in result['logs']:
+            click.echo(line)
+    except ValueError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+
+@cli.command()
+@click.argument('namespace')
+@click.option('--force', is_flag=True, help='Force kill immediately')
+@click.pass_context
+def stop(ctx, namespace, force):
+    """Stop a running server."""
+    try:
+        orch = DockerOrchestrator(registry_path=ctx.obj.get('registry'))
+        result = orch.stop(namespace, force=force)
+        
+        click.echo(f"Status: {result['status']}")
+        click.echo(f"Namespace: {result['namespace']}")
+    except ValueError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+
+@cli.command()
+@click.option('--format', type=click.Choice(['table', 'json']), default='table')
+@click.pass_context
+def status(ctx, format):
+    """Get comprehensive orchestration status."""
+    try:
+        orch = DockerOrchestrator(registry_path=ctx.obj.get('registry'))
+        result = orch.status()
+
+        if format == 'json':
+            click.echo(json.dumps(result, indent=2))
+        else:
+            click.echo(f"Docker: {result['docker_status']}")
+            click.echo(f"Servers running: {result['servers_running']}")
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+
+@cli.command()
+def mcp():
+    """Start MCP server in stdio mode (for AI clients like Cline, Claude Desktop)."""
+    from .mcp_stdio import main as stdio_main
+    stdio_main()
+
+
+def main():
+    """Entry point for CLI."""
+    cli(obj={})
+
+
+if __name__ == '__main__':
+    main()

chora_mcp_orchestration-0.1.0/src/chora_mcp_orchestration/mcp_stdio.py

@@ -0,0 +1,192 @@
+"""MCP stdio server for orchestration tools."""
+
+import sys
+import json
+import logging
+from typing import Dict, Any
+from .orchestrator import DockerOrchestrator
+
+# Configure logging to stderr (stdout reserved for JSON-RPC)
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s',
+    stream=sys.stderr
+)
+logger = logging.getLogger(__name__)
+
+
+def get_tool_definitions() -> list[Dict[str, Any]]:
+    """Return MCP tool definitions for orchestration."""
+    return [
+        {
+            "name": "init",
+            "description": "Initialize MCP ecosystem with gateway and manifest",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "registry_path": {"type": "string", "description": "Path to registry.yaml (optional)"}
+                }
+            }
+        },
+        {
+            "name": "deploy",
+            "description": "Deploy MCP server by namespace",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "namespace": {"type": "string", "description": "Server namespace from registry"}
+                },
+                "required": ["namespace"]
+            }
+        },
+        {
+            "name": "list",
+            "description": "List all running MCP servers",
+            "inputSchema": {
+                "type": "object",
+                "properties": {}
+            }
+        },
+        {
+            "name": "health",
+            "description": "Get health status for a server",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "namespace": {"type": "string", "description": "Server namespace"}
+                },
+                "required": ["namespace"]
+            }
+        },
+        {
+            "name": "logs",
+            "description": "Get logs from a server container",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "namespace": {"type": "string", "description": "Server namespace"},
+                    "tail": {"type": "number", "description": "Number of lines to show", "default": 100}
+                },
+                "required": ["namespace"]
+            }
+        },
+        {
+            "name": "stop",
+            "description": "Stop a running server",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "namespace": {"type": "string", "description": "Server namespace"},
+                    "force": {"type": "boolean", "description": "Force kill immediately", "default": False}
+                },
+                "required": ["namespace"]
+            }
+        },
+        {
+            "name": "status",
+            "description": "Get comprehensive orchestration status",
+            "inputSchema": {
+                "type": "object",
+                "properties": {}
+            }
+        }
+    ]
+
+
+def handle_tool_call(name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
+    """Execute orchestration tool and return result."""
+    try:
+        registry_path = arguments.get("registry_path") if name == "init" else None
+        orch = DockerOrchestrator(registry_path=registry_path)
+        
+        if name == "init":
+            return orch.init()
+        elif name == "deploy":
+            return orch.deploy(arguments["namespace"])
+        elif name == "list":
+            return orch.list()
+        elif name == "health":
+            return orch.health(arguments["namespace"])
+        elif name == "logs":
+            tail = arguments.get("tail", 100)
+            return orch.logs(arguments["namespace"], tail=tail)
+        elif name == "stop":
+            force = arguments.get("force", False)
+            return orch.stop(arguments["namespace"], force=force)
+        elif name == "status":
+            return orch.status()
+        else:
+            raise ValueError(f"Unknown tool: {name}")
+    except Exception as e:
+        logger.error(f"Tool execution error: {e}", exc_info=True)
+        raise
+
+
+def send_response(request_id: Any, result: Any = None, error: Any = None):
+    """Send JSON-RPC response to stdout."""
+    response = {
+        "jsonrpc": "2.0",
+        "id": request_id
+    }
+    
+    if error:
+        response["error"] = {
+            "code": -32603,
+            "message": str(error)
+        }
+    else:
+        response["result"] = result
+    
+    print(json.dumps(response), flush=True)
+
+
+def main():
+    """stdio MCP server main loop."""
+    logger.info("Starting orchestration MCP server (stdio mode)")
+    
+    try:
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            
+            try:
+                request = json.loads(line)
+                request_id = request.get("id")
+                method = request.get("method")
+                params = request.get("params", {})
+                
+                logger.info(f"Received request: method={method}, id={request_id}")
+                
+                if method == "tools/list":
+                    tools = get_tool_definitions()
+                    send_response(request_id, {"tools": tools})
+                
+                elif method == "tools/call":
+                    tool_name = params.get("name")
+                    arguments = params.get("arguments", {})
+                    
+                    logger.info(f"Executing tool: {tool_name} with args: {arguments}")
+                    result = handle_tool_call(tool_name, arguments)
+                    send_response(request_id, result)
+                
+                else:
+                    send_response(request_id, error=f"Unknown method: {method}")
+            
+            except json.JSONDecodeError as e:
+                logger.error(f"JSON decode error: {e}")
+                send_response(None, error=f"Invalid JSON: {e}")
+            
+            except Exception as e:
+                logger.error(f"Request handling error: {e}", exc_info=True)
+                send_response(request_id if 'request_id' in locals() else None, error=str(e))
+    
+    except KeyboardInterrupt:
+        logger.info("Shutting down stdio MCP server")
+    except Exception as e:
+        logger.error(f"Fatal error: {e}", exc_info=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

chora_mcp_orchestration-0.1.0/src/chora_mcp_orchestration/orchestrator.py

@@ -0,0 +1,405 @@
+"""Docker orchestrator for managing MCP server containers."""
+
+import time
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass
+import yaml
+import docker
+import httpx
+
+
+@dataclass
+class ServerDefinition:
+    """Definition of an MCP server from registry."""
+    namespace: str
+    name: str
+    docker_image: str
+    port: int
+    health_url: str
+    tools: List[Dict[str, str]] = None
+    volumes: Dict[str, Dict[str, str]] = None  # {host_path: {'bind': container_path, 'mode': 'rw'}}
+
+
+class DockerOrchestrator:
+    """Manages MCP server containers via Docker SDK."""
+
+    def __init__(self, registry_path: Optional[str] = None):
+        """
+        Initialize orchestrator.
+
+        Args:
+            registry_path: Path to registry.yaml file (absolute or relative to cwd)
+        """
+        import os
+        self.client = docker.from_env()
+
+        # Resolve registry path
+        if registry_path:
+            # Use provided path (make absolute if relative)
+            self.registry_path = os.path.abspath(registry_path) if not os.path.isabs(registry_path) else registry_path
+        else:
+            # Try to find default registry in workspace
+            cwd = os.getcwd()
+            default_path = os.path.join(cwd, "chora-mcp-gateway", "config", "registry.yaml")
+            self.registry_path = default_path
+
+        self.registry = self._load_registry()
+
+    def _load_registry(self) -> Dict[str, Any]:
+        """Load registry from YAML file."""
+        import os
+        try:
+            if not os.path.exists(self.registry_path):
+                # Return empty registry if file doesn't exist
+                return {"version": "1.0", "servers": []}
+
+            with open(self.registry_path, 'r') as f:
+                registry = yaml.safe_load(f)
+
+            # Validate basic registry structure
+            if not isinstance(registry, dict):
+                raise ValueError(f"Invalid registry format in {self.registry_path}: expected dict, got {type(registry)}")
+
+            if "servers" not in registry:
+                registry["servers"] = []
+
+            return registry
+
+        except FileNotFoundError:
+            return {"version": "1.0", "servers": []}
+        except yaml.YAMLError as e:
+            raise ValueError(f"Failed to parse registry YAML at {self.registry_path}: {e}")
+
+    def _get_server_def(self, namespace: str) -> ServerDefinition:
+        """Get server definition by namespace."""
+        for server in self.registry.get("servers", []):
+            if server["namespace"] == namespace:
+                return ServerDefinition(
+                    namespace=server["namespace"],
+                    name=server["name"],
+                    docker_image=server["docker_image"],
+                    port=server["port"],
+                    health_url=server.get("health_url", ""),
+                    tools=server.get("tools", []),
+                    volumes=server.get("volumes")
+                )
+        raise ValueError(f"Namespace '{namespace}' not found in registry")
+
+    def _ensure_network(self) -> None:
+        """Ensure mcp-network exists."""
+        try:
+            self.client.networks.get("mcp-network")
+        except docker.errors.NotFound:
+            self.client.networks.create("mcp-network", driver="bridge")
+
+    def _wait_for_health(self, container_name: str, health_url: str, timeout: int = 30) -> bool:
+        """Wait for container to become healthy."""
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            try:
+                # Check Docker health status
+                container = self.client.containers.get(container_name)
+                health_status = container.attrs.get("State", {}).get("Health", {}).get("Status")
+
+                if health_status == "healthy":
+                    return True
+
+                # Also try HTTP health check
+                if health_url:
+                    try:
+                        response = httpx.get(health_url.replace(container_name, "localhost"), timeout=2.0)
+                        if response.status_code == 200:
+                            return True
+                    except:
+                        pass
+
+            except Exception:
+                pass
+
+            time.sleep(2)
+
+        return False
+
+    def _get_container_by_namespace(self, namespace: str) -> Any:
+        """Find container by namespace."""
+        container_name = f"chora-mcp-{namespace}"
+        try:
+            return self.client.containers.get(container_name)
+        except docker.errors.NotFound:
+            raise ValueError(f"Server not found: {namespace}")
+
+    def init(self) -> Dict[str, Any]:
+        """
+        Initialize MCP ecosystem with gateway and manifest.
+
+        Returns:
+            Status dictionary with initialized services
+        """
+        self._ensure_network()
+
+        services = []
+
+        # Deploy gateway and manifest
+        for namespace in ["gateway", "manifest"]:
+            try:
+                result = self.deploy(namespace)
+                services.append({
+                    "name": namespace,
+                    "status": "healthy" if result.get("health_status") == "healthy" else "unhealthy",
+                    "port": result.get("port")
+                })
+            except Exception as e:
+                services.append({
+                    "name": namespace,
+                    "status": "failed",
+                    "error": str(e)
+                })
+
+        return {
+            "status": "initialized",
+            "services": services,
+            "network": "mcp-network"
+        }
+
+    def deploy(self, namespace: str) -> Dict[str, Any]:
+        """
+        Deploy an MCP server container.
+
+        Args:
+            namespace: Server namespace from registry
+
+        Returns:
+            Deployment status dictionary
+        """
+        server_def = self._get_server_def(namespace)
+        self._ensure_network()
+
+        # Check if container already exists
+        container_name = f"chora-mcp-{namespace}"
+        try:
+            existing = self.client.containers.get(container_name)
+            existing.stop()
+            existing.remove()
+        except docker.errors.NotFound:
+            pass
+
+        # Prepare volumes
+        volumes = server_def.volumes or {}
+
+        # Special handling: auto-mount config for gateway if not specified
+        if namespace == "gateway" and not any("/app/config" in str(v) for v in volumes.values()):
+            # Try to find config directory in workspace
+            import os
+            workspace_root = os.getcwd()
+            config_path = os.path.join(workspace_root, "chora-mcp-gateway", "config")
+            if os.path.exists(config_path):
+                volumes[config_path] = {'bind': '/app/config', 'mode': 'rw'}
+
+        # Run container
+        container = self.client.containers.run(
+            server_def.docker_image,
+            name=container_name,
+            ports={f"{server_def.port}/tcp": server_def.port},
+            network="mcp-network",
+            volumes=volumes if volumes else None,
+            detach=True,
+            remove=False
+        )
+
+        # Wait for health check
+        health_status = "healthy" if self._wait_for_health(container_name, server_def.health_url) else "unhealthy"
+
+        return {
+            "status": "deployed",
+            "namespace": namespace,
+            "container_id": container.id,
+            "port": server_def.port,
+            "health_status": health_status
+        }
+
+    def list(self) -> Dict[str, Any]:
+        """
+        List all running MCP servers.
+
+        Returns:
+            Dictionary with list of servers
+        """
+        containers = self.client.containers.list(filters={"network": "mcp-network"})
+
+        servers = []
+        for container in containers:
+            # Extract namespace from container name
+            name = container.name
+            namespace = name.replace("chora-mcp-", "") if name.startswith("chora-mcp-") else name
+
+            # Get port mapping
+            ports = container.attrs.get("NetworkSettings", {}).get("Ports", {})
+            port = None
+            for port_spec, bindings in ports.items():
+                if bindings:
+                    port = int(bindings[0]["HostPort"])
+                    break
+
+            # Get health status
+            health = container.attrs.get("State", {}).get("Health", {}).get("Status", "unknown")
+
+            # Calculate uptime
+            started_at = container.attrs.get("State", {}).get("StartedAt", "")
+            uptime = "unknown"  # Simplified for now
+
+            servers.append({
+                "namespace": namespace,
+                "container_id": container.id[:12],
+                "status": container.status,
+                "health": health,
+                "port": port,
+                "uptime": uptime
+            })
+
+        return {"servers": servers}
+
+    def health(self, namespace: str) -> Dict[str, Any]:
+        """
+        Get health status for a server.
+
+        Args:
+            namespace: Server namespace
+
+        Returns:
+            Health status dictionary
+        """
+        container = self._get_container_by_namespace(namespace)
+        server_def = self._get_server_def(namespace)
+
+        # Get Docker status
+        docker_status = container.status
+
+        # Query health endpoint
+        health_response = None
+        tools_count = 0
+
+        try:
+            health_url = server_def.health_url.replace(f"chora-mcp-{namespace}", "localhost")
+            response = httpx.get(health_url, timeout=5.0)
+            if response.status_code == 200:
+                health_response = response.json()
+
+                # Also get tools count
+                tools_url = health_url.replace("/health", "/tools")
+                tools_response = httpx.get(tools_url, timeout=5.0)
+                if tools_response.status_code == 200:
+                    tools_count = len(tools_response.json().get("tools", []))
+        except Exception:
+            health_response = {"error": "Health check failed"}
+
+        return {
+            "namespace": namespace,
+            "container_id": container.id[:12],
+            "docker_status": docker_status,
+            "health_endpoint": server_def.health_url.replace(f"chora-mcp-{namespace}", "localhost"),
+            "health_response": health_response,
+            "tools_count": tools_count,
+            "uptime": "unknown"  # Simplified
+        }
+
+    def logs(self, namespace: str, tail: int = 100) -> Dict[str, Any]:
+        """
+        Get logs from a server container.
+
+        Args:
+            namespace: Server namespace
+            tail: Number of lines to return
+
+        Returns:
+            Dictionary with logs
+        """
+        container = self._get_container_by_namespace(namespace)
+
+        logs_bytes = container.logs(tail=tail)
+        logs_str = logs_bytes.decode('utf-8')
+        log_lines = [line for line in logs_str.split('\n') if line.strip()]
+
+        return {
+            "namespace": namespace,
+            "logs": log_lines,
+            "lines": len(log_lines)
+        }
+
+    def stop(self, namespace: str, force: bool = False) -> Dict[str, Any]:
+        """
+        Stop a server container.
+
+        Args:
+            namespace: Server namespace
+            force: If True, kill immediately; otherwise graceful shutdown
+
+        Returns:
+            Stop status dictionary
+        """
+        container = self._get_container_by_namespace(namespace)
+
+        if force:
+            container.kill()
+            graceful = False
+        else:
+            container.stop(timeout=10)
+            graceful = True
+
+        return {
+            "status": "stopped",
+            "namespace": namespace,
+            "graceful": graceful
+        }
+
+    def status(self) -> Dict[str, Any]:
+        """
+        Get comprehensive orchestration status.
+
+        Returns:
+            Status dictionary with all information
+        """
+        # Check Docker daemon
+        try:
+            self.client.ping()
+            docker_status = "connected"
+        except Exception:
+            docker_status = "disconnected"
+            return {
+                "docker_status": docker_status,
+                "error": "Docker daemon not accessible"
+            }
+
+        # Get running servers
+        list_result = self.list()
+        servers = list_result["servers"]
+        servers_running = len(servers)
+        servers_healthy = sum(1 for s in servers if s["health"] == "healthy")
+
+        # Check gateway
+        gateway_status = {"status": "unknown"}
+        gateway_tools_count = 0
+
+        try:
+            response = httpx.get("http://localhost:8080/health", timeout=5.0)
+            if response.status_code == 200:
+                gateway_status = response.json()
+
+                # Get tools count
+                tools_response = httpx.get("http://localhost:8080/tools", timeout=5.0)
+                if tools_response.status_code == 200:
+                    gateway_tools_count = len(tools_response.json().get("tools", []))
+        except Exception:
+            gateway_status = {"status": "unreachable"}
+
+        return {
+            "docker_status": docker_status,
+            "network": "mcp-network",
+            "gateway": {
+                "status": gateway_status.get("status"),
+                "url": "http://localhost:8080",
+                "tools_count": gateway_tools_count
+            },
+            "servers_running": servers_running,
+            "servers_healthy": servers_healthy,
+            "servers": servers
+        }

chora_mcp_orchestration-0.1.0/src/chora_mcp_orchestration/server.py

@@ -0,0 +1,152 @@
+"""MCP HTTP server for orchestration tools."""
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from typing import Optional
+from .orchestrator import DockerOrchestrator
+
+app = FastAPI(title="Chora MCP Orchestration", version="0.1.0")
+
+
+# Pydantic models for request/response
+class InitRequest(BaseModel):
+    registry_path: Optional[str] = None
+
+
+class DeployRequest(BaseModel):
+    namespace: str
+
+
+class HealthRequest(BaseModel):
+    namespace: str
+
+
+class LogsRequest(BaseModel):
+    namespace: str
+    tail: Optional[int] = 100
+
+
+class StopRequest(BaseModel):
+    namespace: str
+    force: Optional[bool] = False
+
+
+class StatusRequest(BaseModel):
+    pass
+
+
+@app.get("/health")
+def health_check():
+    """Health check endpoint."""
+    return {"status": "healthy"}
+
+
+@app.get("/tools")
+def list_tools():
+    """List available MCP tools."""
+    return {
+        "tools": [
+            {"name": "init", "description": "Initialize MCP ecosystem"},
+            {"name": "deploy", "description": "Deploy MCP server"},
+            {"name": "list", "description": "List running servers"},
+            {"name": "health", "description": "Get server health"},
+            {"name": "logs", "description": "Get server logs"},
+            {"name": "stop", "description": "Stop a server"},
+            {"name": "status", "description": "Get orchestration status"}
+        ]
+    }
+
+
+@app.post("/tools/init")
+def init_tool(request: InitRequest):
+    """Initialize MCP ecosystem."""
+    try:
+        orch = DockerOrchestrator(registry_path=request.registry_path)
+        result = orch.init()
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/tools/deploy")
+def deploy_tool(request: DeployRequest):
+    """Deploy MCP server."""
+    try:
+        orch = DockerOrchestrator()
+        result = orch.deploy(request.namespace)
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/tools/list")
+def list_tool(request: dict):
+    """List running servers."""
+    try:
+        orch = DockerOrchestrator()
+        result = orch.list()
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/tools/health")
+def health_tool(request: HealthRequest):
+    """Get server health."""
+    try:
+        orch = DockerOrchestrator()
+        result = orch.health(request.namespace)
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/tools/logs")
+def logs_tool(request: LogsRequest):
+    """Get server logs."""
+    try:
+        orch = DockerOrchestrator()
+        result = orch.logs(request.namespace, tail=request.tail)
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/tools/stop")
+def stop_tool(request: StopRequest):
+    """Stop a server."""
+    try:
+        orch = DockerOrchestrator()
+        result = orch.stop(request.namespace, force=request.force)
+        return result
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/tools/status")
+def status_tool(request: dict):
+    """Get orchestration status."""
+    try:
+        orch = DockerOrchestrator()
+        result = orch.status()
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+def main():
+    """Entry point for MCP HTTP server."""
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8090)
+
+
+if __name__ == "__main__":
+    main()