agent-mcp-framework 0.1.0__tar.gz

agent_mcp_framework-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+venv/
+env/
+.env
+*.log
+.coverage
+htmlcov/
+.tox/

agent_mcp_framework-0.1.0/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.

agent_mcp_framework-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,99 @@
+# 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/examples/code_review_server.py

@@ -0,0 +1,180 @@
+"""Example: Multi-agent code review MCP server.
+
+This demonstrates building a production-ready multi-agent system that:
+1. Analyzes code for quality issues
+2. Checks for security vulnerabilities
+3. Reviews architecture patterns
+4. Produces a scored report
+
+Run as MCP server:
+    agent-mcp serve examples.code_review_server
+
+Or run the pipeline directly:
+    agent-mcp run examples.code_review_server -i '{"code": "import os; os.system(input())"}'
+"""
+
+from agent_mcp_framework import (
+    Agent,
+    AgentContext,
+    AgentMCPServer,
+    AgentResult,
+    ParallelPipeline,
+    SequentialPipeline,
+)
+
+
+class QualityAnalyzer(Agent):
+    """Checks code quality metrics."""
+
+    async def run(self, context: AgentContext) -> AgentResult:
+        code = context.get("code", "")
+        lines = code.splitlines()
+        issues = []
+
+        if len(lines) > 500:
+            issues.append({"severity": "warning", "message": "File exceeds 500 lines"})
+        if any("import *" in line for line in lines):
+            issues.append({"severity": "error", "message": "Wildcard imports detected"})
+        if any(len(line) > 120 for line in lines):
+            issues.append({"severity": "info", "message": "Lines exceed 120 chars"})
+        has_docstring = any(
+            line.strip().startswith('"""') or line.strip().startswith("'''")
+            for line in lines
+        )
+        if not has_docstring:
+            issues.append({"severity": "info", "message": "No docstrings found"})
+
+        context.set("quality_issues", issues)
+        return AgentResult(
+            success=True,
+            output={"issues": issues, "count": len(issues)},
+        )
+
+
+class SecurityScanner(Agent):
+    """Checks for common security issues."""
+
+    PATTERNS = [
+        ("eval(", "Use of eval() — potential code injection"),
+        ("exec(", "Use of exec() — potential code injection"),
+        ("os.system(", "Use of os.system() — potential command injection"),
+        ("subprocess.call(", "Use of subprocess.call with shell=True risk"),
+        ("pickle.loads(", "Deserialization of untrusted data"),
+        ("__import__(", "Dynamic import — potential security risk"),
+        ("password", "Potential hardcoded credentials"),
+        ("secret", "Potential hardcoded secrets"),
+    ]
+
+    async def run(self, context: AgentContext) -> AgentResult:
+        code = context.get("code", "")
+        findings = []
+
+        for pattern, message in self.PATTERNS:
+            if pattern in code.lower():
+                findings.append({"severity": "critical", "message": message, "pattern": pattern})
+
+        context.set("security_findings", findings)
+        return AgentResult(
+            success=True,
+            output={"findings": findings, "count": len(findings)},
+        )
+
+
+class ArchitectureReviewer(Agent):
+    """Reviews architectural patterns and best practices."""
+
+    async def run(self, context: AgentContext) -> AgentResult:
+        code = context.get("code", "")
+        observations = []
+
+        if "class " in code:
+            class_count = code.count("class ")
+            if class_count > 5:
+                observations.append("Multiple classes in one file — consider splitting")
+        if code.count("def ") > 20:
+            observations.append("Many functions — consider modularizing")
+        if "global " in code:
+            observations.append("Global state detected — consider dependency injection")
+        if code.count("try:") > 10:
+            observations.append("Many try/except blocks — consider structured error handling")
+
+        context.set("architecture_notes", observations)
+        return AgentResult(
+            success=True,
+            output={"observations": observations, "count": len(observations)},
+        )
+
+
+class ReportGenerator(Agent):
+    """Combines all analysis into a final scored report."""
+
+    async def run(self, context: AgentContext) -> AgentResult:
+        quality = context.get("quality_issues", [])
+        security = context.get("security_findings", [])
+        architecture = context.get("architecture_notes", [])
+
+        # Score calculation
+        score = 100
+        for issue in quality:
+            score -= {"error": 15, "warning": 10, "info": 3}.get(issue.get("severity", "info"), 5)
+        for finding in security:
+            score -= {"critical": 25, "high": 15, "medium": 10}.get(
+                finding.get("severity", "medium"), 10
+            )
+        score -= len(architecture) * 5
+        score = max(0, score)
+
+        grade = "A" if score >= 90 else "B" if score >= 70 else "C" if score >= 50 else "F"
+
+        report = {
+            "score": score,
+            "grade": grade,
+            "quality": {"count": len(quality), "issues": quality},
+            "security": {"count": len(security), "findings": security},
+            "architecture": {"count": len(architecture), "notes": architecture},
+        }
+
+        return AgentResult(success=True, output=report)
+
+
+# Build the pipeline: analyze in parallel, then generate report
+analysis_pipeline = ParallelPipeline(
+    "analysis",
+    agents=[
+        QualityAnalyzer("quality", description="Code quality analysis"),
+        SecurityScanner("security", description="Security vulnerability scan"),
+        ArchitectureReviewer("architecture", description="Architecture review"),
+    ],
+)
+
+report_pipeline = SequentialPipeline(
+    "report",
+    agents=[ReportGenerator("reporter", description="Generate scored report")],
+)
+
+
+# Combined pipeline for CLI usage
+class PipelineRunner(Agent):
+    """Runs the analysis pipeline then generates a report."""
+
+    async def run(self, context: AgentContext) -> AgentResult:
+        await analysis_pipeline.execute(context)
+        result = await report_pipeline.execute(context)
+        if result.results:
+            return result.results[0]
+        return AgentResult(success=False, error="No report")
+
+
+pipeline = SequentialPipeline("code-review", agents=[PipelineRunner("runner")])
+
+# MCP Server
+server = AgentMCPServer("code-review", description="Multi-agent code review server")
+
+server.add_pipeline_tool(
+    SequentialPipeline("review", agents=[PipelineRunner("runner")]),
+    name="review_code",
+    description="Analyze code for quality, security, and architecture issues.",
+)
+
+if __name__ == "__main__":
+    server.run()

