Skip to content

InteractiveAdvertisingBureau/mcp-config

Repository files navigation

OpenDirect A2A Agent System

Overview

A comprehensive Node.js implementation of an Agent-to-Agent (A2A) system compliant with the A2A Protocol v0.3.0. The system features dual AI-powered agents (Buyer and Seller) for OpenDirect advertising operations, with integrated Model Context Protocol (MCP) support for tool execution.

Built on a clean modular architecture with 5 independent modules that work together seamlessly.

🎯 Key Features

  • πŸ€– Dual AI Agents - Autonomous Buyer and Seller agents with natural language understanding
  • πŸ“‹ A2A Protocol v0.3.0 - Full compliance with agent card discovery, JSON-RPC 2.0, and HTTP+JSON transports
  • πŸ”§ MCP Integration - 33+ auto-generated tools from OpenDirect schemas
  • 🎨 Schema-Driven - Single source of truth from OpenAPI 3.0 schemas
  • πŸ’¬ Multi-Provider AI - Support for OpenAI, Anthropic Claude, and Google Gemini
  • 🌐 Web Interface - Ready-to-use test client for agent interactions

πŸš€ Quick Start (5 Minutes)

Prerequisites

node >= 18.0.0
npm >= 9.0.0

Installation

# Clone repository
git clone https://github.com/InteractiveAdvertisingBureau/mcp-config.git
cd mcp-config

# Install dependencies
npm install

# Install test client
cd client-test && npm install && cd ..

Environment Setup

Create .env file:

NODE_ENV=development
PORT=3000

# AI Provider (choose one)
OPENAI_API_KEY=sk-proj-your-key
OPENAI_MODEL=gpt-4o-mini

# Optional: Other providers
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...

# MCP Configuration
DEFAULT_ANALYSIS_MODEL=openai
DEFAULT_CHAT_MODEL=openai
MCP_ENABLE_ADMIN_TOOLS=false

Or use the quick-start script:

./quick-start.sh

Start Server

npm start
# Expected: Server on port 3000, MCP integration with 33 tools

Start Test Client (new terminal)

cd client-test && npm start
# Expected: Server on http://localhost:8080

Verify

βœ… Agent Card Discovery:

curl http://localhost:3000/a2a/buyer/.well-known/agent-card.json | jq

βœ… Web Client:

http://localhost:8080

βœ… Send test message:

"create an account for Nike"

πŸ—οΈ Architecture Layers

Layer Overview

The system is organized into four distinct layers:

  1. Client Layer - Web UI (client-test/) and A2A-compliant clients communicate via the A2A Protocol v0.3.0 over HTTPS.

  2. A2A Agent Layer - Express.js server (port 3000) hosting Buyer and Seller agents with multiple transport protocols (JSON-RPC 2.0, HTTP+JSON), dynamic agent card generation, and AI-powered execution.

  3. MCP Layer - Schema-driven tool generator using OpenAPI 3.0 specs to dynamically create 33+ tools from the OpenDirect schema, with validation and API handlers via Server-Sent Events (SSE) transport.

  4. Schema Layer - OpenAPI 3.0 specification defining 13 resource types (Account, Order, Line, Product, Creative, etc.), 40+ object definitions, and standardized endpoints with parameters and validations.

Architecture Overview

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                         CLIENT LAYER                                 β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”              β”‚
β”‚  β”‚  Web Client  β”‚  β”‚Claude Desktopβ”‚  β”‚  Test Client β”‚              β”‚
β”‚  β”‚(client-test) β”‚  β”‚  (MCP HTTP)  β”‚  β”‚    (SDK)     β”‚              β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜              β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
          β”‚                  β”‚                  β”‚
          β”‚ HTTP/JSON        β”‚ SSE              β”‚ HTTP
          β”‚ A2A Protocol     β”‚ MCP Protocol     β”‚ A2A Protocol
          β”‚                  β”‚                  β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                    A2A AGENT LAYER (Port 3000)                      β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”‚
