A2A MCP Server

MCP-A2A-Gateway

Um servidor gateway que faz a ponte entre o Model Context Protocol (MCP) e o protocolo Agent-to-Agent (A2A), permitindo que assistentes de IA compatíveis com MCP (como o Claude) interajam perfeitamente com agentes A2A.

Visão Geral

Este projeto serve como uma camada de integração entre dois protocolos de agentes de IA de ponta:

• Model Context Protocol (MCP): Desenvolvido pela Anthropic, o MCP permite que assistentes de IA se conectem a ferramentas e fontes de dados externas. Ele padroniza como aplicações de IA e modelos de linguagem de grande escala se conectam a recursos externos de forma segura e componível.

• Agent-to-Agent Protocol (A2A): Desenvolvido pelo Google, o A2A permite comunicação e interoperabilidade entre diferentes agentes de IA por meio de uma interface JSON-RPC padronizada.

Ao fazer a ponte entre esses protocolos, este servidor permite que clientes MCP (como o Claude) descubram, registrem, comuniquem-se e gerenciem tarefas em agentes A2A por meio de uma interface unificada.

Início Rápido

🎉 O pacote agora está disponível no PyPI!

Sem Necessidade de Instalação

# 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 Desenvolvimento (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

Demonstração

1, Execute o agente hello world no A2A Sample

also support cloud deployed Agent

2, Use o Claude ou o github copilot para registrar o agente.

3, Use o Claude para enviar uma tarefa ao agente hello e obter o resultado.

4, Use o Claude para recuperar o resultado da tarefa.

Recursos

• Gerenciamento de Agentes

  • Registrar agentes A2A no servidor de ponte
  • Listar todos os agentes registrados
  • Cancelar registro de agentes quando não forem mais necessários

• Comunicação

  • Enviar mensagens para agentes A2A e receber respostas
  • Envio assíncrono de mensagens para resposta imediata do servidor.
  • Transmitir respostas de agentes A2A em tempo real

• Gerenciamento de Tarefas

  • Rastrear qual agente A2A lida com qual tarefa
  • Recuperar resultados de tarefas usando IDs de tarefa
  • Obter uma lista de todas as tarefas e seus status.
  • Cancelar tarefas em execução

• Suporte a Transporte

  • Múltiplos tipos de transporte: stdio, streamable-http, SSE
  • Configurar o tipo de transporte usando a variável de ambiente MCP_TRANSPORT

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte instalado:

• Python 3.11+
• uv (para desenvolvimento local)

Instalação

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

Configuração

Variáveis de Ambiente

O servidor pode ser configurado usando as seguintes variáveis de ambiente:

Exemplo de arquivo .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

O A2A MCP Server suporta múltiplos tipos de transporte:

1. stdio (padrão): Usa entrada/saída padrão para comunicação

   • Ideal para uso em linha de comando e testes
   • Nenhum servidor HTTP é iniciado
   • Necessário para o Claude Desktop

2. streamable-http (recomendado para clientes web): Transporte HTTP com suporte a streaming

   • Recomendado para implantações em produção
   • Inicia um servidor HTTP para lidar com solicitações MCP
   • Permite streaming de respostas grandes

3. sse: Transporte Server-Sent Events

   • Fornece streaming de eventos em tempo real
   • Útil para atualizações em tempo real

Para conectar o 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 o 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/"
    }
  }
}

Ferramentas MCP Disponíveis

O servidor expõe as seguintes ferramentas MCP para integração com LLMs como o Claude:

Gerenciamento de Agentes

• register_agent: Registrar um agente A2A no servidor de ponte

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

• list_agents: Obter uma lista de todos os agentes registrados

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

• unregister_agent: Remover um agente A2A do servidor de ponte

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

Processamento de Mensagens

• send_message: Enviar uma mensagem para um agente e obter um task_id para a resposta

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

Gerenciamento de Tarefas

• get_task_result: Recuperar o resultado de uma tarefa usando seu ID

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

