MCP Agent Orchestration System

Sistema de Orquestração de Agentes MCP

Uma implementação em Python de um sistema de orquestração de agentes baseado em estados, utilizando o Model Context Protocol (MCP).

O que é MCP?

O Model Context Protocol (MCP) permite que aplicações forneçam contexto para LLMs de forma padronizada, separando as preocupações de fornecer contexto da interação real com o LLM. Com o MCP, você pode construir servidores que expõem:

• Recursos: Fontes de dados que fornecem informações para LLMs
• Ferramentas: Funções que permitem que LLMs executem ações
• Prompts: Modelos reutilizáveis para interações com LLMs

Instalação

Pré-requisitos

• Python 3.10 ou superior
• MCP Python SDK 1.2.0 ou superior

Configurando Seu Ambiente

Usando uv (recomendado)

# 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

Usando pip

# 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 ou Baixe os Arquivos do Projeto

Coloque os arquivos do projeto no seu diretório:

• orchestrator.py - O servidor MCP principal que implementa a máquina de estados
• orchestrator_client.py - Cliente que demonstra o fluxo de orquestração
• requirements.txt - Dependências do projeto
• .gitignore - Arquivo de ignore do Git

Estrutura do Projeto

• orchestrator.py - O servidor MCP principal que implementa a máquina de estados
• orchestrator_client.py - Cliente que demonstra o fluxo de orquestração
• requirements.txt - Dependências do projeto

Executando o Sistema de Orquestração

1. Inicie o servidor de orquestração diretamente para testes:

python orchestrator.py

2. Em um terminal separado, execute o cliente para ver a orquestração em ação:

python orchestrator_client.py

Integrando com o Claude para Desktop

1. Instale o Claude para Desktop

Certifique-se de ter o Claude para Desktop instalado. Você pode baixar a versão mais recente no site da Anthropic.

2. Configure o Claude para Desktop

1. Abra o arquivo de configuração do Claude para Desktop:

   macOS/Linux:

   # Create or edit the configuration file
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

   Windows:

   # Path may vary depending on your Windows version
   code %APPDATA%\Claude\claude_desktop_config.json
   

2. Adicione a configuração do servidor orquestrador:

   {
       "mcpServers": {
           "agent-orchestrator": {
               "command": "python",
               "args": [
                   "/ABSOLUTE/PATH/TO/YOUR/PROJECT/orchestrator.py"
               ]
           }
       }
   }
   

   Substitua o caminho pelo caminho absoluto para o seu arquivo orchestrator.py.

3. Salve o arquivo de configuração e reinicie o Claude para Desktop.

3. Usando o Orquestrador no Claude

Uma vez configurado, você pode:

1. Abrir o Claude para Desktop
2. Clicar no ícone do servidor MCP na barra lateral
3. Selecionar "agent-orchestrator" na lista de servidores disponíveis
4. Começar a interagir com o sistema de orquestração

O Claude será capaz de:

• Transicionar entre diferentes estados de agente
• Armazenar e recuperar informações da base de conhecimento
• Manter o contexto da conversa entre transições de estado
• Acessar prompts específicos de cada estado

Estados do Agente

O sistema de orquestração implementa uma máquina de estados com os seguintes estados:

• IDLE: Aguardando instruções
• PLANNING: Criando um plano estruturado para uma tarefa
• RESEARCHING: Coletando informações necessárias para uma tarefa
• EXECUTING: Executando ações planejadas
• REVIEWING: Avaliando resultados e determinando próximos passos
• ERROR: Tratando erros ou situações inesperadas

Personalizando o Sistema

Adicionando Novos Estados

1. Adicione o estado ao enum AgentState em orchestrator.py
2. Crie uma função de prompt para o novo estado
3. Atualize a lógica de transição em _get_available_transitions()
4. Adicione manipuladores para o novo estado nas funções de acesso a recursos

Criando Ferramentas Personalizadas

Adicione novas ferramentas criando funções decoradas com @mcp.tool():

@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"

Desenvolvimento e Testes

Usando a CLI do MCP

A CLI do MCP fornece ferramentas para desenvolvimento e testes:

# 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

Testes Manuais com 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"})

Recursos

• Documentação do SDK Python do MCP
• Especificação do Model Context Protocol

Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.