β”‚  β”‚         Client Agent (Orchestrator)                       β”‚     β”‚
β”‚  β”‚  β€’ Autonomous Mode: Auto-selects buyer/seller            β”‚     β”‚
β”‚  β”‚  β€’ Orchestrated Mode: User-directed routing              β”‚     β”‚
β”‚  β”‚  β€’ Session management & conversation history             β”‚     β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β”‚
β”‚                β”‚                        β”‚                           β”‚
β”‚   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”               β”‚
β”‚   β”‚   Buyer Agent         β”‚  β”‚   Seller Agent      β”‚               β”‚
β”‚   β”‚  /a2a/buyer           β”‚  β”‚  /a2a/seller        β”‚               β”‚
β”‚   β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”‚  β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”β”‚               β”‚
β”‚   β”‚  β”‚ Agent Card      β”‚  β”‚  β”‚  β”‚ Agent Card      β”‚β”‚               β”‚
β”‚   β”‚  β”‚ - Skills        β”‚  β”‚  β”‚  β”‚ - Skills        β”‚β”‚               β”‚
β”‚   β”‚  β”‚ - Transports    β”‚  β”‚  β”‚  β”‚ - Transports    β”‚β”‚               β”‚
β”‚   β”‚  β”‚ - Examples      β”‚  β”‚  β”‚  β”‚ - Examples      β”‚β”‚               β”‚
β”‚   β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β”‚  β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜β”‚               β”‚
β”‚   β”‚  Skills:              β”‚  β”‚  Skills:             β”‚               β”‚
β”‚   β”‚  β€’ create_account     β”‚  β”‚  β€’ list_products     β”‚               β”‚
β”‚   β”‚  β€’ create_order       β”‚  β”‚  β€’ search_inventory  β”‚               β”‚
β”‚   β”‚  β€’ search_inventory   β”‚  β”‚  β€’ process_orders    β”‚               β”‚
β”‚   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜               β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                 β”‚                         β”‚
                 β”‚ MCP Tool Calls          β”‚ MCP Tool Calls
                 β”‚                         β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                         MCP LAYER                                    β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”             β”‚
β”‚  β”‚ API Testing  β”‚  β”‚  OpenDirect  β”‚  β”‚Schema-Driven β”‚             β”‚
β”‚  β”‚     MCP      β”‚  β”‚     MCP      β”‚  β”‚     MCP      β”‚             β”‚
β”‚  β”‚  /mcp/sse    β”‚  β”‚/agenticdirectβ”‚  β”‚ /schema/mcp  β”‚             β”‚
β”‚  β”‚   (8 tools)  β”‚  β”‚  /mcp/sse    β”‚  β”‚   /sse       β”‚             β”‚
β”‚  β”‚              β”‚  β”‚  (10 tools)  β”‚  β”‚  (33 tools)  β”‚             β”‚
β”‚  β”‚  Transport:  β”‚  β”‚  Transport:  β”‚  β”‚  Transport:  β”‚             β”‚
β”‚  β”‚  SSE         β”‚  β”‚  SSE         β”‚  β”‚  SSE         β”‚             β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜             β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                              β”‚
                                              β”‚ Schema Loading
                                              β”‚ & Validation
                                              β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                       SCHEMA LAYER                                   β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”‚
β”‚  β”‚          OpenDirect OpenAPI 3.0 Schema                        β”‚  β”‚
β”‚  β”‚          (opendirect-mcp-schema.json)                         β”‚  β”‚
β”‚  β”‚                                                               β”‚  β”‚
β”‚  β”‚  πŸ“‹ 13 Resource Types:                                        β”‚  β”‚
β”‚  β”‚     Account, Order, Line, Product, Creative,                 β”‚  β”‚
β”‚  β”‚     Assignment, Organization, ChangeRequest, Message         β”‚  β”‚
β”‚  β”‚                                                               β”‚  β”‚
β”‚  β”‚  πŸ—οΈ  40+ Object Definitions:                                  β”‚  β”‚
β”‚  β”‚     - Request/Response schemas                               β”‚  β”‚
β”‚  β”‚     - Validation rules (Zod)                                 β”‚  β”‚
β”‚  β”‚     - Parameter specifications                               β”‚  β”‚
β”‚  β”‚                                                               β”‚  β”‚
β”‚  β”‚  βœ… CRUD Operations: create, get, list, update, delete       β”‚  β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

