# Clone the repository
git clone https://github.com/yourusername/mcp-agent.git
cd mcp-agent

# Install the package
pip install -e .

# Or install dependencies directly
pip install -r requirements.txt

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Format code
black src/

# Lint code
ruff check src/

# Run comprehensive agent system demo
python examples/agent_demo.py

import asyncio
from mcp_demo import Agent, AgentCapability, Task
from mcp_demo import CalculatorSubAgent, FileOperationsSubAgent
from mcp_demo import AgentOrchestrator, Workflow, WorkflowStep

async def main():
    # Create main agent with subagents
    main_agent = Agent(name="MainAgent")
    calc_sub = CalculatorSubAgent(parent_agent=main_agent)
    file_sub = FileOperationsSubAgent(parent_agent=main_agent)

    # Create tasks
    calc_task = Task(
        name="Calculate",
        task_type="calculation",
        parameters={"operation": "add", "a": 10, "b": 20},
    )

    # Execute - automatically delegated to appropriate subagent
    async with main_agent, calc_sub, file_sub:
        result = await main_agent.execute_task(calc_task)
        print(f"Result: {result.data}")

asyncio.run(main())

from mcp_demo import AgentOrchestrator, CalculatorSubAgent, Task

async def orchestrate():
    # Create orchestrator
    orch = AgentOrchestrator(name="MainOrch")

    # Register agents
    orch.register_agent(CalculatorSubAgent())

    # Execute tasks in parallel
    async with orch:
        results = await orch.execute_tasks(
            [task1, task2, task3],
            parallel=True,
        )

        # Get statistics
        stats = orch.get_statistics()
        print(f"Success rate: {stats['overall_success_rate']:.1f}%")

# Run directly with Python
python -m mcp_demo.server

# Or use the installed script
mcp-demo

{
  "mcpServers": {
    "demo": {
      "command": "python",
      "args": [
        "-m",
        "mcp_demo.server"
      ],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "demo": {
      "command": "mcp-demo",
      "args": [],
      "env": {}
    }
  }
}

python examples/client.py

mcp-agent/
├── src/
│   └── mcp_demo/
│       ├── __init__.py          # Package initialization
│       ├── server.py            # MCP server implementation
│       ├── agent.py             # Core agent with MCP integration
│       ├── subagent.py          # Specialized subagents
│       ├── orchestrator.py      # Multi-agent orchestration
│       └── task.py              # Task management system
├── examples/
│   ├── client.py                # Example MCP client
│   ├── agent_demo.py            # Comprehensive agent system demo
│   └── claude_config.json       # Example Claude Desktop config
├── tests/
│   ├── __init__.py
│   ├── test_server.py           # Server tests
│   └── test_agents.py           # Agent system tests
├── docs/
│   ├── ARCHITECTURE.md          # MCP server architecture
│   └── AGENT_SYSTEM.md          # Agent system documentation
├── pyproject.toml               # Project configuration
├── requirements.txt             # Production dependencies
├── requirements-dev.txt         # Development dependencies
├── README.md                    # This file
└── LICENSE                      # MIT License

class MCPDemoServer:
    """Main server class with handler methods"""

    def __init__(self, name: str):
        """Initialize server and register handlers"""

    async def list_tools(self) -> list[Tool]:
        """Return available tools"""

    async def call_tool(self, name: str, arguments: Any) -> list[TextContent]:
        """Execute a tool"""

    async def list_resources(self) -> list[Resource]:
        """Return available resources"""

    async def read_resource(self, uri: AnyUrl) -> str:
        """Read a resource"""

    async def list_prompts(self) -> list[Prompt]:
        """Return available prompts"""

    async def get_prompt(self, name: str, arguments: dict) -> GetPromptResult:
        """Get a prompt with arguments"""

# Tool call from LLM client
{
  "name": "calculator",
  "arguments": {
    "operation": "add",
    "a": 15,
    "b": 27
  }
}

# Response
{
  "content": [
    {
      "type": "text",
      "text": "Result: 15 add 27 = 42"
    }
  ]
}

# Read server configuration
{
  "uri": "config://server/settings"
}

# Response (JSON)
{
  "server_name": "mcp-demo-server",
  "version": "1.0.0",
  "max_connections": 100,
  "features": ["tools", "resources", "prompts"]
}

# Get code review prompt
{
  "name": "code-review",
  "arguments": {
    "language": "Python",
    "complexity": "complex"
  }
}

# Response: Detailed code review checklist for Python

class MyToolInput(BaseModel):
    param1: str = Field(description="Description")
    param2: int = Field(default=0, description="Description")

Tool(
    name="my_tool",
    description="What this tool does",
    inputSchema=MyToolInput.model_json_schema(),
)

async def _my_tool(self, arguments: dict) -> list[TextContent]:
    tool_input = MyToolInput(**arguments)
    # Your implementation here
    return [TextContent(type="text", text="Result")]

if name == "my_tool":
    return await self._my_tool(arguments)

Resource(
    uri=AnyUrl("my://resource"),
    name="My Resource",
    description="What this resource provides",
    mimeType="application/json",
)

if uri_str == "my://resource":
    data = {"key": "value"}
    return json.dumps(data, indent=2)

Prompt(
    name="my-prompt",
    description="What this prompt does",
    arguments=[
        {
            "name": "arg1",
            "description": "Argument description",
            "required": True,
        }
    ],
)

if name == "my-prompt":
    arg1 = arguments.get("arg1")
    message = f"Prompt template with {arg1}"
    return GetPromptResult(
        messages=[
            PromptMessage(
                role="user",
                content=TextContent(type="text", text=message),
            )
        ]
    )

# Run all tests
pytest

# Run with coverage
pytest --cov=mcp_demo --cov-report=html

# Run specific test files
pytest tests/test_server.py      # MCP server tests
pytest tests/test_agents.py      # Agent system tests

# Run with verbose output
pytest -v

# Run agent tests only
pytest tests/test_agents.py -v

# Solution: Install in development mode
pip install -e .

# Solution: Check configuration file path and JSON syntax
# Restart Claude Desktop after configuration changes

# Solution: Install latest MCP SDK
pip install --upgrade mcp

import logging
logging.basicConfig(level=logging.DEBUG)

tail -f mcp_server.log