https://github.com/webdevtodayjason/a2amcp
A2AMCP is a Agent2Agent MCP communication Server taking the concept from Google's Agent2Agent Protocol (A2A)
https://github.com/webdevtodayjason/a2amcp
Last synced: 3 months ago
JSON representation
A2AMCP is a Agent2Agent MCP communication Server taking the concept from Google's Agent2Agent Protocol (A2A)
- Host: GitHub
- URL: https://github.com/webdevtodayjason/a2amcp
- Owner: webdevtodayjason
- License: mit
- Created: 2025-06-07T09:27:21.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-06-09T18:28:44.000Z (4 months ago)
- Last Synced: 2025-06-27T10:50:35.363Z (3 months ago)
- Language: Python
- Size: 142 KB
- Stars: 10
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# A2AMCP - Agent-to-Agent Model Context Protocol
[](https://opensource.org/licenses/MIT)
[](https://www.docker.com/)
[](https://redis.io/)
[](https://github.com/webdevtodayjason/A2AMCP)
## Enabling Seamless Multi-Agent Collaboration for AI-Powered Development
A2AMCP brings Google's Agent-to-Agent (A2A) communication concepts to the Model Context Protocol (MCP) ecosystem, enabling AI agents to communicate, coordinate, and collaborate in real-time while working on parallel development tasks.
Originally created for [SplitMind](https://github.com/webdevtodayjason/splitmind), A2AMCP solves the critical problem of isolated AI agents working on the same codebase without awareness of each other's changes.
**✅ Server Status: WORKING! All 17 tools implemented and tested. Uses modern MCP SDK 1.9.3.**
## 🚀 Quick Start
### Using Docker (Recommended)
```bash
# Clone the repository
git clone https://github.com/webdevtodayjason/A2AMCP
cd A2AMCP
# Start the server
docker-compose up -d
# Verify it's running
docker ps | grep splitmind
# Test the connection
python verify_mcp.py
```
### Configure Your Agents
#### Claude Code (CLI)
```bash
# Add the MCP server using Claude Code CLI
claude mcp add splitmind-a2amcp \
-e REDIS_URL=redis://localhost:6379 \
-- docker exec -i splitmind-mcp-server python /app/mcp-server-redis.py
```
#### Claude Desktop
Add to your configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"splitmind-a2amcp": {
"command": "docker",
"args": ["exec", "-i", "splitmind-mcp-server", "python", "/app/mcp-server-redis.py"],
"env": {
"REDIS_URL": "redis://redis:6379"
}
}
}
}
```
## 🎯 What Problem Does A2AMCP Solve?
When multiple AI agents work on the same codebase:
- **Without A2AMCP**: Agents create conflicting code, duplicate efforts, and cause merge conflicts
- **With A2AMCP**: Agents coordinate, share interfaces, prevent conflicts, and work as a team
### Generic Use Cases Beyond SplitMind
A2AMCP can coordinate any multi-agent scenario:
- **Microservices**: Different agents building separate services
- **Full-Stack Apps**: Frontend and backend agents collaborating
- **Documentation**: Multiple agents creating interconnected docs
- **Testing**: Test writers coordinating with feature developers
- **Refactoring**: Agents working on different modules simultaneously
## 🏗️ Architecture
```
┌─────────────────┐
│ A2AMCP Server │ ← Persistent Redis-backed MCP server
│ (Port 5050) │ handling all agent communication
└────────┬────────┘
│ STDIO Protocol (MCP)
┌────┴────┬─────────┬─────────┐
▼ ▼ ▼ ▼
┌────────┐┌────────┐┌────────┐┌────────┐
│Agent 1 ││Agent 2 ││Agent 3 ││Agent N │
│Auth ││Profile ││API ││Frontend│
└────────┘└────────┘└────────┘└────────┘
```
## 🔧 Core Features
### 1. **Real-time Agent Communication**
- Direct queries between agents
- Broadcast messaging
- Async message queues
### 2. **File Conflict Prevention**
- Automatic file locking
- Conflict detection
- Negotiation strategies
### 3. **Shared Context Management**
- Interface/type registry
- API contract sharing
- Dependency tracking
### 4. **Task Transparency**
- Todo list management
- Progress visibility
- Completion tracking
- Task completion signaling
### 5. **Multi-Project Support**
- Isolated project namespaces
- Redis-backed persistence
- Automatic cleanup
### 6. **Modern MCP Integration**
- Uses MCP SDK 1.9.3 with proper decorators
- `@server.list_tools()` and `@server.call_tool()` patterns
- STDIO-based communication protocol
- Full A2AMCP API compliance with 17 tools implemented
## 📦 Installation Options
### Docker Compose (Production)
```yaml
services:
mcp-server:
build: .
container_name: splitmind-mcp-server
ports:
- "5050:5000" # Changed from 5000 to avoid conflicts
environment:
- REDIS_URL=redis://redis:6379
- LOG_LEVEL=INFO
depends_on:
redis:
condition: service_healthy
restart: unless-stopped
redis:
image: redis:7-alpine
container_name: splitmind-redis
ports:
- "6379:6379"
volumes:
- redis-data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 5s
retries: 5
volumes:
redis-data:
driver: local
```
### Python SDK
```bash
pip install a2amcp-sdk
```
### JavaScript/TypeScript SDK (Coming Soon)
```bash
npm install @a2amcp/sdk
```
## 🚦 Usage Example
### Python SDK
```python
from a2amcp import A2AMCPClient, Project, Agent
async def run_agent():
client = A2AMCPClient("localhost:5000")
project = Project(client, "my-app")
async with Agent(project, "001", "feature/auth", "Build authentication") as agent:
# Agent automatically registers and maintains heartbeat
# Coordinate file access
async with agent.files.coordinate("src/models/user.ts") as file:
# File is locked, safe to modify
pass
# File automatically released
# Share interfaces
await project.interfaces.register(
agent.session_name,
"User",
"interface User { id: string; email: string; }"
)
```
### Direct MCP Tool Usage
```python
# Register agent
register_agent("my-project", "task-001", "001", "feature/auth", "Building authentication")
# Query another agent
query_agent("my-project", "task-001", "task-002", "interface", "What's the User schema?")
# Share interface
register_interface("my-project", "task-001", "User", "interface User {...}")
```
## 📚 Documentation
- [Claude Code Setup Guide](./CLAUDE_CODE_SETUP.md)
- [Installation & Setup](./SETUP.md)
- [Full API Reference](https://github.com/webdevtodayjason/A2AMCP/blob/main/docs/API_REFERENCE.md)
- [Python SDK Documentation](https://github.com/webdevtodayjason/A2AMCP/blob/main/sdk/python/README.md)
- [Architecture Overview](https://github.com/webdevtodayjason/A2AMCP/blob/main/docs/ARCHITECTURE.md)
- [SplitMind Integration Guide](https://github.com/webdevtodayjason/A2AMCP/blob/main/docs/SPLITMIND_INTEGRATION.md)
## 🛠️ SDKs and Tools
### Available Now
- **Python SDK**: Full-featured SDK with async support
- **Docker Deployment**: Production-ready containers
### In Development
- **JavaScript/TypeScript SDK**: For Node.js and browser
- **CLI Tools**: Command-line interface for monitoring
- **Go SDK**: High-performance orchestration
- **Testing Framework**: Mock servers and test utilities
See [SDK Development Progress](https://github.com/webdevtodayjason/A2AMCP/blob/main/sdk/TODO.md) for details.
## 🤝 Integration with AI Frameworks
A2AMCP is designed to work with:
- [SplitMind](https://github.com/webdevtodayjason/splitmind) - Original use case
- Claude Code (via MCP)
- Any MCP-compatible AI agent
- Future: LangChain, CrewAI, AutoGen
## 🔍 How It Differs from A2A
While inspired by Google's A2A protocol, A2AMCP makes specific design choices for AI code development:
| Feature | Google A2A | A2AMCP |
|---------|------------|---------|
| Protocol | HTTP-based | MCP tools |
| State | Stateless | Redis persistence |
| Focus | Generic tasks | Code development |
| Deployment | Per-agent servers | Single shared server |
## 🚀 Roadmap
- [x] Core MCP server with Redis
- [x] Modern MCP SDK 1.9.3 integration
- [x] Fixed decorator patterns (`@server.list_tools()`, `@server.call_tool()`)
- [x] Python SDK
- [x] Docker deployment
- [x] All 17 A2AMCP API tools implemented and tested
- [x] Health check endpoint for monitoring
- [x] Verification script for testing connectivity
- [ ] JavaScript/TypeScript SDK
- [ ] CLI monitoring tools
- [ ] SplitMind native integration
- [ ] Framework adapters (LangChain, CrewAI)
- [ ] Enterprise features
## 🛠️ Troubleshooting
### Agents can't see `mcp__splitmind-a2amcp__` tools
1. **Restart Claude Desktop** - MCP connections are established at startup
2. **Verify server is running**: `docker ps | grep splitmind`
3. **Check health endpoint**: `curl http://localhost:5050/health`
4. **Run verification script**: `python verify_mcp.py`
5. **Check configuration**: Ensure `~/Library/Application Support/Claude/claude_desktop_config.json` contains the A2AMCP server configuration
### Common Issues
- **"Tool 'X' not yet implemented"** - Fixed in latest version, pull latest changes
- **Connection failed** - Ensure Docker is running and ports 5050/6379 are free
- **Redis connection errors** - Wait for Redis to be ready (takes ~5-10 seconds on startup)
## 🤝 Contributing
We welcome contributions! See [CONTRIBUTING.md](https://github.com/webdevtodayjason/A2AMCP/blob/main/CONTRIBUTING.md) for guidelines.
### Development Setup
```bash
# Clone repository
git clone https://github.com/webdevtodayjason/A2AMCP
cd A2AMCP
# Install dependencies
pip install -r requirements.txt
# Run tests
pytest
# Start development server
docker-compose -f docker-compose.dev.yml up
```
## 📊 Performance
- Handles 100+ concurrent agents
- Sub-second message delivery
- Automatic cleanup of dead agents
- Horizontal scaling ready
## 🔒 Security
- Project isolation
- Optional authentication (coming soon)
- Encrypted communication (roadmap)
- Audit logging
## 📄 License
MIT License - see [LICENSE](https://github.com/webdevtodayjason/A2AMCP/blob/main/LICENSE) file.
## 🙏 Acknowledgments
- Inspired by [Google's A2A Protocol](https://github.com/google/A2A)
- Built for [SplitMind](https://github.com/webdevtodayjason/splitmind)
- Powered by [Model Context Protocol](https://modelcontextprotocol.io)
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/webdevtodayjason/A2AMCP/issues)
- **Discussions**: [GitHub Discussions](https://github.com/webdevtodayjason/A2AMCP/discussions)
- **Discord**: Coming soon
---
*A2AMCP - Turning isolated AI agents into coordinated development teams*