System Components

Client Layer

  • Web UI (client-test/): Pure HTML/CSS/JavaScript interface
  • A2A Protocol v0.3.0: Standard agent communication
  • Features:
    • Agent selection (Buyer/Seller)
    • Connection management
    • Real-time response display
    • Message history and session tracking

A2A Agent Layer

  • Dual Agents: Buyer (/a2a/buyer) and Seller (/a2a/seller)
  • Agent Card Discovery: /.well-known/agent-card.json
  • Transports:
    • JSON-RPC 2.0 (/jsonrpc)
    • HTTP+JSON (/rest)
    • MCP tools integration
  • AI-Powered Execution: OpenAI GPT for natural language understanding
  • Modes:
    • Autonomous: Agent auto-selects sub-agents
    • Orchestrated: User-directed routing

MCP Layer

  • Schema-Driven Tool Generator: Processes OpenAPI 3.0 specs
  • Validation: Zod schemas for runtime parameter checking
  • Tool Registry:
    • API Testing MCP: 8 tools (register, test, analyze APIs)
    • OpenDirect MCP: 10 tools (manual implementations)
    • Schema-Driven MCP: 33 tools (auto-generated CRUD)
  • Transport: Server-Sent Events (SSE) for streaming

Schema Layer

  • OpenDirect Specification: OpenAPI 3.0 format
  • 13 Resource Types: Account, Order, Line, Product, Creative, etc.
  • 40+ Object Definitions: Complete request/response schemas
  • Validation Rules: JSON Schema with Zod transformation

A2A Protocol Flow

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   Client    β”‚  1. User sends message: "create account for Nike"
β”‚  (Web UI)   β”‚
β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜
       β”‚
       β”‚ POST /api/a2a/chat
       β”‚ { message: "create account for Nike" }
       β”‚
       β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚           Client Agent (Orchestrator)                β”‚
β”‚                                                      β”‚
β”‚  2. Analyze message with AI (OpenAI GPT)           β”‚
β”‚     β†’ Determine: Account creation needed            β”‚
β”‚     β†’ Select: Buyer Agent                           β”‚
β”‚     β†’ Extract params: { name: "Nike" }             β”‚
β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
       β”‚
       β”‚ 3. Route to Buyer Agent
       β”‚
       β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚              Buyer Agent                             β”‚
β”‚             /a2a/buyer                               β”‚
β”‚                                                      β”‚
β”‚  4. Receive message via JSON-RPC 2.0:               β”‚
β”‚     POST /a2a/buyer/jsonrpc                         β”‚
β”‚     {                                                β”‚
β”‚       "method": "sendMessage",                      β”‚
β”‚       "params": {                                    β”‚
β”‚         "message": "create account for Nike"       β”‚
β”‚       }                                              β”‚
β”‚     }                                                β”‚
β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
       β”‚
       β”‚ 5. Execute skill: create_account
       β”‚
       β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚               MCP Layer                              β”‚
β”‚        (Schema-Driven MCP Server)                    β”‚
β”‚                                                      β”‚
β”‚  6. Call MCP tool: create_account                   β”‚
β”‚     POST /schema/mcp/sse                            β”‚
β”‚     {                                                β”‚
β”‚       "method": "tools/call",                       β”‚
β”‚       "params": {                                    β”‚
β”‚         "name": "create_account",                   β”‚
β”‚         "arguments": {                              β”‚
β”‚           "name": "Nike",                           β”‚
β”‚           "type": "advertiser"                      β”‚
β”‚         }                                            β”‚
β”‚       }                                              β”‚
β”‚     }                                                β”‚
β”‚                                                      β”‚
β”‚  7. Validate with Zod schema                        β”‚
β”‚  8. Execute account creation logic                  β”‚
β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
       β”‚
       β”‚ 9. Return result
       β”‚ { accountId: "acc_123", name: "Nike", ... }
       β”‚
       β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚              Buyer Agent                             β”‚