agent_mcp_framework-0.1.0/examples/llm_pipeline.py

@@ -0,0 +1,91 @@
+"""Example: LLM-powered multi-agent pipeline.
+
+This shows how to use LLMAgent with Claude for intelligent analysis.
+Requires ANTHROPIC_API_KEY environment variable.
+
+Run:
+    python examples/llm_pipeline.py
+"""
+
+import asyncio
+
+from agent_mcp_framework import AgentContext, AgentResult, SequentialPipeline
+from agent_mcp_framework.agent import LLMAgent
+
+
+class SummarizerAgent(LLMAgent):
+    """Summarizes text content using Claude."""
+
+    async def run(self, context: AgentContext) -> AgentResult:
+        text = context.get("text", "")
+        if not text:
+            return AgentResult(success=False, error="No text provided")
+
+        summary = await self.complete(
+            f"Summarize this text in 2-3 sentences:\n\n{text}"
+        )
+        context.set("summary", summary)
+        return AgentResult(success=True, output=summary)
+
+
+class SentimentAgent(LLMAgent):
+    """Analyzes sentiment of text using Claude."""
+
+    async def run(self, context: AgentContext) -> AgentResult:
+        text = context.get("text", "")
+        if not text:
+            return AgentResult(success=False, error="No text provided")
+
+        analysis = await self.complete(
+            f"Analyze the sentiment of this text. "
+            f"Return one of: positive, negative, neutral, mixed.\n\n{text}"
+        )
+        context.set("sentiment", analysis.strip().lower())
+        return AgentResult(success=True, output=analysis.strip())
+
+
+class InsightsAgent(LLMAgent):
+    """Generates insights combining summary and sentiment."""
+
+    async def run(self, context: AgentContext) -> AgentResult:
+        summary = context.get("summary", "")
+        sentiment = context.get("sentiment", "")
+
+        insights = await self.complete(
+            f"Given this summary: {summary}\n"
+            f"And this sentiment: {sentiment}\n\n"
+            f"Provide 3 actionable insights in bullet points."
+        )
+        return AgentResult(success=True, output=insights)
+
+
+pipeline = SequentialPipeline("text-analysis", agents=[
+    SummarizerAgent("summarizer", system_prompt="You are a concise summarizer."),
+    SentimentAgent("sentiment", system_prompt="You are a sentiment analyst."),
+    InsightsAgent("insights", system_prompt="You are a business analyst."),
+])
+
+
+async def main():
+    sample_text = """
+    The new product launch exceeded expectations with 50,000 signups in the first week.
+    Customer feedback has been overwhelmingly positive, with particular praise for the
+    intuitive interface and fast performance. However, several users reported issues with
+    the mobile experience and the onboarding flow could be smoother. The engineering team
+    is already working on fixes for the next release.
+    """
+
+    ctx = AgentContext(data={"text": sample_text})
+    result = await pipeline.execute(ctx)
+
+    print(f"Pipeline: {result.pipeline_name}")
+    print(f"Success: {result.success}")
+    print(f"Duration: {result.duration_ms:.0f}ms\n")
+    for r in result.results:
+        print(f"--- {r.agent_name} ({r.duration_ms:.0f}ms) ---")
+        print(r.output)
+        print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent_mcp_framework-0.1.0/examples/quickstart.py

