Agent MCP

Agente MCP

Un marco para crear sistemas multiagente utilizando el MCP (Protocolo de contexto de modelo) para una colaboración de IA coordinada y eficiente.

Guía de inicio rápido

Nota: recomiendo usar https://github.com/rinadelph/MultipleCursor para iniciar diferentes ventanas de Cursor en la misma base de código como en la captura de pantalla anterior.

1. Entorno de configuración :
   • Clonar repositorio y copiar .env.example a .env
   • Agregue su clave API de OpenAI a .env
   • Instalar con uv venv && uv pip install -e .
2. Iniciar el servidor MCP :
   uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project
   Importante : El token de administrador se almacena en la base de datos SQLite .agent/mcp_state.db en el contexto del proyecto. Instale una extensión de visor de SQLite para acceder a él.
3. Crear documento de contexto principal (MCD) :
   • Cree MCD.md detallado con la arquitectura del sistema, rutas de API, modelos de datos, etc.
4. Iniciar agente de administración :
   • Iniciar en una ventana/sesión
   • Dale el token de administrador
5. Inicializar agentes de trabajo :
   • Abrir una nueva ventana/sesión para cada trabajador
   • Copie el mensaje del trabajador con el modo automático de la sección 4 a continuación
   • Reemplazar con el ID del agente y el token de administrador correctos

Siga las instrucciones detalladas a continuación para obtener más información.

Características

• Marco de colaboración entre múltiples agentes
• Gestión y coordinación de tareas
• Contexto y compartición de conocimientos entre agentes
• Visualización gráfica de las interacciones de los agentes
• Soporte para incrustación y capacidades RAG
• Tablero interactivo para visualizar tareas, agentes y contexto.

Planificación del proyecto con el Documento de Contexto Principal (DCM)

Antes de comenzar el desarrollo, es fundamental realizar una investigación exhaustiva para crear un Documento de Contexto Principal (DCM) , la única fuente de información fiable para su aplicación. Este documento proporciona un plan detallado que detalla:

• Arquitectura del sistema y relaciones entre componentes
• Diseño UI/UX para todas las pantallas y componentes
• Rutas y puntos finales de API
• Estructuras y modelos de datos
• Unidades y tareas de implementación
• Dependencias y pila de tecnología

El MCD es fundamental porque:

1. Permite a los agentes comprender el sistema general antes de trabajar en componentes individuales.
2. Permite una construcción lineal y coordinada (como construir una casa a partir de planos).
3. Reduce el uso de tokens al proporcionar un contexto estructurado y relevante
4. Previene implementaciones conflictivas entre agentes.

Revise el archivo MCD.md en este repositorio para comprender la estructura y el nivel de detalle requerido. El MCD debe contener:

• Descripción general y objetivos
• Diagramas de contexto y arquitectura
• Requisitos funcionales
• Especificaciones de diseño (UI/UX, API, modelos de datos)
• Detalles de implementación
• Desglose de tareas para agentes

Con un MCD integral, los agentes pueden implementar su aplicación parte por parte con una comprensión clara de cómo cada pieza encaja en el todo.

Instalación

Prerrequisitos

• Python 3.8+
• uv (recomendado para una instalación más rápida del paquete)

Configuración

1. Clonar el repositorio:
   git clone https://github.com/your-username/agent-mcp.git cd agent-mcp
2. Configure las variables de entorno copiando el archivo de ejemplo:
   cp .env.example .env
3. Edite el archivo .env y agregue su clave API de OpenAI:
   OPENAI_API_KEY=your_openai_api_key_here
4. Instalar usando uv:
   uv venv uv pip install -e .
   O con pip:
   pip install -e .

Flujo de trabajo multiagente

Descripción general del flujo de trabajo

1. Comience con una investigación profunda : antes de codificar, utilice IA para ayudar a crear un Documento de contexto principal (MCD) completo
2. Iniciar la infraestructura : inicie el servidor MCP y ubique su token de administrador en la base de datos
3. Configuración del agente de administración : inicialice su agente de administración con el token y INSTRUCCIONES.md
4. Creación de trabajadores : el administrador crea trabajadores especializados para diferentes aspectos de su proyecto.
5. Asignación de tareas : el administrador divide el MCD en tareas discretas y las asigna a los trabajadores.
6. Desarrollo paralelo : los trabajadores ejecutan tareas mientras comparten contexto a través del MCP
7. Preservación del contexto : todos los agentes almacenan su conocimiento en la base de datos central

