MCP Agent Orchestration System

Sistema de Orquestación de Agentes MCP

Una implementación en Python de un sistema de orquestación de agentes basado en estados, utilizando el Protocolo de Contexto de Modelos (MCP).

¿Qué es MCP?

El Protocolo de Contexto de Modelos (MCP) permite que las aplicaciones proporcionen contexto a los LLM de manera estandarizada, separando las preocupaciones de proporcionar contexto de la interacción real con el LLM. Con MCP, puedes construir servidores que expongan:

• Recursos: Fuentes de datos que proporcionan información a los LLM
• Herramientas: Funciones que permiten a los LLM realizar acciones
• Prompts: Plantillas reutilizables para interacciones con LLM

Instalación

Requisitos previos

• Python 3.10 o superior
• MCP Python SDK 1.2.0 o superior

Configuración de tu entorno

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

Clonar o descargar los archivos del proyecto

Coloca los archivos del proyecto en tu directorio:

• orchestrator.py - El servidor MCP principal que implementa la máquina de estados
• orchestrator_client.py - Cliente que demuestra el flujo de orquestación
• requirements.txt - Dependencias del proyecto
• .gitignore - Archivo de ignorados de Git

Estructura del proyecto

• orchestrator.py - El servidor MCP principal que implementa la máquina de estados
• orchestrator_client.py - Cliente que demuestra el flujo de orquestación
• requirements.txt - Dependencias del proyecto

Ejecución del sistema de orquestación

1. Inicia el servidor de orquestación directamente para pruebas:

python orchestrator.py

2. En una terminal separada, ejecuta el cliente para ver la orquestación en acción:

python orchestrator_client.py

Integración con Claude para Desktop

1. Instalar Claude para Desktop

Asegúrate de tener Claude para Desktop instalado. Puedes descargar la última versión desde el sitio web de Anthropic.

2. Configurar Claude para Desktop

1. Abre tu archivo de configuración de 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. Agrega la configuración del servidor orquestador:

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

   Reemplaza la ruta con la ruta absoluta a tu archivo orchestrator.py.

3. Guarda el archivo de configuración y reinicia Claude para Desktop.

3. Usando el orquestador en Claude

Una vez configurado, puedes:

1. Abrir Claude para Desktop
2. Hacer clic en el ícono del servidor MCP en la barra lateral
3. Seleccionar "agent-orchestrator" de la lista de servidores disponibles
4. Comenzar a interactuar con el sistema de orquestación

Claude podrá:

• Transicionar entre diferentes estados de agente
• Almacenar y recuperar información de la base de conocimientos
• Mantener el contexto de conversación a través de transiciones de estado
• Acceder a prompts específicos de cada estado

Estados del agente

El sistema de orquestación implementa una máquina de estados con los siguientes estados:

• IDLE: Esperando instrucciones
• PLANNING: Creando un plan estructurado para una tarea
• RESEARCHING: Recopilando información necesaria para una tarea
• EXECUTING: Llevando a cabo las acciones planificadas
• REVIEWING: Evaluando resultados y determinando los siguientes pasos
• ERROR: Manejando errores o situaciones inesperadas

Personalización del sistema

Agregar nuevos estados

1. Agrega el estado al enum AgentState en orchestrator.py
2. Crea una función de prompt para el nuevo estado
3. Actualiza la lógica de transición en _get_available_transitions()
4. Agrega manejadores para el nuevo estado en las funciones de acceso a recursos

Crear herramientas personalizadas

Agrega nuevas herramientas creando funciones decoradas con @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"

Desarrollo y pruebas

Usando la CLI de MCP

La CLI de MCP proporciona herramientas para desarrollo y pruebas:

# 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

Pruebas manuales con 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

• Documentación del SDK de Python para MCP
• Especificación del Protocolo de Contexto de Modelos

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.