@@ -0,0 +1,44 @@
+"""Minimal quickstart example showing core concepts.
+
+Run:
+    python examples/quickstart.py
+"""
+
+import asyncio
+
+from agent_mcp_framework import Agent, AgentContext, AgentResult, SequentialPipeline
+
+
+class GreeterAgent(Agent):
+    async def run(self, context: AgentContext) -> AgentResult:
+        name = context.get("name", "World")
+        greeting = f"Hello, {name}!"
+        context.set("greeting", greeting)
+        return AgentResult(success=True, output=greeting)
+
+
+class ShoutAgent(Agent):
+    async def run(self, context: AgentContext) -> AgentResult:
+        greeting = context.get("greeting", "")
+        shouted = greeting.upper()
+        return AgentResult(success=True, output=shouted)
+
+
+async def main():
+    pipeline = SequentialPipeline("greet-and-shout", agents=[
+        GreeterAgent("greeter", description="Says hello"),
+        ShoutAgent("shouter", description="Makes it loud"),
+    ])
+
+    ctx = AgentContext(data={"name": "Developer"})
+    result = await pipeline.execute(ctx)
+
+    print(f"Pipeline: {result.pipeline_name}")
+    print(f"Success: {result.success}")
+    print(f"Duration: {result.duration_ms:.0f}ms")
+    for r in result.results:
+        print(f"  [{r.agent_name}] {r.output}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent_mcp_framework-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-mcp-framework"
+version = "0.1.0"
+description = "A Python framework for building multi-agent MCP servers"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Jarrad Bermingham", email = "jarrad@bifrostlabs.ai" },
+]
+keywords = ["mcp", "agents", "multi-agent", "llm", "ai", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "anthropic>=0.40.0",
+    "click>=8.0.0",
+    "pydantic>=2.0.0",
+    "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.5.0",
+]
+
+[project.scripts]
+agent-mcp = "agent_mcp_framework.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/bifrostlabs/agent-mcp-framework"
+Documentation = "https://github.com/bifrostlabs/agent-mcp-framework#readme"
+Repository = "https://github.com/bifrostlabs/agent-mcp-framework"
+Issues = "https://github.com/bifrostlabs/agent-mcp-framework/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_mcp_framework"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]

agent_mcp_framework-0.1.0/src/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",
+]