mpx-scan 1.0.2 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # mpx-scan 🔍
 
-**Professional website security scanner for developers**
+**Professional website security scanner for developers and AI agents**
 
 Check your site's security headers, SSL/TLS configuration, DNS settings, and get actionable fix suggestions — all from your terminal.
 
@@ -13,10 +13,14 @@ Part of the [Mesaplex](https://mesaplex.com) developer toolchain.
 
 - **Zero-config security scanning** — just point it at a URL
 - **Beautiful terminal output** with color-coded results
+- **Structured JSON output** — `--json` for CI/CD and AI agent consumption
+- **MCP server** — integrates with any MCP-compatible AI agent (Claude, GPT, Cursor, etc.)
 - **Actionable fix suggestions** — copy-paste config for nginx, Apache, Caddy, Cloudflare
+- **Batch scanning** — pipe URLs from stdin
+- **Self-documenting** — `--schema` returns machine-readable tool description
 - **Fast** — scans complete in seconds
 - **Zero native dependencies** — installs cleanly everywhere
-- **CI/CD ready** — JSON output and exit codes for automated testing
+- **CI/CD ready** — predictable exit codes and JSON output
 
 ### Security Checks
 
@@ -50,40 +54,20 @@ mpx-scan https://example.com
 mpx-scan https://example.com
 ```
 
-![Example output](https://example.com/mpx-scan-demo.gif)
-
-### Get Fix Suggestions
-
-```bash
-mpx-scan https://example.com --fix nginx
-mpx-scan https://example.com --fix apache
-mpx-scan https://example.com --fix caddy
-mpx-scan https://example.com --fix cloudflare
-```
-
-Generates copy-paste configuration snippets for your platform.
-
-### Deep Scan (Pro)
-
-```bash
-mpx-scan https://example.com --full
-```
-
-Runs all security checks including DNS, cookies, SRI, exposed files.
-
-### JSON Output (Pro)
+### JSON Output
 
 ```bash
 mpx-scan https://example.com --json
 ```
 
-Perfect for CI/CD pipelines:
+Returns structured JSON to stdout (progress/status goes to stderr):
 
 ```json
 {
   "mpxScan": {
-    "version": "1.0.0",
-    "scannedAt": "2026-02-15T22:00:00.000Z"
+    "version": "1.1.0",
+    "scannedAt": "2026-02-16T22:00:00.000Z",
+    "scanDuration": 350
   },
   "target": {
     "url": "https://example.com",
@@ -98,28 +82,123 @@ Perfect for CI/CD pipelines:
   "summary": {
     "passed": 12,
     "warnings": 3,
-    "failed": 2
-  }
+    "failed": 2,
+    "info": 0
+  },
+  "sections": { ... },
+  "tier": "free"
 }
 ```
 
+### Get Fix Suggestions
+
+```bash
+mpx-scan https://example.com --fix nginx
+mpx-scan https://example.com --fix apache
+mpx-scan https://example.com --fix caddy
+mpx-scan https://example.com --fix cloudflare
+```
+
+### Deep Scan (Pro)
+
+```bash
+mpx-scan https://example.com --full
+```
+
 ### Brief Output
 
 ```bash
 mpx-scan https://example.com --brief
 ```
 
-One-line summary — great for monitoring multiple sites.
+### Batch Scanning
 
-## 🎯 Use Cases
+```bash
+cat urls.txt | mpx-scan --batch --json
+```
+
+Reads one URL per line from stdin, outputs one JSON result per line (JSONL format). Lines starting with `#` are ignored.
+
+### Tool Schema
+
+```bash
+mpx-scan --schema
+```
+
+Returns a JSON schema describing all commands, flags, inputs, and outputs — designed for AI agent tool discovery.
+
+## 🤖 AI Agent Usage
+
+mpx-scan is designed to be used by AI agents as well as humans.
+
+### MCP Integration
+
+Add to your MCP client configuration (Claude Desktop, Cursor, Windsurf, etc.):
 
-### Local Development
+```json
+{
+  "mcpServers": {
+    "mpx-scan": {
+      "command": "npx",
+      "args": ["mpx-scan", "mcp"]
+    }
+  }
+}
+```
+
+The MCP server exposes these tools:
+- **`scan`** — Scan a URL and return structured results
+- **`generate_fixes`** — Scan and generate platform-specific fix config
+- **`get_schema`** — Get full tool schema
+
+### Programmatic Usage
 
 ```bash
-mpx-scan http://localhost:3000 --fix nginx
+# JSON output for parsing
+mpx-scan https://example.com --json
+
+# Batch processing
+cat urls.txt | mpx-scan --batch --json
+
+# Schema discovery
+mpx-scan --schema
+
+# Quiet mode (no banners, progress goes to stderr)
+mpx-scan https://example.com --json --quiet
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Scan complete, no security issues found |
+| 1 | Scan complete, security issues found |
+| 2 | Invalid arguments |
+| 3 | Configuration error (license, rate limit) |
+| 4 | Network/connectivity error |
+
+### Error Responses (JSON mode)
+
+When `--json` is used, errors return structured JSON:
+
+```json
+{
+  "error": "Description of what went wrong",
+  "code": "ERR_NETWORK"
+}
 ```
 
-Check your security before deploying.
+Error codes: `ERR_NETWORK`, `ERR_SCAN`, `ERR_RATE_LIMIT`, `ERR_PRO_REQUIRED`, `ERR_NO_INPUT`
+
+### Automation Tips
+
+- Use `--json` for machine-parseable output (stdout only, no ANSI)
+- Use `--no-color` to strip ANSI codes from human-readable output
+- Use `--quiet` to suppress banners and progress info
+- Pipe `--batch --json` for JSONL (one result per line) processing
+- Check exit codes for pass/fail decisions in CI/CD
+
+## 🎯 Use Cases
 
 ### CI/CD Integration
 
@@ -131,14 +210,17 @@ jobs:
   scan:
     runs-on: ubuntu-latest
     steps:
-      - run: npx mpx-scan https://mysite.com --json
+      - run: npx mpx-scan https://mysite.com --ci --min-score 70 --json
 ```
 
-### Batch Scanning (Pro)
+### Monitoring Script
 
 ```bash
+#!/bin/bash
 for site in site1.com site2.com site3.com; do
-  mpx-scan $site --json >> security-report.jsonl
+  result=$(npx mpx-scan "$site" --json 2>/dev/null)
+  grade=$(echo "$result" | jq -r '.score.grade')
+  echo "$site: $grade"
 done
 ```
 
@@ -150,38 +232,27 @@ done
 | **Security headers** | ✅ | ✅ |
 | **SSL/TLS checks** | ✅ | ✅ |
 | **Server info checks** | ✅ | ✅ |
+| **JSON output** | ✅ | ✅ |
+| **Batch scanning** | ✅ | ✅ |
+| **MCP server** | ✅ | ✅ |
 | **DNS security** | ❌ | ✅ |
 | **Cookie security** | ❌ | ✅ |
 | **SRI checks** | ❌ | ✅ |
 | **Exposed files** | ❌ | ✅ |
 | **Mixed content** | ❌ | ✅ |
-| **JSON export** | ❌ | ✅ |
-| **Batch scanning** | ❌ | ✅ |
-| **CI/CD integration** | ❌ | ✅ |
+| **Full scan (--full)** | ❌ | ✅ |
 
 **Upgrade to Pro:** [https://mesaplex.com/mpx-scan](https://mesaplex.com/mpx-scan)
 
 ## 🔐 License Management
 
-### Check License Status
-
-```bash
-mpx-scan license
-```
-
-### Activate Pro License
-
-```bash
-mpx-scan activate MPX-PRO-XXXXXXXXXXXXXXXX
-```
-
-### Deactivate
-
 ```bash
-mpx-scan deactivate
+mpx-scan license                         # Check status
+mpx-scan activate MPX-PRO-XXXXXXXX      # Activate Pro
+mpx-scan deactivate                      # Return to free tier
 ```
 
-## 🛠️ CLI Options
+## 🛠️ CLI Reference
 
 ```
 Usage: mpx-scan [url] [options]
@@ -190,48 +261,44 @@ Arguments:
   url                      URL to scan
 
 Options:
-  -V, --version            output the version number
+  -V, --version            Output version number
+  --json                   Output as structured JSON
   --full                   Run all checks (Pro only)
-  --json                   Output as JSON (Pro only)
-  --brief                  Brief output (one-line summary)
+  --brief                  Brief one-line output
+  --quiet, -q              Minimal output (no banners)
+  --no-color               Disable ANSI color codes
+  --batch                  Read URLs from stdin (one per line)
+  --schema                 Output JSON schema for tool discovery
   --fix <platform>         Generate fix config (nginx, apache, caddy, cloudflare)
-  --timeout <seconds>      Connection timeout (default: "10")
-  -h, --help               display help for command
+  --timeout <seconds>      Connection timeout (default: 10)
+  --ci                     CI mode: exit 1 if below --min-score
+  --min-score <score>      Minimum score for CI mode (default: 70)
+  -h, --help               Display help
 
 Commands:
-  license                  Manage your mpx-scan license
-  activate <key>           Activate a Pro license
-  deactivate               Deactivate license
+  license                  Show license status
+  activate <key>           Activate Pro license
+  deactivate               Return to free tier
+  mcp                      Start MCP stdio server
 ```
 
 ## 📦 Installation
 
-### Global Install
-
 ```bash
+# Global
 npm install -g mpx-scan
-```
-
-### Project Dependency
 
-```bash
+# Project dependency
 npm install --save-dev mpx-scan
-```
-
-Add to `package.json`:
 
-```json
-{
-  "scripts": {
-    "security": "mpx-scan https://mysite.com"
-  }
-}
+# One-off with npx
+npx mpx-scan https://example.com
 ```
 
 ### Requirements
 
 - Node.js 18.0.0 or higher
-- No other dependencies required for scanning
+- No native dependencies
 - Works on macOS, Linux, Windows
 
 ## 🧪 Testing
@@ -240,11 +307,9 @@ Add to `package.json`:
 npm test
 ```
 
-Runs the built-in test suite for core scanning logic.
-
 ## 🤝 Contributing
 
-This is a commercial product with a free tier. Security improvements and bug fixes are welcome!
+Security improvements and bug fixes are welcome!
 
 ## 📄 License
 
@@ -255,22 +320,15 @@ See [LICENSE](LICENSE) for full terms.
 ## 🔗 Links
 
 - **Website:** [https://mesaplex.com/mpx-scan](https://mesaplex.com/mpx-scan)
-- **Documentation:** [https://docs.mesaplex.com/mpx-scan](https://docs.mesaplex.com/mpx-scan)
+- **npm:** [https://www.npmjs.com/package/mpx-scan](https://www.npmjs.com/package/mpx-scan)
+- **GitHub:** [https://github.com/mesaplexdev/mpx-scan](https://github.com/mesaplexdev/mpx-scan)
 - **Support:** support@mesaplex.com
-- **Twitter:** [@mesaplex](https://twitter.com/mesaplex)
-
-## 🐛 Known Issues
-
-None currently! Report issues via email: support@mesaplex.com
 
 ## 📚 Related Tools
 
-Part of the Mesaplex developer toolchain:
-
 - **mpx-scan** — Security scanner (you are here)
-- **mpx-api** — API testing toolkit *(coming soon)*
-- **mpx-perf** — Performance profiler *(coming soon)*
-- **mpx-deploy** — Deployment automation *(coming soon)*
+- **[mpx-api](https://www.npmjs.com/package/mpx-api)** — API testing toolkit
+- **[mpx-db](https://www.npmjs.com/package/mpx-db)** — Database toolkit
 
 ---
 

package/bin/cli.js

@@ -13,6 +13,7 @@ const { scan } = require('../src/index');
 const { formatReport, formatBrief } = require('../src/reporters/terminal');
 const { formatJSON } = require('../src/reporters/json');
 const { generateFixes, PLATFORMS } = require('../src/generators/fixes');
+const { getSchema } = require('../src/schema');
 const { 
   getLicense, 
   activateLicense, 
@@ -24,6 +25,18 @@ const {
 
 const pkg = require('../package.json');
 
+// Exit codes per AI-native spec
+const EXIT = {
+  SUCCESS: 0,           // Success, no issues found
+  ISSUES_FOUND: 1,      // Success, issues found
+  BAD_ARGS: 2,          // Invalid arguments
+  CONFIG_ERROR: 3,      // Configuration error
+  NETWORK_ERROR: 4      // Network/connectivity error
+};
+
+// Auto-detect non-interactive mode
+const isInteractive = process.stdout.isTTY && !process.env.CI;
+
 const program = new Command();
 
 program
@@ -32,105 +45,252 @@ program
   .version(pkg.version)
   .argument('[url]', 'URL to scan')
   .option('--full', 'Run all checks (Pro only)')
-  .option('--json', 'Output as JSON')
+  .option('--json', 'Output as JSON (machine-readable)')
   .option('--brief', 'Brief output (one-line summary)')
+  .option('--quiet, -q', 'Minimal output (results only, no banners)')
+  .option('--no-color', 'Disable colored output')
+  .option('--batch', 'Batch mode: read URLs from stdin (one per line)')
+  .option('--schema', 'Output JSON schema describing all commands and flags')
   .option('--fix <platform>', `Generate fix config for platform (${PLATFORMS.join(', ')})`)
   .option('--timeout <seconds>', 'Connection timeout', '10')
   .option('--ci', 'CI/CD mode: exit 1 if score below threshold')
   .option('--min-score <score>', 'Minimum score for CI mode (default: 70)', '70')
   .action(async (url, options) => {
+    // Handle --schema flag
+    if (options.schema) {
+      console.log(JSON.stringify(getSchema(), null, 2));
+      process.exit(EXIT.SUCCESS);
+      return;
+    }
+
+    // Handle --batch mode (read URLs from stdin)
+    if (options.batch) {
+      await runBatchMode(options);
+      return;
+    }
+
     // Show help if no URL provided
     if (!url) {
       program.help();
       return;
     }
     
-    try {
-      // Check license and rate limits
-      const license = getLicense();
-      const rateLimit = checkRateLimit();
-      
-      // Handle rate limiting
-      if (!rateLimit.allowed) {
+    const exitCode = await runSingleScan(url, options);
+    process.exit(exitCode);
+  });
+
+async function runSingleScan(url, options) {
+  const jsonMode = options.json;
+  const quietMode = options.quiet || options.Q;
+  
+  // Disable chalk if --no-color or non-TTY
+  if (options.color === false || !process.stdout.isTTY) {
+    chalk.level = 0;
+  }
+
+  try {
+    // Check license and rate limits
+    const license = getLicense();
+    const rateLimit = checkRateLimit();
+    
+    // Handle rate limiting
+    if (!rateLimit.allowed) {
+      if (jsonMode) {
+        console.log(JSON.stringify({
+          error: 'Daily scan limit reached',
+          code: 'ERR_RATE_LIMIT',
+          resetsAt: new Date(rateLimit.resetsAt).toISOString(),
+          limit: FREE_DAILY_LIMIT,
+          upgrade: 'https://mesaplex.com/mpx-scan'
+        }, null, 2));
+      } else {
         console.error(chalk.red.bold('\n❌ Daily scan limit reached'));
         console.error(chalk.yellow(`Free tier: ${FREE_DAILY_LIMIT} scans/day`));
         console.error(chalk.gray(`Resets: ${new Date(rateLimit.resetsAt).toLocaleString()}\n`));
         console.error(chalk.blue('Upgrade to Pro for unlimited scans:'));
         console.error(chalk.blue('  https://mesaplex.com/mpx-scan\n'));
-        process.exit(1);
       }
-      
-      // Check for Pro-only features
-      if (options.full && license.tier !== 'pro') {
+      return EXIT.CONFIG_ERROR;
+    }
+    
+    // Check for Pro-only features
+    if (options.full && license.tier !== 'pro') {
+      if (jsonMode) {
+        console.log(JSON.stringify({
+          error: '--full flag requires Pro license',
+          code: 'ERR_PRO_REQUIRED',
+          upgrade: 'https://mesaplex.com/mpx-scan'
+        }, null, 2));
+      } else {
         console.error(chalk.red.bold('\n❌ --full flag requires Pro license'));
         console.error(chalk.yellow('Free tier includes: headers, SSL, server checks'));
         console.error(chalk.yellow('Pro includes: all checks (DNS, cookies, SRI, exposed files, etc.)\n'));
         console.error(chalk.blue('Upgrade: https://mesaplex.com/mpx-scan\n'));
-        process.exit(1);
       }
-      
-      if (options.json && license.tier !== 'pro') {
-        console.error(chalk.red.bold('\n❌ --json output requires Pro license\n'));
-        console.error(chalk.blue('Upgrade: https://mesaplex.com/mpx-scan\n'));
-        process.exit(1);
+      return EXIT.CONFIG_ERROR;
+    }
+    
+    // Show scan info (unless quiet/json/brief)
+    if (!jsonMode && !options.brief && !quietMode) {
+      console.error(chalk.bold.cyan('🔍 Scanning...'));
+      if (license.tier === 'free') {
+        console.error(chalk.gray(`Free tier: ${rateLimit.remaining} scan(s) remaining today`));
       }
-      
-      // Show scan info
-      if (!options.json && !options.brief) {
-        console.log('');
-        console.log(chalk.bold.cyan('🔍 Scanning...'));
-        if (license.tier === 'free') {
-          console.log(chalk.gray(`Free tier: ${rateLimit.remaining} scan(s) remaining today\n`));
+    }
+    
+    // Run scan
+    const results = await scan(url, {
+      timeout: parseInt(options.timeout) * 1000,
+      tier: license.tier,
+      full: options.full
+    });
+    
+    // Record scan for rate limiting
+    recordScan();
+    
+    // Output results
+    if (options.fix) {
+      console.log(generateFixes(options.fix, results));
+    } else if (jsonMode) {
+      console.log(formatJSON(results, true));
+    } else if (options.brief) {
+      console.log(formatBrief(results));
+    } else {
+      console.log(formatReport(results, { ...options, quiet: quietMode }));
+    }
+    
+    // Determine exit code based on findings
+    if (options.ci) {
+      const minScore = parseInt(options.minScore);
+      const percentage = Math.round((results.score / results.maxScore) * 100);
+      if (percentage < minScore) {
+        if (!jsonMode && !options.brief && !quietMode) {
+          console.error(chalk.yellow(`\n⚠️  CI mode: Score ${percentage}/100 below minimum ${minScore}`));
         }
+        return EXIT.ISSUES_FOUND;
       }
+    }
+    
+    // Exit 1 if there are failures, 0 if clean
+    if (results.summary.failed > 0) {
+      return EXIT.ISSUES_FOUND;
+    }
+    return EXIT.SUCCESS;
+    
+  } catch (err) {
+    if (jsonMode) {
+      const code = isNetworkError(err) ? 'ERR_NETWORK' : 'ERR_SCAN';
+      console.log(JSON.stringify({ error: err.message, code }, null, 2));
+    } else {
+      console.error(chalk.red.bold('\n❌ Error:'), err.message);
+      console.error('');
+    }
+    return isNetworkError(err) ? EXIT.NETWORK_ERROR : EXIT.ISSUES_FOUND;
+  }
+}
+
+async function runBatchMode(options) {
+  const jsonMode = options.json;
+
+  // Read URLs from stdin
+  const input = await readStdin();
+  if (!input.trim()) {
+    if (jsonMode) {
+      console.log(JSON.stringify({ error: 'No URLs provided on stdin', code: 'ERR_NO_INPUT' }, null, 2));
+    } else {
+      console.error(chalk.red('No URLs provided. Pipe URLs via stdin:'));
+      console.error(chalk.gray('  cat urls.txt | mpx-scan --batch --json'));
+    }
+    process.exit(EXIT.BAD_ARGS);
+    return;
+  }
+
+  const urls = input.split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('#'));
+  
+  if (urls.length === 0) {
+    if (jsonMode) {
+      console.log(JSON.stringify({ error: 'No valid URLs found in input', code: 'ERR_NO_INPUT' }, null, 2));
+    } else {
+      console.error(chalk.red('No valid URLs found in input.'));
+    }
+    process.exit(EXIT.BAD_ARGS);
+    return;
+  }
+
+  let hasIssues = false;
+  let hasErrors = false;
+
+  for (const url of urls) {
+    try {
+      const license = getLicense();
+      const rateLimit = checkRateLimit();
       
-      // Run scan
+      if (!rateLimit.allowed) {
+        if (jsonMode) {
+          console.log(JSON.stringify({
+            url,
+            error: 'Rate limit reached',
+            code: 'ERR_RATE_LIMIT'
+          }));
+        }
+        hasErrors = true;
+        continue;
+      }
+
       const results = await scan(url, {
         timeout: parseInt(options.timeout) * 1000,
         tier: license.tier,
         full: options.full
       });
       
-      // Record scan for rate limiting
       recordScan();
       
-      // Output results
-      if (options.fix) {
-        console.log(generateFixes(options.fix, results));
-      } else if (options.json) {
-        console.log(formatJSON(results, true));
+      if (results.summary.failed > 0) hasIssues = true;
+
+      if (jsonMode) {
+        // JSONL: one JSON object per line
+        console.log(formatJSON(results, false));
       } else if (options.brief) {
         console.log(formatBrief(results));
       } else {
         console.log(formatReport(results, options));
       }
-      
-      // Exit code logic:
-      // - Exit 0: scan completed successfully (default)
-      // - Exit 1: only in --ci mode if score below threshold
-      if (options.ci) {
-        const minScore = parseInt(options.minScore);
-        const percentage = Math.round((results.score / results.maxScore) * 100);
-        if (percentage < minScore) {
-          if (!options.json && !options.brief) {
-            console.error(chalk.yellow(`\n⚠️  CI mode: Score ${percentage}/100 below minimum ${minScore}`));
-          }
-          process.exit(1);
-        }
-      }
-      
-      process.exit(0);
-      
     } catch (err) {
-      if (options.json) {
-        console.log(JSON.stringify({ error: err.message }, null, 2));
+      hasErrors = true;
+      if (jsonMode) {
+        console.log(JSON.stringify({ url, error: err.message, code: isNetworkError(err) ? 'ERR_NETWORK' : 'ERR_SCAN' }));
       } else {
-        console.error(chalk.red.bold('\n❌ Error:'), err.message);
-        console.error('');
+        console.error(chalk.red(`Error scanning ${url}: ${err.message}`));
       }
-      process.exit(1);
     }
+  }
+
+  if (hasErrors) process.exit(EXIT.NETWORK_ERROR);
+  if (hasIssues) process.exit(EXIT.ISSUES_FOUND);
+  process.exit(EXIT.SUCCESS);
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) {
+      resolve('');
+      return;
+    }
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => data += chunk);
+    process.stdin.on('end', () => resolve(data));
   });
+}
+
+function isNetworkError(err) {
+  const msg = (err.message || '').toLowerCase();
+  return msg.includes('econnrefused') || msg.includes('enotfound') || 
+         msg.includes('timeout') || msg.includes('network') ||
+         msg.includes('dns') || msg.includes('econnreset') ||
+         err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || 
+         err.code === 'ETIMEDOUT';
+}
 
 // License management subcommands
 program
@@ -187,7 +347,7 @@ program
     } catch (err) {
       console.error(chalk.red.bold('\n❌ Activation failed:'), err.message);
       console.error('');
-      process.exit(1);
+      process.exit(EXIT.CONFIG_ERROR);
     }
   });
 
@@ -202,20 +362,43 @@ program
     console.log('');
   });
 
+// MCP subcommand
+program
+  .command('mcp')
+  .description('Start MCP (Model Context Protocol) stdio server')
+  .action(async () => {
+    try {
+      const { startMCPServer } = require('../src/mcp');
+      await startMCPServer();
+    } catch (err) {
+      console.error(JSON.stringify({ error: err.message, code: 'ERR_MCP_START' }));
+      process.exit(EXIT.CONFIG_ERROR);
+    }
+  });
+
 // Examples
 program.addHelpText('after', `
 ${chalk.bold('Examples:')}
   ${chalk.cyan('mpx-scan https://example.com')}           Quick security scan
   ${chalk.cyan('mpx-scan example.com --full')}            Deep scan (Pro only)
-  ${chalk.cyan('mpx-scan example.com --json')}            JSON output (Pro only)
+  ${chalk.cyan('mpx-scan example.com --json')}            JSON output
   ${chalk.cyan('mpx-scan example.com --fix nginx')}       Generate nginx config
   ${chalk.cyan('mpx-scan example.com --brief')}           One-line summary
+  ${chalk.cyan('mpx-scan --schema')}                      Show tool schema (JSON)
+  ${chalk.cyan('cat urls.txt | mpx-scan --batch --json')} Batch scan from stdin
+  ${chalk.cyan('mpx-scan mcp')}                           Start MCP server
   ${chalk.cyan('mpx-scan license')}                       Check license status
-  ${chalk.cyan('mpx-scan activate MPX-PRO-XXX')}          Activate Pro license
+
+${chalk.bold('Exit Codes:')}
+  0  Success, no issues found
+  1  Success, issues found
+  2  Invalid arguments
+  3  Configuration error (license, rate limit)
+  4  Network/connectivity error
 
 ${chalk.bold('Free vs Pro:')}
   ${chalk.yellow('Free:')}  3 scans/day, basic checks (headers, SSL, server)
-  ${chalk.green('Pro:')}   Unlimited scans, all checks, JSON export, CI/CD integration
+  ${chalk.green('Pro:')}   Unlimited scans, all checks, batch mode, CI/CD integration
 
   ${chalk.blue('Upgrade: https://mesaplex.com/mpx-scan')}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mpx-scan",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Professional website security scanner CLI. Check headers, SSL, cookies, DNS, and get actionable fix suggestions. Part of the Mesaplex developer toolchain.",
   "main": "src/index.js",
   "bin": {
@@ -25,7 +25,11 @@
     "security-headers",
     "ssl-check",
     "dns-security",
-    "cors"
+    "cors",
+    "mcp",
+    "ai-native",
+    "model-context-protocol",
+    "automation"
   ],
   "author": "Mesaplex <support@mesaplex.com>",
   "license": "SEE LICENSE IN LICENSE",
@@ -39,6 +43,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^4.1.2",
     "commander": "^12.0.0"
   },

package/src/mcp.js

@@ -0,0 +1,260 @@
+/**
+ * MCP (Model Context Protocol) Server
+ * 
+ * Exposes mpx-scan capabilities as MCP tools for AI agent integration.
+ * Runs over stdio transport.
+ */
+
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} = require('@modelcontextprotocol/sdk/types.js');
+
+const { scan } = require('./index');
+const { formatJSON } = require('./reporters/json');
+const { getSchema } = require('./schema');
+const { getLicense, checkRateLimit, recordScan } = require('./license');
+const { generateFixes, PLATFORMS } = require('./generators/fixes');
+const pkg = require('../package.json');
+
+async function startMCPServer() {
+  const server = new Server(
+    { name: 'mpx-scan', version: pkg.version },
+    { capabilities: { tools: {} } }
+  );
+
+  // List available tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: 'scan',
+          description: 'Scan a website for security issues. Returns structured results with grade, score, and per-check details.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              url: {
+                type: 'string',
+                description: 'URL to scan (https:// added automatically if missing)'
+              },
+              full: {
+                type: 'boolean',
+                description: 'Run all security checks (Pro license required)',
+                default: false
+              },
+              timeout: {
+                type: 'number',
+                description: 'Connection timeout in seconds',
+                default: 10
+              }
+            },
+            required: ['url']
+          }
+        },
+        {
+          name: 'generate_fixes',
+          description: 'Generate platform-specific configuration to fix security issues found by a scan.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              url: {
+                type: 'string',
+                description: 'URL to scan and generate fixes for'
+              },
+              platform: {
+                type: 'string',
+                enum: PLATFORMS,
+                description: 'Target platform for fix configuration'
+              },
+              timeout: {
+                type: 'number',
+                description: 'Connection timeout in seconds',
+                default: 10
+              }
+            },
+            required: ['url', 'platform']
+          }
+        },
+        {
+          name: 'get_schema',
+          description: 'Get the full JSON schema describing all mpx-scan 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 'scan': {
+          const license = getLicense();
+          const rateLimit = checkRateLimit();
+          
+          if (!rateLimit.allowed) {
+            return {
+              content: [{
+                type: 'text',
+                text: JSON.stringify({
+                  error: 'Daily scan limit reached',
+                  code: 'ERR_RATE_LIMIT',
+                  resetsAt: new Date(rateLimit.resetsAt).toISOString()
+                }, null, 2)
+              }],
+              isError: true
+            };
+          }
+
+          const results = await scan(args.url, {
+            timeout: (args.timeout || 10) * 1000,
+            tier: license.tier,
+            full: args.full || false
+          });
+          
+          recordScan();
+
+          return {
+            content: [{
+              type: 'text',
+              text: formatJSON(results, true)
+            }]
+          };
+        }
+
+        case 'generate_fixes': {
+          const license = getLicense();
+          const rateLimit2 = checkRateLimit();
+          
+          if (!rateLimit2.allowed) {
+            return {
+              content: [{
+                type: 'text',
+                text: JSON.stringify({
+                  error: 'Daily scan limit reached',
+                  code: 'ERR_RATE_LIMIT',
+                  resetsAt: new Date(rateLimit2.resetsAt).toISOString()
+                }, null, 2)
+              }],
+              isError: true
+            };
+          }
+
+          const fixResults = await scan(args.url, {
+            timeout: (args.timeout || 10) * 1000,
+            tier: license.tier,
+            full: false
+          });
+          
+          recordScan();
+
+          // Collect issues and generate structured fix data
+          const issues = [];
+          for (const [sectionName, section] of Object.entries(fixResults.sections)) {
+            for (const check of section.checks) {
+              if ((check.status === 'fail' || check.status === 'warn') && check.recommendation) {
+                issues.push({
+                  section: sectionName,
+                  name: check.name,
+                  status: check.status,
+                  recommendation: check.recommendation
+                });
+              }
+            }
+          }
+
+          // Extract headers from issues
+          const headers = {};
+          for (const issue of issues) {
+            const rec = issue.recommendation;
+            if (rec.includes('Strict-Transport-Security')) headers['Strict-Transport-Security'] = 'max-age=31536000; includeSubDomains; preload';
+            if (rec.includes('Content-Security-Policy')) headers['Content-Security-Policy'] = "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: https:; font-src 'self'; connect-src 'self'; frame-ancestors 'none'";
+            if (rec.includes('X-Content-Type-Options')) headers['X-Content-Type-Options'] = 'nosniff';
+            if (rec.includes('X-Frame-Options')) headers['X-Frame-Options'] = 'DENY';
+            if (rec.includes('Referrer-Policy')) headers['Referrer-Policy'] = 'strict-origin-when-cross-origin';
+            if (rec.includes('Permissions-Policy')) headers['Permissions-Policy'] = 'camera=(), microphone=(), geolocation=()';
+            if (rec.includes('Cross-Origin-Opener-Policy')) headers['Cross-Origin-Opener-Policy'] = 'same-origin';
+            if (rec.includes('Cross-Origin-Resource-Policy')) headers['Cross-Origin-Resource-Policy'] = 'same-origin';
+          }
+
+          const hasSSL = issues.some(i => i.section === 'ssl');
+
+          // Build platform-specific config snippet
+          let configSnippet = '';
+          const p = args.platform;
+          if (p === 'nginx') {
+            const headerLines = Object.entries(headers).map(([h, v]) => `    add_header ${h} "${v}" always;`).join('\n');
+            configSnippet = `server {\n    # ... your existing config ...\n\n${headerLines}\n}`;
+            if (hasSSL) configSnippet += '\n\n# SSL/TLS\nssl_protocols TLSv1.2 TLSv1.3;\nssl_prefer_server_ciphers on;';
+          } else if (p === 'apache') {
+            const headerLines = Object.entries(headers).map(([h, v]) => `    Header always set ${h} "${v}"`).join('\n');
+            configSnippet = `<IfModule mod_headers.c>\n${headerLines}\n</IfModule>`;
+          } else if (p === 'caddy') {
+            const headerLines = Object.entries(headers).map(([h, v]) => `        ${h} "${v}"`).join('\n');
+            configSnippet = `header {\n${headerLines}\n}`;
+          } else if (p === 'cloudflare') {
+            configSnippet = Object.entries(headers).map(([h, v]) => `Set "${h}" to "${v}"`).join('\n');
+          }
+
+          const fixData = {
+            url: args.url,
+            platform: args.platform,
+            issueCount: issues.length,
+            issues: issues.map(i => ({ section: i.section, name: i.name, status: i.status, recommendation: i.recommendation })),
+            headers,
+            hasSSLIssues: hasSSL,
+            configSnippet,
+            instructions: {
+              nginx: 'Add to server {} block, then: sudo nginx -t && sudo systemctl reload nginx',
+              apache: 'Add to .htaccess or site config, then: sudo apachectl configtest && sudo systemctl reload apache2',
+              caddy: 'Add to Caddyfile site block, then: sudo systemctl reload caddy',
+              cloudflare: 'Dashboard → Rules → Transform Rules → Modify Response Header'
+            }[args.platform]
+          };
+
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(fixData, 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_SCAN' }, null, 2)
+        }],
+        isError: true
+      };
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+module.exports = { startMCPServer };