β”‚                                                      β”‚
β”‚  10. Format response                                 β”‚
β”‚      "βœ… Created account for Nike (ID: acc_123)"   β”‚
β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
       β”‚
       β”‚ 11. Return to orchestrator
       β”‚
       β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚         Client Agent (Orchestrator)                  β”‚
β”‚                                                      β”‚
β”‚  12. Add to conversation history                     β”‚
β”‚  13. Publish progress events                         β”‚
β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
       β”‚
       β”‚ 14. Return to client
       β”‚ {
       β”‚   response: "βœ… Created account...",
       β”‚   data: { accountId: "acc_123", ... }
       β”‚ }
       β”‚
       β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   Client    β”‚  15. Display response to user
β”‚  (Web UI)   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Multi-Step Workflow Example:

Message: "Create account for Adidas and create order for Adidas with budget $300"

Step 1: create_account
  └─> Response: { accountId: "acc_456" }
       β”‚
       β–Ό
Step 2: create_order
  └─> Input: { accountId: "acc_456", budget: 300 }
  └─> Response: { orderId: "ord_789", accountId: "acc_456" }

The orchestrator automatically:

  • βœ… Chains multiple operations
  • βœ… Passes data between steps (account ID)
  • βœ… Maintains conversation context
  • βœ… Handles errors gracefully

Key Components

Component File/Module Purpose
Main Server server.js Express setup, module orchestration, routing
Agent Card modules/a2a-protocol/lib/a2aEndpoints.js Agent discovery with skills, capabilities, security
Agent Executor modules/a2a-protocol/lib/agentExecutor.js AI-powered tool selection and task management
Client Agent modules/a2a-protocol/lib/clientAgent.js Agent orchestrator (autonomous/orchestrated modes)
MCP Server modules/schema-driven-mcp/server.js Schema-driven tool registry with SSE transport
Tool Generator modules/schema-driven-mcp/lib/toolGenerator.js Auto-generate CRUD tools from schemas
Schema Loader modules/schema-driven-mcp/lib/schemaLoader.js Load and validate OpenAPI schemas
Web Client client-test/ HTML/CSS/JS A2A test interface
OpenDirect Schema opendirect-mcp-schema.json OpenAPI 3.0 resource definitions and validations

πŸ“‹ Detailed Layer Descriptions

1. Client Layer

  • Web UI (client-test/): Pure HTML/CSS/JS interface
  • Direct A2A protocol calls
  • Agent selection (Buyer/Seller)
  • Real-time monitoring and status updates
  • Message streaming support

2. A2A Agent Layer

  • Express.js server (Port 3000)
  • Dual agents:
    • Buyer: /a2a/buyer
    • Seller: /a2a/seller
  • Agent card discovery: /.well-known/agent-card.json
  • Skills: Order creation, campaigns, creative management, product search
  • Multiple transports: JSON-RPC 2.0, HTTP+JSON, MCP tools
  • AI-powered orchestration: Natural language β†’ tool mapping

3. MCP Layer

  • Schema-driven tool generator from OpenAPI schemas
  • Input: OpenDirect OpenAPI 3.0 specification
  • Output: 33+ executable MCP tools with validation
  • Transport: Server-Sent Events (SSE) for streaming
  • Tool categories: CRUD operations, search, validation

4. Schema Layer

  • OpenDirect JSON specification (OpenAPI 3.0)
  • 13 resource types: Account, Order, Line, Product, Creative, etc.
  • 40+ object definitions with full validation schemas
  • Parameter validation and response schemas

πŸ“‚ Project Structure

