@adcp/client 2.3.2 → 2.4.1

package/README.md

@@ -455,6 +455,31 @@ WHERE operation_id = 'delivery_report_agent_x_2025-10'
 ORDER BY sequence_number;
 ```
 
+## CLI Tool
+
+For development and testing, use the included CLI tool to interact with AdCP agents:
+
+```bash
+# List available tools from an agent
+npx @adcp/client mcp https://test-agent.adcontextprotocol.org
+
+# Call a tool with inline JSON payload
+npx @adcp/client a2a https://agent.example.com get_products '{"brief":"Coffee brands"}'
+
+# Use a file for payload
+npx @adcp/client mcp https://agent.example.com create_media_buy @payload.json
+
+# With authentication
+npx @adcp/client mcp https://agent.example.com get_products '{"brief":"..."}' --auth your-token
+
+# JSON output for scripting
+npx @adcp/client mcp https://agent.example.com get_products '{"brief":"..."}' --json
+```
+
+**MCP Endpoint Discovery**: The client automatically discovers MCP endpoints. Just provide any URL - it tests your path first, and if no MCP server responds, it tries adding `/mcp`. Works with root domains, custom paths, anything.
+
+See [docs/CLI.md](docs/CLI.md) for complete CLI documentation including webhook support for async operations.
+
 ## Testing
 
 Try the live testing UI at `http://localhost:8080` when running the server:

