@sigma4life/mysql-mcp-server 1.0.0

package/dist/mysql/queries.js

@@ -0,0 +1,206 @@
+import { appConfig } from '../core/config.js';
+import { db } from './connection.js';
+import { likePattern } from './identifiers.js';
+export async function listTables(tableNames) {
+    const tableFilter = tableNames?.length
+        ? 'AND t.TABLE_NAME IN (:tableNames)'
+        : '';
+    return db.query(`
+SELECT
+  t.TABLE_SCHEMA AS schemaName,
+  t.TABLE_NAME AS tableName,
+  t.TABLE_TYPE AS tableType,
+  t.CREATE_TIME AS createDate,
+  t.TABLE_ROWS AS rowCount
+FROM information_schema.TABLES t
+WHERE t.TABLE_SCHEMA = :database
+  AND t.TABLE_TYPE IN ('BASE TABLE', 'VIEW')
+  ${tableFilter}
+ORDER BY t.TABLE_NAME
+`, { database: appConfig.db.name, tableNames });
+}
+export async function getColumns(tableNames) {
+    const tableFilter = tableNames?.length
+        ? 'AND c.TABLE_NAME IN (:tableNames)'
+        : '';
+    return db.query(`
+SELECT
+  c.COLUMN_NAME AS name,
+  c.ORDINAL_POSITION AS ordinal,
+  c.COLUMN_TYPE AS dataType,
+  CASE WHEN c.IS_NULLABLE = 'YES' THEN true ELSE false END AS nullable,
+  CASE WHEN c.EXTRA LIKE '%auto_increment%' THEN true ELSE false END AS isIdentity,
+  CASE WHEN c.EXTRA LIKE '%VIRTUAL GENERATED%' OR c.EXTRA LIKE '%STORED GENERATED%' THEN true ELSE false END AS isComputed,
+  c.COLUMN_DEFAULT AS defaultValue,
+  c.COLUMN_COMMENT AS description,
+  CASE WHEN kcu.CONSTRAINT_NAME = 'PRIMARY' THEN true ELSE false END AS isPrimaryKey,
+  CASE WHEN fk.CONSTRAINT_NAME IS NOT NULL THEN true ELSE false END AS isForeignKey,
+  c.TABLE_SCHEMA AS \`schema\`,
+  c.TABLE_NAME AS tableName
+FROM information_schema.COLUMNS c
+LEFT JOIN information_schema.KEY_COLUMN_USAGE kcu
+  ON kcu.TABLE_SCHEMA = c.TABLE_SCHEMA
+  AND kcu.TABLE_NAME = c.TABLE_NAME
+  AND kcu.COLUMN_NAME = c.COLUMN_NAME
+  AND kcu.CONSTRAINT_NAME = 'PRIMARY'
+LEFT JOIN information_schema.KEY_COLUMN_USAGE fk
+  ON fk.TABLE_SCHEMA = c.TABLE_SCHEMA
+  AND fk.TABLE_NAME = c.TABLE_NAME
+  AND fk.COLUMN_NAME = c.COLUMN_NAME
+  AND fk.REFERENCED_TABLE_NAME IS NOT NULL
+WHERE c.TABLE_SCHEMA = :database
+  ${tableFilter}
+ORDER BY c.TABLE_NAME, c.ORDINAL_POSITION
+`, { database: appConfig.db.name, tableNames });
+}
+export async function getPrimaryKeys(tableNames) {
+    const tableFilter = tableNames?.length
+        ? 'AND kcu.TABLE_NAME IN (:tableNames)'
+        : '';
+    return db.query(`
+SELECT
+  kcu.TABLE_NAME AS tableName,
+  kcu.CONSTRAINT_NAME AS constraintName,
+  GROUP_CONCAT(kcu.COLUMN_NAME ORDER BY kcu.ORDINAL_POSITION SEPARATOR ',') AS columns
+FROM information_schema.KEY_COLUMN_USAGE kcu
+WHERE kcu.TABLE_SCHEMA = :database
+  AND kcu.CONSTRAINT_NAME = 'PRIMARY'
+  ${tableFilter}
+GROUP BY kcu.TABLE_NAME, kcu.CONSTRAINT_NAME
+`, { database: appConfig.db.name, tableNames });
+}
+export async function getForeignKeys(tableNames) {
+    const tableFilter = tableNames?.length
+        ? 'AND kcu.TABLE_NAME IN (:tableNames)'
+        : '';
+    return db.query(`
+SELECT
+  kcu.TABLE_NAME AS tableName,
+  kcu.CONSTRAINT_NAME AS constraintName,
+  kcu.TABLE_SCHEMA AS fromSchema,
+  kcu.TABLE_NAME AS fromTable,
+  GROUP_CONCAT(kcu.COLUMN_NAME ORDER BY kcu.ORDINAL_POSITION SEPARATOR ',') AS fromColumns,
+  kcu.REFERENCED_TABLE_SCHEMA AS toSchema,
+  kcu.REFERENCED_TABLE_NAME AS toTable,
+  GROUP_CONCAT(kcu.REFERENCED_COLUMN_NAME ORDER BY kcu.ORDINAL_POSITION SEPARATOR ',') AS toColumns,
+  rc.DELETE_RULE AS onDelete,
+  rc.UPDATE_RULE AS onUpdate
+FROM information_schema.KEY_COLUMN_USAGE kcu
+JOIN information_schema.REFERENTIAL_CONSTRAINTS rc
+  ON rc.CONSTRAINT_SCHEMA = kcu.CONSTRAINT_SCHEMA
+  AND rc.CONSTRAINT_NAME = kcu.CONSTRAINT_NAME
+WHERE kcu.TABLE_SCHEMA = :database
+  AND kcu.REFERENCED_TABLE_NAME IS NOT NULL
+  ${tableFilter}
+GROUP BY
+  kcu.TABLE_NAME,
+  kcu.CONSTRAINT_NAME,
+  kcu.TABLE_SCHEMA,
+  kcu.REFERENCED_TABLE_SCHEMA,
+  kcu.REFERENCED_TABLE_NAME,
+  rc.DELETE_RULE,
+  rc.UPDATE_RULE
+`, { database: appConfig.db.name, tableNames });
+}
+export async function getIndexes(tableNames) {
+    const tableFilter = tableNames?.length
+        ? 'AND s.TABLE_NAME IN (:tableNames)'
+        : '';
+    return db.query(`
+SELECT
+  s.TABLE_NAME AS tableName,
+  s.INDEX_NAME AS name,
+  s.INDEX_TYPE AS type,
+  CASE WHEN s.NON_UNIQUE = 0 THEN true ELSE false END AS isUnique,
+  CASE WHEN s.INDEX_NAME = 'PRIMARY' THEN true ELSE false END AS isPrimaryKey,
+  GROUP_CONCAT(s.COLUMN_NAME ORDER BY s.SEQ_IN_INDEX SEPARATOR ',') AS columns
+FROM information_schema.STATISTICS s
+WHERE s.TABLE_SCHEMA = :database
+  ${tableFilter}
+GROUP BY s.TABLE_NAME, s.INDEX_NAME, s.INDEX_TYPE, s.NON_UNIQUE
+`, { database: appConfig.db.name, tableNames });
+}
+export async function getStatistics(tableNames) {
+    const tableFilter = tableNames?.length
+        ? 'AND t.TABLE_NAME IN (:tableNames)'
+        : '';
+    return db.query(`
+SELECT
+  t.TABLE_NAME AS tableName,
+  t.TABLE_ROWS AS rowCount,
+  ROUND(((t.DATA_LENGTH + t.INDEX_LENGTH) / 1024), 0) AS totalSizeKB,
+  ROUND((t.DATA_LENGTH / 1024), 0) AS usedSizeKB
+FROM information_schema.TABLES t
+WHERE t.TABLE_SCHEMA = :database
+  ${tableFilter}
+`, { database: appConfig.db.name, tableNames });
+}
+export async function findTables(pattern, hasColumn) {
+    const params = {
+        database: appConfig.db.name,
+        pattern: likePattern(pattern),
+        hasColumn: likePattern(hasColumn),
+    };
+    return db.query(`
+SELECT DISTINCT
+  t.TABLE_SCHEMA AS schemaName,
+  t.TABLE_NAME AS tableName,
+  t.TABLE_ROWS AS rowCount,
+  t.CREATE_TIME AS createDate
+FROM information_schema.TABLES t
+${hasColumn ? `JOIN information_schema.COLUMNS c
+  ON c.TABLE_SCHEMA = t.TABLE_SCHEMA AND c.TABLE_NAME = t.TABLE_NAME` : ''}
+WHERE t.TABLE_SCHEMA = :database
+  AND t.TABLE_TYPE IN ('BASE TABLE', 'VIEW')
+  ${pattern ? 'AND t.TABLE_NAME LIKE :pattern' : ''}
+  ${hasColumn ? 'AND c.COLUMN_NAME LIKE :hasColumn' : ''}
+ORDER BY t.TABLE_NAME
+LIMIT 100
+`, params);
+}
+export async function searchObjects(search, type) {
+    const pattern = likePattern(search) || `%${search}%`;
+    const includeTables = !type || type === 'table';
+    const includeColumns = !type || type === 'column';
+    const parts = [];
+    if (includeTables) {
+        parts.push(`
+SELECT t.TABLE_SCHEMA AS schemaName, t.TABLE_NAME AS tableName, NULL AS columnName
+FROM information_schema.TABLES t
+WHERE t.TABLE_SCHEMA = :database
+  AND t.TABLE_NAME LIKE :pattern`);
+    }
+    if (includeColumns) {
+        parts.push(`
+SELECT c.TABLE_SCHEMA AS schemaName, c.TABLE_NAME AS tableName, c.COLUMN_NAME AS columnName
+FROM information_schema.COLUMNS c
+WHERE c.TABLE_SCHEMA = :database
+  AND c.COLUMN_NAME LIKE :pattern`);
+    }
+    if (parts.length === 0) {
+        return [];
+    }
+    return db.query(`${parts.join('\nUNION ALL\n')}\nORDER BY tableName, columnName\nLIMIT 100`, { database: appConfig.db.name, pattern });
+}
+export async function getRelationships() {
+    return db.query(`
+SELECT
+  kcu.TABLE_SCHEMA AS fromSchema,
+  kcu.TABLE_NAME AS fromTable,
+  kcu.COLUMN_NAME AS fromColumn,
+  kcu.REFERENCED_TABLE_SCHEMA AS toSchema,
+  kcu.REFERENCED_TABLE_NAME AS toTable,
+  kcu.REFERENCED_COLUMN_NAME AS toColumn,
+  kcu.CONSTRAINT_NAME AS constraintName,
+  rc.DELETE_RULE AS deleteAction,
+  rc.UPDATE_RULE AS updateAction
+FROM information_schema.KEY_COLUMN_USAGE kcu
+JOIN information_schema.REFERENTIAL_CONSTRAINTS rc
+  ON rc.CONSTRAINT_SCHEMA = kcu.CONSTRAINT_SCHEMA
+  AND rc.CONSTRAINT_NAME = kcu.CONSTRAINT_NAME
+WHERE kcu.TABLE_SCHEMA = :database
+  AND kcu.REFERENCED_TABLE_NAME IS NOT NULL
+ORDER BY kcu.TABLE_NAME, kcu.ORDINAL_POSITION
+`, { database: appConfig.db.name });
+}
+//# sourceMappingURL=queries.js.map

