agent-mcp-framework 0.1.0__py3-none-any.whl

agent_mcp_framework/__init__.py

@@ -0,0 +1,35 @@
+"""agent-mcp-framework: Build multi-agent MCP servers in Python."""
+
+from agent_mcp_framework.agent import (
+    Agent,
+    AgentContext,
+    AgentResult,
+    FunctionAgent,
+    LLMAgent,
+)
+from agent_mcp_framework.pipeline import (
+    ConditionalPipeline,
+    MapReducePipeline,
+    ParallelPipeline,
+    Pipeline,
+    PipelineResult,
+    SequentialPipeline,
+)
+from agent_mcp_framework.server import AgentMCPServer
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Agent",
+    "AgentContext",
+    "AgentResult",
+    "AgentMCPServer",
+    "ConditionalPipeline",
+    "FunctionAgent",
+    "LLMAgent",
+    "MapReducePipeline",
+    "ParallelPipeline",
+    "Pipeline",
+    "PipelineResult",
+    "SequentialPipeline",
+]

agent_mcp_framework/agent.py

@@ -0,0 +1,190 @@
+"""Core Agent abstraction for multi-agent systems."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class AgentStatus(str, Enum):
+    IDLE = "idle"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class AgentContext(BaseModel):
+    """Shared context passed between agents in a pipeline."""
+
+    data: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    errors: list[str] = Field(default_factory=list)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.data.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        self.data[key] = value
+
+    def merge(self, other: AgentContext) -> AgentContext:
+        """Merge another context into this one, returning a new context."""
+        merged_data = {**self.data, **other.data}
+        merged_metadata = {**self.metadata, **other.metadata}
+        merged_errors = self.errors + other.errors
+        return AgentContext(data=merged_data, metadata=merged_metadata, errors=merged_errors)
+
+
+class AgentResult(BaseModel):
+    """Result returned by an agent after execution."""
+
+    success: bool
+    output: Any = None
+    error: str | None = None
+    duration_ms: float = 0.0
+    agent_name: str = ""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Agent(ABC):
+    """Base class for all agents.
+
+    Subclass this and implement `run()` to create an agent.
+
+    Example:
+        class MyAgent(Agent):
+            async def run(self, context: AgentContext) -> AgentResult:
+                data = context.get("input")
+                result = process(data)
+                context.set("output", result)
+                return AgentResult(success=True, output=result, agent_name=self.name)
+    """
+
+    def __init__(self, name: str, description: str = ""):
+        self.name = name
+        self.description = description
+        self.status = AgentStatus.IDLE
+        self._hooks: dict[str, list] = {
+            "before_run": [],
+            "after_run": [],
+            "on_error": [],
+        }
+
+    def on(self, event: str, callback) -> Agent:
+        """Register a lifecycle hook."""
+        if event not in self._hooks:
+            raise ValueError(f"Unknown event: {event}. Valid: {list(self._hooks.keys())}")
+        self._hooks[event].append(callback)
+        return self
+
+    async def _fire(self, event: str, **kwargs) -> None:
+        for cb in self._hooks.get(event, []):
+            result = cb(**kwargs)
+            if asyncio.iscoroutine(result):
+                await result
+
+    @abstractmethod
+    async def run(self, context: AgentContext) -> AgentResult:
+        """Execute the agent's logic. Must be implemented by subclasses."""
+        ...
+
+    async def execute(self, context: AgentContext) -> AgentResult:
+        """Run the agent with lifecycle hooks and error handling."""
+        self.status = AgentStatus.RUNNING
+        start = time.monotonic()
+        try:
+            await self._fire("before_run", agent=self, context=context)
+            result = await self.run(context)
+            result.agent_name = self.name
+            result.duration_ms = (time.monotonic() - start) * 1000
+            self.status = AgentStatus.COMPLETED
+            await self._fire("after_run", agent=self, context=context, result=result)
+            return result
+        except Exception as e:
+            self.status = AgentStatus.FAILED
+            duration = (time.monotonic() - start) * 1000
+            error_result = AgentResult(
+                success=False,
+                error=str(e),
+                agent_name=self.name,
+                duration_ms=duration,
+            )
+            context.errors.append(f"{self.name}: {e}")
+            await self._fire("on_error", agent=self, context=context, error=e)
+            return error_result
+
+
+class LLMAgent(Agent):
+    """Agent that uses an LLM (Claude) for processing.
+
+    Subclass this for agents that need LLM capabilities. Provides
+    a configured Anthropic client and helper methods.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        description: str = "",
+        model: str = "claude-sonnet-4-5-20250929",
+        system_prompt: str = "",
+        max_tokens: int = 4096,
+    ):
+        super().__init__(name, description)
+        self.model = model
+        self.system_prompt = system_prompt
+        self.max_tokens = max_tokens
+        self._client = None
+
+    @property
+    def client(self):
+        if self._client is None:
+            import anthropic
+            self._client = anthropic.AsyncAnthropic()
+        return self._client
+
+    async def complete(self, prompt: str, **kwargs) -> str:
+        """Send a completion request to Claude."""
+        messages = [{"role": "user", "content": prompt}]
+        params = {
+            "model": kwargs.pop("model", self.model),
+            "max_tokens": kwargs.pop("max_tokens", self.max_tokens),
+            "messages": messages,
+            **kwargs,
+        }
+        if self.system_prompt:
+            params["system"] = self.system_prompt
+        response = await self.client.messages.create(**params)
+        if not response.content:
+            raise ValueError(
+                f"Empty response from {params['model']} "
+                f"(stop_reason: {response.stop_reason})"
+            )
+        return response.content[0].text
+
+
+class FunctionAgent(Agent):
+    """Agent created from a plain function.
+
+    Example:
+        async def analyze(ctx: AgentContext) -> AgentResult:
+            data = ctx.get("input")
+            return AgentResult(success=True, output=len(data))
+
+        agent = FunctionAgent("counter", fn=analyze)
+    """
+
+    def __init__(self, name: str, fn, description: str = ""):
+        super().__init__(name, description or f"Function agent: {fn.__name__}")
+        self._fn = fn
+
+    async def run(self, context: AgentContext) -> AgentResult:
+        result = self._fn(context)
+        if asyncio.iscoroutine(result):
+            result = await result
+        if isinstance(result, AgentResult):
+            return result
+        return AgentResult(success=True, output=result, agent_name=self.name)

agent_mcp_framework/cli.py

@@ -0,0 +1,117 @@
+"""CLI interface for running agent-mcp-framework servers and pipelines."""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import sys
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from agent_mcp_framework import __version__
+
+console = Console()
+
+
+@click.group()
+@click.version_option(version=__version__)
+def main():
+    """agent-mcp-framework: Build multi-agent MCP servers in Python."""
+    pass
+
+
+@main.command()
+@click.argument("module_path")
+@click.option("--transport", "-t", default="stdio", type=click.Choice(["stdio", "sse"]))
+def serve(module_path: str, transport: str):
+    """Start an MCP server from a Python module.
+
+    MODULE_PATH should be a dotted path to a module containing an AgentMCPServer
+    instance named 'server' (e.g., 'my_project.server').
+    """
+    try:
+        mod = importlib.import_module(module_path)
+    except ImportError as e:
+        console.print(f"[red]Error:[/red] Could not import '{module_path}': {e}")
+        sys.exit(1)
+
+    server = getattr(mod, "server", None)
+    if server is None:
+        console.print(
+            f"[red]Error:[/red] Module '{module_path}' has no 'server' attribute. "
+            "Define an AgentMCPServer instance named 'server'."
+        )
+        sys.exit(1)
+
+    console.print(f"[green]Starting MCP server[/green] '{server.name}' via {transport}")
+    server.run(transport=transport)
+
+
+@main.command()
+@click.argument("module_path")
+@click.option("--input", "-i", "input_data", default=None, help="JSON input data")
+@click.option(
+    "--format", "-f", "output_format",
+    default="text",
+    type=click.Choice(["json", "markdown", "text"]),
+)
+def run(module_path: str, input_data: str | None, output_format: str):
+    """Run a pipeline directly from a Python module.
+
+    MODULE_PATH should be a dotted path to a module containing a Pipeline
+    instance named 'pipeline' (e.g., 'my_project.pipeline').
+    """
+    import json as json_mod
+
+    from agent_mcp_framework.agent import AgentContext
+    from agent_mcp_framework.server import format_pipeline_result
+
+    try:
+        mod = importlib.import_module(module_path)
+    except ImportError as e:
+        console.print(f"[red]Error:[/red] Could not import '{module_path}': {e}")
+        sys.exit(1)
+
+    pipeline = getattr(mod, "pipeline", None)
+    if pipeline is None:
+        console.print(
+            f"[red]Error:[/red] Module '{module_path}' has no 'pipeline' attribute."
+        )
+        sys.exit(1)
+
+    ctx = AgentContext()
+    if input_data:
+        try:
+            ctx.data = json_mod.loads(input_data)
+        except json_mod.JSONDecodeError as e:
+            console.print(f"[red]Error:[/red] Invalid JSON input: {e}")
+            sys.exit(1)
+
+    result = asyncio.run(pipeline.execute(ctx))
+    output = format_pipeline_result(result, output_format)
+    console.print(output)
+
+    if not result.success:
+        sys.exit(1)
+
+
+@main.command()
+def info():
+    """Show framework version and capabilities."""
+    table = Table(title="agent-mcp-framework")
+    table.add_column("Property", style="cyan")
+    table.add_column("Value", style="green")
+
+    table.add_row("Version", __version__)
+    table.add_row("Agents", "Agent, LLMAgent, FunctionAgent")
+    table.add_row("Pipelines", "Sequential, Parallel, Conditional, MapReduce")
+    table.add_row("Transports", "stdio, SSE")
+    table.add_row("Output Formats", "JSON, Markdown, Text")
+
+    console.print(table)
+
+
+if __name__ == "__main__":
+    main()

agent_mcp_framework/formatters.py

@@ -0,0 +1,61 @@
+"""Output formatting for agent results."""
+
+from __future__ import annotations
+
+import json
+
+from agent_mcp_framework.agent import AgentResult
+
+
+def format_result(result: AgentResult, fmt: str = "json") -> str:
+    """Format an agent result for output."""
+    if fmt == "json":
+        return _format_json(result)
+    elif fmt == "markdown":
+        return _format_markdown(result)
+    elif fmt == "text":
+        return _format_text(result)
+    else:
+        raise ValueError(f"Unknown format: {fmt}. Valid: json, markdown, text")
+
+
+def _format_json(result: AgentResult) -> str:
+    data = {
+        "success": result.success,
+        "agent": result.agent_name,
+        "duration_ms": round(result.duration_ms, 2),
+    }
+    if result.output is not None:
+        data["output"] = result.output
+    if result.error:
+        data["error"] = result.error
+    if result.metadata:
+        data["metadata"] = result.metadata
+    return json.dumps(data, indent=2, default=str)
+
+
+def _format_markdown(result: AgentResult) -> str:
+    icon = "+" if result.success else "x"
+    lines = [
+        f"## [{icon}] {result.agent_name}",
+        f"**Duration:** {result.duration_ms:.0f}ms",
+        "",
+    ]
+    if result.output is not None:
+        output = result.output
+        if isinstance(output, (dict, list)):
+            output = json.dumps(output, indent=2, default=str)
+        lines.append(f"```\n{output}\n```")
+    if result.error:
+        lines.append(f"**Error:** {result.error}")
+    return "\n".join(lines)
+
+
+def _format_text(result: AgentResult) -> str:
+    status = "OK" if result.success else "FAIL"
+    parts = [f"[{status}] {result.agent_name} ({result.duration_ms:.0f}ms)"]
+    if result.output is not None:
+        parts.append(str(result.output))
+    if result.error:
+        parts.append(f"Error: {result.error}")
+    return "\n".join(parts)

agent_mcp_framework/pipeline.py

@@ -0,0 +1,238 @@
+"""Pipeline composition patterns for multi-agent workflows."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+from pydantic import BaseModel, Field
+
+from agent_mcp_framework.agent import Agent, AgentContext, AgentResult
+
+
+class PipelineResult(BaseModel):
+    """Aggregated result from a pipeline execution."""
+
+    success: bool
+    results: list[AgentResult] = Field(default_factory=list)
+    duration_ms: float = 0.0
+    pipeline_name: str = ""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def failed(self) -> list[AgentResult]:
+        return [r for r in self.results if not r.success]
+
+    @property
+    def outputs(self) -> dict[str, Any]:
+        return {r.agent_name: r.output for r in self.results}
+
+
+class Pipeline(ABC):
+    """Base class for agent composition patterns."""
+
+    def __init__(self, name: str, agents: list[Agent] | None = None):
+        self.name = name
+        self.agents: list[Agent] = agents or []
+
+    def add(self, agent: Agent) -> Pipeline:
+        """Add an agent to the pipeline."""
+        self.agents.append(agent)
+        return self
+
+    @abstractmethod
+    async def execute(self, context: AgentContext | None = None) -> PipelineResult:
+        """Execute the pipeline. Must be implemented by subclasses."""
+        ...
+
+
+class SequentialPipeline(Pipeline):
+    """Execute agents one after another. Each agent sees the updated context.
+
+    If `stop_on_failure` is True (default), the pipeline stops when any agent fails.
+    """
+
+    def __init__(
+        self, name: str, agents: list[Agent] | None = None, stop_on_failure: bool = True
+    ):
+        super().__init__(name, agents)
+        self.stop_on_failure = stop_on_failure
+
+    async def execute(self, context: AgentContext | None = None) -> PipelineResult:
+        ctx = context or AgentContext()
+        results: list[AgentResult] = []
+        start = time.monotonic()
+
+        for agent in self.agents:
+            result = await agent.execute(ctx)
+            results.append(result)
+            if not result.success and self.stop_on_failure:
+                break
+
+        duration = (time.monotonic() - start) * 1000
+        all_ok = all(r.success for r in results)
+        return PipelineResult(
+            success=all_ok,
+            results=results,
+            duration_ms=duration,
+            pipeline_name=self.name,
+        )
+
+
+class ParallelPipeline(Pipeline):
+    """Execute agents concurrently with isolated contexts.
+
+    Each agent receives a snapshot of the input context to prevent race
+    conditions on shared mutable state. After all agents complete, their
+    contexts are merged back into the original.
+
+    If `max_concurrency` is set, limits how many agents run simultaneously.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        agents: list[Agent] | None = None,
+        max_concurrency: int | None = None,
+    ):
+        super().__init__(name, agents)
+        self.max_concurrency = max_concurrency
+
+    async def execute(self, context: AgentContext | None = None) -> PipelineResult:
+        ctx = context or AgentContext()
+        start = time.monotonic()
+
+        # Each agent gets an isolated copy to prevent race conditions
+        snapshots = [ctx.model_copy(deep=True) for _ in self.agents]
+
+        if self.max_concurrency:
+            sem = asyncio.Semaphore(self.max_concurrency)
+
+            async def run_with_sem(agent: Agent, snap: AgentContext) -> AgentResult:
+                async with sem:
+                    return await agent.execute(snap)
+
+            results = await asyncio.gather(
+                *[run_with_sem(a, s) for a, s in zip(self.agents, snapshots)]
+            )
+        else:
+            results = await asyncio.gather(
+                *[a.execute(s) for a, s in zip(self.agents, snapshots)]
+            )
+
+        # Merge snapshot data back into the original context
+        for snap in snapshots:
+            ctx.data.update(snap.data)
+            ctx.errors.extend(e for e in snap.errors if e not in ctx.errors)
+
+        results = list(results)
+        duration = (time.monotonic() - start) * 1000
+        all_ok = all(r.success for r in results)
+        return PipelineResult(
+            success=all_ok,
+            results=results,
+            duration_ms=duration,
+            pipeline_name=self.name,
+        )
+
+
+class ConditionalPipeline(Pipeline):
+    """Route to different agents based on a condition function.
+
+    The `router` function receives the context and returns the name of the
+    agent to execute, or None to skip.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        agents: list[Agent] | None = None,
+        router: Callable[[AgentContext], str | None] = None,
+    ):
+        super().__init__(name, agents)
+        self.router = router
+
+    def _agent_map(self) -> dict[str, Agent]:
+        return {a.name: a for a in self.agents}
+
+    async def execute(self, context: AgentContext | None = None) -> PipelineResult:
+        ctx = context or AgentContext()
+        start = time.monotonic()
+
+        if self.router is None:
+            raise ValueError("ConditionalPipeline requires a router function")
+
+        target_name = self.router(ctx)
+        results: list[AgentResult] = []
+
+        if target_name is not None:
+            agent_map = self._agent_map()
+            if target_name not in agent_map:
+                raise ValueError(
+                    f"Router returned '{target_name}' but no agent with that name exists. "
+                    f"Available: {list(agent_map.keys())}"
+                )
+            result = await agent_map[target_name].execute(ctx)
+            results.append(result)
+
+        duration = (time.monotonic() - start) * 1000
+        all_ok = all(r.success for r in results) if results else True
+        return PipelineResult(
+            success=all_ok,
+            results=results,
+            duration_ms=duration,
+            pipeline_name=self.name,
+        )
+
+
+class MapReducePipeline(Pipeline):
+    """Fan-out work across agents, then reduce results.
+
+    The `splitter` function breaks the context into N sub-contexts (one per agent).
+    The `reducer` function combines all results into the final context.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        agents: list[Agent] | None = None,
+        splitter: Callable[[AgentContext], list[AgentContext]] | None = None,
+        reducer: Callable[[list[AgentResult], AgentContext], None] | None = None,
+    ):
+        super().__init__(name, agents)
+        self.splitter = splitter
+        self.reducer = reducer
+
+    async def execute(self, context: AgentContext | None = None) -> PipelineResult:
+        ctx = context or AgentContext()
+        start = time.monotonic()
+
+        if self.splitter is None:
+            raise ValueError("MapReducePipeline requires a splitter function")
+
+        sub_contexts = self.splitter(ctx)
+
+        if len(sub_contexts) != len(self.agents):
+            raise ValueError(
+                f"Splitter returned {len(sub_contexts)} contexts but pipeline "
+                f"has {len(self.agents)} agents"
+            )
+
+        results = await asyncio.gather(
+            *[agent.execute(sub_ctx) for agent, sub_ctx in zip(self.agents, sub_contexts)]
+        )
+        results = list(results)
+
+        if self.reducer:
+            self.reducer(results, ctx)
+
+        duration = (time.monotonic() - start) * 1000
+        all_ok = all(r.success for r in results)
+        return PipelineResult(
+            success=all_ok,
+            results=results,
+            duration_ms=duration,
+            pipeline_name=self.name,
+        )

agent_mcp_framework/server.py

@@ -0,0 +1,155 @@
+"""MCP Server that exposes agent pipelines as tools."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+
+from mcp.server.fastmcp import FastMCP
+
+from agent_mcp_framework.agent import Agent, AgentContext
+from agent_mcp_framework.formatters import format_result
+from agent_mcp_framework.pipeline import Pipeline, PipelineResult
+
+
+class AgentMCPServer:
+    """Wraps agent pipelines as MCP tools served over stdio/SSE.
+
+    Example:
+        server = AgentMCPServer("my-server", description="Code analysis tools")
+        server.add_agent_tool(
+            my_agent,
+            name="analyze",
+            description="Analyze code quality",
+        )
+        server.run()
+    """
+
+    def __init__(self, name: str, description: str = ""):
+        self.name = name
+        self.description = description
+        self._mcp = FastMCP(name)
+        self._agents: dict[str, Agent] = {}
+        self._pipelines: dict[str, Pipeline] = {}
+
+    def add_agent_tool(
+        self,
+        agent: Agent,
+        name: str | None = None,
+        description: str | None = None,
+        context_mapper: Callable[[dict[str, Any]], AgentContext] | None = None,
+        output_format: str = "json",
+    ) -> AgentMCPServer:
+        """Register an agent as an MCP tool.
+
+        Args:
+            agent: The agent to expose as a tool.
+            name: Tool name (defaults to agent.name).
+            description: Tool description (defaults to agent.description).
+            context_mapper: Function to convert tool params into an AgentContext.
+            output_format: How to format the result ("json", "markdown", "text").
+        """
+        tool_name = name or agent.name
+        tool_desc = description or agent.description
+        self._agents[tool_name] = agent
+        mapper = context_mapper or _default_context_mapper
+
+        async def tool_handler(**kwargs) -> str:
+            ctx = mapper(kwargs)
+            result = await agent.execute(ctx)
+            return format_result(result, output_format)
+
+        # Register with FastMCP
+        self._mcp.add_tool(
+            tool_handler,
+            name=tool_name,
+            description=tool_desc,
+        )
+        return self
+
+    def add_pipeline_tool(
+        self,
+        pipeline: Pipeline,
+        name: str | None = None,
+        description: str = "",
+        context_mapper: Callable[[dict[str, Any]], AgentContext] | None = None,
+        output_format: str = "json",
+    ) -> AgentMCPServer:
+        """Register a pipeline as an MCP tool."""
+        tool_name = name or pipeline.name
+        self._pipelines[tool_name] = pipeline
+
+        mapper = context_mapper or _default_context_mapper
+
+        async def pipeline_handler(**kwargs) -> str:
+            ctx = mapper(kwargs)
+            result = await pipeline.execute(ctx)
+            return format_pipeline_result(result, output_format)
+
+        self._mcp.add_tool(
+            pipeline_handler,
+            name=tool_name,
+            description=description,
+        )
+        return self
+
+    def run(self, transport: str = "stdio") -> None:
+        """Start the MCP server."""
+        self._mcp.run(transport=transport)
+
+    async def run_async(self, transport: str = "stdio") -> None:
+        """Start the MCP server asynchronously."""
+        if transport == "stdio":
+            await self._mcp.run_stdio_async()
+        elif transport == "sse":
+            await self._mcp.run_sse_async()
+        else:
+            raise ValueError(f"Unknown transport: {transport}")
+
+
+def _default_context_mapper(params: dict[str, Any]) -> AgentContext:
+    """Default mapping: put all params into context.data."""
+    return AgentContext(data=params)
+
+
+def format_pipeline_result(result: PipelineResult, fmt: str = "json") -> str:
+    """Format a pipeline result for MCP output."""
+    if fmt == "json":
+        return json.dumps(
+            {
+                "success": result.success,
+                "pipeline": result.pipeline_name,
+                "duration_ms": round(result.duration_ms, 2),
+                "results": [
+                    {
+                        "agent": r.agent_name,
+                        "success": r.success,
+                        "output": r.output,
+                        "error": r.error,
+                        "duration_ms": round(r.duration_ms, 2),
+                    }
+                    for r in result.results
+                ],
+            },
+            indent=2,
+            default=str,
+        )
+    elif fmt == "markdown":
+        lines = [f"## Pipeline: {result.pipeline_name}"]
+        lines.append(f"**Status:** {'Success' if result.success else 'Failed'}")
+        lines.append(f"**Duration:** {result.duration_ms:.0f}ms\n")
+        for r in result.results:
+            icon = "+" if r.success else "x"
+            lines.append(f"### [{icon}] {r.agent_name} ({r.duration_ms:.0f}ms)")
+            if r.output is not None:
+                lines.append(f"```\n{r.output}\n```")
+            if r.error:
+                lines.append(f"**Error:** {r.error}")
+            lines.append("")
+        return "\n".join(lines)
+    else:
+        parts = [f"Pipeline '{result.pipeline_name}': {'OK' if result.success else 'FAILED'}"]
+        for r in result.results:
+            status = "OK" if r.success else "FAIL"
+            parts.append(f"  [{status}] {r.agent_name}: {r.output or r.error}")
+        return "\n".join(parts)

