A2A MCP Server

MCP-A2A-Gateway

Un servidor puente que conecta el Protocolo de Contexto de Modelos (MCP) con el protocolo Agente-a-Agente (A2A), permitiendo que asistentes de IA compatibles con MCP (como Claude) interactúen sin problemas con agentes A2A.

Descripción General

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

• Protocolo de Contexto de Modelos (MCP): Desarrollado por Anthropic, MCP permite a los asistentes de IA conectarse a herramientas y fuentes de datos externas. Estandariza cómo las aplicaciones de IA y los modelos de lenguaje grandes se conectan a recursos externos de manera segura y componible.

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

Al conectar estos protocolos, este servidor permite que los clientes MCP (como Claude) descubran, registren, se comuniquen y gestionen tareas en agentes A2A a través de una interfaz unificada.

Inicio Rápido

🎉 ¡El paquete ya está disponible en PyPI!

Sin Instalación Requerida

# Run with default settings (stdio transport)
uvx mcp-a2a-gateway

# Run with HTTP transport for web clients
MCP_TRANSPORT=streamable-http MCP_PORT=10000 uvx mcp-a2a-gateway

# Run with custom data directory
MCP_DATA_DIR="/Users/your-username/Desktop/a2a_data" uvx mcp-a2a-gateway

# Run with specific version
uvx mcp-a2a-gateway==0.1.6

# Run with multiple environment variables
MCP_TRANSPORT=stdio MCP_DATA_DIR="/custom/path" LOG_LEVEL=DEBUG uvx mcp-a2a-gateway

Para Desarrollo (Local)

# Clone and run locally
git clone https://github.com/yw0nam/MCP-A2A-Gateway.git
cd MCP-A2A-Gateway

# Run with uv
uv run mcp-a2a-gateway

# Run with uvx from local directory
uvx --from . mcp-a2a-gateway

# Run with custom environment for development
MCP_TRANSPORT=streamable-http MCP_PORT=8080 uvx --from . mcp-a2a-gateway

Demo

1, Ejecuta el agente hello world en el ejemplo A2A

also support cloud deployed Agent

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

3, Usa Claude para enviar una tarea al agente hello y obtener el resultado.

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

Características

• Gestión de Agentes

  • Registrar agentes A2A con el servidor puente
  • Listar todos los agentes registrados
  • Anular el registro de agentes cuando ya no sean necesarios

• Comunicación

  • Enviar mensajes a agentes A2A y recibir respuestas
  • Envío de mensajes asíncronos para respuesta inmediata del servidor.
  • Transmitir respuestas de agentes A2A en tiempo real

• Gestión de Tareas

  • Rastrear qué agente A2A maneja qué tarea
  • Recuperar resultados de tareas usando IDs de tarea
  • Obtener 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 usando la variable de entorno MCP_TRANSPORT

Requisitos Previos

Antes de comenzar, asegúrate de tener instalado lo siguiente:

• Python 3.11+
• uv (para desarrollo local)

Instalación

uvx mcp-a2a-gateway

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

uv run mcp-a2a-gateway

uvx --from . mcp-a2a-gateway

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

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

Configuración

Variables de Entorno

El servidor se puede configurar usando las siguientes variables de entorno:

Ejemplo de archivo .env:

# Transport configuration
MCP_TRANSPORT=stdio
MCP_HOST=0.0.0.0
MCP_PORT=10000
MCP_PATH=/mcp

# Data storage
MCP_DATA_DIR=/Users/your-username/Desktop/data/a2a_gateway

# Timeouts
MCP_REQUEST_TIMEOUT=30
MCP_REQUEST_IMMEDIATE_TIMEOUT=2

# Logging
LOG_LEVEL=INFO

Tipos de Transporte

El A2A MCP Server admite múltiples tipos de transporte:

1. stdio (predeterminado): Usa entrada/salida estándar para la comunicación

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

2. streamable-http (recomendado para clientes web): Transporte HTTP con soporte de transmisión

   • Recomendado para implementaciones de producción
   • Inicia un servidor HTTP para manejar solicitudes MCP
   • Habilita la transmisión de respuestas grandes

3. sse: Transporte de Eventos Enviados por el Servidor

   • Proporciona transmisión de eventos en tiempo real
   • Útil para actualizaciones en tiempo real

Para conectar github copilot

"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": "/Users/your-username/Desktop/data/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": "/Users/your-username/Desktop/data/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": "/Users/your-username/Desktop/data/Copilot/a2a_gateway/"
    }
  }
}

Para conectar claude desktop

"mcpServers": {
  "mcp_a2a_gateway": {
    "command": "uvx",
    "args": ["mcp-a2a-gateway"],
    "env": {
      "MCP_TRANSPORT": "stdio",
      "MCP_DATA_DIR": "/Users/your-username/Desktop/data/Claude/a2a_gateway/"
    }
  }
}

"mcpServers": {
  "mcp_a2a_gateway": {
    "command": "uvx",
    "args": ["--from", "/path/to/MCP-A2A-Gateway", "mcp-a2a-gateway"],
    "env": {
      "MCP_TRANSPORT": "stdio",
      "MCP_DATA_DIR": "/Users/your-username/Desktop/data/Claude/a2a_gateway/"
    }
  }
}