package/src/schema.js

@@ -0,0 +1,198 @@
+/**
+ * Schema Module
+ * 
+ * Returns a machine-readable JSON schema describing all commands,
+ * flags, inputs, and outputs for AI agent discovery.
+ */
+
+const pkg = require('../package.json');
+const { PLATFORMS } = require('./generators/fixes');
+const { SCANNER_TIERS } = require('./index');
+
+function getSchema() {
+  return {
+    tool: 'mpx-scan',
+    version: pkg.version,
+    description: pkg.description,
+    homepage: pkg.homepage,
+    commands: {
+      scan: {
+        description: 'Scan a URL for security issues',
+        usage: 'mpx-scan <url> [options]',
+        arguments: {
+          url: {
+            type: 'string',
+            required: true,
+            description: 'URL to scan (https:// prefix added automatically if missing)'
+          }
+        },
+        flags: {
+          '--json': {
+            type: 'boolean',
+            default: false,
+            description: 'Output results as structured JSON'
+          },
+          '--full': {
+            type: 'boolean',
+            default: false,
+            description: 'Run all security checks (Pro license required)'
+          },
+          '--brief': {
+            type: 'boolean',
+            default: false,
+            description: 'One-line summary output'
+          },
+          '--quiet': {
+            type: 'boolean',
+            default: false,
+            description: 'Minimal output (no banners or progress)'
+          },
+          '--no-color': {
+            type: 'boolean',
+            default: false,
+            description: 'Disable ANSI color codes in output'
+          },
+          '--batch': {
+            type: 'boolean',
+            default: false,
+            description: 'Read URLs from stdin (one per line), output JSONL with --json'
+          },
+          '--fix': {
+            type: 'string',
+            enum: PLATFORMS,
+            description: 'Generate fix configuration for specified platform'
+          },
+          '--timeout': {
+            type: 'number',
+            default: 10,
+            description: 'Connection timeout in seconds'
+          },
+          '--ci': {
+            type: 'boolean',
+            default: false,
+            description: 'CI/CD mode: exit 1 if score below --min-score'
+          },
+          '--min-score': {
+            type: 'number',
+            default: 70,
+            description: 'Minimum score threshold for --ci mode (0-100)'
+          },
+          '--schema': {
+            type: 'boolean',
+            default: false,
+            description: 'Output this schema as JSON'
+          }
+        },
+        output: {
+          json: {
+            description: 'Structured scan results when --json is used',
+            schema: {
+              type: 'object',
+              properties: {
+                mpxScan: {
+                  type: 'object',
+                  properties: {
+                    version: { type: 'string' },
+                    scannedAt: { type: 'string', format: 'date-time' },
+                    scanDuration: { type: 'number', description: 'Duration in milliseconds' }
+                  }
+                },
+                target: {
+                  type: 'object',
+                  properties: {
+                    url: { type: 'string' },
+                    hostname: { type: 'string' }
+                  }
+                },
+                score: {
+                  type: 'object',
+                  properties: {
+                    grade: { type: 'string', enum: ['A+', 'A', 'B', 'C', 'D', 'F'] },
+                    numeric: { type: 'number' },
+                    maxScore: { type: 'number' },
+                    percentage: { type: 'number', minimum: 0, maximum: 100 }
+                  }
+                },
+                summary: {
+                  type: 'object',
+                  properties: {
+                    passed: { type: 'number' },
+                    warnings: { type: 'number' },
+                    failed: { type: 'number' },
+                    info: { type: 'number' }
+                  }
+                },
+                sections: { type: 'object', description: 'Per-scanner results keyed by scanner name' },
+                tier: { type: 'string', enum: ['free', 'pro'] }
+              }
+            }
+          },
+          error: {
+            description: 'Error response when scan fails',
+            schema: {
+              type: 'object',
+              properties: {
+                error: { type: 'string' },
+                code: { type: 'string', enum: ['ERR_NETWORK', 'ERR_SCAN', 'ERR_RATE_LIMIT', 'ERR_PRO_REQUIRED', 'ERR_NO_INPUT'] }
+              }
+            }
+          }
+        },
+        exitCodes: {
+          0: 'Success, no security issues found',
+          1: 'Success, security issues found',
+          2: 'Invalid arguments',
+          3: 'Configuration error (license, rate limit)',
+          4: 'Network/connectivity error'
+        },
+        examples: [
+          { command: 'mpx-scan https://example.com --json', description: 'Scan with JSON output' },
+          { command: 'mpx-scan https://example.com --json --full', description: 'Full scan with JSON (Pro)' },
+          { command: 'cat urls.txt | mpx-scan --batch --json', description: 'Batch scan from stdin' },
+          { command: 'mpx-scan https://example.com --fix nginx', description: 'Get nginx fix config' }
+        ]
+      },
+      mcp: {
+        description: 'Start MCP (Model Context Protocol) stdio server for AI agent integration',
+        usage: 'mpx-scan mcp',
+        arguments: {},
+        flags: {},
+        examples: [
+          { command: 'mpx-scan mcp', description: 'Start MCP stdio server' }
+        ]
+      },
+      license: {
+        description: 'Show current license status',
+        usage: 'mpx-scan license'
+      },
+      activate: {
+        description: 'Activate a Pro license key',
+        usage: 'mpx-scan activate <key>',
+        arguments: {
+          key: { type: 'string', required: true, description: 'License key (MPX-PRO-...)' }
+        }
+      },
+      deactivate: {
+        description: 'Deactivate Pro license and return to free tier',
+        usage: 'mpx-scan deactivate'
+      }
+    },
+    scanners: {
+      free: SCANNER_TIERS.free,
+      pro: SCANNER_TIERS.pro
+    },
+    mcpConfig: {
+      description: 'Add to your MCP client configuration to use mpx-scan as an AI tool',
+      config: {
+        mcpServers: {
+          'mpx-scan': {
+            command: 'npx',
+            args: ['mpx-scan', 'mcp']
+          }
+        }
+      }
+    }
+  };
+}
+
+module.exports = { getSchema };