Metadata-Version: 2.4
Name: a2a_mcp_server
Version: 0.1.0
Summary: A bridge server that connects Model Context Protocol (MCP) with Agent-to-Agent (A2A) protocol
Project-URL: Homepage, https://github.com/GongRzhe/A2A-MCP-Server
Project-URL: Bug Tracker, https://github.com/GongRzhe/A2A-MCP-Server/issues
Project-URL: Repository, https://github.com/GongRzhe/A2A-MCP-Server
Project-URL: Documentation, https://github.com/GongRzhe/A2A-MCP-Server/blob/main/README.md
Author-email: GongRzhe <gongrzhe@gmail.com>
Maintainer-email: GongRzhe <gongrzhe@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: A2A,AI,Agent-to-Agent,LLM,MCP,Model Context Protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.3.4
Requires-Dist: httpx-sse>=0.4.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: jwcrypto>=1.5.6
Requires-Dist: pydantic>=2.10.6
Requires-Dist: pyjwt>=2.10.1
Requires-Dist: sse-starlette>=2.2.1
Requires-Dist: starlette>=0.46.1
Requires-Dist: typing-extensions>=4.12.2
Requires-Dist: uvicorn>=0.34.0
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.3.5; extra == 'dev'
Requires-Dist: ruff>=0.11.2; extra == 'dev'
Description-Content-Type: text/markdown

# A2A MCP Server

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

A middleware server that bridges the Model Context Protocol (MCP) with the Agent-to-Agent (A2A) protocol, enabling MCP-compatible AI assistants (like Claude) to seamlessly interact with A2A agents.

## Overview

This project serves as an integration layer between two cutting-edge AI agent protocols:

- **Model Context Protocol (MCP)**: Developed by Anthropic, MCP allows AI assistants to connect to external tools and data sources. It standardizes how AI applications and large language models connect to external resources in a secure, composable way.

- **Agent-to-Agent Protocol (A2A)**: Developed by Google, A2A enables communication and interoperability between different AI agents through a standardized JSON-RPC interface.

By bridging these protocols, this server allows MCP clients (like Claude) to discover, register, communicate with, and manage tasks on A2A agents through a unified interface.

## Features

- **Agent Management**
  - Register A2A agents with the bridge server
  - List all registered agents
  - Unregister agents when no longer needed

- **Communication**
  - Send messages to A2A agents and receive responses
  - Stream responses from A2A agents in real-time

- **Task Management**
  - Track which A2A agent handles which task
  - Retrieve task results using task IDs
  - Cancel running tasks

- **Transport Support**
  - Multiple transport types: stdio, streamable-http, SSE
  - Configure transport type using MCP_TRANSPORT environment variable

## Installation

### Prerequisites

- Python 3.11+
- [FastMCP](https://github.com/anthropics/fastmcp) library (2.3.4+)
- A2A client library

### Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/a2a-mcp-server.git
   cd a2a-mcp-server
   ```

2. Set up a virtual environment:
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

4. Configure environment variables (optional):
   ```bash
   export MCP_HOST="0.0.0.0"  # Host for the MCP server
   export MCP_PORT="8000"     # Port for the MCP server
   export MCP_TRANSPORT="streamable-http"  # Transport type: stdio, streamable-http, or sse
   ```

5. Run the server:
   ```bash
   python a2a_mcp_server.py
   ```

## Available MCP Tools

The server exposes the following MCP tools for integration with LLMs like Claude:

### Agent Management

- **register_agent**: Register an A2A agent with the bridge server
  ```json
  {
    "name": "register_agent",
    "arguments": {
      "url": "http://localhost:41242"
    }
  }
  ```

- **list_agents**: Get a list of all registered agents
  ```json
  {
    "name": "list_agents",
    "arguments": {}
  }
  ```

- **unregister_agent**: Remove an A2A agent from the bridge server
  ```json
  {
    "name": "unregister_agent",
    "arguments": {
      "url": "http://localhost:41242"
    }
  }
  ```

### Message Processing

- **send_message**: Send a message to an agent and get a task_id for the response
  ```json
  {
    "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**: Send a message and stream the response
  ```json
  {
    "name": "send_message_stream",
    "arguments": {
      "agent_url": "http://localhost:41242",
      "message": "Tell me a story about AI agents.",
      "session_id": "optional-session-id"
    }
  }
  ```

### Task Management

- **get_task_result**: Retrieve a task's result using its ID
  ```json
  {
    "name": "get_task_result",
    "arguments": {
      "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1",
      "history_length": null
    }
  }
  ```

- **cancel_task**: Cancel a running task
  ```json
  {
    "name": "cancel_task",
    "arguments": {
      "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1"
    }
  }
  ```

## Usage Examples

### Basic Workflow

```
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
```

### Example with Claude as the MCP Client

```
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."
```

## Architecture

The A2A MCP server consists of several key components:

1. **FastMCP Server**: Exposes tools to MCP clients
2. **A2A Client**: Communicates with registered A2A agents
3. **Task Manager**: Handles task forwarding and management
4. **Agent Card Fetcher**: Retrieves information about A2A agents

### Communication Flow

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

## Task ID Management

When sending a message to an A2A agent, the server:

1. Generates a unique `task_id`
2. Maps this ID to the agent's URL in the `task_agent_mapping` dictionary
3. Returns the `task_id` to the MCP client
4. Uses this mapping to route task retrieval and cancellation requests

## Error Handling

The server provides detailed error messages for common issues:

- Agent not registered
- Task ID not found
- Connection errors to agents
- Parsing errors in responses

## Troubleshooting

### Agent Registration Issues

If an agent can't be registered:
- Verify the agent URL is correct and accessible
- Check if the agent has a proper agent card at `/.well-known/agent.json`

### Message Delivery Problems

If messages aren't being delivered:
- Ensure the agent is registered (use `list_agents`)
- Verify the agent is running and accessible

### Task Result Retrieval Issues

If you can't retrieve a task result:
- Make sure you're using the correct task_id
- Check if too much time has passed (some agents might discard old tasks)

## Development

### Adding New Tool Methods

To add new capabilities to the server, add methods decorated with `@mcp.tool()` in the `a2a_mcp_server.py` file.

### Custom Task Manager

The server uses a custom `A2AServerTaskManager` class that extends `InMemoryTaskManager`. You can customize its behavior by modifying this class.

## Project Structure

```
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
├── .gitignore             # Git ignore file
├── pyproject.toml         # Project metadata and dependencies
├── README.md              # This file
└── requirements.txt       # Project dependencies
```

## License

This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) file for details.

The code in the `common/` directory is from the [Google A2A project](https://github.com/google/A2A) and is also licensed under the Apache License, Version 2.0.

## Acknowledgments

- Anthropic for the [Model Context Protocol](https://modelcontextprotocol.io/)
- Google for the [Agent-to-Agent Protocol](https://github.com/google/A2A)
- Contributors to the FastMCP library
