Mgabr90/a2a-bridge-mcp

A2A-MCP Bridge Project

This project enables Agent-to-Agent (A2A) communication between Claude Code and Gemini CLI through a standardized bridge server that translates between the Model Context Protocol (MCP) and A2A protocols.

Architecture

Claude Code (MCP Client) <--> A2A-MCP Bridge Server <--> Gemini CLI (A2A Agent)

Features Preserved from Reference Implementation

• ✅ FastMCP Integration: Proper MCP protocol support with FastMCP
• ✅ Persistent Storage: Agents and tasks are saved to disk with periodic backups
• ✅ Streaming Support: Real-time communication capabilities
• ✅ Comprehensive Error Handling: Robust error handling and logging
• ✅ Task Management: Full task lifecycle management with status tracking
• ✅ Agent Discovery: Automatic discovery via .well-known/agent.json
• ✅ JSON-RPC 2.0: Standard A2A protocol communication
• ✅ Docker Containerization: Isolated and portable deployment

Quick Start

1. Install the Package

# One-command installation
npx @a2a-bridge/mcp-server install

# Or install globally
npm install -g @a2a-bridge/mcp-server
a2a-mcp-install install

2. Verify Installation

# Test the MCP server
a2a-bridge-mcp test

# Check status
a2a-bridge-mcp status

Usage

Once configured, Claude Code will have access to these MCP tools:

register_agent

Register a new A2A agent with the bridge.

// Available in Claude Code after installation
register_agent("http://new-agent:port")

list_agents

List all registered A2A agents.

// View all registered agents
list_agents()

send_message

Send a message to an A2A agent.

send_message(
    "http://localhost:9222",  // agent_url
    "Help me write a JavaScript function",  // message
    "optional-session-id"  // session_id
)

get_task_result

Retrieve results of a previously sent task.

get_task_result("uuid-task-id")

Environment Variables

MCP Server Configuration

• GEMINI_CLI_URL: URL of local Gemini CLI (default: http://localhost:9222)
• A2A_MCP_DATA_DIR: Directory for persistent storage (default: ~/.a2a-bridge)
• DEBUG: Enable debug logging (set to 'a2a-bridge:*')
• NODE_ENV: Environment mode (development/production)

Gemini CLI Authentication

• GOOGLE_API_KEY or GEMINI_API_KEY: Google Gemini API key
• OAuth: Use gemini auth for browser-based authentication

Components

@a2a-bridge/mcp-server

• Purpose: MCP server that bridges Claude Code with Gemini CLI
• Features: Automatic installation, cross-platform support, persistent storage
• Integration: Works directly with Claude Desktop via MCP protocol

Gemini CLI Integration

• Purpose: Uses local Gemini CLI installation for AI communication
• Port: 9222 (default local Gemini CLI port)
• Authentication: Supports both API keys and OAuth

Data Persistence

The MCP server persists:

• Registered agents: ~/.a2a-bridge/registered_agents.json
• Task mappings: ~/.a2a-bridge/task_agent_mapping.json

Data is automatically saved:

• On exit (atexit handler)
• Every 5 minutes (periodic save)
• After each agent registration
• After each task submission

Testing

Test the npm package functionality:

# Test installation and configuration
a2a-bridge-mcp test

# Run package tests
cd packages/npm
npm test

# Test CLI commands
a2a-bridge-mcp status
a2a-mcp-install --help

Tests include:

• Package installation
• Claude Desktop configuration
• Gemini CLI connectivity
• MCP server functionality

Troubleshooting

Check Installation Status

a2a-bridge-mcp status

View Debug Logs

# Enable debug mode
export DEBUG=a2a-bridge:*
export NODE_ENV=development
a2a-bridge-mcp start

Test Components

# Test Gemini CLI connectivity
gemini --version
gemini auth status

# Test MCP server
a2a-bridge-mcp test

# Test installation process
a2a-mcp-install install

Reset Configuration

# Remove configuration data
rm -rf ~/.a2a-bridge

# Reconfigure
a2a-mcp-install install

Development

Local Development

cd packages/npm
npm install
npm run build
npm link  # For local testing

Add New A2A Agents

Use the MCP tools in Claude Code:

// Register a new agent
register_agent("http://your-agent:port")

// List all agents
list_agents()

Extend MCP Tools

Add new tools in packages/npm/src/index.js:

// Add new MCP tool handler
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  
  if (name === 'your_new_tool') {
    // Implementation here
    return { result: 'success' };
  }
});

Security Notes

• This is a development setup - add authentication for production
• Gemini API key should be properly secured
• Network isolation is provided by Docker networks
• Consider TLS termination for production deployments