n8n-nodes-a2a-protocol/README.md

Agent2Agent (A2A) Protocol nodes for n8n - Enable agent interoperability, communication, and MCP integration

# N8N A2A Protocol Nodes

A collection of n8n custom nodes implementing the Agent-to-Agent (A2A) Protocol for enabling agent interoperability and communication within n8n workflows.

## Overview

This package provides a complete set of n8n nodes for implementing A2A Protocol communication:

- **A2A Agent Registry** - Central registry for agent discovery and management
- **A2A Remote Agent Server** - Server node that receives and processes A2A tasks
- **A2A Client Agent** - Client node for sending tasks to remote A2A agents
- **A2A Client Tool** - 🆕 **NEW!** MCP-compatible tool for seamless agent communication
- **A2A Callback** - Enhanced callback node for returning results to A2A servers

## Features

✅ **Full A2A Protocol Compliance** - Implements A2A v1.0 specification
✅ **MCP Integration** - 🆕 **NEW!** Model Context Protocol compatibility with `usableAsTool: true`
✅ **Synchronous & Asynchronous Processing** - Support for both sync and async workflows
✅ **Agent Discovery** - Automatic agent registration and discovery
✅ **Workflow Integration** - Native n8n workflow compatibility
✅ **Flexible Callback System** - Multiple callback URL resolution methods
✅ **Enhanced Debugging** - Comprehensive logging and error reporting
✅ **Clean Console Output** - Minimal logging in production (debug available in callback node)

## Installation

### NPM Installation (Recommended)

```bash
# Install the community node package
npm install -g n8n-nodes-a2a-protocol

# Start n8n (nodes auto-load)
n8n start
```

**That's it!** The A2A Protocol nodes will automatically appear in your n8n interface.

### Local Development Installation

For local development and testing:

```bash
# Clone and install locally
git clone https://github.com/Vinoth-Paulraj-HID/n8n-a2a-protocol.git
cd n8n-a2a-protocol/n8n
npm install
npm run build

# Install globally from local project folder
npm install -g .

# Start n8n
n8n start
```

### Development/Source Installation

```bash
git clone https://github.com/Vinoth-Paulraj-HID/n8n-a2a-protocol.git
cd n8n-a2a-protocol/n8n
npm install
npm run build
npm install -g .
```

## Usage

### Using A2A Nodes (After npm Installation)

After installing via npm, the nodes are automatically available in n8n:

```bash
# Simply start n8n - nodes are auto-discovered
n8n start
```

**No environment variables needed!** The nodes will appear in your n8n node palette under:
- **Triggers**: A2A Agent Registry, A2A Remote Agent Server
- **Regular**: A2A Client Agent, A2A Callback
- **Transform**: A2A Client Tool 🆕 **NEW!**

### MCP Integration Setup

For MCP Server Trigger compatibility:

```bash
# Enable community package tool usage
export N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE="true"
n8n start
```

```powershell
# Windows PowerShell
$env:N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE="true"
n8n start
```

### Manual/Development Setup Only

⚠️ **Only needed for local development or manual installation:**

```bash
# Set custom extensions path (development only)
export N8N_CUSTOM_EXTENSIONS="/path/to/n8n-nodes-a2a-protocol"
n8n start
```

```powershell
# Windows PowerShell (development only)
$env:N8N_CUSTOM_EXTENSIONS="C:\path\to\n8n-nodes-a2a-protocol"
n8n start
```

## Node Documentation

### A2A Client Tool 🆕 **NEW!**

**MCP-compatible tool for seamless A2A agent communication:**

- **MCP Integration**: `usableAsTool: true` enables MCP Server Trigger discovery
- **Agent Discovery**: Automatic A2A agent discovery via registry
- **Message Integration**: Enhanced message handling in both top-level params and data payload
- **Processing Modes**: Sync/async processing with configurable timeout
- **Registry Support**: Auto-populated local servers with fallback to manual entry
- **JSON-RPC 2.0**: Full A2A protocol compliance with enhanced error handling

**Perfect for MCP workflows:**
```
[MCP Client] → [MCP Server Trigger] → [A2A Client Tool] → [A2A Remote Agent Server]
```