mcp-config/
β”œβ”€β”€ server.js                       # Main entry point (modular architecture)
β”œβ”€β”€ package.json                    # Dependencies
β”‚
β”œβ”€β”€ modules/                        # 5 Independent modules
β”‚   β”œβ”€β”€ a2a-protocol/              # ⭐ Agent-to-Agent communication
β”‚   β”‚   β”œβ”€β”€ server.js              # A2A agent orchestrator
β”‚   β”‚   β”œβ”€β”€ routes/                # Agent endpoints
β”‚   β”‚   └── lib/                   # Agent cards, executors, SDK integration
β”‚   β”œβ”€β”€ opendirect-mcp/            # OpenDirect MCP implementation
β”‚   β”œβ”€β”€ schema-driven-mcp/         # Schema-to-tools generator
β”‚   β”œβ”€β”€ api-testing-mcp/           # API testing & validation
β”‚   └── ai-chat/                   # Multi-provider AI chat
β”‚
β”œβ”€β”€ shared/                         # Shared utilities
β”‚   β”œβ”€β”€ config/                    # Centralized configuration
β”‚   β”œβ”€β”€ database/                  # Database connection
β”‚   β”œβ”€β”€ utils/                     # Logger, UUID, date utilities
β”‚   └── middleware/                # CORS, error handlers
β”‚
β”œβ”€β”€ client/                         # Frontend clients
β”‚   └── standalone/                # AI chat UI
β”œβ”€β”€ client-test/                    # ⭐ A2A test client
β”‚   β”œβ”€β”€ index.html                 # Web interface
β”‚   β”œβ”€β”€ app.js                     # Client logic
β”‚   └── style.css                  # Styling
β”œβ”€β”€ client-test-sdk/                # SDK-based test client
β”‚
β”œβ”€β”€ prompts/                        # AI agent prompts
β”‚   β”œβ”€β”€ buyer/                     # Buyer agent prompts
β”‚   └── seller/                    # Seller agent prompts
β”‚
β”œβ”€β”€ tests/                          # Test resources
β”‚   β”œβ”€β”€ schemas/                   # Test schemas
β”‚   └── test.sh                    # Module testing script
β”‚
β”œβ”€β”€ opendirect-mcp-schema.json     # OpenDirect schema
β”œβ”€β”€ claude-desktop-config.json     # MCP client configuration
β”œβ”€β”€ quick-start.sh                 # Quick setup script
β”œβ”€β”€ deploy.sh                      # Cloud deployment script
β”œβ”€β”€ Dockerfile                     # Docker configuration
β”‚
└── a2a-agenticdirect-standalone/  # Standalone A2A module

πŸ€– A2A Agent System

Agent Card Discovery

Each agent exposes a standard agent card at /.well-known/agent-card.json:

# Buyer Agent Card
curl http://localhost:3000/a2a/buyer/.well-known/agent-card.json

# Seller Agent Card
curl http://localhost:3000/a2a/seller/.well-known/agent-card.json

Agent Card Structure:

  • Identity: Name, description, version
  • Skills: Available operations (create_order, search_products, etc.)
  • Transports: JSON-RPC 2.0, HTTP+JSON, MCP tools
  • Security: Authentication requirements
  • Examples: Sample requests and responses

Agent Modes

1. Autonomous Mode (Default)

  • Agent automatically selects appropriate sub-agents
  • Natural language understanding
  • Multi-step workflow orchestration
  • Example: "Create order for Nike" β†’ Agent calls buyer agent with correct tools

2. Orchestrated Mode

  • User manually selects target agent
  • Direct agent communication
  • More control over agent selection

Agent Communication Endpoints

JSON-RPC 2.0 Transport

POST /a2a/{agent}/jsonrpc
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "sendMessage",
  "params": {
    "message": "create an account for Nike",
    "context": {}
  },
  "id": 1
}

HTTP+JSON Transport

POST /a2a/{agent}/rest
Content-Type: application/json

{
  "message": "search for video ad products",
  "sessionId": "optional-session-id"
}

Client Agent API

# Send message to orchestrator
POST /api/a2a/chat

# Get conversation history
GET /api/a2a/chat/:sessionId/history

# Clear conversation
DELETE /api/a2a/chat/:sessionId

# Get progress events
GET /api/a2a/chat/:sessionId/progress

# Set/get agent mode
POST /api/a2a/mode
GET /api/a2a/mode

πŸ”§ Available Modules

⭐ 1. A2A Protocol (Primary Feature)

Purpose: Agent-to-agent communication using official @a2a-js/sdk with AI orchestration.

Endpoints:

  • /a2a/agents - Agent discovery
  • /a2a/buyer/.well-known/agent-card.json - Buyer agent card
  • /a2a/seller/.well-known/agent-card.json - Seller agent card
  • /api/a2a/chat - Client agent chat
  • /api/a2a/mode - Set orchestration mode