"mcpServers": {
  "mcp_a2a_gateway": {
    "command": "uv",
    "args": ["--directory", "/path/to/MCP-A2A-Gateway", "run", "mcp-a2a-gateway"],
    "env": {
      "MCP_TRANSPORT": "stdio",
      "MCP_DATA_DIR": "/Users/your-username/Desktop/data/Claude/a2a_gateway/"
    }
  }
}

Herramientas MCP Disponibles

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

Gestión de Agentes

• register_agent: Registrar un agente A2A con 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: Eliminar un agente A2A del servidor puente

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

Procesamiento de Mensajes

• send_message: Enviar un mensaje a un agente y obtener un task_id para la respuesta

  {
    "name": "send_message",
    "arguments": {
      "agent_url": "http://localhost:41242",
      "message": "What's the exchange rate from USD to EUR?",
      "session_id": "optional-session-id"
    }
  }
  

Gestión de Tareas

• get_task_result: Recuperar el resultado de una tarea usando su ID

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

• get_task_list: Obtener 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 el gateway! Damos la bienvenida a contribuciones de todo tipo. Aquí está nuestra hoja de ruta de desarrollo actual, centrada en crear primero una base sólida.

Estabilidad Central y Experiencia del Desarrollador (¡Se Busca Ayuda! 👍)

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

• Implementar Respuestas de Transmisión: Soporte completo para respuestas de transmisión de agentes A2A.
• Mejorar el Manejo de Errores: Proporcionar mensajes de error más claros y códigos de estado HTTP adecuados para todos los escenarios.
• Validación de Entrada: Sanear y validar las URLs de los agentes durante el registro para una mejor seguridad.
• Agregar Endpoint de Verificación de Salud: Un endpoint simple /health para monitorear el estado del servidor.
• Validación de Configuración: Verificar las variables de entorno necesarias al inicio.
• Pruebas de Integración Integrales: Aumentar la cobertura de pruebas para garantizar la confiabilidad.
• Cancelar Tarea: Implementar la cancelación de tareas
• Implementar Actualización de Transmisión: Implementar la actualización de tareas en transmisión. Para que el usuario pueda verificar el progreso.

Comunidad y Distribución

• Instalación Fácil: Agregar soporte para uvx
• Soporte Docker: Proporcionar una configuración de Docker Compose para una implementación fácil.
• Mejor Documentación: Crear un sitio de documentación dedicado o expandir la Wiki.

¿Quieres contribuir? ¡Revisa la pestaña de issues 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 - consulta el archivo LICENSE para más detalles.

Agradecimientos

• Anthropic por el Protocolo de Contexto de Modelos
• Google por el Protocolo Agente-a-Agente
• Contribuyentes de la biblioteca FastMCP
• Contribuyentes de A2A-MCP-Server (Este proyecto está altamente inspirado en este repositorio.)

Publicación y Lanzamientos Automatizados

Este proyecto utiliza publicación automatizada a través de GitHub Actions para lanzamientos sin problemas.

Proceso de Lanzamiento Automatizado

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

# Patch release (0.1.6 → 0.1.7)
./release.sh patch

# Minor release (0.1.6 → 0.2.0)  
./release.sh minor

# Major release (0.1.6 → 1.0.0)
./release.sh major

El script:

1. ✅ Verificará que estés en la rama main con el directorio de trabajo limpio
2. 📈 Incrementará automáticamente la versión en pyproject.toml
3. 🔨 Compilará y probará el paquete localmente
4. 📤 Confirmará el cambio de versión y creará una etiqueta git
5. 🚀 Hará push a GitHub, activando la publicación automatizada en PyPI

Opción 2: Creación Manual de Etiquetas

# Update version in pyproject.toml manually
# Then create and push a tag
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: Lanzamientos de GitHub

1. Ve a https://github.com/yw0nam/MCP-A2A-Gateway/releases
2. Haz clic en "Create a new release"
3. Elige o crea una etiqueta (por ejemplo, v0.1.7)
4. Completa las notas del lanzamiento
5. Publica el lanzamiento

Configuración de la Publicación Automatizada

Para habilitar la publicación automatizada, agrega tu token de API de PyPI a los Secretos de GitHub:

1. Obtén el Token de API de PyPI:

   • Ve a https://pypi.org/manage/account/token/
   • Crea un nuevo token con alcance de "Entire account"
   • Copia el token (comienza con pypi-)

2. Agrégalo a los Secretos de GitHub:

   • Ve a tu repositorio → Settings → Secrets and variables → Actions
   • Agrega un nuevo secreto de repositorio:
     • Nombre: PYPI_API_TOKEN
     • Valor: Tu token de PyPI

3. Prueba el Flujo de Trabajo:

   • Haz push de una etiqueta o crea un lanzamiento
   • Revisa la pestaña de Actions para ver el estado de la publicación

Publicación Manual

Para lanzamientos de emergencia o pruebas locales:

# Build and get manual publish instructions
./publish.sh

# Or publish directly (with credentials configured)
uv build
uv publish