Bucle de desarrollo

Descripción general de la arquitectura

El sistema MCP utiliza una estructura jerárquica con:

• Agente administrativo : coordina a otros agentes, asigna tareas y mantiene la dirección general del proyecto.
• Agentes trabajadores : agentes especializados que ejecutan tareas específicas (frontend, backend, modelado de datos, etc.)

Configuración y funcionamiento del agente

1. Iniciar el servidor MCP

Opciones:

• --port : Puerto donde se ejecutará el servidor (predeterminado: 8080)
• --project-dir : Directorio base para el proyecto

2. Token de administrador de acceso

El token de administrador proporciona acceso privilegiado al servidor MCP y es necesario para todas las operaciones del agente.

Encontrar el token de administrador :

1. Después de iniciar el servidor, se genera automáticamente un token
2. Este token se almacena en la base de datos SQLite .agent/mcp_state.db
3. Instalar una extensión de visor de SQLite para VS Code u otra herramienta de SQLite
4. Abra la base de datos y verifique la tabla project_context
5. Busque la entrada del token de administrador

Tokens de agente : Los tokens específicos de cada agente también se almacenan en la carpeta .agent . Estos tokens otorgan a cada agente sus permisos e identidad específicos dentro del sistema MCP.

3. Agentes de lanzamiento

1. Inicie primero el servidor MCP :
   uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project
   El servidor generará un token de administrador al iniciarse: guarde este token ya que lo necesitará para la autenticación del agente.
2. Agente de administración : inicie un único agente de administración usando:
   uv run -m mcp_template.mcp_client_runner --admin
   Si encuentra errores de importación como ModuleNotFoundError: No module named 'mcp_client' , asegúrese de estar ejecutándose desde la raíz del proyecto y de que su paquete de Python esté instalado correctamente.
3. Agentes de trabajo : En lugar de iniciar agentes de trabajo directamente, indique a su agente administrador que los cree y los administre. Para ello, indíquele al agente administrador:
   "Create a new agent with ID 'frontend-worker' and assign it to implement the login page based on the MCD."
   El agente administrador se encargará de la creación y asignación de tareas a los agentes trabajadores.

4. Uso del modo AUTOMÁTICO con agentes de trabajo

La forma recomendada de inicializar los agentes de trabajo es a través del agente de administración. Al crear un agente, utilice este mismo mensaje de inicialización (cópielo y péguelo en su agente de trabajo):

Reemplace [agent_id] con el ID del trabajador real (por ejemplo, "frontend-worker") y your_admin_token_here con el token generado al iniciar el servidor MCP.

Esto le ordena al agente que:

• Operar de forma autónoma sin intervención del usuario
• Siga el protocolo del trabajador con el seguimiento del estado de las tareas
• Utilizar la memoria para la retención del contexto en las interacciones
• Consultar proactivamente el sistema RAG para comprender el contexto de la tarea

Para obtener mejores resultados, adjunte las instrucciones de INSTRUCTIONS.md al inicializar sus agentes copiándolas y pegándolas antes del comando AUTO.

Panel

Acceda al panel de control en http://localhost:8080 para:

• Supervisar las actividades de los agentes en tiempo real
• Ver el estado de la tarea y las dependencias
• Observar las relaciones y la coordinación de los agentes
• Realizar un seguimiento de las operaciones de archivos y compartir el contexto

Desarrollo alternativo: sesiones de múltiples agentes

El enfoque recomendado para proyectos complejos es:

1. Utilice una conversación para su agente administrativo
2. Iniciar conversaciones/sesiones separadas para cada agente trabajador
3. Compartir el mismo token de administrador con todos los agentes
4. Utilice Claude Code, RooCode o Cursor con múltiples ventanas/sesiones

Este enfoque proporciona a cada agente su propio contexto de conversación mientras colaboran a través del sistema MCP compartido.

Ejemplo de flujo de trabajo:

