A2A MCP Server

Um servidor de ponte que conecta o Model Context Protocol (MCP) com o protocolo Agent-to-Agent (A2A).

GitHub
148

Documentação

A2A MCP Server

License smithery badge

Um servidor MCP 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 externas e fontes de dados. Ele padroniza como aplicações de IA e modelos de linguagem de grande porte 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.

Demonstração

1, Execute o Agente de Moeda no Exemplo A2A

agent

also support cloud deployed Agent

cloudAgent

2, Use o Claude para Registrar o Agente de Moeda

register

3, Use o Claude para Enviar uma tarefa ao Agente de Moeda e obter o resultado

task

Recursos

  • Gerenciamento de Agentes

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

  • Comunicação

    • Enviar mensagens para agentes A2A e receber respostas
    • 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
    • Cancelar tarefas em execução

  • Suporte a Transporte

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

Instalação

Instalando via Smithery

Para instalar o A2A Bridge Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @GongRzhe/A2A-MCP-Server --client claude

Opção 1: Instalar a partir do PyPI

pip install a2a-mcp-server

Opção 2: Instalação Local

  1. Clone o repositório:

    git clone https://github.com/GongRzhe/A2A-MCP-Server.git
cd A2A-MCP-Server

  2. Configure um ambiente virtual:

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

  3. Instale as dependências:

    pip install -r requirements.txt

Configuração

Variáveis de Ambiente

Configure como o servidor MCP é executado usando estas variáveis de ambiente:

# Transport type: stdio, streamable-http, or sse
export MCP_TRANSPORT="streamable-http"

# Host for the MCP server
export MCP_HOST="0.0.0.0"

# Port for the MCP server (when using HTTP transports)
export MCP_PORT="8000"

# Path for the MCP server endpoint (when using HTTP transports)
export MCP_PATH="/mcp"

# Path for SSE endpoint (when using SSE transport)
export MCP_SSE_PATH="/sse"

# Enable debug logging
export MCP_DEBUG="true"

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 requisições MCP
    • Permite o 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 especificar o tipo de transporte:

# Using environment variable
export MCP_TRANSPORT="streamable-http"
uvx a2a-mcp-server

# Or directly in the command
MCP_TRANSPORT=streamable-http uvx a2a-mcp-server

Executando o Servidor

Pela Linha de Comando

# Using default settings (stdio transport)
uvx a2a-mcp-server

# Using HTTP transport on specific host and port
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8080 uvx a2a-mcp-server

Configurando no Claude Desktop

O Claude Desktop permite configurar servidores MCP no arquivo claude_desktop_config.json. Este arquivo normalmente está localizado em:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Método 1: Instalação via PyPI (Recomendado)

Adicione o seguinte à seção mcpServers do seu claude_desktop_config.json:

"a2a": {
  "command": "uvx",
  "args": [
    "a2a-mcp-server"
  ]
}

Observe que para o Claude Desktop, você deve usar "MCP_TRANSPORT": "stdio" pois o Claude requer comunicação stdio com servidores MCP.

Método 2: Instalação Local

Se você clonou o repositório e deseja executar o servidor a partir da sua instalação local:

"a2a": {
  "command": "C:\\path\\to\\python.exe",
  "args": [
    "C:\\path\\to\\A2A-MCP-Server\\a2a_mcp_server.py"
  ],
  "env": {
    "MCP_TRANSPORT": "stdio",
    "PYTHONPATH": "C:\\path\\to\\A2A-MCP-Server"
  }
}

Substitua C:\\path\\to\\ pelos caminhos reais do seu sistema.

Usando o Criador de Configuração

Este repositório inclui um script config_creator.py para ajudar você a gerar a configuração:

# If using local installation
python config_creator.py

O script irá:

  • Detectar automaticamente os caminhos do Python, do script e do repositório quando possível
  • Configurar o transporte stdio, que é necessário para o Claude Desktop
  • Permitir que você adicione variáveis de ambiente adicionais, se necessário
  • Criar ou atualizar seu arquivo de configuração do Claude Desktop

Exemplo Completo

Aqui está um exemplo de um arquivo claude_desktop_config.json completo com o A2A-MCP-Server configurado:

{
  "mcpServers": {
    "a2a": {
      "command": "uvx",
      "args": [
        "a2a-mcp-server"
      ]
    }
  }
}

Usando com Clientes MCP

Claude

O Claude pode usar agentes A2A por meio das ferramentas MCP fornecidas por este servidor. Veja como configurar:

  1. Para o Claude Web: Inicie o servidor MCP com o transporte streamable-http:

    MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

  2. Para o Claude Web: Na interface web do Claude, habilite a conexão de URL MCP no seu menu Ferramentas.

    • Use a URL: http://127.0.0.1:8000/mcp

  3. Para o Claude Desktop: Adicione a configuração ao seu arquivo claude_desktop_config.json conforme descrito acima. A maneira mais fácil é usar o script config_creator.py fornecido, que detectará automaticamente os caminhos e criará a configuração adequada.

  4. No Claude, agora você pode usar as seguintes funções:

    Registrar um agente A2A:

    I need to register a new agent. Can you help me with that?
