loopengt 0.1.0__py3-none-any.whl

loopengt/mcp/client/manager.py

@@ -0,0 +1,118 @@
+"""MCP client connection management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+class MCPClientManager:
+    """Manages connections to external MCP servers.
+
+    Handles server discovery, connection lifecycle, and reconnection.
+
+    Usage::
+
+        manager = MCPClientManager()
+        await manager.connect("github-server", transport="stdio", command=["mcp-github"])
+        tools = await manager.list_tools("github-server")
+        result = await manager.call_tool("github-server", "search_repos", {"query": "loopengt"})
+    """
+
+    def __init__(self) -> None:
+        self._connections: dict[str, Any] = {}
+        self._log = logger.bind(component="mcp_client")
+
+    async def connect(
+        self,
+        server_name: str,
+        *,
+        transport: str = "stdio",
+        command: list[str] | None = None,
+        url: str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> None:
+        """Connect to an MCP server.
+
+        Parameters
+        ----------
+        server_name:
+            Unique identifier for this connection.
+        transport:
+            "stdio" or "sse".
+        command:
+            Command to launch (stdio transport).
+        url:
+            Server URL (SSE transport).
+        env:
+            Environment variables to pass.
+        """
+        self._log.info(
+            "mcp_client.connect",
+            server=server_name,
+            transport=transport,
+        )
+
+        # Store connection config (actual MCP client integration deferred)
+        self._connections[server_name] = {
+            "transport": transport,
+            "command": command,
+            "url": url,
+            "env": env or {},
+            "connected": True,
+        }
+
+    async def disconnect(self, server_name: str) -> None:
+        """Disconnect from an MCP server."""
+        if server_name in self._connections:
+            del self._connections[server_name]
+            self._log.info("mcp_client.disconnect", server=server_name)
+
+    async def disconnect_all(self) -> None:
+        """Disconnect from all MCP servers."""
+        self._connections.clear()
+
+    async def list_tools(self, server_name: str) -> list[dict[str, Any]]:
+        """List tools available on a connected MCP server."""
+        if server_name not in self._connections:
+            raise ConnectionError(f"Not connected to server: {server_name}")
+
+        # Stub — returns empty until real MCP client is wired
+        self._log.info("mcp_client.list_tools", server=server_name)
+        return []
+
+    async def call_tool(
+        self,
+        server_name: str,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+    ) -> Any:
+        """Call a tool on a connected MCP server."""
+        if server_name not in self._connections:
+            raise ConnectionError(f"Not connected to server: {server_name}")
+
+        self._log.info(
+            "mcp_client.call_tool",
+            server=server_name,
+            tool=tool_name,
+        )
+
+        # Stub response
+        return {
+            "server": server_name,
+            "tool": tool_name,
+            "arguments": arguments,
+            "result": f"[stub] {tool_name} called on {server_name}",
+        }
+
+    @property
+    def connected_servers(self) -> list[str]:
+        """List names of connected servers."""
+        return list(self._connections.keys())
+
+    def is_connected(self, server_name: str) -> bool:
+        """Check if a server is connected."""
+        return server_name in self._connections

loopengt/mcp/client/tools.py

@@ -0,0 +1,107 @@
+"""MCP tool invocation helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import structlog
+
+from loopengt.mcp.client.manager import MCPClientManager
+
+logger = structlog.get_logger(__name__)
+
+
+class MCPToolInvoker:
+    """High-level tool invocation over MCP.
+
+    Wraps ``MCPClientManager`` with retry, timeout, and error handling.
+
+    Usage::
+
+        invoker = MCPToolInvoker(manager)
+        result = await invoker.invoke("server", "tool_name", {"arg": "value"})
+    """
+
+    def __init__(
+        self,
+        manager: MCPClientManager,
+        *,
+        default_timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        self._manager = manager
+        self._timeout = default_timeout
+        self._max_retries = max_retries
+        self._log = logger.bind(component="mcp_invoker")
+
+    async def invoke(
+        self,
+        server_name: str,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        timeout: float | None = None,
+    ) -> Any:
+        """Invoke an MCP tool with retry logic.
+
+        Parameters
+        ----------
+        server_name:
+            Name of the MCP server.
+        tool_name:
+            Name of the tool to invoke.
+        arguments:
+            Tool arguments.
+        timeout:
+            Per-call timeout override.
+
+        Returns
+        -------
+        Any
+            The tool's result payload.
+        """
+        effective_timeout = timeout or self._timeout
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                self._log.info(
+                    "mcp.invoke",
+                    server=server_name,
+                    tool=tool_name,
+                    attempt=attempt + 1,
+                )
+
+                result = await self._manager.call_tool(
+                    server_name, tool_name, arguments
+                )
+                return result
+
+            except Exception as exc:  # noqa: BLE001
+                self._log.warning(
+                    "mcp.invoke_error",
+                    server=server_name,
+                    tool=tool_name,
+                    attempt=attempt + 1,
+                    error=str(exc),
+                )
+                if attempt >= self._max_retries:
+                    raise
+
+        return None  # unreachable but satisfies type checker
+
+    async def invoke_many(
+        self,
+        calls: list[tuple[str, str, dict[str, Any] | None]],
+    ) -> list[Any]:
+        """Invoke multiple tools sequentially.
+
+        Parameters
+        ----------
+        calls:
+            List of (server_name, tool_name, arguments) tuples.
+        """
+        results = []
+        for server, tool, args in calls:
+            result = await self.invoke(server, tool, args)
+            results.append(result)
+        return results

loopengt/mcp/server/__init__.py

@@ -0,0 +1 @@
+"""MCP server subpackage."""

loopengt/mcp/server/prompts.py

@@ -0,0 +1,82 @@
+"""MCP server prompts — loop engineering prompts exposed via MCP."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+def register_prompts(server: Any) -> None:
+    """Register loopengt prompts with the FastMCP server."""
+
+    @server.prompt()
+    async def design(goal: str) -> str:
+        """Design a new agent loop from a natural-language goal.
+
+        Args:
+            goal: The objective for the loop to achieve.
+        """
+        return (
+            "You are the Loop Engineering Architect (LOOPENGT).\n\n"
+            f"## Goal\n{goal}\n\n"
+            "## Instructions\n"
+            "Design an optimal agent loop specification for the above goal.\n\n"
+            "1. Select the best orchestration pattern (sequential, supervisor_worker, "
+            "parallel_fan_out, handoff, evaluator_optimizer)\n"
+            "2. Define the minimum necessary agents with clear roles\n"
+            "3. Specify the execution steps with dependencies\n"
+            "4. Add verification gates at critical boundaries\n"
+            "5. Define stop conditions and policies\n\n"
+            "Output a complete `loop.yaml` specification and a `LOOP_DESIGN.md` "
+            "design document."
+        )
+
+    @server.prompt()
+    async def review(loop_yaml: str) -> str:
+        """Review an existing loop specification for correctness and efficiency.
+
+        Args:
+            loop_yaml: The YAML content of the loop specification.
+        """
+        return (
+            "You are a Loop Engineering Reviewer.\n\n"
+            "## Loop Specification\n"
+            f"```yaml\n{loop_yaml}\n```\n\n"
+            "## Review Criteria\n"
+            "1. **Correctness**: Are step dependencies valid? Do agents exist?\n"
+            "2. **Efficiency**: Are there redundant steps or agents?\n"
+            "3. **Resilience**: Are retry policies and verification gates adequate?\n"
+            "4. **Observability**: Are traces and logging sufficient?\n"
+            "5. **Security**: Are tool auth configs appropriate?\n\n"
+            "Provide specific, actionable feedback."
+        )
+
+    @server.prompt()
+    async def improve(loop_yaml: str, feedback: str = "") -> str:
+        """Improve a loop specification based on feedback or best practices.
+
+        Args:
+            loop_yaml: The current YAML specification.
+            feedback: Optional specific feedback to address.
+        """
+        feedback_section = (
+            f"\n## Feedback to Address\n{feedback}\n" if feedback else ""
+        )
+        return (
+            "You are a Loop Engineering Optimizer.\n\n"
+            "## Current Specification\n"
+            f"```yaml\n{loop_yaml}\n```\n"
+            f"{feedback_section}\n"
+            "## Optimization Goals\n"
+            "1. Reduce unnecessary complexity\n"
+            "2. Improve error handling and recovery\n"
+            "3. Add missing verification gates\n"
+            "4. Optimize agent capabilities and tool assignments\n"
+            "5. Enhance observability\n\n"
+            "Output an improved `loop.yaml` with explanations for each change."
+        )
+
+    logger.info("mcp.prompts.registered", count=3)

loopengt/mcp/server/resources.py

@@ -0,0 +1,75 @@
+"""MCP server resources — loop specs, traces, and templates as resources."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import structlog
+import yaml
+
+logger = structlog.get_logger(__name__)
+
+
+def register_resources(server: Any) -> None:
+    """Register loopengt resources with the FastMCP server."""
+
+    @server.resource("loop://spec/{name}")
+    async def get_loop_spec(name: str) -> str:
+        """Retrieve a loop specification by name.
+
+        Searches .loopengt/templates/ and the current directory.
+        """
+        search_paths = [
+            Path(f".loopengt/templates/{name}/loop.yaml"),
+            Path(f"{name}.yaml"),
+            Path(f"{name}/loop.yaml"),
+        ]
+
+        for path in search_paths:
+            if path.exists():
+                content = path.read_text(encoding="utf-8")
+                return content
+
+        return json.dumps({"error": f"Loop spec '{name}' not found"})
+
+    @server.resource("trace://run/{run_id}")
+    async def get_run_trace(run_id: str) -> str:
+        """Retrieve the execution trace for a run."""
+        trace_path = Path(f".loopengt/runs/{run_id}.json")
+        if trace_path.exists():
+            return trace_path.read_text(encoding="utf-8")
+        return json.dumps({"error": f"Trace '{run_id}' not found"})
+
+    @server.resource("template://list")
+    async def list_templates() -> str:
+        """List all available loop templates."""
+        templates = []
+
+        # Built-in templates
+        builtins = {
+            "planner_executor": "Sequential plan-then-execute pattern",
+            "reviewer_retry": "Code review with iterative retry on failure",
+            "supervisor_workers": "Supervisor delegates to specialised workers",
+            "research_architect": "Research → synthesise → architect workflow",
+            "handoff_loop": "Sequential agent-to-agent handoff pattern",
+        }
+        for name, desc in builtins.items():
+            templates.append({"name": name, "source": "builtin", "description": desc})
+
+        # Local templates
+        local_dir = Path(".loopengt/templates")
+        if local_dir.exists():
+            for entry in sorted(local_dir.iterdir()):
+                if entry.is_dir() and (entry / "loop.yaml").exists():
+                    if entry.name not in builtins:
+                        templates.append({
+                            "name": entry.name,
+                            "source": "local",
+                            "description": "",
+                        })
+
+        return json.dumps(templates, indent=2)
+
+    logger.info("mcp.resources.registered", count=3)

loopengt/mcp/server/server.py

@@ -0,0 +1,50 @@
+"""FastMCP server setup — the loopengt MCP server entry point."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+def create_server() -> Any:
+    """Create and configure the loopengt FastMCP server.
+
+    Returns a FastMCP server instance with all tools, resources, and
+    prompts registered.
+
+    Raises
+    ------
+    ImportError
+        If fastmcp is not installed.
+    """
+    from fastmcp import FastMCP
+
+    server = FastMCP(
+        name="loopengt",
+        instructions=(
+            "Loop Engineering Agent — design, orchestrate, and evaluate agent loops. "
+            "Use the provided tools to create loop specifications, execute loops, "
+            "inspect traces, and manage templates."
+        ),
+    )
+
+    # Register tools
+    from loopengt.mcp.server.tools import register_tools
+
+    register_tools(server)
+
+    # Register resources
+    from loopengt.mcp.server.resources import register_resources
+
+    register_resources(server)
+
+    # Register prompts
+    from loopengt.mcp.server.prompts import register_prompts
+
+    register_prompts(server)
+
+    logger.info("mcp.server.created")
+    return server

loopengt/mcp/server/tools.py

@@ -0,0 +1,214 @@
+"""MCP server tools — loop lifecycle operations exposed over MCP."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Any
+
+import structlog
+import yaml
+
+logger = structlog.get_logger(__name__)
+
+
+def register_tools(server: Any) -> None:
+    """Register loopengt tools with the FastMCP server."""
+
+    @server.tool()
+    async def create_loop(
+        name: str,
+        goal: str,
+        pattern: str = "sequential",
+        agents: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        """Create a new loop specification.
+
+        Args:
+            name: Loop identifier.
+            goal: The objective this loop achieves.
+            pattern: Orchestration pattern (sequential, supervisor_worker, etc.).
+            agents: Optional list of agent definitions.
+
+        Returns:
+            The created loop specification as a dict.
+        """
+        from loopengt.cli.commands.design import _generate_stub_spec, _generate_stub_design
+        import yaml
+        from pathlib import Path
+
+        spec = _generate_stub_spec(goal, template=None)
+        spec["name"] = name
+        spec["pattern"] = pattern
+
+        if agents:
+            spec["agents"] = agents
+
+        design_md = _generate_stub_design(goal, spec)
+        
+        # Write files to disk
+        Path("loop.yaml").write_text(yaml.dump(spec, sort_keys=False), encoding="utf-8")
+        Path("loopengt.md").write_text(design_md, encoding="utf-8")
+
+        return {
+            "status": "created", 
+            "spec": spec,
+            "message": "Loop architecture designed and saved to loopengt.md and loop.yaml. Please read loopengt.md and act as the orchestrator: execute the steps defined by invoking your coding capabilities to fulfill the roles of each agent described in the document."
+        }
+
+    @server.tool()
+    async def run_loop(
+        spec: dict[str, Any] | None = None,
+        spec_path: str | None = None,
+    ) -> dict[str, Any]:
+        """Execute a loop from a spec dict or YAML file path.
+
+        Args:
+            spec: Loop specification as a dict.
+            spec_path: Path to a loop.yaml file.
+
+        Returns:
+            Execution result with run_id and status.
+        """
+        if spec is None and spec_path:
+            path = Path(spec_path)
+            if not path.exists():
+                return {"error": f"Spec file not found: {spec_path}"}
+            spec = yaml.safe_load(path.read_text(encoding="utf-8"))
+
+        if spec is None:
+            return {"error": "Either spec or spec_path must be provided"}
+
+        try:
+            from loopengt.core.models.loop_spec import LoopSpec
+            from loopengt.core.runtime.executor import LoopExecutor
+
+            loop_spec = LoopSpec.model_validate(spec)
+            executor = LoopExecutor(loop_spec)
+            result = await executor.execute()
+
+            return {
+                "status": result.status.value,
+                "run_id": result.run_id,
+                "turns": result.turn,
+                "steps_completed": sum(
+                    1
+                    for s in result.step_states.values()
+                    if s.status.value == "completed"
+                ),
+            }
+        except Exception as exc:
+            return {"error": str(exc)}
+
+    @server.tool()
+    async def resume_loop(
+        run_id: str,
+        checkpoint_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Resume a paused or failed loop run.
+
+        Args:
+            run_id: ID of the run to resume.
+            checkpoint_id: Optional specific checkpoint to resume from.
+
+        Returns:
+            Resumption result with status.
+        """
+        return {
+            "status": "resumed",
+            "run_id": run_id,
+            "checkpoint_id": checkpoint_id,
+            "note": "Full resume support requires checkpoint loading",
+        }
+
+    @server.tool()
+    async def list_runs(
+        runs_dir: str = ".loopengt/runs",
+    ) -> dict[str, Any]:
+        """List all loop runs.
+
+        Args:
+            runs_dir: Directory containing run traces.
+
+        Returns:
+            List of run IDs and their statuses.
+        """
+        runs_path = Path(runs_dir)
+        if not runs_path.exists():
+            return {"runs": [], "count": 0}
+
+        runs = []
+        for f in sorted(runs_path.glob("*.json")):
+            try:
+                data = json.loads(f.read_text(encoding="utf-8"))
+                runs.append({
+                    "run_id": data.get("run_id", f.stem),
+                    "status": data.get("status", "unknown"),
+                    "loop_name": data.get("loop_name", ""),
+                })
+            except Exception:
+                runs.append({"run_id": f.stem, "status": "unknown"})
+
+        return {"runs": runs, "count": len(runs)}
+
+    @server.tool()
+    async def inspect_trace(
+        run_id: str,
+        runs_dir: str = ".loopengt/runs",
+    ) -> dict[str, Any]:
+        """Inspect the execution trace of a run.
+
+        Args:
+            run_id: Run ID to inspect.
+            runs_dir: Directory containing run traces.
+
+        Returns:
+            The full trace data for the run.
+        """
+        trace_path = Path(runs_dir) / f"{run_id}.json"
+        if not trace_path.exists():
+            return {"error": f"Trace not found: {run_id}"}
+
+        try:
+            return json.loads(trace_path.read_text(encoding="utf-8"))
+        except Exception as exc:
+            return {"error": f"Failed to read trace: {exc}"}
+
+    @server.tool()
+    async def evaluate_run(
+        run_id: str,
+        metrics: list[str] | None = None,
+        runs_dir: str = ".loopengt/runs",
+    ) -> dict[str, Any]:
+        """Run evaluations against a completed loop run.
+
+        Args:
+            run_id: Run ID to evaluate.
+            metrics: Specific metrics to evaluate (default: all).
+            runs_dir: Directory containing run traces.
+
+        Returns:
+            Evaluation results with metric scores.
+        """
+        trace_path = Path(runs_dir) / f"{run_id}.json"
+        if not trace_path.exists():
+            return {"error": f"Trace not found: {run_id}"}
+
+        try:
+            trace_data = json.loads(trace_path.read_text(encoding="utf-8"))
+        except Exception as exc:
+            return {"error": f"Failed to read trace: {exc}"}
+
+        from loopengt.cli.commands.eval import _evaluate_builtin_metrics
+
+        results = _evaluate_builtin_metrics(trace_data, metrics)
+        return {
+            "run_id": run_id,
+            "results": [
+                {"metric": name, "value": value, "status": status}
+                for name, value, status in results
+            ],
+        }
+
+    logger.info("mcp.tools.registered", count=6)

loopengt/mcp/shared/__init__.py

@@ -0,0 +1 @@
+"""MCP shared schemas subpackage."""