Metadata-Version: 2.4
Name: mcp-a2a-gateway
Version: 0.1.6
Summary: A bridge server that connects Model Context Protocol (MCP) with Agent-to-Agent (A2A) protocol
Project-URL: Homepage, https://github.com/yw0nam/mcp-a2a-gateway
Project-URL: Bug Tracker, https://github.com/yw0nam/mcp-a2a-gateway/issues
Project-URL: Repository, https://github.com/yw0nam/mcp-a2a-gateway
Project-URL: Documentation, https://github.com/yw0nam/mcp-a2a-gateway/blob/main/README.md
Author-email: yw0nam <spow2544@gmail.com>
Maintainer-email: yw0nam <spow2544@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: A2A,AI,Agent-to-Agent,LLM,MCP,Model Context Protocol,uvx
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
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: a2a-sdk>=0.2.8
Requires-Dist: fastmcp>=2.8.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: pytest-asyncio>=1.0.0
Requires-Dist: pytest>=8.4.1
Requires-Dist: uvicorn>=0.34.0
Description-Content-Type: text/markdown

# MCP-A2A-Gateway

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
![](https://badge.mcpx.dev?type=server 'MCP Server')

A gateway 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.

## Quick Start

⚠️ **Note**: The package needs to be published to PyPI first before using `uvx run`.

### For Development (Local)
```bash
# Clone and run locally
git clone https://github.com/yw0nam/MCP-A2A-Gateway.git
cd MCP-A2A-Gateway
uv run mcp-a2a-gateway

# Or use uvx with local path
uvx --from . mcp-a2a-gateway
```

### After Publishing to PyPI
```bash
# Run the latest version directly
uvx run mcp-a2a-gateway

# Run with custom environment variables
MCP_TRANSPORT=stdio uvx run mcp-a2a-gateway

# Run with specific version
uvx run mcp-a2a-gateway==0.1.5
```

### Demo

#### 1, Run The hello world Agent in A2A Sample

![agent](public/agent.png)

`also support cloud deployed Agent`

![cloudAgent](https://github.com/user-attachments/assets/481cbf01-95a0-4b0a-9ac5-898aef66a944)

#### 2, Use Claude or github copilot to register the agent.

![register_claude](public/register_claude.png)
![register_copilot](public/register_copilot.png)

#### 3, Use Claude to Send a task to the hello Agent and get the result.

![send_message](public/send_message.png)

#### 4, Use Claude to retrieve the task result.

![retrieve_result](public/retrieve_result.png)

## 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
  - Asynchronous message sending for immediate server response.
  - Stream responses from A2A agents in real-time

- **Task Management**
  - Track which A2A agent handles which task
  - Retrieve task results using task IDs
  - Get a list of all tasks and their statuses.
  - Cancel running tasks

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

## Prerequisites

Before you begin, ensure you have the following installed:

- Python 3.11+
- [uv](https://github.com/astral-sh/uv) (for local development)

## Installation

### Option 1: Direct Run with uvx (After PyPI Publishing)

Run directly without installation using `uvx`:

```bash
uvx run mcp-a2a-gateway
```

This will automatically download and run the latest version from PyPI.

### Option 2: Local Development

1. Clone the repository:

```bash
git clone https://github.com/yw0nam/MCP-A2A-Gateway.git
cd MCP-A2A-Gateway
```

2. Run using uv:

```bash
uv run mcp-a2a-gateway
```

3. Or use uvx with local path:

```bash
uvx --from . mcp-a2a-gateway
```

### Option 3: Install from PyPI (After Publishing)

```bash
# Using uv
uv add mcp-a2a-gateway
uv run mcp-a2a-gateway

# Using pip
pip install mcp-a2a-gateway
mcp-a2a-gateway

# Run as Python module (after installation)
python -m mcp_a2a_gateway
```

## Configuration

### Environment Variables

Modify`.env.example` file in the root of the project to `'.env'`

### Transport Types

The A2A MCP Server supports multiple transport types:

1. **stdio** (default): Uses standard input/output for communication
   - Ideal for command-line usage and testing
   - No HTTP server is started
   - Required for Claude Desktop

2. **streamable-http** (recommended for web clients): HTTP transport with streaming support
   - Recommended for production deployments
   - Starts an HTTP server to handle MCP requests
   - Enables streaming of large responses

3. **sse**: Server-Sent Events transport
   - Provides real-time event streaming
   - Useful for real-time updates



## TO connect github copilot

Add below setting.json for sse or http
```
"mcp_a2a_gateway": {
    "url": "http://0.0.0.0:10000/mcp"
}
```

For stdio (local development):

```json
"mcp_a2a_gateway": {
    "type": "stdio",
    "command": "uv",
    "args": [
        "--directory",
        "$INSTALLED_DIR",
        "run",
        "mcp-a2a-gateway"
    ]
}
```

For stdio (using uvx - after PyPI publishing):

```json
"mcpServers": {
  "mcp_a2a_gateway": {
    "type": "stdio",
    "command": "uvx",
    "args": ["mcp-a2a-gateway"]
  }
}
```

For stdio (using uvx - local development):

```json
"mcpServers": {
  "mcp_a2a_gateway": {
    "type": "stdio",
    "command": "uvx",
    "args": ["--from", "/path/to/MCP-A2A-Gateway", "mcp-a2a-gateway"]
  }
}
```

## To Connect claude desktop

### Using local development version:
Add this to claude_config.json

```json
"mcpServers": {
  "mcp_a2a_gateway": {
    "command": "uv",
    "args": ["--directory", "/path/to/MCP-A2A-Gateway", "run", "mcp-a2a-gateway"],
    "env": {
      "MCP_TRANSPORT": "stdio"
    }
  }
}
```

### Using uvx (after PyPI publishing):
Add this to claude_config.json

```json
"mcpServers": {
  "mcp_a2a_gateway": {
    "command": "uvx",
    "args": ["mcp-a2a-gateway"],
    "env": {
      "MCP_TRANSPORT": "stdio"
    }
  }
}
```

### Using uvx (local development):
Add this to claude_config.json

```json
"mcpServers": {
  "mcp_a2a_gateway": {
    "command": "uvx",
    "args": ["--from", "/path/to/MCP-A2A-Gateway", "mcp-a2a-gateway"],
    "env": {
      "MCP_TRANSPORT": "stdio"
    }
  }
}
```


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

-   **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"
      }
    }
    ```

### 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",
      }
    }
    ```

-   **get_task_list**: Get a list of all tasks and their statuses.

    ```json
    {
        "name": "get_task_list",
        "arguments": {}
    }
    ```


## Roadmap & How to Contribute

We are actively developing and improving the gateway! We welcome contributions of all kinds. Here is our current development roadmap, focusing on creating a rock-solid foundation first.

### Core Stability & Developer Experience (Help Wanted! 👍)

This is our current focus. Our goal is to make the gateway as stable and easy to use as possible.

-   [ ] **Implement Streaming Responses**: Full support for streaming responses from A2A agents.
-   [ ] **Enhance Error Handling**: Provide clearer error messages and proper HTTP status codes for all scenarios.
-   [ ] **Input Validation**: Sanitize and validate agent URLs during registration for better security.
-   [ ] **Add Health Check Endpoint**: A simple `/health` endpoint to monitor the server's status.
-   [ ] **Configuration Validation**: Check for necessary environment variables at startup.
-   [ ] **Comprehensive Integration Tests**: Increase test coverage to ensure reliability.
-   [ ] **Cancel Task**: Implement task cancellation
-   [ ] **Implement Streaming Update**: Implement streaming task update. So that user check the progress.


### Community & Distribution

-   [ ] **Easy Installation**: Add support for `npx`
-   [ ] **Docker Support**: Provide a Docker Compose setup for easy deployment.
-   [ ] **Better Documentation**: Create a dedicated documentation site or expand the Wiki.

---
**Want to contribute?** Check out the issues tab or feel free to open a new one to discuss your ideas!

## License

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

## 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
- Contributors of [A2A-MCP-Server](https://github.com/GongRzhe/A2A-MCP-Server) (This project highly inspired from this repo.)

## Publishing to PyPI

To make the package available for `uvx run`, you need to publish it to PyPI:

### Prerequisites
- PyPI account and API token
- `uv` or `build` + `twine` installed

### Publishing Steps

1. **Build the package:**
```bash
# Using uv (recommended)
uv build

# Or using build
python -m build
```

2. **Upload to PyPI:**
```bash
# Using uv (if supported)
uv publish

# Or using twine
twine upload dist/*
```

3. **Test the published package:**
```bash
# Wait a few minutes for PyPI to process, then test
uvx run mcp-a2a-gateway
```

### Version Management
Update the version in `pyproject.toml` before each release:
```toml
version = "0.1.6"  # Increment as needed
```
