mpx-api 1.0.2 → 1.2.0

package/README.md

@@ -182,6 +182,134 @@ mpx-api history -n 50
 
 Cookies are automatically saved and sent with subsequent requests. Cookie jar is stored at `~/.mpx-api/cookies.json`.
 
+## AI Agent Usage 🤖
+
+**mpx-api is AI-native!** Every command supports structured JSON output, schema discovery, and MCP (Model Context Protocol) integration for seamless AI agent automation.
+
+### JSON Output
+
+Add `--json` to any command for machine-readable output:
+
+```bash
+# HTTP request with JSON output
+mpx-api get https://api.github.com/users/octocat --json
+
+# Output structure
+{
+  "request": {
+    "method": "GET",
+    "url": "https://api.github.com/users/octocat",
+    "headers": {},
+    "body": null
+  },
+  "response": {
+    "status": 200,
+    "statusText": "OK",
+    "headers": { "content-type": "application/json" },
+    "body": { "login": "octocat", ... },
+    "rawBody": "...",
+    "responseTime": 145,
+    "size": 1234
+  }
+}
+```
+
+### Schema Discovery
+
+AI agents can discover all available commands, flags, and output formats:
+
+```bash
+mpx-api --schema
+```
+
+Returns a complete JSON schema describing:
+- All commands and subcommands
+- Available flags and their types
+- Input/output schemas
+- Usage examples
+- Exit codes
+
+Perfect for dynamic tool discovery by AI assistants!
+
+### MCP Server Mode
+
+Start mpx-api as an MCP (Model Context Protocol) server for AI agent integration:
+
+```bash
+mpx-api mcp
+```
+
+Add to your MCP client configuration (e.g., Claude Desktop, Cline):
+
+```json
+{
+  "mcpServers": {
+    "mpx-api": {
+      "command": "npx",
+      "args": ["mpx-api", "mcp"]
+    }
+  }
+}
+```
+
+**Available MCP tools:**
+
+- `http_request` - Send HTTP requests with full control over method, headers, body
+- `get_schema` - Get the complete tool schema for dynamic discovery
+
+**Example MCP usage:**
+
+AI agents can now make API requests on your behalf:
+- "Make a GET request to https://api.github.com/users/octocat"
+- "POST to https://api.example.com/users with JSON body {name: 'Alice'}"
+- "What commands does mpx-api support?" (via get_schema)
+
+### Quiet Mode
+
+Suppress non-essential output with `--quiet` or `-q`:
+
+```bash
+mpx-api get https://api.example.com/data --quiet --json
+```
+
+Perfect for scripting and automation where you only want the result data.
+
+### Composability
+
+All commands are designed for Unix-style composition:
+
+```bash
+# Pipe output to jq
+mpx-api get https://api.github.com/users/octocat --json | jq '.response.body.login'
+
+# Use in scripts
+STATUS=$(mpx-api get https://api.example.com/health --json | jq -r '.response.status')
+if [ "$STATUS" -eq 200 ]; then
+  echo "API is healthy"
+fi
+
+# Batch processing
+cat urls.txt | while read url; do
+  mpx-api get "$url" --json >> results.jsonl
+done
+```
+
+### Exit Codes
+
+Predictable exit codes for automation:
+
+- `0` - Success (2xx or 3xx HTTP status)
+- `1` - Request failed or 4xx/5xx HTTP status
+
+```bash
+# Check if request succeeded
+if mpx-api get https://api.example.com/endpoint --quiet; then
+  echo "Success!"
+else
+  echo "Request failed"
+fi
+```
+
 ## Pro Features 💎
 
 Upgrade to **mpx-api Pro** ($12/mo) for advanced features:

package/bin/mpx-api.js

@@ -15,6 +15,10 @@ import { registerHistoryCommand } from '../src/commands/history.js';
 import { registerLoadCommand } from '../src/commands/load.js';
 import { registerDocsCommand } from '../src/commands/docs.js';
 
+// AI-native features
+import { getSchema } from '../src/schema.js';
+import { startMCPServer } from '../src/mcp.js';
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
@@ -22,10 +26,20 @@ const pkg = JSON.parse(
   readFileSync(join(__dirname, '../package.json'), 'utf8')
 );
 