package/dist/mysql/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../src/mysql/queries.ts"],"names":[],"mappings":"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"}

package/docs/clients/claude-code.md

@@ -0,0 +1,28 @@
+# Claude Code
+
+Add the server as a local stdio MCP:
+
+```bash
+claude mcp add --transport stdio mysql \
+  --env DATABASE_URL=mysql://mcp_reader:password@localhost:3306/app_db \
+  -- npx -y @sigma4life/mysql-mcp-server
+```
+
+For read-query support, also pass:
+
+```bash
+--env SCHEMA_ONLY_MODE=false \
+--env QUERY_ACCESS_CONFIG=/absolute/path/to/query-access.json
+```
+
+Check status inside Claude Code:
+
+```text
+/mcp
+```
+
+Try:
+
+```text
+Use mysql to show me the tables in this database.
+```

package/docs/clients/claude-desktop.md

@@ -0,0 +1,35 @@
+# Claude Desktop
+
+Add this to your Claude Desktop MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": ["-y", "@sigma4life/mysql-mcp-server"],
+      "env": {
+        "DATABASE_URL": "mysql://mcp_reader:password@localhost:3306/app_db",
+        "SCHEMA_ONLY_MODE": "true"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing the config.
+
+For read-query support, set:
+
+```json
+{
+  "SCHEMA_ONLY_MODE": "false",
+  "QUERY_ACCESS_CONFIG": "/absolute/path/to/query-access.json"
+}
+```
+
+Try:
+
+```text
+Show me the schema for customers and orders.
+```

package/docs/clients/codex.md

@@ -0,0 +1,28 @@
+# Codex
+
+Add the server as a local stdio MCP:
+
+```bash
+codex mcp add mysql \
+  --env DATABASE_URL=mysql://mcp_reader:password@localhost:3306/app_db \
+  -- npx -y @sigma4life/mysql-mcp-server
+```
+
+Verify:
+
+```bash
+codex mcp list
+```
+
+For read-query support, also pass:
+
+```bash
+--env SCHEMA_ONLY_MODE=false \
+--env QUERY_ACCESS_CONFIG=/absolute/path/to/query-access.json
+```
+
+Try:
+
+```text
+Use mysql to find tables with an email column.
+```

package/docs/clients/cursor.md

@@ -0,0 +1,26 @@
+# Cursor
+
+Create or update `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": ["-y", "@sigma4life/mysql-mcp-server"],
+      "env": {
+        "DATABASE_URL": "mysql://mcp_reader:password@localhost:3306/app_db",
+        "SCHEMA_ONLY_MODE": "true"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor after editing the config.
+
+Try:
+
+```text
+Use mysql to show me the database tables.
+```

package/docs/clients/opencode.md

@@ -0,0 +1,35 @@
+# OpenCode
+
+Add a local MCP server to `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "mysql": {
+      "type": "local",
+      "command": ["npx", "-y", "@sigma4life/mysql-mcp-server"],
+      "enabled": true,
+      "environment": {
+        "DATABASE_URL": "mysql://mcp_reader:password@localhost:3306/app_db",
+        "SCHEMA_ONLY_MODE": "true"
+      }
+    }
+  }
+}
+```
+
+For read-query support, add:
+
+```json
+{
+  "SCHEMA_ONLY_MODE": "false",
+  "QUERY_ACCESS_CONFIG": "/absolute/path/to/query-access.json"
+}
+```
+
+Try:
+
+```text
+Use the mysql tool to show relationships from orders.
+```

package/docs/clients/vscode.md

@@ -0,0 +1,25 @@
+# VS Code
+
+Create `.vscode/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "mysql": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@sigma4life/mysql-mcp-server"],
+      "env": {
+        "DATABASE_URL": "mysql://mcp_reader:password@localhost:3306/app_db",
+        "SCHEMA_ONLY_MODE": "true"
+      }
+    }
+  }
+}
+```
+
+Try:
+
+```text
+Use mysql to inspect the customers table.
+```

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@sigma4life/mysql-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for MySQL schema introspection and guarded read-only queries",
+  "main": "dist/index.js",
+  "bin": {
+    "mysql-mcp-server": "dist/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js serve",
+    "test": "npm run build && node --test dist/**/*.test.js",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts"
+  },
+  "keywords": [
+    "mcp",
+    "mysql",
+    "database",
+    "schema",
+    "ai"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "dotenv": "^16.4.7",
+    "mysql2": "^3.12.0",
+    "node-sql-parser": "^5.3.6",
+    "winston": "^3.17.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.20.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "eslint": "^9.18.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/query-access.example.json

@@ -0,0 +1,21 @@
+{
+  "requireExplicitColumns": true,
+  "databases": {
+    "app_db": {
+      "tables": {
+        "mode": "whitelist",
+        "list": ["customers", "orders", "products", "order_items"],
+        "columnAccess": {
+          "customers": {
+            "mode": "exclusion",
+            "columns": ["password_hash", "api_token"]
+          },
+          "orders": {
+            "mode": "inclusion",
+            "columns": ["id", "customer_id", "status", "total", "created_at"]
+          }
+        }
+      }
+    }
+  }
+}

package/src/cli.ts

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { maskDatabaseUrl } from './core/database-url.js';
+
+const DEFAULT_DATABASE_URL = 'mysql://mcp_reader:change_me@localhost:3306/app_db';
+
+function usage(): void {
+  console.log(`mysql-mcp-server
+
+Usage:
+  mysql-mcp-server                 Start the MCP stdio server
+  mysql-mcp-server serve           Start the MCP stdio server
+  mysql-mcp-server doctor          Check configuration and database connectivity
+  mysql-mcp-server init [--force]  Create starter .env, query-access.json, and client snippets
+
+Environment:
+  DATABASE_URL=mysql://user:password@host:3306/database
+`);
+}
+
+function writeFileIfMissing(filePath: string, content: string, force: boolean): 'created' | 'skipped' {
+  if (fs.existsSync(filePath) && !force) {
+    return 'skipped';
+  }
+  fs.writeFileSync(filePath, content);
+  return 'created';
+}
+
+function envTemplate(): string {
+  return `# One-line setup. Individual DB_* variables may override parts of this URL.
+DATABASE_URL=${DEFAULT_DATABASE_URL}
+
+# Safer first-run default: schema tools only. Set false to enable execute_query.
+SCHEMA_ONLY_MODE=true
+
+# Required only when SCHEMA_ONLY_MODE=false.
+# QUERY_ACCESS_CONFIG=${path.resolve('query-access.json')}
+
+MAX_QUERY_ROWS=100
+QUERY_TIMEOUT_MS=30000
+MCP_SERVER_NAME=mysql-mcp-server
+MCP_SERVER_VERSION=1.0.0
+LOG_LEVEL=info
+LOG_FILE=mcp-server.log
+`;
+}
+
+function queryAccessTemplate(): string {
+  return JSON.stringify(
+    {
+      requireExplicitColumns: true,
+      databases: {
+        app_db: {
+          tables: {
+            mode: 'whitelist',
+            list: ['customers', 'orders', 'products', 'order_items'],
+            columnAccess: {
+              customers: {
+                mode: 'exclusion',
+                columns: ['password_hash', 'api_token'],
+              },
+            },
+          },
+        },
+      },
+    },
+    null,
+    2,
+  ) + '\n';
+}
+
+function clientSnippetsTemplate(): string {
+  return `# mysql-mcp-server client snippets
+
+Replace the sample DATABASE_URL with your real MySQL connection string.
+
+## Claude Code
+
+\`\`\`bash
+claude mcp add --transport stdio mysql \\
+  --env DATABASE_URL=${DEFAULT_DATABASE_URL} \\
+  -- npx -y @sigma4life/mysql-mcp-server
+\`\`\`
+
+## Codex
+
+\`\`\`bash
+codex mcp add mysql \\
+  --env DATABASE_URL=${DEFAULT_DATABASE_URL} \\
+  -- npx -y @sigma4life/mysql-mcp-server
+\`\`\`
+
+## Claude Desktop
+
+\`\`\`json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": ["-y", "@sigma4life/mysql-mcp-server"],
+      "env": {
+        "DATABASE_URL": "${DEFAULT_DATABASE_URL}"
+      }
+    }
+  }
+}
+\`\`\`
+
+## OpenCode
+
+\`\`\`json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "mysql": {
+      "type": "local",
+      "command": ["npx", "-y", "@sigma4life/mysql-mcp-server"],
+      "enabled": true,
+      "environment": {
+        "DATABASE_URL": "${DEFAULT_DATABASE_URL}"
+      }
+    }
+  }
+}
+\`\`\`
+`;
+}
+
+async function runInit(args: string[]): Promise<void> {
+  const force = args.includes('--force');
+  const files = [
+    ['.env', envTemplate()],
+    ['query-access.json', queryAccessTemplate()],
+    ['mysql-mcp-clients.md', clientSnippetsTemplate()],
+  ] as const;
+
+  for (const [file, content] of files) {
+    const status = writeFileIfMissing(path.resolve(file), content, force);
+    console.log(`${status === 'created' ? 'created' : 'skipped'} ${file}`);
+  }
+
+  console.log('\nNext steps:');
+  console.log('1. Edit .env with your MySQL credentials.');
+  console.log('2. Run: mysql-mcp-server doctor');
+  console.log('3. Add one of the snippets from mysql-mcp-clients.md to your MCP client.');
+}
+
+async function runDoctor(): Promise<void> {
+  console.log('mysql-mcp-server doctor\n');
+
+  try {
+    const { appConfig } = await import('./core/config.js');
+    const { db } = await import('./mysql/connection.js');
+
+    console.log(`server: ${appConfig.server.name} v${appConfig.server.version}`);
+    console.log(`database: ${appConfig.db.user}@${appConfig.db.host}:${appConfig.db.port}/${appConfig.db.name}`);
+    console.log(`ssl: ${appConfig.db.ssl ? 'enabled' : 'disabled'}`);
+    console.log(`schema-only mode: ${appConfig.server.schemaOnlyMode ? 'enabled' : 'disabled'}`);
+    if (process.env.DATABASE_URL) {
+      console.log(`DATABASE_URL: ${maskDatabaseUrl(process.env.DATABASE_URL)}`);
+    }
+
+    const versionRows = await db.query<any>('SELECT VERSION() AS version');
+    console.log(`mysql: ${versionRows[0]?.version || 'connected'}`);
+
+    const tableRows = await db.query<any>(
+      `SELECT COUNT(*) AS tableCount
+FROM information_schema.TABLES
+WHERE TABLE_SCHEMA = :database
+  AND TABLE_TYPE IN ('BASE TABLE', 'VIEW')`,
+      { database: appConfig.db.name },
+    );
+    console.log(`tables/views visible: ${tableRows[0]?.tableCount ?? 0}`);
+
+    if (!appConfig.server.schemaOnlyMode) {
+      if (process.env.QUERY_ACCESS_CONFIG) {
+        const { loadAccessControlConfig } = await import('./core/security/access-control.js');
+        loadAccessControlConfig();
+        console.log('query access config: ok');
+      } else {
+        console.log('query access config: missing; execute_query will be blocked');
+      }
+    }
+
+    await db.close();
+    console.log('\nDoctor passed.');
+  } catch (error) {
+    console.error('Doctor failed.');
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}
+
+async function main(): Promise<void> {
+  const [command = 'serve', ...args] = process.argv.slice(2);
+
+  switch (command) {
+    case 'serve':
+      await import('./index.js');
+      break;
+    case 'doctor':
+      await runDoctor();
+      break;
+    case 'init':
+      await runInit(args);
+      break;
+    case '--help':
+    case '-h':
+    case 'help':
+      usage();
+      break;
+    default:
+      console.error(`Unknown command: ${command}\n`);
+      usage();
+      process.exitCode = 1;
+  }
+}
+
+main();