a2a-bridge-mcp-server/README.md

Agent-to-Agent Bridge MCP Server with intelligent model fallback, cross-platform support, and automatic installation for Claude Desktop and Claude Code

# a2a-bridge-mcp-server

[![npm version](https://badge.fury.io/js/a2a-bridge-mcp-server.svg)](https://badge.fury.io/js/a2a-bridge-mcp-server)
[![Node.js Version](https://img.shields.io/node/v/@a2a-bridge/mcp-server.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Agent-to-Agent Bridge MCP Server for seamless Claude Code and Gemini CLI integration with automatic installation and configuration.

## 🚀 Quick Start

### One-Command Installation

```bash
npx a2a-bridge-mcp-server install
```

That's it! The installer will:
- ✅ Detect your operating system
- ✅ Check/install Gemini CLI
- ✅ Configure Claude Desktop automatically
- ✅ Test the installation
- ✅ Provide setup guidance

### Alternative Installation Methods

```bash
# Global installation
npm install -g a2a-bridge-mcp-server
a2a-mcp-install install

# Manual configuration
a2a-bridge-mcp setup
a2a-bridge-mcp test
```

## 🌟 Features

- 🌉 **Seamless Integration**: Bridge Claude Code with Gemini CLI via standardized protocols
- 🔄 **Automatic Setup**: One-command installation with OS detection and configuration
- 🔐 **Flexible Authentication**: Support for both API keys and Google OAuth
- 🤖 **AI-to-AI Communication**: Real-time message routing via A2A protocol
- 📡 **Agent Discovery**: Automatic agent registration and capability detection
- 💾 **Persistent Storage**: Agent registry and task history management
- ⚡ **Real-time Processing**: Instant message routing and response handling
- 🛠️ **Complete MCP Tools**: Full suite of agent management and communication tools
- 🔧 **Smart Configuration**: Automatic Claude Desktop configuration across platforms

## 🛠️ Available MCP Tools

Once installed, these tools will be available in Claude Code:

### Core A2A Bridge Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `register_agent` | Register A2A-compatible agents | `url`, `name?` |
| `list_agents` | List all registered agents | - |
| `send_message` | Send messages to agents | `agent_url`, `message`, `session_id?` |
| `get_task_result` | Retrieve task results | `task_id` |

### Direct Gemini Integration

| Tool | Description | Parameters |
|------|-------------|------------|
| `gemini_chat` | Chat directly with Gemini AI | `prompt`, `model?` |

## 📋 System Requirements

- **Node.js**: 18.0.0 or higher
- **Operating System**: macOS, Linux, or Windows (with WSL)
- **Claude Desktop**: Latest version installed
- **Gemini CLI**: Will be installed automatically or prompt for installation

## 🔧 CLI Commands

### Installation & Setup
```bash
a2a-mcp-install install    # Interactive installation
a2a-mcp-install test       # Test installation
a2a-mcp-install uninstall  # Remove installation
```

### Server Management
```bash
a2a-bridge-mcp start       # Start MCP server
a2a-bridge-mcp status      # Check status
a2a-bridge-mcp setup       # Configure manually
a2a-bridge-mcp test        # Run diagnostics
```

## 🖥️ Platform Support

### macOS
- ✅ Claude Desktop auto-configuration
- ✅ Automatic Gemini CLI installation
- ✅ OAuth and API key authentication
- ✅ Full MCP integration

### Linux
- ✅ Claude Desktop auto-configuration
- ✅ Automatic Gemini CLI installation
- ✅ OAuth and API key authentication
- ✅ Full MCP integration

### Windows
- ⚠️ Requires WSL (Windows Subsystem for Linux)
- ✅ Claude Desktop configuration (in Windows)
- ✅ Gemini CLI installation (in WSL)
- ✅ Cross-platform bridge functionality

## 🔐 Authentication Options

### Option 1: Google API Key (Recommended for Development)
1. Get your API key: https://aistudio.google.com/app/apikey
2. The installer will prompt for it, or set `GOOGLE_API_KEY` environment variable

### Option 2: OAuth (Recommended for Personal Use)
1. Run: `gemini auth`
2. Complete Google authentication in browser
3. The installer will detect and verify authentication

## 📁 Configuration Files

### Claude Desktop Config
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

### A2A Bridge Data
- **Storage**: `~/.a2a-bridge/`
- **Agents**: `registered_agents.json`
- **Tasks**: `task_agent_mapping.json`

## 🎯 Usage Examples

### In Claude Code

1. **List available agents**:
   ```
   Show me all registered A2A agents
   ```

2. **Chat with Gemini**:
   ```
   Use Gemini to explain the difference between async and await in JavaScript
   ```

3. **Send message to agent**:
   ```
   Send a message to the Gemini agent asking about Python best practices
   ```

4. **Register new agent**:
   ```
   Register the agent at http://my-ai-service:8080 with name "My Custom AI"
   ```

### Command Line Testing

```bash
# Check everything is working
a2a-bridge-mcp test

# Start in interactive mode for debugging
a2a-bridge-mcp start --interactive

# Check detailed status
a2a-bridge-mcp status
```

## 🔍 Troubleshooting

### Common Issues

**"Gemini CLI not found"**
```bash
npm install -g @google/gemini-cli
gemini --version
```

**"Authentication failed"**
```bash
# Option 1: OAuth
gemini auth

# Option 2: API Key
export GOOGLE_API_KEY="your-api-key-here"
```

**"MCP server not loading in Claude"**
1. Restart Claude Desktop completely
2. Check configuration: `a2a-bridge-mcp status`
3. View Claude Desktop Developer tab for errors

**"Installation fails"**
```bash
# Run with debugging
NODE_ENV=development a2a-mcp-install install

# Check permissions
sudo chown -R $USER ~/.a2a-bridge
```

### Debug Mode

Enable detailed logging:
```bash
export DEBUG=a2a-bridge:*
export NODE_ENV=development
a2a-bridge-mcp start
```

### Getting Help

```bash
a2a-bridge-mcp help
a2a-mcp-install --help
```

## 🏗️ Development

### Local Development Setup

```bash
# Clone the repository
git clone https://github.com/a2a-bridge-project/mcp-server
cd mcp-server/npm-package

# Install dependencies
npm install

# Build the package
npm run build

# Test locally
npm link
a2a-mcp-install install
```

### Testing

```bash
npm test                    # Run test suite
npm run test:integration   # Integration tests
npm run test:cli          # CLI tests
```

### Building

```bash
npm run build     # Build for distribution
npm run dev       # Development mode
npm run prepare   # Pre-publish build
```

## 📦 Publishing

```bash
# Build and test
npm run build
npm test

# Publish to npm
npm publish --access public
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md).

### Development Workflow
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make changes and add tests
4. Run tests: `npm test`
5. Commit with conventional commits: `feat: add new feature`
6. Push and create a Pull Request

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🔗 Related Projects

- **Desktop Extension**: One-click installation via DXT format
- **Docker Version**: Containerized deployment option
- **Python Bridge**: Original Python implementation
- **Claude Code**: AI-powered development environment

## 📚 Documentation

- [Installation Guide](docs/installation.md)
- [Configuration Reference](docs/configuration.md)
- [API Documentation](docs/api.md)
- [Troubleshooting Guide](docs/troubleshooting.md)
- [Development Guide](docs/development.md)

## 🌟 Support

- 🐛 **Issues**: [GitHub Issues](https://github.com/a2a-bridge-project/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/a2a-bridge-project/discussions)
- 📧 **Email**: contact@a2a-bridge-project.com
- 🌐 **Website**: https://a2a-bridge-project.com

---

**Made with ❤️ for the AI development community**

*Enable seamless AI-to-AI collaboration in your development workflow!* 🚀