agent_mcp_framework-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: agent-mcp-framework
+Version: 0.1.0
+Summary: A Python framework for building multi-agent MCP servers
+Project-URL: Homepage, https://github.com/bifrostlabs/agent-mcp-framework
+Project-URL: Documentation, https://github.com/bifrostlabs/agent-mcp-framework#readme
+Project-URL: Repository, https://github.com/bifrostlabs/agent-mcp-framework
+Project-URL: Issues, https://github.com/bifrostlabs/agent-mcp-framework/issues
+Author-email: Jarrad Bermingham <jarrad@bifrostlabs.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,llm,mcp,model-context-protocol,multi-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agent-mcp-framework
+
+A Python framework for building multi-agent MCP (Model Context Protocol) servers.
+
+Build production-ready multi-agent systems that expose their capabilities as MCP tools — ready to integrate with Claude, VSCode, and any MCP-compatible client.
+
+## Features
+
+- **Agent abstractions** — `Agent`, `LLMAgent`, `FunctionAgent` with lifecycle hooks
+- **Pipeline composition** — Sequential, Parallel, Conditional, and MapReduce patterns
+- **MCP integration** — Expose agent pipelines as MCP tools over stdio or SSE
+- **Output formatting** — JSON, Markdown, and plain text output modes
+- **CLI** — Run servers and pipelines from the command line
+
+## Installation
+
+```bash
+pip install agent-mcp-framework
+```
+
+## Quick Start
+
+```python
+from agent_mcp_framework import Agent, AgentContext, AgentResult, SequentialPipeline, AgentMCPServer
+
+
+class AnalyzerAgent(Agent):
+    async def run(self, context: AgentContext) -> AgentResult:
+        code = context.get("code", "")
+        issues = []
+        if len(code.splitlines()) > 500:
+            issues.append("File exceeds 500 lines — consider splitting")
+        if "import *" in code:
+            issues.append("Wildcard imports detected")
+        context.set("issues", issues)
+        return AgentResult(success=True, output={"issues": issues, "count": len(issues)})
+
+
+class ScorerAgent(Agent):
+    async def run(self, context: AgentContext) -> AgentResult:
+        issues = context.get("issues", [])
+        score = max(0, 100 - len(issues) * 15)
+        return AgentResult(success=True, output={"score": score, "grade": "A" if score >= 90 else "B" if score >= 70 else "C"})
+
+
+# Compose agents into a pipeline
+pipeline = SequentialPipeline("code-review", agents=[
+    AnalyzerAgent("analyzer", description="Find code issues"),
+    ScorerAgent("scorer", description="Score code quality"),
+])
+
+# Expose as an MCP server
+server = AgentMCPServer("code-review-server", description="Multi-agent code review")
+server.add_pipeline_tool(
+    pipeline,
+    name="review_code",
+    description="Analyze code quality and return a score",
+)
+
+if __name__ == "__main__":
+    server.run()  # Starts MCP server on stdio
+```
+
+## Agent Types
+
+### `Agent` — Base class
+Implement `run()` to define your agent's logic.
+
+### `LLMAgent` — Claude-powered agent
+Built-in Anthropic client with `complete()` helper for LLM calls.
+
+### `FunctionAgent` — Quick inline agents
+Wrap any async function as an agent without subclassing.
+
+## Pipeline Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `SequentialPipeline` | Run agents one after another, each seeing updated context |
+| `ParallelPipeline` | Run agents concurrently with optional concurrency limits |
+| `ConditionalPipeline` | Route to agents based on a condition function |
+| `MapReducePipeline` | Split work, fan out, and reduce results |
+
+## CLI
+
+```bash
+# Start an MCP server
+agent-mcp serve my_project.server
+
+# Run a pipeline directly
+agent-mcp run my_project.pipeline --input '{"code": "import *"}'
+
+# Show framework info
+agent-mcp info
+```
+
+## License
+
+MIT

