Pasarela MCP-A2A

Un servidor pasarela que une el Protocolo de Contexto de Modelo (MCP) con el protocolo Agente-a-Agente (A2A), permitiendo a los asistentes de IA compatibles con MCP (como Claude) interactuar sin problemas con agentes A2A.

Visión general

Este proyecto sirve de capa de integración entre dos protocolos de agentes de IA de vanguardia:

• Model Context Protocol (MCP): Desarrollado por Anthropic, el MCP permite a los asistentes de IA conectarse a herramientas y fuentes de datos externas. Estandariza el modo en que las aplicaciones de IA y los grandes modelos lingüísticos se conectan a recursos externos de forma segura y componible.

• Protocolo agente-agente (A2A): Desarrollado por Google, A2A permite la comunicación y la interoperabilidad entre diferentes agentes de IA a través de una interfaz JSON-RPC estandarizada.

Al tender puentes entre estos protocolos, este servidor permite a los clientes MCP (como Claude) descubrir, registrarse, comunicarse y gestionar tareas en agentes A2A a través de una interfaz unificada.

Inicio rápido

🎉 ¡El paquete ya está disponible en PyPI!

No requiere instalación

# Ejecutar con configuración por defecto (transporte stdio) uvx mcp-a2a-gateway # Ejecutar con transporte HTTP para clientes web MCP_TRANSPORT=streamable-http MCP_PORT=10000 uvx mcp-a2a-gateway # Ejecutar con directorio de datos personalizado MCP_DATA_DIR="/Usu/nombre-de-usuario/Escritorio/a2a_data" uvx mcp-a2a-gateway # Ejecutar con versión específica uvx mcp-a2a-gateway==0.1.6 # Ejecutar con múltiples variables de entorno MCP_TRANSPORT=stdio MCP_DATA_DIR="/custom/path" LOG_LEVEL=DEBUG uvx mcp-a2a-gateway

Para desarrollo (local)

# Clonar y ejecutar localmente git clone https://github.com/yw0nam/MCP-A2A-Gateway.git cd MCP-A2A-Gateway # Ejecutar con uv uv run mcp-a2a-gateway # Ejecutar con uvx desde directorio local uvx --from . mcp-a2a-gateway # Ejecutar con entorno personalizado para desarrollo MCP_TRANSPORT=streamable-http MCP_PORT=8080 uvx --from . mcp-a2a-gateway

Demo

1, Ejecutar el Agente hello world en A2A Sample

también soporta Agente desplegado en la nube

2, Utilice Claude o github copilot para registrar el agente.

3, Utilice Claude para enviar una tarea al Agente hello y obtener el resultado.

4, Utilice Claude para recuperar el resultado de la tarea.

Características

• Gestión de Agentes

  • Registro de agentes A2A en el servidor puente
  • Listar todos los agentes registrados
  • Anulación del registro de agentes cuando ya no sean necesarios

• Comunicación

  • Envío de mensajes a agentes A2A y recepción de respuestas
  • Envío asíncrono de mensajes para una respuesta inmediata del servidor
  • Transmisión de respuestas de agentes A2A en tiempo real

• Gestión de tareas

  • Seguimiento de qué agente A2A gestiona qué tarea
  • Recupere los resultados de las tareas utilizando los ID de tarea
  • Obtenga una lista de todas las tareas y sus estados
  • Cancelar tareas en ejecución

• Soporte de transporte

  • Múltiples tipos de transporte: stdio, streamable-http, SSE
  • Configurar el tipo de transporte utilizando la variable de entorno MCP_TRANSPORT

Requisitos previos

Antes de comenzar, asegúrese de tener instalado lo siguiente

• Python 3.11+
• uv (para desarrollo local)

Instalación

Ejecutar directamente sin instalación utilizando uvx:

uvx mcp-a2a-gateway

1. Clona el repositorio:

git clone https://github.com/yw0nam/MCP-A2A-Gateway.git cd MCP-A2A-Gateway

2. Ejecutar utilizando uv:

uv run mcp-a2a-gateway

3. O utilice uvx con la ruta local

uvx --from . mcp-a2a-gateway

Inicie el servidor con transporte HTTP:

# Usando uvx MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=10000 uvx mcp-a2a-gateway

Inicie el servidor con transporte SSE:

# Usando uvx MCP_TRANSPORT=sse MCP_HOST=0.0.0.0 MCP_PORT=10000 uvx mcp-a2a-gateway

Configuración

Variables de entorno

El servidor puede configurarse utilizando las siguientes variables de entorno:

Ejemplo de fichero .env:

