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 MultipleCursor para iniciar diferentes ventanas de chat en la misma base de código como se muestra 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

IMPORTANTE : Al iniciar el servidor, se creará una base de datos en la carpeta .agent de tu proyecto. Tu token de administrador se almacena en esta base de datos. Para encontrarlo:

1. Instale una extensión de visor de SQLite en su editor de código
2. Abra la base de datos en /path/to/your/project/.agent/mcp_state.db
3. Consulte la tabla project_context para el token de administrador

3. Crear un documento de contexto principal (MCD)

• Cree un archivo MCD.md detallado en su proyecto con arquitectura, rutas API, modelos de datos, etc.
• Este puede ser un solo archivo o varios archivos (para proyectos complejos)
• Consulte la carpeta MCD-EXAMPLE para obtener plantillas

4. Iniciar el agente de administración

1. Abra su asistente de codificación de IA (Claude Code, Cursor, etc.) en la carpeta de su proyecto
2. Copia el token de administrador que encontraste en el paso 2
3. Pídale a la IA que se "inicie como agente administrador con este token: [your-token]"
4. Dígale al agente administrativo que agregue su MCD al contexto del proyecto con:
   Please add the MCD.md file to the project context. Don't summarize it.

5. Crear y administrar agentes de trabajo a través del administrador

1. Pídale a su agente administrativo que cree un agente trabajador:
   Create a worker agent with ID "frontend-worker" to implement the login page.
2. Abra una nueva ventana/sesión en su asistente de IA (misma base de código)
3. Inicialice el trabajador con este mensaje exacto:
   You are [worker-id] agent, your Admin Token: "[admin-token]" Look at your tasks and ask the project RAG agent at least 5-7 questions to understand what you need to do. I want you to critically think when asking a question, then criticize yourself before asking that question. How you criticize yourself is by proposing an idea, criticizing it, and based on that criticism you pull through with that idea. AUTO --worker --memory
4. El trabajador encontrará automáticamente sus tareas asignadas y comenzará a trabajar.

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
• Panel interactivo para visualizar tareas, agentes y contexto

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

Vea el video tutorial: Cómo agregar contexto MCD a Agent MCP

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 docs/INSTRUCTIONS.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. Entendiendo los tokens MCP

El sistema MCP utiliza dos tipos de tokens para la autenticación:

Token de administrador :

1. Después de iniciar el servidor, se genera automáticamente un token de administrador
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
6. El token de administrador SÓLO debe usarse con el agente de administración

Fichas de trabajador :

1. Cuando el agente de administración crea un agente de trabajo, se genera un token de trabajo específico
2. El agente de administración proporcionará este token de trabajador cuando se le solicite crear un trabajador.
3. Cada trabajador tiene su propio token único con permisos específicos.
4. Los tokens de trabajo también se almacenan en la base de datos .agent/mcp_state.db

IMPORTANTE : NO utilice el token de administrador para los agentes de trabajo. Utilice siempre el token de trabajo específico proporcionado por el agente de administración al crear el trabajador.

3. Flujo de trabajo del agente (IMPORTANTE)

Nota : Todos los agentes se crean y administran a través del chat con su asistente de IA; NO utiliza herramientas de línea de comando para crear agentes.

Servidor MCP : este es el ÚNICO componente que se inicia con un comando:

Agente de administración : crea diciéndole a tu asistente de IA:

Agentes de trabajo : crear a través del agente de administración con:

1. Dígale al agente administrativo: "Cree un agente de trabajo con ID 'frontend-worker' para implementar la página de inicio de sesión".
2. El administrador proporcionará un token de trabajador específico para este agente.
3. Abrir una nueva ventana/sesión del asistente de IA
4. Inicialice con el token de trabajador y el indicador de trabajador de la sección 4 a continuación

