# MCP Demo Server with Intelligent Agent System
A production-ready demonstration of a **Model Context Protocol (MCP)** server implemented in Python, featuring an intelligent **Agent System** with subagents and orchestration capabilities. This project showcases best practices for building MCP servers and multi-agent systems with comprehensive examples.
## What is MCP?
The **Model Context Protocol (MCP)** is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). MCP servers expose:
- **Tools**: Executable functions that LLMs can call (e.g., calculator, file operations)
- **Resources**: Data sources that LLMs can read (e.g., configuration, documentation)
- **Prompts**: Reusable prompt templates for common tasks
## Features
### Agent System (NEW!)
**Production-ready intelligent agents that work with MCP:**
1. **Agent** - Core agent with MCP integration
- Execute tasks using MCP tools
- Delegate work to specialized subagents
- Track task execution and results
- Handle errors, retries, and timeouts
2. **SubAgents** - Specialized agents for specific tasks
- CalculatorSubAgent - Mathematical calculations
- FileOperationsSubAgent - File system operations
- WeatherSubAgent - Weather information
- TimestampSubAgent - Timestamp operations
- DataProcessingSubAgent - Data processing pipelines
3. **AgentOrchestrator** - Multi-agent coordination
- Manage pools of agents
- Auto-assign tasks to capable agents
- Execute workflows with dependencies
- Parallel and sequential execution
- Result aggregation and statistics
4. **Task Management** - Robust task system
- Task definitions with priorities
- State tracking (pending, in_progress, completed, failed)
- Retry logic and timeout handling
- Detailed result tracking
### MCP Server Tools
1. **Calculator** - Basic mathematical operations
- Operations: add, subtract, multiply, divide
- Full input validation and error handling
2. **File Operations** - File system interactions
- Read, write, list directories, check file existence
- Safe path handling with proper error messages
3. **Weather** - Simulated weather information
- Get weather data for any city
- Support for Celsius and Fahrenheit
4. **Timestamp** - Get current time in various formats
- ISO format, Unix timestamp, human-readable format
### Resources Available
1. **Server Configuration** (`config://server/settings`)
- Current server settings and metadata
- JSON formatted configuration
2. **System Information** (`system://info`)
- OS, Python version, working directory
- Server process information
3. **Documentation** (`docs://getting-started`)
- Getting started guide
- Usage instructions
### Prompts Provided
1. **Code Review** - Generate code review checklists
- Customizable by programming language
- Adjustable complexity level
2. **Documentation** - Documentation templates
- API, User, and Developer documentation types
- Project-specific customization
3. **Debug Assistant** - Debugging guidance
- Structured debugging approach
- Common techniques and best practices
## Installation
### Prerequisites
- Python 3.10 or higher
- pip (Python package manager)
### Install Dependencies
```bash
# 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
```
### Development Setup
```bash
# Install development dependencies
pip install -r requirements-dev.txt
# Run tests
pytest
# Format code
black src/
# Lint code
ruff check src/
```
## Usage
### Running the Agent System Demo
Experience the full power of the agent system:
```bash
# Run comprehensive agent system demo
python examples/agent_demo.py
```
This demo showcases:
- Simple agent with basic tasks
- Agent with subagents (task delegation)
- Orchestrator managing multiple agents
- Multi-step workflow execution
- Data processing pipeline
### Quick Agent System Example
```python
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())
```
### Using the Orchestrator
```python
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}%")
```
### Running the MCP Server
The server uses stdio for communication, which is the standard transport for MCP servers:
```bash
# Run directly with Python
python -m mcp_demo.server
# Or use the installed script
mcp-demo
```
### Configuration for Claude Desktop
To use this MCP server with Claude Desktop, add it to your Claude configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"demo": {
"command": "python",
"args": [
"-m",
"mcp_demo.server"
],
"env": {}
}
}
}
```
Or using the installed command:
```json
{
"mcpServers": {
"demo": {
"command": "mcp-demo",
"args": [],
"env": {}
}
}
}
```
### Using with MCP Client
You can also use the included example client:
```bash
python examples/client.py
```
## Project Structure
```
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
```
## Code Architecture
### Server Implementation
The server follows a clean, modular architecture:
```python
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"""
```
### Key Design Patterns
1. **Type Safety**: Full type hints with Pydantic models
2. **Error Handling**: Comprehensive try-catch with logging
3. **Validation**: Input validation using Pydantic schemas
4. **Logging**: Structured logging to file and stderr
5. **Async/Await**: Proper async patterns throughout
6. **Separation of Concerns**: Each tool in its own method
## Examples
### Example 1: Using the Calculator Tool
```python
# Tool call from LLM client
{
"name": "calculator",
"arguments": {
"operation": "add",
"a": 15,
"b": 27
}
}
# Response
{
"content": [
{
"type": "text",
"text": "Result: 15 add 27 = 42"
}
]
}
```
### Example 2: Reading a Resource
```python
# 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"]
}
```
### Example 3: Getting a Prompt
```python
# Get code review prompt
{
"name": "code-review",
"arguments": {
"language": "Python",
"complexity": "complex"
}
}
# Response: Detailed code review checklist for Python
```
## Development
### Adding a New Tool
1. Define input schema with Pydantic:
```python
class MyToolInput(BaseModel):
param1: str = Field(description="Description")
param2: int = Field(default=0, description="Description")
```
2. Add tool to `list_tools()`:
```python
Tool(
name="my_tool",
description="What this tool does",
inputSchema=MyToolInput.model_json_schema(),
)
```
3. Implement tool logic:
```python
async def _my_tool(self, arguments: dict) -> list[TextContent]:
tool_input = MyToolInput(**arguments)
# Your implementation here
return [TextContent(type="text", text="Result")]
```
4. Add to `call_tool()` dispatcher:
```python
if name == "my_tool":
return await self._my_tool(arguments)
```
### Adding a New Resource
1. Add to `list_resources()`:
```python
Resource(
uri=AnyUrl("my://resource"),
name="My Resource",
description="What this resource provides",
mimeType="application/json",
)
```
2. Add handler in `read_resource()`:
```python
if uri_str == "my://resource":
data = {"key": "value"}
return json.dumps(data, indent=2)
```
### Adding a New Prompt
1. Add to `list_prompts()`:
```python
Prompt(
name="my-prompt",
description="What this prompt does",
arguments=[
{
"name": "arg1",
"description": "Argument description",
"required": True,
}
],
)
```
2. Add handler in `get_prompt()`:
```python
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),
)
]
)
```
## Testing
Run the comprehensive test suite:
```bash
# 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
```
## Best Practices Demonstrated
1. **Input Validation**: All tool inputs validated with Pydantic
2. **Error Handling**: Comprehensive error handling with meaningful messages
3. **Logging**: Structured logging for debugging and monitoring
4. **Type Safety**: Full type hints throughout the codebase
5. **Documentation**: Comprehensive docstrings and comments
6. **Testing**: Unit tests for all major functionality
7. **Code Quality**: Formatted with Black, linted with Ruff
8. **Async Patterns**: Proper use of async/await
9. **Resource Management**: Proper cleanup and resource handling
10. **Security**: Safe file operations with path validation
## Troubleshooting
### Common Issues
**Issue**: Module not found error
```bash
# Solution: Install in development mode
pip install -e .
```
**Issue**: Server not appearing in Claude Desktop
```bash
# Solution: Check configuration file path and JSON syntax
# Restart Claude Desktop after configuration changes
```
**Issue**: Import errors for `mcp` package
```bash
# Solution: Install latest MCP SDK
pip install --upgrade mcp
```
### Debug Mode
Enable debug logging:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```
Check the log file:
```bash
tail -f mcp_server.log
```
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Documentation
- [Agent System Documentation](docs/AGENT_SYSTEM.md) - Complete guide to the agent system
- [MCP Server Architecture](docs/ARCHITECTURE.md) - MCP server design and implementation
- [Agent Demo Examples](examples/agent_demo.py) - Comprehensive usage examples
## Resources
- [MCP Documentation](https://modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Claude Desktop](https://claude.ai/download)
- [MCP Specification](https://spec.modelcontextprotocol.io/)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Built with the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- Inspired by the MCP community examples
- Thanks to Anthropic for developing the Model Context Protocol
## Support
- Create an issue: [GitHub Issues](https://github.com/yourusername/mcp-agent/issues)
- Documentation: [README](README.md)
- MCP Community: [MCP Discord](https://discord.gg/mcp)
---
**Happy MCP Server Building!** 🚀