# Configuración de transporte MCP_TRANSPORT=stdio MCP_HOST=0.0.0.0 MCP_PORT=10000 MCP_PATH=/mcp # Almacenamiento de datos MCP_DATA_DIR=/Usuarios/nombre_de_usuario/Escritorio/datos/a2a_gateway # Tiempos de espera MCP_REQUEST_TIMEOUT=30 MCP_REQUEST_IMMEDIATE_TIMEOUT=2 # Registro LOG_LEVEL=INFO

Tipos de transporte

El servidor A2A MCP admite varios tipos de transporte:

1. stdio (por defecto): Utiliza la entrada/salida estándar para la comunicación

   • Ideal para uso y pruebas desde la línea de comandos
   • No se inicia ningún servidor HTTP
   • Necesario para Claude Desktop

2. streamable-http (recomendado para clientes web): Transporte HTTP con soporte para streaming

   • Recomendado para instalaciones de producción
   • Inicia un servidor HTTP para gestionar las solicitudes MCP
   • Permite la transmisión de respuestas de gran tamaño

3. sse: transporte de eventos enviados por servidor

   • Proporciona streaming de eventos en tiempo real
   • Útil para actualizaciones en tiempo real

Para conectar github copilot

Añada lo siguiente a VS Code settings.json para sse o http:

"mcpServers": { "mcp_a2a_gateway": { "url": "http://0.0.0.0:10000/mcp" } }