(Agent URL: http://localhost:41242)

    Enviar mensagem para um agente:

    Ask the agent at http://localhost:41242 what it can do.

    Recuperar resultados de tarefas:

    Can you get the results for task ID: 550e8400-e29b-41d4-a716-446655440000?

Cursor IDE

O Cursor IDE pode se conectar a servidores MCP para adicionar ferramentas ao seu assistente de IA:

  1. Execute seu servidor A2A MCP com o transporte streamable-http:

    MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

  2. No Cursor IDE, vá para Configurações > IA > Servidores MCP

    • Adicione um novo Servidor MCP com URL: http://127.0.0.1:8000/mcp
    • Habilite o servidor

  3. Agora você pode usar as ferramentas A2A dentro do assistente de IA do Cursor.

Navegador Windsurf

O Windsurf é um navegador com suporte MCP integrado:

  1. Execute seu servidor A2A MCP com o transporte streamable-http:

    MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

  2. No navegador Windsurf, vá para Configurações > Conexões MCP

    • Adicione uma nova conexão MCP com URL: http://127.0.0.1:8000/mcp
    • Habilite a conexão

  3. Agora você pode usar ferramentas A2A dentro do assistente de IA do Windsurf.

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": {}
}

  • 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"
  }
}

  • send_message_stream: Enviar uma mensagem e transmitir a resposta

    {
  "name": "send_message_stream",
  "arguments": {
    "agent_url": "http://localhost:41242",
    "message": "Tell me a story about AI agents.",
    "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",
    "history_length": null
  }
}

  • cancel_task: Cancelar uma tarefa em execução

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

Exemplos de Uso

Fluxo de Trabalho Básico

1. Client registers an A2A agent
   ↓
2. Client sends a message to the agent (gets task_id)
   ↓
3. Client retrieves the task result using task_id

Exemplo com o Claude como Cliente MCP

User: Register an agent at http://localhost:41242

Claude uses: register_agent(url="http://localhost:41242")
Claude: Successfully registered agent: ReimbursementAgent

User: Ask the agent what it can do

Claude uses: send_message(agent_url="http://localhost:41242", message="What can you do?")
Claude: I've sent your message. Here's the task_id: b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1

User: Get the answer to my question

Claude uses: get_task_result(task_id="b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1")
Claude: The agent replied: "I can help you process reimbursement requests. Just tell me what you need to be reimbursed for, including the date, amount, and purpose."

Arquitetura

O servidor A2A MCP consiste em vários componentes principais:

  1. Servidor FastMCP: Expõe ferramentas para clientes MCP
  2. Cliente A2A: Comunica-se com agentes A2A registrados
  3. Gerenciador de Tarefas: Lida com o encaminhamento e gerenciamento de tarefas
  4. Buscador de Cartões de Agente: Recupera informações sobre agentes A2A

Fluxo de Comunicação

MCP Client → FastMCP Server → A2A Client → A2A Agent
                   ↑                ↓
                   └──── Response ──┘

Gerenciamento de IDs de Tarefa

Ao enviar uma mensagem para um agente A2A, o servidor:

  1. Gera um task_id único
  2. Mapeia este ID para a URL do agente no dicionário task_agent_mapping
  3. Retorna o task_id para o cliente MCP
  4. Usa este mapeamento para rotear solicitações de recuperação e cancelamento de tarefas

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para problemas comuns:

  • Agente não registrado
  • ID de tarefa não encontrado
  • Erros de conexão com agentes
  • Erros de análise em respostas

Solução de Problemas

Problemas de Registro de Agentes

Se um agente não puder ser registrado:

  • Verifique se a URL do agente está correta e acessível
  • Verifique se o agente possui um cartão de agente adequado em /.well-known/agent.json

Problemas de Entrega de Mensagens

Se as mensagens não estiverem sendo entregues:

  • Certifique-se de que o agente está registrado (use list_agents)
  • Verifique se o agente está em execução e acessível

Problemas na Recuperação de Resultados de Tarefas

Se você não conseguir recuperar um resultado de tarefa:

  • Certifique-se de que está usando o task_id correto
  • Verifique se muito tempo se passou (alguns agentes podem descartar tarefas antigas)

Problemas de Transporte

Se você tiver problemas com um tipo específico de transporte:

  • Problemas com stdio: Certifique-se de que os fluxos de entrada/saída não estejam redirecionados ou modificados
  • Problemas com streamable-http: Verifique se a porta está disponível e não está bloqueada por um firewall
  • Problemas com sse: Verifique se o cliente suporta Server-Sent Events

Problemas de Configuração do Claude Desktop

Se o Claude Desktop não estiver iniciando seu A2A-MCP-Server:

  • Verifique se os caminhos no seu claude_desktop_config.json estão corretos
  • Verifique se o Python está no seu PATH se estiver usando "command": "python"
  • Para instalação local, certifique-se de que o PYTHONPATH está correto
  • Certifique-se de que MCP_TRANSPORT está definido como "stdio" na seção env
  • Tente executar o comando manualmente para ver se funciona fora do Claude
  • Use o script config_creator.py para detecção automática de caminhos e configuração

Desenvolvimento

Adicionando Novos Métodos de Ferramenta

Para adicionar novas capacidades ao servidor, adicione métodos decorados com @mcp.tool() no arquivo a2a_mcp_server.py.

Gerenciador de Tarefas Personalizado

O servidor usa uma classe A2AServerTaskManager personalizada que estende InMemoryTaskManager. Você pode personalizar seu comportamento modificando esta classe.

Estrutura do Projeto

a2a-mcp-server/
├── a2a_mcp_server.py      # Main server implementation
├── common/                # A2A protocol code (from google/A2A)
│   ├── client/            # A2A client implementation
│   ├── server/            # A2A server implementation
│   ├── types.py           # Common type definitions
│   └── utils/             # Utility functions
├── config_creator.py      # Script to help create Claude Desktop configuration
├── .gitignore             # Git ignore file
├── pyproject.toml         # Project metadata and dependencies
├── README.md              # This file
└── requirements.txt       # Project dependencies

Licença

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

O código no diretório common/ é do projeto Google A2A e também está licenciado sob a Apache License, Versão 2.0.

Agradecimentos