+// Handle --schema flag early (before commander parsing)
+if (process.argv.includes('--schema')) {
+  console.log(JSON.stringify(getSchema(), null, 2));
+  process.exit(0);
+}
+
 program
   .name('mpx-api')
   .description('Developer-first API testing, mocking, and documentation CLI')
-  .version(pkg.version);
+  .version(pkg.version)
+  .enablePositionalOptions()
+  .passThroughOptions()
+  .option('-o, --output <format>', 'Output format: json for structured JSON (machine-readable)')
+  .option('-q, --quiet', 'Suppress non-essential output');
 
 // Register HTTP method commands (get, post, put, patch, delete, head, options)
 registerRequestCommands(program);
@@ -49,4 +63,17 @@ registerHistoryCommand(program);
 registerLoadCommand(program);
 registerDocsCommand(program);
 
+// MCP subcommand
+program
+  .command('mcp')
+  .description('Start MCP (Model Context Protocol) stdio server')
+  .action(async () => {
+    try {
+      await startMCPServer();
+    } catch (err) {
+      console.error(JSON.stringify({ error: err.message, code: 'ERR_MCP_START' }));
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mpx-api",
-  "version": "1.0.2",
-  "description": "Developer-first API testing, mocking, and documentation CLI",
+  "version": "1.2.0",
+  "description": "Developer-first API testing, mocking, and documentation CLI with AI-native features (JSON output, MCP server)",
   "main": "src/index.js",
   "bin": {
     "mpx-api": "bin/mpx-api.js"
@@ -16,7 +16,11 @@
     "postman",
     "httpie",
     "openapi",
-    "swagger"
+    "swagger",
+    "mcp",
+    "ai-native",
+    "model-context-protocol",
+    "automation"
   ],
   "author": "Mesaplex <support@mesaplex.com>",
   "license": "MIT",
@@ -33,12 +37,13 @@
   },
   "type": "module",
   "scripts": {
-    "test": "node --test test/**/*.test.js",
+    "test": "node --test test/*.test.js",
     "test:watch": "node --test --watch test/**/*.test.js",
     "lint": "echo 'TODO: Add eslint'",
     "prepublishOnly": "npm test"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "yaml": "^2.3.4",

package/src/commands/collection.js

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs';
 import { parse, stringify } from 'yaml';
 import { ensureLocalDir } from '../lib/config.js';
-import { formatSuccess, formatError, formatInfo } from '../lib/output.js';
+import { formatSuccess, formatError, formatInfo, formatWarning } from '../lib/output.js';
 import { runCollection } from '../lib/collection-runner.js';
 import { formatTestResults } from '../lib/output.js';
 import { join } from 'path';
@@ -95,7 +95,8 @@ export function registerCollectionCommands(program) {
     .description('Run a collection')
     .option('-e, --env <name>', 'Environment to use')
     .option('--base-url <url>', 'Override base URL')
-    .action(async (file, options) => {
+    .option('--json', 'Output results as JSON')
+    .action(async (file, options, command) => {
       try {
         const collectionPath = file || join('.mpx-api', 'collection.yaml');
         
@@ -123,9 +124,17 @@ export function registerCollectionCommands(program) {
         
         const results = await runCollection(collection, { env, baseUrl });
         
-        const allPassed = formatTestResults(results);
+        const globalOpts = command.optsWithGlobals();
+        const jsonOutput = options.json || globalOpts.output === 'json';
         
-        process.exit(allPassed ? 0 : 1);
+        if (jsonOutput) {
+          console.log(JSON.stringify(results, null, 2));
+          const allPassed = results.every(r => r.passed);
+          process.exit(allPassed ? 0 : 1);
+        } else {
+          const allPassed = formatTestResults(results);
+          process.exit(allPassed ? 0 : 1);
+        }
       } catch (err) {
         formatError(err);
         process.exit(1);
@@ -170,6 +179,4 @@ export function registerCollectionCommands(program) {
     });
 }
 
-function formatWarning(message) {
-  console.log(chalk.yellow('⚠'), message);
-}
+// formatWarning imported from output.js

package/src/commands/request.js

@@ -17,8 +17,14 @@ export function registerRequestCommands(program) {
       .option('--no-follow', 'Do not follow redirects')
       .option('--no-verify', 'Skip SSL certificate verification')
       .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
-      .action(async (url, options) => {
+      .option('-o, --output <format>', 'Output format (json)')
+      .action(async (url, options, command) => {
         try {
+          // Get global options
+          const globalOpts = command.optsWithGlobals();
+          const jsonOutput = options.output === 'json' || globalOpts.output === 'json';
+          const quiet = options.quiet || globalOpts.quiet || false;
+
           const client = new HttpClient({
             followRedirects: options.follow,
             verifySsl: options.verify,
@@ -34,7 +40,11 @@ export function registerRequestCommands(program) {
             try {
               requestOptions.json = JSON.parse(options.json);
             } catch (err) {
-              formatError(new Error(`Invalid JSON: ${err.message}`));
+              if (jsonOutput) {
+                console.log(JSON.stringify({ error: `Invalid JSON: ${err.message}` }));
+              } else {
+                formatError(new Error(`Invalid JSON: ${err.message}`));
+              }
               process.exit(1);
             }
           } else if (options.data) {
@@ -57,7 +67,14 @@ export function registerRequestCommands(program) {
           // Format and display response
           formatResponse(response, {
             verbose: options.verbose,
-            quiet: options.quiet,
+            quiet: quiet,
+            jsonOutput: jsonOutput,
+            request: {
+              method: method.toUpperCase(),
+              url,
+              headers: requestOptions.headers,
+              body: requestOptions.json || requestOptions.body,
+            }
           });
 
           // Exit with non-zero code for 4xx/5xx errors
@@ -65,7 +82,12 @@ export function registerRequestCommands(program) {
             process.exit(1);
           }
         } catch (err) {
-          formatError(err);
+          const globalOpts = command.optsWithGlobals();
+          if (options.output === 'json' || globalOpts.output === 'json') {
+            console.log(JSON.stringify({ error: err.message, code: err.code || 'ERR_REQUEST' }));
+          } else {
+            formatError(err);
+          }
           process.exit(1);
         }
       });

package/src/lib/assertion.js

@@ -1,3 +1,5 @@
+import { getNestedValue } from './utils.js';
+
 // Assertion engine for testing
 
 export function runAssertions(response, assertions) {
@@ -75,27 +77,7 @@ export function runAssertions(response, assertions) {
   return results;
 }
 
-function getNestedValue(obj, path) {
-  const parts = path.split('.');
-  let current = obj;
-  
-  for (const part of parts) {
-    if (current === null || current === undefined) return undefined;
-    
-    // Handle array indexing
-    const arrayMatch = part.match(/^(.+?)\[(\d+)\]$/);
-    if (arrayMatch) {
-      const [, key, index] = arrayMatch;
-      current = current[key];
-      if (!Array.isArray(current)) return undefined;
-      current = current[parseInt(index)];
-    } else {
-      current = current[part];
-    }
-  }
-  
-  return current;
-}
+// getNestedValue imported from utils.js
 
 function evaluateOperators(actual, expected) {
   for (const [op, value] of Object.entries(expected)) {

package/src/lib/http-client.js

@@ -1,8 +1,14 @@
 import { request } from 'undici';
 import { CookieJar } from 'tough-cookie';
 import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
 import { getCookieJarPath } from './config.js';
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkgVersion = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8')).version;
+
 export class HttpClient {
   constructor(options = {}) {
     this.followRedirects = options.followRedirects !== false;
@@ -40,7 +46,7 @@ export class HttpClient {
     
     // Set default User-Agent, allow override via options.headers
     const defaultHeaders = {
-      'user-agent': 'mpx-api/1.0.1',
+      'user-agent': `mpx-api/${pkgVersion}`,
     };
     
     // Merge headers, with user headers taking precedence
@@ -52,7 +58,18 @@ export class HttpClient {
       body: options.body,
     };
     
-    // Note: undici follows redirects by default, maxRedirections removed in newer versions
+    // Handle redirects
+    if (!this.followRedirects) {
+      requestOptions.maxRedirections = 0;
+    }
+
+    // Handle timeout
+    if (this.timeout) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      requestOptions.signal = controller.signal;
+      requestOptions._timeoutId = timeoutId;
+    }
 
     // Add cookies to request
     const cookies = await this.cookieJar.getCookies(url);
@@ -72,7 +89,10 @@ export class HttpClient {
     }
 
     try {
+      const timeoutId = requestOptions._timeoutId;
+      delete requestOptions._timeoutId;
       const response = await request(url, requestOptions);
+      if (timeoutId) clearTimeout(timeoutId);
       
       // Store cookies from response
       const setCookieHeaders = response.headers['set-cookie'];
@@ -119,7 +139,9 @@ export class HttpClient {
       };
     } catch (err) {
       // Handle network errors gracefully
-      if (err.code === 'ENOTFOUND') {
+      if (err.name === 'AbortError' || err.code === 'UND_ERR_ABORTED') {
+        throw new Error(`Request timeout after ${this.timeout}ms`);
+      } else if (err.code === 'ENOTFOUND') {
         throw new Error(`DNS lookup failed for ${url}`);
       } else if (err.code === 'ECONNREFUSED') {
         throw new Error(`Connection refused to ${url}`);

package/src/lib/output.js

@@ -3,8 +3,34 @@ import { highlight } from 'cli-highlight';
 
 const MAX_BODY_SIZE = 50 * 1024; // 50KB max for terminal display
 
+export function formatResponseJSON(response, request = {}) {
+  return JSON.stringify({
+    request: {
+      method: request.method || response.method,
+      url: request.url || response.url,
+      headers: request.headers || {},
+      body: request.body || null
+    },
+    response: {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+      body: response.body,
+      rawBody: response.rawBody,
+      responseTime: response.responseTime,
+      size: response.size
+    }
+  }, null, 2);
+}
+
 export function formatResponse(response, options = {}) {
-  const { verbose = false, quiet = false } = options;
+  const { verbose = false, quiet = false, jsonOutput = false } = options;
+  
+  // Handle JSON output mode
+  if (jsonOutput) {
+    console.log(formatResponseJSON(response, options.request || {}));
+    return;
+  }
   
   if (quiet) {
     // Only output body

package/src/lib/template.js

@@ -1,3 +1,5 @@
+import { getNestedValue } from './utils.js';
+
 // Template variable interpolation
 // Supports: {{varName}}, {{env.VAR}}, {{request-name.response.body.field}}
 
@@ -39,25 +41,4 @@ export function interpolateObject(obj, context = {}) {
   return obj;
 }
 
-function getNestedValue(obj, path) {
-  // Handle array indexing: users[0].name
-  const parts = path.split('.');
-  let current = obj;
-  
-  for (const part of parts) {
-    if (!current) return undefined;
-    
-    // Check for array indexing
-    const arrayMatch = part.match(/^(.+?)\[(\d+)\]$/);
-    if (arrayMatch) {
-      const [, key, index] = arrayMatch;
-      current = current[key];
-      if (!Array.isArray(current)) return undefined;
-      current = current[parseInt(index)];
-    } else {
-      current = current[part];
-    }
-  }
-  
-  return current;
-}
+// getNestedValue imported from utils.js

package/src/lib/utils.js

@@ -0,0 +1,25 @@
+/**
+ * Get a nested value from an object using dot notation.
+ * Supports array indexing: users[0].name
+ */
+export function getNestedValue(obj, path) {
+  const parts = path.split('.');
+  let current = obj;
+  
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    
+    // Handle array indexing
+    const arrayMatch = part.match(/^(.+?)\[(\d+)\]$/);
+    if (arrayMatch) {
+      const [, key, index] = arrayMatch;
+      current = current[key];
+      if (!Array.isArray(current)) return undefined;
+      current = current[parseInt(index)];
+    } else {
+      current = current[part];
+    }
+  }
+  
+  return current;
+}

package/src/mcp.js

@@ -0,0 +1,180 @@
+/**
+ * MCP (Model Context Protocol) Server
+ * 
+ * Exposes mpx-api capabilities as MCP tools for AI agent integration.
+ * Runs over stdio transport.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { HttpClient } from './lib/http-client.js';
+import { getSchema } from './schema.js';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+export async function startMCPServer() {
+  const server = new Server(
+    { name: 'mpx-api', version: pkg.version },
+    { capabilities: { tools: {} } }
+  );
+
+  // List available tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: 'http_request',
+          description: 'Send an HTTP request (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS). Returns structured response with status, headers, body, and timing.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              method: {
+                type: 'string',
+                enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
+                description: 'HTTP method'
+              },
+              url: {
+                type: 'string',
+                description: 'Target URL'
+              },
+              headers: {
+                type: 'object',
+                description: 'Request headers as key-value pairs',
+                additionalProperties: { type: 'string' }
+              },
+              json: {
+                type: 'object',
+                description: 'JSON body (automatically sets Content-Type: application/json)'
+              },
+              body: {
+                type: 'string',
+                description: 'Raw request body (use either json or body, not both)'
+              },
+              followRedirects: {
+                type: 'boolean',
+                default: true,
+                description: 'Follow HTTP redirects'
+              },
+              verifySsl: {
+                type: 'boolean',
+                default: true,
+                description: 'Verify SSL certificates'
+              },
+              timeout: {
+                type: 'number',
+                default: 30000,
+                description: 'Request timeout in milliseconds'
+              }
+            },
+            required: ['method', 'url']
+          }
+        },
+        {
+          name: 'get_schema',
+          description: 'Get the full JSON schema describing all mpx-api commands, flags, and output formats.',
+          inputSchema: {
+            type: 'object',
+            properties: {}
+          }
+        }
+      ]
+    };
+  });
+
+  // Handle tool calls
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      switch (name) {
+        case 'http_request': {
+          const client = new HttpClient({
+            followRedirects: args.followRedirects !== false,
+            verifySsl: args.verifySsl !== false,
+            timeout: args.timeout || 30000,
+          });
+
+          const requestOptions = {
+            headers: args.headers || {},
+          };
+
+          // Handle JSON or raw body
+          if (args.json) {
+            requestOptions.json = args.json;
+          } else if (args.body) {
+            requestOptions.body = args.body;
+          }
+
+          const method = (args.method || 'GET').toLowerCase();
+          const response = await client.request(method, args.url, requestOptions);
+
+          // Return structured response
+          const result = {
+            request: {
+              method: method.toUpperCase(),
+              url: args.url,
+              headers: requestOptions.headers,
+              body: args.json || args.body || null
+            },
+            response: {
+              status: response.status,
+              statusText: response.statusText,
+              headers: response.headers,
+              body: response.body,
+              rawBody: response.rawBody,
+              responseTime: response.responseTime,
+              size: response.size
+            }
+          };
+
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(result, null, 2)
+            }]
+          };
+        }
+
+        case 'get_schema': {
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(getSchema(), null, 2)
+            }]
+          };
+        }
+
+        default:
+          return {
+            content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+            isError: true
+          };
+      }
+    } catch (err) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ 
+            error: err.message,
+            code: err.code || 'ERR_REQUEST',
+            stack: err.stack
+          }, null, 2)
+        }],
+        isError: true
+      };
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/schema.js

@@ -0,0 +1,294 @@
+/**
+ * Schema Module
+ * 
+ * Returns a machine-readable JSON schema describing all commands,
+ * flags, inputs, and outputs for AI agent discovery.
+ */
+
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+export function getSchema() {
+  return {
+    tool: 'mpx-api',
+    version: pkg.version,
+    description: pkg.description,
+    homepage: pkg.homepage,
+    commands: {
+      'http-methods': {
+        description: 'Send HTTP requests (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)',
+        usage: 'mpx-api <method> <url> [options]',
+        methods: ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'],
+        arguments: {
+          url: {
+            type: 'string',
+            required: true,
+            description: 'Target URL for the HTTP request'
+          }
+        },
+        flags: {
+          '-H, --header': {
+            type: 'array',
+            description: 'Add request headers (format: "key:value" or "key: value")',
+            repeatable: true
+          },
+          '-j, --json': {
+            type: 'string',
+            description: 'Send JSON data (automatically sets Content-Type: application/json)'
+          },
+          '-d, --data': {
+            type: 'string',
+            description: 'Send raw request body'
+          },
+          '-v, --verbose': {
+            type: 'boolean',
+            default: false,
+            description: 'Show response headers in output'
+          },
+          '-q, --quiet': {
+            type: 'boolean',
+            default: false,
+            description: 'Only output response body (no headers, no formatting)'
+          },
+          '--no-follow': {
+            type: 'boolean',
+            default: false,
+            description: 'Do not follow HTTP redirects'
+          },
+          '--no-verify': {
+            type: 'boolean',
+            default: false,
+            description: 'Skip SSL certificate verification'
+          },
+          '--timeout': {
+            type: 'number',
+            default: 30000,
+            description: 'Request timeout in milliseconds'
+          }
+        },
+        output: {
+          json: {
+            description: 'Structured response data when --output json is used',
+            schema: {
+              type: 'object',
+              properties: {
+                request: {
+                  type: 'object',
+                  properties: {
+                    method: { type: 'string' },
+                    url: { type: 'string' },
+                    headers: { type: 'object' },
+                    body: { type: ['string', 'object', 'null'] }
+                  }
+                },
+                response: {
+                  type: 'object',
+                  properties: {
+                    status: { type: 'number' },
+                    statusText: { type: 'string' },
+                    headers: { type: 'object' },
+                    body: { type: ['string', 'object', 'null'] },
+                    rawBody: { type: 'string' },
+                    responseTime: { type: 'number', description: 'Response time in milliseconds' },
+                    size: { type: 'number', description: 'Response size in bytes' }
+                  }
+                }
+              }
+            }
+          },
+          error: {
+            description: 'Error response when request fails',
+            schema: {
+              type: 'object',
+              properties: {
+                error: { type: 'string' },
+                message: { type: 'string' },
+                code: { type: 'string' }
+              }
+            }
+          }
+        },
+        exitCodes: {
+          0: 'Success (2xx or 3xx status)',
+          1: 'Request error or 4xx/5xx status'
+        },
+        examples: [
+          { command: 'mpx-api get https://api.example.com/users --output json', description: 'GET request with JSON output' },
+          { command: 'mpx-api post https://api.example.com/users -j \'{"name":"John"}\' --output json', description: 'POST JSON data with structured output' },
+          { command: 'mpx-api get https://api.example.com/data -H "Authorization: Bearer token"', description: 'GET with custom headers' }
+        ]
+      },
+      collection: {
+        description: 'Manage and run request collections',
+        subcommands: {
+          init: {
+            usage: 'mpx-api collection init [options]',
+            description: 'Initialize a new collection in current directory',
+            flags: {
+              '-n, --name': {
+                type: 'string',
+                default: 'API Collection',
+                description: 'Collection name'
+              }
+            }
+          },
+          add: {
+            usage: 'mpx-api collection add <name> <method> <url> [options]',
+            description: 'Add a request to the collection',
+            arguments: {
+              name: { type: 'string', required: true, description: 'Request name' },
+              method: { type: 'string', required: true, description: 'HTTP method' },
+              url: { type: 'string', required: true, description: 'Request URL' }
+            },
+            flags: {
+              '-H, --header': { type: 'array', description: 'Request headers' },
+              '-j, --json': { type: 'string', description: 'JSON body' },
+              '-d, --data': { type: 'string', description: 'Request body' }
+            }
+          },
+          run: {
+            usage: 'mpx-api collection run [file] [options]',
+            description: 'Run a collection',
+            arguments: {
+              file: { type: 'string', required: false, description: 'Collection file (default: .mpx-api/collection.yaml)' }
+            },
+            flags: {
+              '-e, --env': { type: 'string', description: 'Environment name to use' },
+              '--base-url': { type: 'string', description: 'Override base URL' },
+              '--json': { type: 'boolean', description: 'Output results as JSON' }
+            }
+          },
+          list: {
+            usage: 'mpx-api collection list [file]',
+            description: 'List requests in a collection'
+          }
+        }
+      },
+      env: {
+        description: 'Manage environments',
+        subcommands: {
+          init: {
+            usage: 'mpx-api env init',
+            description: 'Initialize environments directory with dev, staging, production'
+          },
+          set: {
+            usage: 'mpx-api env set <environment> <variable>',
+            description: 'Set an environment variable (KEY=value format)',
+            arguments: {
+              environment: { type: 'string', required: true, description: 'Environment name' },
+              variable: { type: 'string', required: true, description: 'Variable in KEY=value format' }
+            }
+          },
+          list: {
+            usage: 'mpx-api env list [environment]',
+            description: 'List all environments or variables in a specific environment',
+            arguments: {
+              environment: { type: 'string', required: false, description: 'Environment name (optional)' }
+            }
+          }
+        }
+      },
+      mock: {
+        description: 'Start a mock API server',
+        usage: 'mpx-api mock [file] [options]',
+        arguments: {
+          file: { type: 'string', required: false, description: 'Mock definition file' }
+        },
+        flags: {
+          '-p, --port': { type: 'number', default: 3000, description: 'Server port' },
+          '--watch': { type: 'boolean', description: 'Watch file for changes' }
+        }
+      },
+      test: {
+        description: 'Run API tests',
+        usage: 'mpx-api test <file> [options]',
+        arguments: {
+          file: { type: 'string', required: false, description: 'Test file to run (default: .mpx-api/collection.yaml)' }
+        },
+        flags: {
+          '-e, --env': { type: 'string', description: 'Environment name' },
+          '--json': { type: 'boolean', description: 'Output results as JSON' }
+        }
+      },
+      history: {
+        description: 'View request history',
+        usage: 'mpx-api history [options]',
+        flags: {
+          '-n, --limit': { type: 'number', default: 10, description: 'Number of entries to show' },
+          '--clear': { type: 'boolean', description: 'Clear history' }
+        }
+      },
+      load: {
+        description: 'Load test API endpoint (Pro)',
+        usage: 'mpx-api load <url> [options]',
+        arguments: {
+          url: { type: 'string', required: true, description: 'Target URL' }
+        },
+        flags: {
+          '--rps': { type: 'number', default: 10, description: 'Requests per second' },
+          '-d, --duration': { type: 'number', default: 10, description: 'Test duration in seconds' },
+          '-H, --header': { type: 'array', description: 'Add request headers' },
+          '--method': { type: 'string', default: 'GET', description: 'HTTP method' }
+        }
+      },
+      docs: {
+        description: 'Generate API documentation (Pro)',
+        usage: 'mpx-api docs <file> [options]',
+        arguments: {
+          file: { type: 'string', required: true, description: 'Collection or OpenAPI file' }
+        },
+        flags: {
+          '-o, --output': { type: 'string', description: 'Output directory' },
+          '--format': { type: 'string', enum: ['html', 'markdown'], default: 'html', description: 'Output format' }
+        }
+      },
+      mcp: {
+        description: 'Start MCP (Model Context Protocol) stdio server for AI agent integration',
+        usage: 'mpx-api mcp',
+        examples: [
+          { command: 'mpx-api mcp', description: 'Start MCP stdio server' }
+        ]
+      }
+    },
+    globalFlags: {
+      '-o, --output': {
+        type: 'string',
+        description: 'Output format: "json" for structured JSON for machine consumption'
+      },
+      '-q, --quiet': {
+        type: 'boolean',
+        default: false,
+        description: 'Suppress non-essential output'
+      },
+      '--schema': {
+        type: 'boolean',
+        default: false,
+        description: 'Output this schema as JSON'
+      },
+      '--version': {
+        type: 'boolean',
+        description: 'Show version number'
+      },
+      '--help': {
+        type: 'boolean',
+        description: 'Show help information'
+      }
+    },
+    mcpConfig: {
+      description: 'Add to your MCP client configuration to use mpx-api as an AI tool',
+      config: {
+        mcpServers: {
+          'mpx-api': {
+            command: 'npx',
+            args: ['mpx-api', 'mcp']
+          }
+        }
+      }
+    }
+  };
+}