package/bin/adcp-async-handler.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+
+/**
+ * Async webhook handler for AdCP CLI
+ *
+ * This module handles async/webhook responses by:
+ * 1. Starting a temporary HTTP server for webhooks
+ * 2. Using ngrok to expose the server publicly (if available)
+ * 3. Waiting for the async response
+ */
+
+const http = require('http');
+const { spawn } = require('child_process');
+const { randomUUID } = require('crypto');
+
+class AsyncWebhookHandler {
+  constructor(options = {}) {
+    this.port = options.port || 0; // 0 = random available port
+    this.timeout = options.timeout || 300000; // 5 minutes default
+    this.debug = options.debug || false;
+    this.server = null;
+    this.ngrokProcess = null;
+    this.webhookUrl = null;
+    this.operationId = randomUUID();
+    this.responsePromise = null;
+    this.responseResolver = null;
+  }
+
+  /**
+   * Check if ngrok is installed
+   */
+  static isNgrokAvailable() {
+    return new Promise((resolve) => {
+      const check = spawn('which', ['ngrok']);
+      check.on('close', (code) => resolve(code === 0));
+    });
+  }
+
+  /**
+   * Start the webhook server and optionally ngrok tunnel
+   * @param {boolean} useNgrok - Whether to use ngrok (default: true)
+   */
+  async start(useNgrok = true) {
+    // Create the promise that will resolve when we get the webhook
+    this.responsePromise = new Promise((resolve, reject) => {
+      this.responseResolver = resolve;
+      this.responseRejector = reject;
+
+      // Set timeout
+      setTimeout(() => {
+        reject(new Error(`Webhook timeout after ${this.timeout}ms`));
+      }, this.timeout);
+    });
+
+    // Start HTTP server
+    await this.startServer();
+
+    if (useNgrok) {
+      // Start ngrok tunnel
+      const ngrokAvailable = await AsyncWebhookHandler.isNgrokAvailable();
+      if (ngrokAvailable) {
+        await this.startNgrok();
+      } else {
+        throw new Error('ngrok is not installed. Install it with: brew install ngrok (Mac) or download from https://ngrok.com');
+      }
+    } else {
+      // Use local URL (for local agents)
+      this.webhookUrl = `http://localhost:${this.port}`;
+
+      if (this.debug) {
+        console.error(`✅ Local webhook server ready: ${this.webhookUrl}`);
+      }
+    }
+
+    return this.webhookUrl;
+  }
+
+  /**
+   * Start the HTTP server
+   */
+  startServer() {
+    return new Promise((resolve, reject) => {
+      this.server = http.createServer((req, res) => {
+        if (req.method === 'POST') {
+          let body = '';
+
+          req.on('data', chunk => {
+            body += chunk.toString();
+          });
+
+          req.on('end', () => {
+            try {
+              const payload = JSON.parse(body);
+
+              if (this.debug) {
+                console.error('\n🎣 Webhook received:');
+                console.error(JSON.stringify(payload, null, 2));
+              }
+
+              // Send 202 Accepted response
+              res.writeHead(202, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify({ status: 'accepted' }));
+
+              // Resolve the promise with the webhook payload
+              if (this.responseResolver) {
+                this.responseResolver(payload);
+              }
+            } catch (error) {
+              if (this.debug) {
+                console.error('Error parsing webhook:', error);
+              }
+              res.writeHead(400, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify({ error: 'Invalid JSON' }));
+            }
+          });
+        } else {
+          // Health check endpoint
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ status: 'ready', operation_id: this.operationId }));
+        }
+      });
+
+      this.server.listen(this.port, () => {
+        const address = this.server.address();
+        this.port = address.port;
+
+        if (this.debug) {
+          console.error(`✅ Webhook server listening on port ${this.port}`);
+        }
+
+        resolve();
+      });
+
+      this.server.on('error', reject);
+    });
+  }
+
+  /**
+   * Start ngrok tunnel
+   */
+  startNgrok() {
+    return new Promise((resolve, reject) => {
+      if (this.debug) {
+        console.error(`🚇 Starting ngrok tunnel for port ${this.port}...`);
+      }
+
+      // Start ngrok with JSON output for easier parsing
+      this.ngrokProcess = spawn('ngrok', ['http', String(this.port), '--log=stdout', '--log-format=json']);
+
+      let ngrokStarted = false;
+      let buffer = '';
+
+      this.ngrokProcess.stdout.on('data', (data) => {
+        buffer += data.toString();
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || ''; // Keep incomplete line in buffer
+
+        for (const line of lines) {
+          if (!line.trim()) continue;
+
+          try {
+            const parsed = JSON.parse(line);
+
+            // Look for the tunnel URL in ngrok's JSON output
+            if (parsed.url && parsed.url.startsWith('https://')) {
+              this.webhookUrl = parsed.url;
+              ngrokStarted = true;
+
+              if (this.debug) {
+                console.error(`✅ ngrok tunnel ready: ${this.webhookUrl}`);
+              }
+
+              resolve();
+            }
+          } catch (e) {
+            // Not JSON, might be plain text output
+            // Try to extract URL from plain text
+            const urlMatch = line.match(/https:\/\/[a-z0-9-]+\.ngrok(?:-free)?\.(?:app|io)/);
+            if (urlMatch && !ngrokStarted) {
+              this.webhookUrl = urlMatch[0];
+              ngrokStarted = true;
+
+              if (this.debug) {
+                console.error(`✅ ngrok tunnel ready: ${this.webhookUrl}`);
+              }
+
+              resolve();
+            }
+          }
+        }
+      });
+
+      this.ngrokProcess.stderr.on('data', (data) => {
+        if (this.debug) {
+          console.error('ngrok stderr:', data.toString());
+        }
+      });
+
+      this.ngrokProcess.on('error', (error) => {
+        reject(new Error(`Failed to start ngrok: ${error.message}`));
+      });
+
+      this.ngrokProcess.on('close', (code) => {
+        if (!ngrokStarted && code !== 0) {
+          reject(new Error(`ngrok exited with code ${code}`));
+        }
+      });
+
+      // Timeout for ngrok startup
+      setTimeout(() => {
+        if (!ngrokStarted) {
+          reject(new Error('ngrok failed to start within 10 seconds'));
+        }
+      }, 10000);
+    });
+  }
+
+  /**
+   * Wait for the webhook response
+   */
+  async waitForResponse() {
+    if (this.debug) {
+      console.error('\n⏳ Waiting for async response...');
+    }
+
+    const startTime = Date.now();
+    const result = await this.responsePromise;
+    const duration = Date.now() - startTime;
+
+    if (this.debug) {
+      console.error(`✅ Response received after ${(duration / 1000).toFixed(1)}s\n`);
+    }
+
+    return result;
+  }
+
+  /**
+   * Clean up resources
+   */
+  async cleanup() {
+    if (this.debug) {
+      console.error('🧹 Cleaning up...');
+    }
+
+    // Close HTTP server
+    if (this.server) {
+      await new Promise((resolve) => {
+        this.server.close(() => resolve());
+      });
+    }
+
+    // Kill ngrok process
+    if (this.ngrokProcess) {
+      this.ngrokProcess.kill();
+    }
+
+    if (this.debug) {
+      console.error('✅ Cleanup complete');
+    }
+  }
+
+  /**
+   * Get the webhook URL with operation ID
+   */
+  getWebhookUrl() {
+    if (!this.webhookUrl) {
+      throw new Error('Webhook server not started');
+    }
+    return `${this.webhookUrl}?operation_id=${this.operationId}`;
+  }
+}
+
+module.exports = { AsyncWebhookHandler };

