mpx-db 1.0.3 → 1.1.0

package/README.md

@@ -13,6 +13,7 @@ Stop juggling multiple database tools. `mpx-db` gives you one clean interface fo
 ✅ **Schema operations** — Dump, describe, visualize database structure  
 ✅ **Data export** — Export to JSON/CSV with one command  
 ✅ **Secure** — Encrypted credential storage  
+✅ **AI-native** — JSON output, MCP server, schema discovery for AI agents  
 
 ## Installation
 
@@ -224,6 +225,135 @@ mpx-db migrate create add_order_status_field
 mpx-db export dev orders --format csv --output orders-backup.csv
 ```
 
+## AI Agent Usage
+
+`mpx-db` is **AI-native** — designed for both humans and AI agents. Every command supports machine-readable output and schema discovery.
+
+### JSON Output
+
+Add `--json` to any command for structured output:
+
+```bash
+# Query with JSON output
+mpx-db query dev "SELECT * FROM users LIMIT 3" --json
+{
+  "success": true,
+  "type": "query",
+  "rows": [
+    { "id": 1, "name": "Alice", "email": "alice@example.com" },
+    { "id": 2, "name": "Bob", "email": "bob@example.com" },
+    { "id": 3, "name": "Charlie", "email": "charlie@example.com" }
+  ],
+  "rowCount": 3,
+  "duration": 12
+}
+
+# List tables with JSON
+mpx-db tables dev --json
+{
+  "tables": [
+    { "name": "users", "type": "table", "rowCount": 150 },
+    { "name": "orders", "type": "table", "rowCount": 892 }
+  ]
+}
+
+# Migration status
+mpx-db migrate status dev --json
+{
+  "migrations": [
+    { "name": "20260215_100000_create_users", "status": "applied", "appliedAt": "2026-02-15T10:05:00.000Z" },
+    { "name": "20260216_120000_add_orders", "status": "pending", "appliedAt": null }
+  ]
+}
+```
+
+### Schema Discovery
+
+Get the full command schema for AI agent integration:
+
+```bash
+mpx-db --schema
+```
+
+Returns a comprehensive JSON schema describing all commands, flags, inputs, outputs, and examples.
+
+### MCP (Model Context Protocol) Server
+
+Run `mpx-db` as an MCP server for seamless AI agent integration:
+
+```bash
+mpx-db mcp
+```
+
+#### Claude Desktop Integration
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "mpx-db": {
+      "command": "npx",
+      "args": ["mpx-db", "mcp"]
+    }
+  }
+}
+```
+
+Now Claude can directly query your databases, inspect schemas, and run migrations!
+
+#### Available MCP Tools
+
+- `query` — Execute SQL queries
+- `list_tables` — Get all tables with row counts
+- `describe_table` — Show table schema
+- `get_info` — Database information
+- `export_table` — Export table data as JSON
+- `get_schema` — Get full command schema
+
+### Quiet Mode
+
+Suppress non-essential output with `--quiet`:
+
+```bash
+# Just the data, no banners or progress messages
+mpx-db query dev "SELECT COUNT(*) FROM users" --quiet --json
+```
+
+### Exit Codes
+
+Predictable exit codes for CI/CD and scripting:
+
+- `0` — Success
+- `1` — Error (connection failed, query failed, etc.)
+
+```bash
+#!/bin/bash
+if mpx-db query dev "SELECT 1" --quiet; then
+  echo "Database is up"
+else
+  echo "Database is down"
+  exit 1
+fi
+```
+
+### Example: AI Agent Workflow
+
+```javascript
+// AI agent discovers available commands
+const schema = await exec('mpx-db --schema');
+
+// Agent queries database
+const result = await exec('mpx-db query dev "SELECT * FROM orders WHERE status = \'pending\'" --json');
+const orders = JSON.parse(result.stdout);
+
+// Agent inspects schema
+const tables = await exec('mpx-db tables dev --json');
+
+// Agent runs migration
+await exec('mpx-db migrate up dev --json --quiet');
+```
+
 ## Architecture
 
 ```
@@ -310,15 +440,18 @@ Test suite includes:
 
 ## Roadmap
 
-**v1.0 (Current)** ✅
+**v1.1 (Current)** ✅
 - SQLite, PostgreSQL, MySQL support
 - Connection management
 - Query execution with beautiful output
 - Schema inspection (dump, describe, tables, info)
 - Migration system (create, up, down, status)
 - Data export (JSON, CSV)
+- **AI-native features:** JSON output (`--json`), schema discovery (`--schema`), MCP server mode
+- **Quiet mode** (`--quiet`) for scripting
+- Predictable exit codes
 
-**v1.1 (Planned)**
+**v1.2 (Planned)**
 - Interactive query REPL mode
 - Query history and favorites
 - Auto-complete for table/column names

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mpx-db",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Database management CLI - Connect, query, migrate, and manage databases from the terminal",
   "main": "src/index.js",
   "bin": {
@@ -20,7 +20,12 @@
     "mysql",
     "sqlite",
     "schema",
-    "sql"
+    "sql",
+    "mcp",
+    "ai-native",
+    "model-context-protocol",
+    "automation",
+    "json-output"
   ],
   "author": "Mesaplex <support@mesaplex.com>",
   "license": "MIT",
@@ -34,6 +39,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "better-sqlite3": "^12.6.2",
     "chalk": "^5.3.0",
     "cli-table3": "^0.6.5",

package/src/cli.js

@@ -14,6 +14,7 @@ import {
   rollbackMigration 
 } from './commands/migrate.js';
 import { exportData } from './commands/data.js';
+import { getSchema } from './schema.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -21,10 +22,27 @@ const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8')
 
 const program = new Command();
 
+// Global options state (passed to commands via options parameter)
+let globalOptions = {};
+
 program
   .name('mpx-db')
   .description('Database management CLI - Connect, query, migrate, and manage databases')
-  .version(pkg.version);
+  .version(pkg.version)
+  .option('--json', 'Output as JSON (machine-readable)')
+  .option('-q, --quiet', 'Suppress non-essential output')
+  .option('--schema', 'Output JSON schema describing all commands and flags')
+  .hook('preAction', (thisCommand) => {
+    // Merge parent options with command options
+    const parentOpts = thisCommand.parent?.opts() || {};
+    const opts = thisCommand.opts();
+    globalOptions = { ...parentOpts, ...opts };
+    
+    // Disable chalk if JSON mode
+    if (globalOptions.json) {
+      chalk.level = 0;
+    }
+  });
 
 // Connect command
 program
@@ -32,7 +50,7 @@ program
   .description('Test and optionally save a database connection')
   .argument('<url>', 'Connection URL (sqlite://, postgres://, mysql://)')
   .option('-s, --save <name>', 'Save connection with a name')
-  .action(handleConnect);
+  .action((url, options) => handleConnect(url, { ...globalOptions, ...options }));
 
 // Connections command
 const connections = program
@@ -42,13 +60,13 @@ const connections = program
 connections
   .command('list')
   .description('List all saved connections')
-  .action(listConnections);
+  .action(() => listConnections(globalOptions));
 
 connections
   .command('remove')
   .description('Remove a saved connection')
   .argument('<name>', 'Connection name')
-  .action(removeConnection);
+  .action((name) => removeConnection(name, globalOptions));
 
 // Query command
 program
@@ -56,21 +74,21 @@ program
   .description('Execute a SQL query')
   .argument('<target>', 'Connection name or URL')
   .argument('<sql>', 'SQL query to execute')
-  .action(handleQuery);
+  .action((target, sql) => handleQuery(target, sql, globalOptions));
 
 // Info command
 program
   .command('info')
   .description('Show database information')
   .argument('<target>', 'Connection name or URL')
-  .action(showInfo);
+  .action((target) => showInfo(target, globalOptions));
 
 // Tables command
 program
   .command('tables')
   .description('List all tables')
   .argument('<target>', 'Connection name or URL')
-  .action(listTables);
+  .action((target) => listTables(target, globalOptions));
 
 // Describe command
 program
@@ -78,7 +96,7 @@ program
   .description('Show table schema')
   .argument('<target>', 'Connection name or URL')
   .argument('<table>', 'Table name')
-  .action(describeTable);
+  .action((target, table) => describeTable(target, table, globalOptions));
 
 // Schema commands
 const schema = program
@@ -89,7 +107,7 @@ schema
   .command('dump')
   .description('Dump database schema as SQL')
   .argument('<target>', 'Connection name or URL')
-  .action(dumpSchema);
+  .action((target) => dumpSchema(target, globalOptions));
 
 // Migration commands
 const migrate = program
@@ -99,31 +117,31 @@ const migrate = program
 migrate
   .command('init')
   .description('Initialize migrations directory')
-  .action(initMigrations);
+  .action(() => initMigrations(globalOptions));
 
 migrate
   .command('create')
   .description('Create a new migration file')
   .argument('<description>', 'Migration description')
-  .action(createMigration);
+  .action((description) => createMigration(description, globalOptions));
 
 migrate
   .command('status')
   .description('Show migration status')
   .argument('<target>', 'Connection name or URL')
-  .action(showMigrationStatus);
+  .action((target) => showMigrationStatus(target, globalOptions));
 
 migrate
   .command('up')
   .description('Run pending migrations')
   .argument('<target>', 'Connection name or URL')
-  .action(runMigrations);
+  .action((target) => runMigrations(target, globalOptions));
 
 migrate
   .command('down')
   .description('Rollback last migration')
   .argument('<target>', 'Connection name or URL')
-  .action(rollbackMigration);
+  .action((target) => rollbackMigration(target, globalOptions));
 
 // Export command
 program
@@ -133,7 +151,27 @@ program
   .argument('<table>', 'Table name')
   .option('-f, --format <format>', 'Output format (json, csv)', 'json')
   .option('-o, --output <file>', 'Output file path')
-  .action(exportData);
+  .action((target, table, options) => exportData(target, table, { ...globalOptions, ...options }));
+
+// MCP subcommand
+program
+  .command('mcp')
+  .description('Start MCP (Model Context Protocol) stdio server')
+  .action(async () => {
+    try {
+      const { startMCPServer } = await import('./mcp.js');
+      await startMCPServer();
+    } catch (err) {
+      console.error(JSON.stringify({ error: err.message, code: 'ERR_MCP_START' }));
+      process.exit(1);
+    }
+  });
+
+// Handle --schema before parsing (to avoid argument validation)
+if (process.argv.includes('--schema')) {
+  console.log(JSON.stringify(getSchema(), null, 2));
+  process.exit(0);
+}
 
 // Error handling
 program.exitOverride();

package/src/commands/connections.js

@@ -6,14 +6,40 @@ import { createConnection } from '../db/connection.js';
 /**
  * Handle connect command
  */
-export async function handleConnect(url, options) {
+export async function handleConnect(url, options = {}) {
   try {
     // Test connection
-    console.log(chalk.gray('Testing connection...'));
+    if (!options.quiet && !options.json) {
+      console.log(chalk.gray('Testing connection...'));
+    }
+    
     const db = await createConnection(url);
     const info = await db.getInfo();
     await db.disconnect();
     
+    // Save if requested
+    let saved = false;
+    if (options.save) {
+      saveConnection(options.save, url);
+      saved = true;
+    }
+    
+    // JSON output
+    if (options.json) {
+      console.log(JSON.stringify({
+        success: true,
+        connection: {
+          type: info.type,
+          database: info.database,
+          path: info.path
+        },
+        saved,
+        name: options.save || null
+      }, null, 2));
+      return;
+    }
+    
+    // Human-readable output
     console.log(chalk.green('✓ Connection successful'));
     console.log(chalk.gray(`  Type: ${info.type}`));
     if (info.database) {
@@ -23,15 +49,17 @@ export async function handleConnect(url, options) {
       console.log(chalk.gray(`  Path: ${info.path}`));
     }
     
-    // Save if requested
     if (options.save) {
-      saveConnection(options.save, url);
       console.log(chalk.green(`✓ Saved connection as "${options.save}"`));
     }
     
   } catch (err) {
-    console.error(chalk.red('✗ Connection failed'));
-    console.error(chalk.red(`  ${err.message}`));
+    if (options.json) {
+      console.log(JSON.stringify({ success: false, error: err.message }, null, 2));
+    } else {
+      console.error(chalk.red('✗ Connection failed'));
+      console.error(chalk.red(`  ${err.message}`));
+    }
     process.exit(1);
   }
 }
@@ -39,13 +67,27 @@ export async function handleConnect(url, options) {
 /**
  * List saved connections
  */
-export async function listConnections() {
+export async function listConnections(options = {}) {
   const connections = loadConnections();
   
+  // JSON output
+  if (options.json) {
+    const connArray = Object.entries(connections).map(([name, conn]) => ({
+      name,
+      type: conn.type,
+      createdAt: new Date(conn.createdAt).toISOString()
+    }));
+    console.log(JSON.stringify({ connections: connArray }, null, 2));
+    return;
+  }
+  
+  // Human-readable output
   if (Object.keys(connections).length === 0) {
     console.log(chalk.yellow('No saved connections'));
-    console.log(chalk.gray('\nSave a connection with:'));
-    console.log(chalk.gray('  mpx-db connect --save <name> <url>'));
+    if (!options.quiet) {
+      console.log(chalk.gray('\nSave a connection with:'));
+      console.log(chalk.gray('  mpx-db connect --save <name> <url>'));
+    }
     return;
   }
   
@@ -68,9 +110,20 @@ export async function listConnections() {
 /**
  * Delete a saved connection
  */
-export async function removeConnection(name) {
+export async function removeConnection(name, options = {}) {
   const deleted = deleteConnection(name);
   
+  // JSON output
+  if (options.json) {
+    console.log(JSON.stringify({
+      success: deleted,
+      name,
+      message: deleted ? 'Connection deleted' : 'Connection not found'
+    }, null, 2));
+    return;
+  }
+  
+  // Human-readable output
   if (deleted) {
     console.log(chalk.green(`✓ Deleted connection "${name}"`));
   } else {

package/src/commands/data.js

@@ -6,7 +6,7 @@ import { resolveConnection } from './query.js';
 /**
  * Export table data to CSV or JSON
  */
-export async function exportData(target, tableName, options) {
+export async function exportData(target, tableName, options = {}) {
   let db;
   
   try {
@@ -17,12 +17,14 @@ export async function exportData(target, tableName, options) {
     const rows = await db.query(`SELECT * FROM ${tableName}`);
     
     if (rows.length === 0) {
-      console.log(chalk.yellow('No data to export'));
+      if (!options.quiet) {
+        console.log(chalk.yellow('No data to export'));
+      }
       return;
     }
     
     const format = options.format || 'json';
-    const output = options.output || `${tableName}.${format}`;
+    const output = options.output;
     
     let content;
     
@@ -34,12 +36,23 @@ export async function exportData(target, tableName, options) {
       throw new Error(`Unsupported format: ${format}`);
     }
     
-    fs.writeFileSync(output, content);
-    
-    console.log(chalk.green(`✓ Exported ${rows.length} rows to ${output}`));
+    // If output file specified, write to file
+    if (output) {
+      fs.writeFileSync(output, content);
+      if (!options.quiet) {
+        console.log(chalk.green(`✓ Exported ${rows.length} rows to ${output}`));
+      }
+    } else {
+      // Write to stdout
+      console.log(content);
+    }
     
   } catch (err) {
-    console.error(chalk.red(`✗ Export failed: ${err.message}`));
+    if (options.json) {
+      console.log(JSON.stringify({ error: err.message }, null, 2));
+    } else {
+      console.error(chalk.red(`✗ Export failed: ${err.message}`));
+    }
     process.exit(1);
   } finally {
     if (db) {