• get_task_list: Obter uma lista de todas as tarefas e seus status.

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

Roteiro e Como Contribuir

Estamos desenvolvendo e melhorando ativamente o gateway! Recebemos contribuições de todos os tipos. Aqui está nosso roteiro de desenvolvimento atual, com foco em criar primeiro uma base sólida.

Estabilidade Central e Experiência do Desenvolvedor (Ajuda Necessária! 👍)

Este é nosso foco atual. Nosso objetivo é tornar o gateway o mais estável e fácil de usar possível.

• Implementar Respostas em Streaming: Suporte completo para respostas em streaming de agentes A2A.
• Melhorar o Tratamento de Erros: Fornecer mensagens de erro mais claras e códigos de status HTTP adequados para todos os cenários.
• Validação de Entrada: Sanitizar e validar URLs de agentes durante o registro para melhor segurança.
• Adicionar Endpoint de Verificação de Saúde: Um endpoint simples /health para monitorar o status do servidor.
• Validação de Configuração: Verificar variáveis de ambiente necessárias na inicialização.
• Testes de Integração Abrangentes: Aumentar a cobertura de testes para garantir confiabilidade.
• Cancelar Tarefa: Implementar cancelamento de tarefas
• Implementar Atualização em Streaming: Implementar atualização de tarefas em streaming. Para que o usuário verifique o progresso.

Comunidade e Distribuição

• Instalação Fácil: Adicionar suporte para uvx
• Suporte a Docker: Fornecer uma configuração Docker Compose para implantação fácil.
• Melhor Documentação: Criar um site de documentação dedicado ou expandir a Wiki.

Quer contribuir? Verifique a aba de issues ou sinta-se à vontade para abrir uma nova para discutir suas ideias!

Licença

Este projeto está licenciado sob a Apache License, Versão 2.0 - consulte o arquivo LICENSE para detalhes.

Agradecimentos

• Anthropic pelo Model Context Protocol
• Google pelo Agent-to-Agent Protocol
• Contribuidores da biblioteca FastMCP
• Contribuidores do A2A-MCP-Server (Este projeto foi altamente inspirado neste repositório.)

Publicação Automatizada e Lançamentos

Este projeto usa publicação automatizada por meio do GitHub Actions para lançamentos contínuos.

Processo de Lançamento Automatizado

Opção 1: Usando o Script de Lançamento (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

O script irá:

1. ✅ Verificar se você está na branch main com diretório de trabalho limpo
2. 📈 Aumentar automaticamente a versão em pyproject.toml
3. 🔨 Compilar e testar o pacote localmente
4. 📤 Confirmar a mudança de versão e criar uma tag git
5. 🚀 Enviar para o GitHub, acionando a publicação automatizada no PyPI

Opção 2: Criação Manual de Tag

# 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

Opção 3: Lançamentos do GitHub

1. Vá para https://github.com/yw0nam/MCP-A2A-Gateway/releases
2. Clique em "Create a new release"
3. Escolha ou crie uma tag (ex.: v0.1.7)
4. Preencha as notas de lançamento
5. Publique o lançamento

Configurando a Publicação Automatizada

Para habilitar a publicação automatizada, adicione seu token de API do PyPI aos Segredos do GitHub:

1. Obter Token de API do PyPI:

   • Vá para https://pypi.org/manage/account/token/
   • Crie um novo token com escopo "Entire account"
   • Copie o token (começa com pypi-)

2. Adicionar aos Segredos do GitHub:

   • Vá para seu repositório → Settings → Secrets and variables → Actions
   • Adicione um novo segredo de repositório:
     • Nome: PYPI_API_TOKEN
     • Valor: Seu token do PyPI

3. Testar o Fluxo de Trabalho:

   • Envie uma tag ou crie um lançamento
   • Verifique a aba Actions para o status da publicação

Publicação Manual

Para lançamentos de emergência ou testes locais:

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

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