Agent Skills:

Buyer Agent:

  • Create and manage accounts
  • Create advertising orders
  • Manage campaigns and budgets
  • Search for ad inventory
  • Assign creatives to placements

Seller Agent:

  • List available products
  • Process orders
  • Manage inventory
  • Handle change requests

Key Features:

  • βœ… Agent card auto-generation with skills, examples, security
  • βœ… Multiple transports: JSON-RPC 2.0, HTTP+JSON, MCP tools
  • βœ… AI-powered natural language understanding (OpenAI GPT)
  • βœ… Autonomous and orchestrated modes
  • βœ… Session management and conversation history
  • βœ… Progress tracking and streaming responses

2. OpenDirect MCP

Purpose: Advertising operations following OpenDirect v2.1 specification.

Endpoints: /agenticdirect/mcp/sse

Tools (10 core operations):

  • Organization, Account, Order, Line, Creative management
  • Product search and inventory queries
  • Change requests and messaging

3. Schema-Driven MCP

Purpose: Auto-generate MCP tools from OpenAPI schemas with runtime validation.

Endpoints: /schema/mcp/sse

Tools (33+ auto-generated):

  • CRUD operations for all OpenDirect resources
  • Runtime JSON Schema validation
  • Hot-reload capability without server restart
  • Sandbox testing environment

Schema Management API:

POST /api/schema/register      # Register custom schema
POST /api/schema/fetch-url     # Fetch schema from URL
POST /api/schema/reset         # Reset to default
POST /api/schema/test-tool     # Test tool in sandbox
GET  /api/schema/current       # Get current schema
GET  /api/schema/history       # Get registration history

4. API Testing MCP

Purpose: Test and validate REST APIs with AI analysis.

Endpoints: /mcp/sse

Tools: Register APIs, test endpoints, generate AI-powered analysis and test scenarios.


5. AI Chat

Purpose: Multi-provider AI chat with MCP integration.

Endpoints: /chat

Providers: Anthropic Claude, OpenAI GPT, Google Gemini


πŸ§ͺ Testing

Test Agent Card Discovery

curl http://localhost:3000/a2a/buyer/.well-known/agent-card.json | jq

Expected Response:

{
  "name": "OpenDirect Buyer Agent",
  "version": "1.0.0",
  "skills": [
    {
      "name": "create_account",
      "description": "Create a new buyer account",
      "parameters": { ... }
    }
  ],
  "transports": [
    {
      "type": "jsonrpc",
      "version": "2.0",
      "endpoint": "/a2a/buyer/jsonrpc"
    }
  ]
}

Test JSON-RPC Message

curl -X POST http://localhost:3000/a2a/buyer/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "sendMessage",
    "params": {
      "message": "create an account for Nike"
    },
    "id": 1
  }' | jq

Test MCP Tools

# List available MCP tools
curl http://localhost:3000/schema/mcp/tools | jq '.tools[].name'

# Test MCP health
curl http://localhost:3000/schema/mcp/health
curl http://localhost:3000/agenticdirect/mcp/health
curl http://localhost:3000/mcp/health

Run All Module Tests

./tests/test.sh

πŸ’¬ Common Test Scenarios

Buyer Agent Examples

# Account creation
"create an account for Nike"

# Order creation
"create an order for Adidas with budget $50000"

# Inventory search
"search for video ad inventory"

# Campaign setup
"create a campaign for summer sale targeting 25-34 age group"

Seller Agent Examples

# Product listing
"list available products"

# Inventory search
"search for premium ad space"

# Order processing
"process order for account ABC"

# Change requests
"handle change request for order 12345"

πŸ”Œ Claude Desktop Integration

HTTP Transport (Recommended)

Create claude-desktop-config.json:

{
  "mcpServers": {
    "api-testing-mcp": {
      "url": "http://localhost:3000/mcp/sse",
      "transport": "http"
    },
    "opendirect-mcp": {
      "url": "http://localhost:3000/agenticdirect/mcp/sse",
      "transport": "http"
    },
    "schema-driven-mcp": {
      "url": "http://localhost:3000/schema/mcp/sse",
      "transport": "http"
    }
  }
}