El panel de control ( http://localhost:8080 ):

• Esto es solo para visualización: no se crean agentes aquí.
• Todo el trabajo real se realiza a través de las ventanas de chat de tu asistente de IA.
• El panel muestra las relaciones entre agentes y tareas.

4. Inicialización de agentes de trabajo (Copiar y pegar esto)

Después de que su agente administrativo cree un trabajador, abra una nueva ventana del asistente de IA e inicialice el trabajador con este mensaje EXACTO:

Haz estos dos reemplazos:

1. Reemplace [agent_id] con el ID del trabajador que le indicó al administrador que creara (por ejemplo, "frontend-worker")
2. Reemplace your_worker_token_here con el token de trabajador específico que el agente de administración proporcionó al crear este trabajador (NO el token de administrador)

Después de la inicialización, el trabajador hará lo siguiente:

1. Comprobar tareas asignadas a su ID
2. Pregúntele al sistema RAG sobre el contexto del proyecto
3. Empieza a trabajar en sus tareas de forma autónoma
4. Almacenar detalles de implementación en el sistema de memoria compartida

Para obtener mejores resultados, también copie el contenido de docs/INSTRUCTIONS.md y péguelo antes del comando AUTO.

Interfaz de usuario del panel y terminal

Tablero de instrumentos (visualización)

Acceda al panel de control en http://localhost:8080 para visualizar lo que sucede en su sistema multiagente:

• 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

Importante: El panel es solo para visualización; aquí no se crean ni se gestionan agentes. La creación de agentes y la asignación de tareas se realizan a través del chat del asistente de IA.

Sesiones de múltiples agentes: Guía visual

Para proyectos complejos, tendrás varias sesiones de chat abiertas a la vez:

Cómo funciona esto:

1. Una ventana/sesión para su agente administrativo
2. Ventanas/sesiones independientes para cada agente de trabajo
3. El administrador usa el token de administrador, los trabajadores usan sus tokens de trabajador específicos
4. Cada trabajador tiene un ID de agente y un token ÚNICOS

Ejemplo de configuración con 3 agentes:

Puede utilizar Claude Code, RooCode o MultipleCursor para administrar varias ventanas/sesiones que trabajen en la misma base de código.

Ejemplo completo de flujo de trabajo

A continuación se muestra un ejemplo paso a paso de cómo utilizar Agent MCP de principio a fin:

Paso 1: Crea tu proyecto

Paso 2: Instalar el agente MCP

Paso 3: Crea tu MCD

Paso 4: Iniciar el servidor MCP

Paso 5: Encuentra el token de administrador

1. Instale SQLite Viewer en su editor de código
2. Abra .agent/mcp_state.db
3. Busque el token en la tabla project_context

Paso 6: Inicializar el agente de administración

1. Abre tu asistente de IA (Claude Code, Cursor, etc.)
2. Cuéntalo:

Paso 7: Crear un agente de trabajo

1. Dígale al agente administrativo:

2. El agente administrativo le proporcionará un token de trabajador para este nuevo agente.

Paso 8: Inicializar el agente de trabajo

1. Abrir una nueva ventana del asistente de IA
2. Cuéntalo:

¡El trabajador ahora comenzará a trabajar automáticamente en sus tareas asignadas!

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 OpenAI : consumidos 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 (Sistema de Memoria Central)

Mira el tutorial de arriba: Mira exactamente cómo agregar tu MCD al sistema de memoria central

Cómo funciona el sistema de memoria

1. El servidor MCP mantiene una base de datos central para todo el contexto del proyecto.
2. Cuando inicia el servidor, se crea una carpeta .agent en el directorio de su proyecto
3. Su agente administrativo agrega su MCD a esta base de datos cuando lo inicializa
4. Los agentes de trabajo consultan automáticamente esta base de datos para comprender sus tareas.
5. Todos los detalles de implementación se almacenan en esta base de datos para que otros agentes puedan acceder a ellos.

Configuración del proyecto RAG

El sistema de Recuperación-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 agent_mcp.features.rag.indexing -- --project-dir /path/to/project
2. Añadir documentación a la base de conocimientos:
   python -m agent_mcp.features.rag.indexing -- --add-doc /path/to/document.md

Uso de RAG en flujos de trabajo de agentes

Los agentes pueden consultar la base de conocimientos utilizando:

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.