agent_mcp_framework-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+agent_mcp_framework/__init__.py,sha256=O4RglxX_Z6niquDMIRH-w4AP1UCaWOuptsv4A573Hnk,706
+agent_mcp_framework/agent.py,sha256=EgGZBRcRvtSaf34hImb6uyDQBHdLIIGx9gkmXq-o2ts,6313
+agent_mcp_framework/cli.py,sha256=3Ur6RoN_fNbLSQ6ml0ys7Y6Fpu53sOCRmBBPu04H5V4,3502
+agent_mcp_framework/formatters.py,sha256=PQZtBUfkNYNDqhHKVYxBM84WZq25CHN43dAu-tG9U2s,1856
+agent_mcp_framework/pipeline.py,sha256=s-aerkmcVh-QLiDVa59bZh5l94nOFxV-TN-LCO217hc,7712
+agent_mcp_framework/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_mcp_framework/server.py,sha256=i8H93qLIuyKaPRepEXsEfbNBzbtxNMTpvawXGwRvS_4,5414
+agent_mcp_framework-0.1.0.dist-info/METADATA,sha256=54-L4DnAUy06oChebbpFnk2W8F9LrHDotUnZCLB1w2g,4665
+agent_mcp_framework-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+agent_mcp_framework-0.1.0.dist-info/entry_points.txt,sha256=viNuRjlGdG6WC0pWF6Ts41TZPMPGcVN2menoNKfYKEY,59
+agent_mcp_framework-0.1.0.dist-info/licenses/LICENSE,sha256=pxGZ-WmjWu8N3FUJi6lu7o-p1fW3m5TqAR5SWn1HvIg,1089
+agent_mcp_framework-0.1.0.dist-info/RECORD,,

agent_mcp_framework-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_mcp_framework-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-mcp = agent_mcp_framework.cli:main

agent_mcp_framework-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jarrad Bermingham / Bifrost Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.