🐳 Docker Deployment

# Build image
docker build -t mcp-config .

# Run container
docker run -p 3000:3000 \
  -e PORT=3000 \
  -e OPENAI_API_KEY=sk-proj-... \
  -e OPENAI_MODEL=gpt-4o-mini \
  mcp-config

☁️ Cloud Run Deployment

# Deploy to Google Cloud Run
./deploy.sh

# Or manually
gcloud run deploy mcp-config \
  --source . \
  --platform managed \
  --region us-east4 \
  --allow-unauthenticated

πŸ› οΈ Troubleshooting

Issue Solution
Port 3000 in use lsof -i :3000 then kill -9 <PID>
Missing API key Verify .env contains OPENAI_API_KEY
Server not responding curl http://localhost:3000/mcp/health
Client connection fails Confirm server running, check CORS
Agent card 404 Check /a2a/buyer/.well-known/agent-card.json
MCP tools not loading Verify schema loaded: GET /api/schema/current

Debug Mode

# Enable debug logging
NODE_ENV=development node server.js

# Check server logs
tail -f /tmp/server-test.log

# Test each module independently
curl http://localhost:3000/mcp/health
curl http://localhost:3000/agenticdirect/mcp/health
curl http://localhost:3000/schema/mcp/health
curl http://localhost:3000/a2a/agents

πŸ“š API Reference

Health Endpoints

GET /mcp/health                     # API Testing MCP
GET /agenticdirect/mcp/health       # OpenDirect MCP
GET /schema/mcp/health              # Schema-Driven MCP
GET /a2a/agents                     # A2A Protocol
GET /api/ai-health                  # AI Chat

Agent Endpoints

GET  /a2a/agents                                         # List agents
GET  /a2a/{agent}/.well-known/agent-card.json           # Agent card
POST /a2a/{agent}/jsonrpc                               # JSON-RPC 2.0
POST /a2a/{agent}/rest                                  # HTTP+JSON
POST /api/a2a/chat                                      # Client chat
GET  /api/a2a/chat/:sessionId/history                   # History
POST /api/a2a/mode                                      # Set mode

MCP Endpoints

POST /mcp/sse                       # API Testing MCP (SSE)
POST /agenticdirect/mcp/sse         # OpenDirect MCP (SSE)
POST /schema/mcp/sse                # Schema-Driven MCP (SSE)

GET  /schema/mcp/tools              # List generated tools
GET  /schema/mcp/resources          # List resources

βœ… Verification Checklist

After setup, verify:

  • βœ… Server running on http://localhost:3000
  • βœ… Test client running on http://localhost:8080
  • βœ… Agent cards accessible:
    • http://localhost:3000/a2a/buyer/.well-known/agent-card.json
    • http://localhost:3000/a2a/seller/.well-known/agent-card.json
  • βœ… MCP endpoints healthy:
    • http://localhost:3000/mcp/health
    • http://localhost:3000/schema/mcp/health
  • βœ… Messages sent/received successfully via web client
  • βœ… Response data displayed as JSON
  • βœ… Multi-step workflows execute sequentially

🎨 Architecture Benefits

  1. Protocol Compliance - Full A2A v0.3.0 support with agent cards
  2. Scalability - Modular design allows independent scaling
  3. Extensibility - Schema-driven tool generation from OpenAPI
  4. Maintainability - Clear separation of concerns across modules
  5. AI-Powered - Natural language understanding with multiple AI providers
  6. Interoperability - Standard MCP protocol for tool execution

πŸš€ Next Steps

  1. Explore Agent Cards - Review buyer and seller capabilities
  2. Test with Web Client - Use http://localhost:8080 for interactive testing
  3. Review MCP Tools - Check /schema/mcp/tools for available operations
  4. Integrate with Claude - Use HTTP transport configuration
  5. Deploy to Production - Use deploy.sh for Cloud Run deployment
  6. Customize Agents - Modify prompts in prompts/buyer/ and prompts/seller/

πŸ“š Resources

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •