Content
# MCP Agent Orchestration System
A Python implementation of a state-based agent orchestration system using the Model Context Protocol (MCP).
## What is MCP?
The Model Context Protocol (MCP) allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. With MCP, you can build servers that expose:
- **Resources**: Data sources that provide information to LLMs
- **Tools**: Functions that allow LLMs to perform actions
- **Prompts**: Reusable templates for LLM interactions
## Installation
### Prerequisites
- Python 3.10 or higher
- MCP Python SDK 1.2.0 or higher
### Setting Up Your Environment
#### Using uv (recommended)
```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create a new directory for our project
uv init mcp-agents-orchestra
cd mcp-agents-orchestra
# Create virtual environment and activate it
uv venv
source .venv/bin/activate # On Unix/macOS
.venv\Scripts\activate # On Windows
# Install dependencies
uv add "mcp[cli]" httpx
```
#### Using pip
```bash
# Create a new directory for our project
mkdir mcp-agents-orchestra
cd mcp-agents-orchestra
# Create a virtual environment
python -m venv venv
source venv/bin/activate # On Unix/macOS
venv\Scripts\activate # On Windows
# Install dependencies
pip install "mcp[cli]" httpx
```
### Clone or Download Project Files
Place the project files in your directory:
- `orchestrator.py` - The main MCP server implementing the state machine
- `orchestrator_client.py` - Client demonstrating the orchestration flow
- `requirements.txt` - Dependencies for the project
- `.gitignore` - Git ignore file
## Project Structure
- `orchestrator.py` - The main MCP server implementing the state machine
- `orchestrator_client.py` - Client demonstrating the orchestration flow
- `requirements.txt` - Dependencies for the project
## Running the Orchestration System
1. Start the orchestration server directly for testing:
```bash
python orchestrator.py
```
2. In a separate terminal, run the client to see the orchestration in action:
```bash
python orchestrator_client.py
```
## Integrating with Claude for Desktop
### 1. Install Claude for Desktop
Make sure you have Claude for Desktop installed. You can download the latest version from [Anthropic's website](https://claude.ai/desktop).
### 2. Configure Claude for Desktop
1. Open your Claude for Desktop configuration file:
**macOS/Linux:**
```bash
# Create or edit the configuration file
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
**Windows:**
```bash
# Path may vary depending on your Windows version
code %APPDATA%\Claude\claude_desktop_config.json
```
2. Add the orchestrator server configuration:
```json
{
"mcpServers": {
"agent-orchestrator": {
"command": "python",
"args": [
"/ABSOLUTE/PATH/TO/YOUR/PROJECT/orchestrator.py"
]
}
}
}
```
Replace the path with the absolute path to your orchestrator.py file.
3. Save the configuration file and restart Claude for Desktop.
### 3. Using the Orchestrator in Claude
Once configured, you can:
1. Open Claude for Desktop
2. Click on the MCP server icon in the sidebar
3. Select "agent-orchestrator" from the list of available servers
4. Start interacting with the orchestration system
Claude will be able to:
- Transition between different agent states
- Store and retrieve information from the knowledge base
- Maintain conversation context across state transitions
- Access state-specific prompts
## Agent States
The orchestration system implements a state machine with the following states:
- **IDLE**: Waiting for instructions
- **PLANNING**: Creating a structured plan for a task
- **RESEARCHING**: Gathering information needed for a task
- **EXECUTING**: Carrying out planned actions
- **REVIEWING**: Evaluating results and determining next steps
- **ERROR**: Handling errors or unexpected situations
## Customizing the System
### Adding New States
1. Add the state to the `AgentState` enum in `orchestrator.py`
2. Create a prompt function for the new state
3. Update the transition logic in `_get_available_transitions()`
4. Add handlers for the new state in resource access functions
### Creating Custom Tools
Add new tools by creating functions decorated with `@mcp.tool()`:
```python
@mcp.tool()
def my_custom_tool(arg1: str, arg2: int, ctx: Context) -> str:
"""Description of what this tool does
Args:
arg1: Description of arg1
arg2: Description of arg2
"""
# Implementation here
return "Result"
```
## Development and Testing
### Using the MCP CLI
The MCP CLI provides tools for development and testing:
```bash
# Install MCP CLI if you haven't already
pip install "mcp[cli]"
# Test your server with the MCP Inspector
mcp dev orchestrator.py
# Install in Claude Desktop
mcp install orchestrator.py
```
### Manual Testing with Python
```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async with stdio_client(StdioServerParameters(command="python", args=["orchestrator.py"])) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# Test state transitions
await session.call_tool("transition_state", arguments={"new_state": "PLANNING"})
```
## Resources
- [MCP Python SDK Documentation](https://github.com/anthropics/anthropic-mcp)
- [Model Context Protocol Specification](https://github.com/anthropics/anthropic-mcp/blob/main/README.md)
## License
This project is licensed under the MIT License - see the LICENSE file for details.