"mcpServers": { "mcp_a2a_gateway": { "type": "stdio", "command": "uvx", "args": ["mcp-a2a-gateway"], "env": {"MCP_TRANSPORT": "stdio", "MCP_DATA_DIR": "/Usuarios/nombre_de_usuario/Escritorio/datos/Copilot/a2a_gateway/" } }

"mcpServers": { "mcp_a2a_gateway": { "type": "stdio", "command": "uvx", "args": ["--from", "/path/to/MCP-A2A-Gateway", "mcp-a2a-gateway"], "env": {"MCP_TRANSPORT": "stdio", "MCP_DATA_DIR": "/Usuarios/nombre_de_usuario/Escritorio/datos/Copilot/a2a_gateway/" } }

"mcpServers": { "mcp_a2a_gateway": { "type": "stdio", "command": "uv", "args": [ "--directory", "/path/to/MCP-A2A-Gateway", "run", "mcp-a2a-gateway" ], "env": { "MCP_TRANSPORT": "stdio", "MCP_DATA_DIR": "/Usuarios/nombre_de_usuario/Escritorio/datos/Copilot/a2a_gateway/" } }

Para conectar el escritorio claude

Añade esto a claude_config.json

"mcpServers": { "mcp_a2a_gateway": { "command": "uvx", "args": ["mcp-a2a-gateway"], "env": {"MCP_TRANSPORT": "stdio", "MCP_DATA_DIR": "/Usuarios/nombre_de_usuario/Escritorio/datos/Claude/a2a_gateway/" } }

Añada esto a claude_config.json

"mcpServers": { "mcp_a2a_gateway": { "command": "uvx", "args": ["--from", "/path/to/MCP-A2A-Gateway", "mcp-a2a-gateway"], "env": {"MCP_TRANSPORT": "stdio", "MCP_DATA_DIR": "/Usuarios/nombre_de_usuario/Escritorio/datos/Claude/a2a_gateway/" } }

Añada esto a claude_config.json

"mcpServers": { "mcp_a2a_gateway": { "command": "uv", "args": ["--directory", "/path/to/MCP-A2A-Gateway", "run", "mcp-a2a-gateway"], "env": {"MCP_TRANSPORT": "stdio", "MCP_DATA_DIR": "/Usuarios/nombre_de_usuario/Escritorio/datos/Claude/a2a_gateway/" } }

Herramientas MCP disponibles

El servidor expone las siguientes herramientas MCP para la integración con LLMs como Claude:

Gestión de Agentes

• register_agent: Registrar un agente A2A en el servidor puente

  { "name": "register_agent", "arguments": { "url": "http://localhost:41242" } }

• list_agents: Obtener una lista de todos los agentes registrados

  { "name": "list_agents", "arguments": {"dummy": "" } }

• unregister_agent: Elimina un agente A2A del servidor puente

  {"name": "unregister_agent", "arguments": { "url": "http://localhost:41242" } }

Procesamiento de mensajes

• send_message: Envía un mensaje a un agente y obtiene un task_id para la respuesta

  { "name": "send_message", "arguments": { "agent_url": "http://localhost:41242", "message": "¿Cuál es el tipo de cambio de USD a EUR?", "session_id": "optional-session-id" } }

Gestión de tareas

• get_task_result: Recupera el resultado de una tarea utilizando su ID

  { "name": "get_task_result", "arguments": { "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1", } }

• get_task_list: Obtiene una lista de todas las tareas y sus estados.

  { "name": "get_task_list", "arguments": {} }

Hoja de ruta y cómo contribuir

Estamos desarrollando y mejorando activamente la pasarela Agradecemos todo tipo de contribuciones. Este es nuestro plan de desarrollo actual, centrado primero en crear una base sólida como una roca.

Estabilidad del núcleo y experiencia del desarrollador (¡se necesita ayuda! 👍)

Este es nuestro objetivo actual. Nuestro objetivo es hacer que la pasarela sea lo más estable y fácil de usar posible.

• Implementación de respuestas en tiempo real: Soporte completo para el flujo de respuestas de los agentes A2A.
• Mejorar la gestión de errores: Proporcionar mensajes de error más claros y códigos de estado HTTP adecuados para todos los escenarios.
• Validación de entradas: Desinfección y validación de las URL de los agentes durante el registro para mejorar la seguridad.
• Añadir punto final de comprobación de estado: Un sencillo punto final /health para supervisar el estado del servidor.
• Validación de configuración: Comprobación de las variables de entorno necesarias durante el inicio.
• Pruebas de integración exhaustivas: Aumente la cobertura de las pruebas para garantizar la fiabilidad.
• Cancelación de tareas: Implementar la cancelación de tareas
• Implementar Streaming Update: Implementar streaming de actualización de tareas. Para que el usuario compruebe el progreso.

Comunidad y distribución

• Instalación fácil: Añadir soporte para uvx
• Soporte Docker: Proporcionar una configuración de Docker Compose para facilitar el despliegue.
• Mejor documentación: Crear un sitio dedicado a la documentación o ampliar la Wiki.

¿Quieres contribuir? Echa un vistazo a la pestaña de problemas o siéntete libre de abrir una nueva para discutir tus ideas

Licencia

Este proyecto está licenciado bajo la Licencia Apache, Versión 2.0 - ver el archivo LICENSE para más detalles.

Agradecimientos

• Anthropic por el Protocolo de Contexto del Modelo
• A Google por el protocolo agente-agente
• Colaboradores de la biblioteca FastMCP
• Contribuyentes de A2A-MCP-Server (Este proyecto está muy inspirado en este repositorio.)

Publicación y lanzamientos automatizados

Este proyecto utiliza la publicación automatizada a través de las Acciones de GitHub para realizar publicaciones sin problemas.

Proceso de publicación automatizada

Opción 1: Usando el Script de Publicación (Recomendado)

# Lanzamiento del parche (0.1.6 → 0.1.7) ./release.sh patch Lanzamiento menor (0.1.6 → 0.2.0) ./release.sh minor Lanzamiento mayor (0.1.6 → 1.0.0) ./release.sh major

El script lo hará:

1. ✅ Comprobará que estás en la rama principal con directorio de trabajo limpio
2. 📈 Automáticamente bump la versión en pyproject.toml
3. 🔨 Construye y prueba el paquete localmente
4. 📤 Confirmar el cambio de versión y crear una etiqueta git
5. 🚀 Empuja a GitHub, activando la publicación automatizada en PyPI

Opción 2: Creación manual de etiquetas

# Actualizar la versión en pyproject.toml manualmente # Luego crear y enviar una etiqueta git add pyproject.toml git commit -m "chore: bump version to 0.1.7" git tag v0.1.7 git push origin main git push origin v0.1.7

Opción 3: Versiones de GitHub

1. Ir a https://github.com/yw0nam/MCP-A2A-Gateway/releases
2. Haz clic en "Crear una nueva versión"
3. Elige o crea una etiqueta (por ejemplo, v0.1.7)
4. Rellena las notas de la versión
5. Publique la versión

Configuración de la publicación automática

Para habilitar la publicación automatizada, añade tu token de la API de PyPI a GitHub Secrets:

1. Obtén el token de la API de PyPI:

   • Ir a https://pypi.org/manage/account/token/
   • Crea un nuevo token con el alcance "Cuenta completa"
   • Copia el token (empieza por pypi-)

2. Añádelo a GitHub Secrets:

   • Ve a tu repositorio → Configuración → Secretos y variables → Acciones
   • Añade un nuevo secreto de repositorio
     • Nombre: PYPI_API_TOKEN
     • Valor: Tu token PyPI

3. Prueba el flujo de trabajo:

   • Enviar una etiqueta o crear una publicación
   • Comprueba el estado de publicación en la pestaña Acciones

Publicación manual

Para publicaciones de emergencia o pruebas locales:

# Construya y obtenga instrucciones de publicación manual ./publish.sh # O publique directamente (con credenciales configuradas) uv build uv publish