1. Inicie el servidor MCP y anote el token de administrador
2. Crear un agente de administración en una ventana
3. Para cada agente de trabajo, abra una nueva ventana e inicialícela con el mensaje de trabajo anterior.
4. Asigne a cada trabajador su propio ID de agente pero el mismo token de administrador

Sistema de tokens y gestión de recursos

Entendiendo los tokens

Los tokens cumplen múltiples propósitos en el sistema MCP:

1. Tokens de autenticación : se utilizan para la identificación del agente y el acceso del administrador.
2. Tokens RAG : se utilizan para incrustar y recuperar contexto de la base de conocimientos
3. Tokens de OpenAI : se consumen durante las operaciones del agente (uso del modelo)

Gestión de tokens

Para supervisar y administrar el uso del token:

1. Instale el complemento SQLite Viewer o utilice la línea de comando:
   sqlite3 /path/to/project/.agent/mcp_state.db
2. Uso del token de consulta:
   SELECT * FROM token_usage;
3. Monitor en el panel de control en la pestaña "Recursos"

Optimización de recursos

Para proyectos grandes:

1. Utilice agentes especializados con capacidades enfocadas para reducir el tamaño del contexto
2. Divida las tareas en unidades más pequeñas con dependencias claras
3. Utilice el sistema RAG para una recuperación de contexto eficiente
4. Almacenar información compartida en el contexto del proyecto en lugar de repetirla en mensajes

Proyecto RAG y Base de Conocimiento

Configuración del proyecto RAG

El sistema de recuperación y generación aumentada (RAG) permite a los agentes acceder al conocimiento relevante del proyecto de manera eficiente:

1. Índice de archivos del proyecto:
   python -m mcp_template.rag_indexer --project-dir /path/to/project
2. Añadir documentación a la base de conocimientos:
   python -m mcp_template.rag_indexer --add-doc /path/to/document.md

Uso de RAG en flujos de trabajo de agentes

Los agentes pueden consultar la base de conocimientos utilizando:

Esto devuelve el contexto relevante sin cargar archivos completos, ahorrando tokens y mejorando la calidad de la respuesta.

Estrategia de asignación de tareas del agente

Para un rendimiento óptimo, siga estas pautas:

1. Granularidad de tareas : divida tareas grandes en unidades atómicas con entradas y salidas claras
2. Seguimiento de dependencias : defina explícitamente las dependencias de las tareas en la asignación
3. Coincidencia de capacidades : asigne tareas a agentes con capacidades relevantes
4. Monitoreo del progreso : utilice actualizaciones de estado explícitas para realizar un seguimiento del progreso de las tareas
5. Intercambio de contexto : proporcione el contexto necesario en el momento de la tarea para reducir las búsquedas posteriores

Ejemplo de asignación de tareas de administrador a trabajador:

Al crear un nuevo agente de trabajo:

1. Dígale a su agente administrador: "Cree un nuevo agente con ID 'frontend-worker' y asígnelo para implementar la página de inicio de sesión según el MCD".
2. Abra una nueva ventana/sesión e inicialice el agente de trabajo con el mensaje AUTO descrito anteriormente
3. Asegúrese de incluir el token de administrador para que el trabajador pueda acceder a sus tareas asignadas.

Componentes

• main.py : implementación del servidor MCP
• mcp_client.py : Biblioteca de cliente para conectar agentes a MCP
• dashboard_api.py : puntos finales de API para visualización
• rag_agent_test.py : Ejemplo de un agente compatible con RAG
• INSTRUCTIONS.md : Pautas operativas para agentes

Variables de entorno

• OPENAI_API_KEY : Su clave API de OpenAI
• MCP_SERVER_URL : URL del servidor MCP
• MCP_ADMIN_TOKEN : (opcional) Token de administrador para acceso directo
• MCP_PROJECT_DIR : Ruta al directorio del proyecto

Licencia

Licencia MIT

Comunidad

Únete a nuestra comunidad de Discord para hablar sobre Agent MCP, compartir tus proyectos, obtener ayuda y conectar con otros desarrolladores que desarrollan con herramientas de IA. Somos una comunidad en crecimiento centrada en superar los límites de lo posible con los sistemas multiagente y la colaboración con IA.