package/bin/adcp.js

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+
+/**
+ * AdCP CLI Tool
+ *
+ * Simple command-line utility to call AdCP agents directly
+ *
+ * Usage:
+ *   adcp <protocol> <agent-url> <tool-name> [payload-json] [--auth token]
+ *
+ * Examples:
+ *   adcp mcp https://agent.example.com/mcp get_products '{"brief":"coffee brands"}'
+ *   adcp a2a https://agent.example.com list_creative_formats '{}' --auth your_token_here
+ *   adcp mcp https://agent.example.com/mcp create_media_buy @payload.json --auth $AGENT_TOKEN
+ */
+
+const { ADCPClient } = require('../dist/lib/index.js');
+const { readFileSync } = require('fs');
+const { AsyncWebhookHandler } = require('./adcp-async-handler.js');
+
+/**
+ * Display agent info - just calls library method
+ */
+async function displayAgentInfo(agentConfig, jsonOutput) {
+  const client = new ADCPClient(agentConfig);
+  const info = await client.getAgentInfo();
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(info, null, 2));
+  } else {
+    console.log(`\n📋 Agent Information\n`);
+    console.log(`Name: ${info.name}`);
+    if (info.description) {
+      console.log(`Description: ${info.description}`);
+    }
+    console.log(`Protocol: ${info.protocol.toUpperCase()}`);
+    console.log(`URL: ${info.url}`);
+    console.log(`\nAvailable Tools (${info.tools.length}):\n`);
+
+    if (info.tools.length === 0) {
+      console.log('No tools found.');
+    } else {
+      info.tools.forEach((tool, i) => {
+        console.log(`${i + 1}. ${tool.name}`);
+        if (tool.description) {
+          console.log(`   ${tool.description}`);
+        }
+        if (tool.parameters && tool.parameters.length > 0) {
+          console.log(`   Parameters: ${tool.parameters.join(', ')}`);
+        }
+        console.log('');
+      });
+    }
+  }
+}
+
+function printUsage() {
+  console.log(`
+AdCP CLI Tool - Direct Agent Communication
+
+USAGE:
+  adcp <protocol> <agent-url> [tool-name] [payload] [options]
+
+ARGUMENTS:
+  protocol      Protocol to use: 'mcp' or 'a2a'
+  agent-url     Full URL to the agent endpoint
+  tool-name     Name of the tool to call (optional - omit to list available tools)
+  payload       JSON payload for the tool (default: {})
+                - Can be inline JSON: '{"brief":"text"}'
+                - Can be file path: @payload.json
+                - Can be stdin: -
+
+OPTIONS:
+  --auth TOKEN    Authentication token for the agent
+  --wait          Wait for async/webhook responses (requires ngrok or --local)
+  --local         Use local webhook without ngrok (for local agents only)
+  --timeout MS    Webhook timeout in milliseconds (default: 300000 = 5min)
+  --help, -h      Show this help message
+  --json          Output raw JSON response (default: pretty print)
+  --debug         Show debug information
+
+EXAMPLES:
+  # List available tools
+  adcp mcp https://agent.example.com/mcp
+  adcp a2a https://creative.adcontextprotocol.org
+
+  # Simple product discovery
+  adcp mcp https://agent.example.com/mcp get_products '{"brief":"coffee brands"}'
+
+  # With authentication
+  adcp a2a https://agent.example.com list_creative_formats '{}' --auth your_token
+
+  # Wait for async response (requires ngrok)
+  adcp mcp https://agent.example.com/mcp create_media_buy @payload.json --auth $TOKEN --wait
+
+  # Wait for async response from local agent (no ngrok needed)
+  adcp mcp http://localhost:3000/mcp create_media_buy @payload.json --wait --local
+
+  # From file
+  adcp mcp https://agent.example.com/mcp create_media_buy @payload.json --auth $TOKEN
+
+  # From stdin
+  echo '{"brief":"travel"}' | adcp mcp https://agent.example.com/mcp get_products -
+
+ENVIRONMENT VARIABLES:
+  ADCP_AUTH_TOKEN    Default authentication token (overridden by --auth)
+  ADCP_DEBUG         Enable debug mode (set to 'true')
+
+EXIT CODES:
+  0   Success
+  1   General error
+  2   Invalid arguments
+  3   Agent error
+`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Handle help
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    printUsage();
+    process.exit(0);
+  }
+
+  // Parse arguments
+  if (args.length < 2) {
+    console.error('ERROR: Missing required arguments\n');
+    printUsage();
+    process.exit(2);
+  }
+
+  // Parse options first
+  const authIndex = args.indexOf('--auth');
+  const authToken = authIndex !== -1 ? args[authIndex + 1] : process.env.ADCP_AUTH_TOKEN;
+  const jsonOutput = args.includes('--json');
+  const debug = args.includes('--debug') || process.env.ADCP_DEBUG === 'true';
+  const waitForAsync = args.includes('--wait');
+  const useLocalWebhook = args.includes('--local');
+  const timeoutIndex = args.indexOf('--timeout');
+  const timeout = timeoutIndex !== -1 ? parseInt(args[timeoutIndex + 1]) : 300000;
+
+  // Filter out flag arguments to find positional arguments
+  const positionalArgs = args.filter(arg =>
+    !arg.startsWith('--') &&
+    arg !== authToken && // Don't include the auth token value
+    arg !== (timeoutIndex !== -1 ? args[timeoutIndex + 1] : null) // Don't include timeout value
+  );
+
+  const protocol = positionalArgs[0];
+  const agentUrl = positionalArgs[1];
+  const toolName = positionalArgs[2]; // Optional - if not provided, list tools
+  let payloadArg = positionalArgs[3] || '{}';
+
+  // Validate protocol
+  if (protocol !== 'mcp' && protocol !== 'a2a') {
+    console.error(`ERROR: Invalid protocol '${protocol}'. Must be 'mcp' or 'a2a'\n`);
+    printUsage();
+    process.exit(2);
+  }
+
+  // Parse payload
+  let payload;
+  try {
+    if (payloadArg === '-') {
+      // Read from stdin
+      const stdin = readFileSync(0, 'utf-8');
+      payload = JSON.parse(stdin);
+    } else if (payloadArg.startsWith('@')) {
+      // Read from file
+      const filePath = payloadArg.substring(1);
+      const fileContent = readFileSync(filePath, 'utf-8');
+      payload = JSON.parse(fileContent);
+    } else {
+      // Parse inline JSON
+      payload = JSON.parse(payloadArg);
+    }
+  } catch (error) {
+    console.error(`ERROR: Invalid JSON payload: ${error.message}\n`);
+    process.exit(2);
+  }
+
+  if (debug) {
+    console.error('DEBUG: Configuration');
+    console.error(`  Protocol: ${protocol}`);
+    console.error(`  Agent URL: ${agentUrl}`);
+    console.error(`  Tool: ${toolName}`);
+    console.error(`  Auth: ${authToken ? 'provided' : 'none'}`);
+    console.error(`  Payload: ${JSON.stringify(payload, null, 2)}`);
+    console.error('');
+  }
+
+  // Create agent config
+  const agentConfig = {
+    id: 'cli-agent',
+    name: 'CLI Agent',
+    agent_uri: agentUrl,
+    protocol: protocol,
+    ...(authToken && { auth_token_env: authToken })
+  };
+
+  try {
+    // If no tool name provided, display agent info
+    if (!toolName) {
+      if (debug) {
+        console.error('DEBUG: No tool specified, displaying agent info...\n');
+      }
+
+      await displayAgentInfo(agentConfig, jsonOutput);
+      process.exit(0);
+    }
+
+    // Set up webhook handler if --wait flag is used
+    let webhookHandler = null;
+    let webhookUrl = null;
+
+    if (waitForAsync) {
+      const useNgrok = !useLocalWebhook;
+
+      // Check if ngrok is available (unless using --local)
+      if (useNgrok) {
+        const ngrokAvailable = await AsyncWebhookHandler.isNgrokAvailable();
+        if (!ngrokAvailable) {
+          console.error('\n❌ ERROR: --wait flag requires ngrok to be installed\n');
+          console.error('Install ngrok:');
+          console.error('  Mac:     brew install ngrok');
+          console.error('  Windows: choco install ngrok');
+          console.error('  Linux:   Download from https://ngrok.com/download');
+          console.error('\nOr use --local flag for local agents (e.g., http://localhost:3000)\n');
+          process.exit(2);
+        }
+      }
+
+      if (debug) {
+        console.error(`DEBUG: Setting up ${useNgrok ? 'ngrok' : 'local'} webhook handler...\n`);
+      }
+
+      webhookHandler = new AsyncWebhookHandler({
+        timeout: timeout,
+        debug: debug
+      });
+
+      try {
+        webhookUrl = await webhookHandler.start(useNgrok);
+
+        if (!jsonOutput) {
+          console.log(`\n🌐 ${useNgrok ? 'Public webhook' : 'Local webhook'} endpoint ready`);
+          console.log(`   URL: ${webhookUrl}`);
+          console.log(`   Timeout: ${timeout / 1000}s`);
+          if (useLocalWebhook) {
+            console.log(`   ⚠️  Local mode: Agent must be accessible at localhost`);
+          }
+          console.log('');
+        }
+      } catch (error) {
+        console.error('\n❌ ERROR: Failed to start webhook handler\n');
+        console.error(error.message);
+        if (debug) {
+          console.error('\nStack trace:');
+          console.error(error.stack);
+        }
+        process.exit(1);
+      }
+    }
+
+    // Create ADCP client with optional webhook configuration
+    const client = new ADCPClient(agentConfig, {
+      debug: debug,
+      ...(webhookUrl && {
+        webhookUrlTemplate: webhookUrl,
+        webhookSecret: 'cli-webhook-secret'
+      })
+    });
+
+    if (debug) {
+      console.error('DEBUG: Executing task...\n');
+    }
+
+    // Execute the task
+    const result = await client.executeTask(toolName, payload);
+
+    // If waiting for async response, handle webhook
+    if (waitForAsync && webhookHandler) {
+      if (result.status === 'submitted' || result.status === 'working') {
+        if (!jsonOutput) {
+          console.log('📤 Task submitted, waiting for async response...');
+        }
+
+        try {
+          const webhookResponse = await webhookHandler.waitForResponse();
+
+          // Clean up webhook handler
+          await webhookHandler.cleanup();
+
+          // Output webhook response
+          if (jsonOutput) {
+            console.log(JSON.stringify(webhookResponse.result || webhookResponse, null, 2));
+          } else {
+            console.log('\n✅ ASYNC RESPONSE RECEIVED\n');
+            console.log('Response:');
+            console.log(JSON.stringify(webhookResponse.result || webhookResponse, null, 2));
+          }
+
+          process.exit(0);
+        } catch (error) {
+          await webhookHandler.cleanup();
+          console.error('\n❌ WEBHOOK TIMEOUT\n');
+          console.error(error.message);
+          process.exit(3);
+        }
+      } else {
+        // Task completed synchronously, clean up webhook
+        await webhookHandler.cleanup();
+      }
+    }
+
+    // Handle result
+    if (result.success) {
+      if (jsonOutput) {
+        // Raw JSON output
+        console.log(JSON.stringify(result.data, null, 2));
+      } else {
+        // Pretty output
+        console.log('\n✅ SUCCESS\n');
+        console.log('Response:');
+        console.log(JSON.stringify(result.data, null, 2));
+        console.log('');
+        console.log(`Response Time: ${result.metadata.responseTimeMs}ms`);
+        console.log(`Task ID: ${result.metadata.taskId}`);
+      }
+      process.exit(0);
+    } else {
+      console.error('\n❌ TASK FAILED\n');
+      console.error(`Error: ${result.error || 'Unknown error'}`);
+      if (result.metadata?.clarificationRounds) {
+        console.error(`Clarifications: ${result.metadata.clarificationRounds}`);
+      }
+      if (debug && result.metadata) {
+        console.error('\nMetadata:');
+        console.error(JSON.stringify(result.metadata, null, 2));
+      }
+      process.exit(3);
+    }
+  } catch (error) {
+    console.error('\n❌ ERROR\n');
+    console.error(error.message);
+    if (debug) {
+      console.error('\nStack trace:');
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+main().catch(error => {
+  console.error('FATAL ERROR:', error.message);
+  process.exit(1);
+});