mpx-api 1.0.2 → 1.1.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,19 @@ 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)
+  .option('--json', 'Output structured JSON (machine-readable)')
+  .option('--quiet, -q', 'Suppress non-essential output')
+  .option('--schema', 'Output JSON schema describing all commands and flags');
 
 // Register HTTP method commands (get, post, put, patch, delete, head, options)
 registerRequestCommands(program);
@@ -49,4 +62,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.1.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/request.js

@@ -17,8 +17,13 @@ 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) => {
+      .action(async (url, options, command) => {
         try {
+          // Get global options
+          const globalOpts = command.optsWithGlobals();
+          const jsonOutput = globalOpts.json || false;
+          const quiet = options.quiet || globalOpts.quiet || false;
+
           const client = new HttpClient({
             followRedirects: options.follow,
             verifySsl: options.verify,
@@ -34,7 +39,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 +66,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 +81,12 @@ export function registerRequestCommands(program) {
             process.exit(1);
           }
         } catch (err) {
-          formatError(err);
+          const globalOpts = command.optsWithGlobals();
+          if (globalOpts.json) {
+            console.log(JSON.stringify({ error: err.message, code: err.code || 'ERR_REQUEST' }));
+          } else {
+            formatError(err);
+          }
           process.exit(1);
         }
       });

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/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,307 @@
+/**
+ * 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'
+          },
+          '--json-output': {
+            type: 'boolean',
+            default: false,
+            description: 'Output results as structured JSON'
+          }
+        },
+        output: {
+          json: {
+            description: 'Structured response data when --json-output 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 --json-output', description: 'GET request with JSON output' },
+          { command: 'mpx-api post https://api.example.com/users -j \'{"name":"John"}\' --json-output', description: 'POST JSON data with structured output' },
+          { command: 'mpx-api get https://api.example.com/data -H "Authorization: Bearer token" --json-output', 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-output': { 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: {
+          list: {
+            usage: 'mpx-api env list',
+            description: 'List all environments',
+            flags: {
+              '--json-output': { type: 'boolean', description: 'Output as JSON' }
+            }
+          },
+          set: {
+            usage: 'mpx-api env set <name> <key> <value>',
+            description: 'Set an environment variable',
+            arguments: {
+              name: { type: 'string', required: true, description: 'Environment name' },
+              key: { type: 'string', required: true, description: 'Variable key' },
+              value: { type: 'string', required: true, description: 'Variable value' }
+            }
+          },
+          get: {
+            usage: 'mpx-api env get <name> <key>',
+            description: 'Get an environment variable',
+            flags: {
+              '--json-output': { type: 'boolean', description: 'Output as JSON' }
+            }
+          },
+          delete: {
+            usage: 'mpx-api env delete <name>',
+            description: 'Delete an environment'
+          }
+        }
+      },
+      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: true, description: 'Test file to run' }
+        },
+        flags: {
+          '-e, --env': { type: 'string', description: 'Environment name' },
+          '--json-output': { 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' },
+          '--json-output': { type: 'boolean', description: 'Output as JSON' }
+        }
+      },
+      load: {
+        description: 'Load test API endpoint (Pro)',
+        usage: 'mpx-api load <url> [options]',
+        arguments: {
+          url: { type: 'string', required: true, description: 'Target URL' }
+        },
+        flags: {
+          '-c, --concurrency': { type: 'number', default: 10, description: 'Concurrent requests' },
+          '-n, --requests': { type: 'number', default: 100, description: 'Total requests' },
+          '--json-output': { type: 'boolean', description: 'Output results as JSON' }
+        }
+      },
+      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: {
+      '--json-output': {
+        type: 'boolean',
+        default: false,
+        description: 'Output structured JSON for machine consumption'
+      },
+      '--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']
+          }
+        }
+      }
+    }
+  };
+}