### A2A Remote Agent Server

Acts as a trigger node that receives A2A tasks and forwards them to your n8n workflow:

- **Port**: 7000 (default)
- **Processing Modes**: sync, async, mixed
- **Auto-registration**: Registers with A2A Registry automatically

### A2A Callback

Enhanced callback node with multiple URL resolution methods:

- **Auto-detect**: Automatically finds callback URL from A2A Server data
- **Expression**: Use n8n expressions like `{{ $("A2A  Agent Server").item.json._workflow_instructions.callback_url}}`
- **Manual**: Manually specify callback URLs

### A2A Agent Registry

Central registry for agent discovery:

- **Port**: 8080 (default)
- **Health Monitoring**: Tracks agent availability
- **Discovery API**: RESTful API for agent lookup

### A2A Client Agent

Send tasks to remote A2A agents:

- **Target Selection**: Manual or registry-based agent discovery
- **Processing Modes**: Support for sync/async requests
- **Error Handling**: Comprehensive error reporting

## Configuration Examples

### Basic MCP Workflow 🆕 **NEW!**

```
[MCP Server Trigger] → [A2A Client Tool] → [Process Response]
```

### Basic Sync Workflow

```
A2A Remote Agent Server → Your Processing → A2A Callback
```

### Advanced Workflow with Agent Discovery

```
A2A Agent Registry → A2A Client Agent → Process Response
```

### MCP + A2A Integration

```
[MCP Client] → [MCP Server Trigger] → [A2A Client Tool] → [A2A Remote Agent Server] → [Processing] → [A2A Callback]
```

## Troubleshooting

### Common Issues

1. **"Could not get parameter" Error**
   - Ensure all required parameters have default values
   - Check node configuration and connections

2. **Callback URL Not Found**
   - Verify A2A Server node is connected and configured
   - Use "From Node Expression" mode in A2A Callback
   - Check the exact node name in your workflow

3. **MCP Tool Not Discoverable** 🆕
   - Ensure `N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE="true"` is set
   - Verify the tool appears in the "Transform" section
   - Check that `usableAsTool: true` is properly configured

4. **Port Already in Use**
   - Change port numbers in node configuration
   - Stop existing A2A processes

### Debug Mode

The A2A Callback node includes comprehensive debugging:

- Set `callbackUrlSource` to `expression` to see available nodes
- Check console output for detailed field information
- Verify node names and data structures

## Development

### Building

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Linting

```bash
npm run lint
npm run lintfix
```

## Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   A2A Client    │───▶│  A2A Registry    │◀───│  A2A Server     │
│     Agent       │    │                  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                         │
                              🆕 NEW MCP FLOW            ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│ MCP Server Trigger│───▶│ A2A Client Tool │
│                 │    │                  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                         │
                                                         ▼
                                              ┌─────────────────┐
                                              │  N8N Workflow   │
                                              │   Processing    │
                                              └─────────────────┘
                                                         │
                                                         ▼
                                              ┌─────────────────┐
                                              │  A2A Callback   │
                                              │    Response     │
                                              └─────────────────┘
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Version History

### v1.1.0 🆕 **NEW!**
- **Major Enhancement**: Added A2A Client Tool with MCP integration
- **MCP Compatibility**: Implements `usableAsTool: true` for MCP Server Trigger discovery
- **Enhanced Agent Discovery**: Dynamic agent discovery with registry integration
- **Message Integration**: Dual message placement in both top-level params and data payload
- **JSON-RPC 2.0**: Full A2A protocol compliance with enhanced error handling
- **Local Installation**: Added `npm install -g .` command for local development
- **Tool Pattern**: Follows standard n8n tool pattern with `group: ['transform']`

### v1.0.0
- Initial release with full A2A Protocol support
- All four core nodes implemented
- Enhanced callback system with expression support
- Comprehensive debugging and error handling
- Clean console output (removed verbose logging from server nodes)

## Support

For issues and questions:
1. Check the troubleshooting section above
2. Enable debug mode in A2A Callback node
3. Review console output for detailed error information
4. Submit issues with complete debug logs