@hyperdrive.bot/bmad-workflow 1.0.17 → 1.0.19

package/dist/commands/mcp/credential/validate.js

@@ -0,0 +1,150 @@
+/**
+ * MCP Credential Validate Command
+ *
+ * Validates all credentials required by enabled MCP servers by resolving them
+ * via the credential resolution chain and testing against live health checks.
+ */
+import { Command } from '@oclif/core';
+import chalk from 'chalk';
+import ora from 'ora';
+import { loadServerTemplate } from '../../../mcp/utils/template-loader.js';
+import { McpConfigManager } from '../../../services/mcp/mcp-config-manager.js';
+import { McpCredentialManager } from '../../../services/mcp/mcp-credential-manager.js';
+import { McpHealthChecker } from '../../../services/mcp/mcp-health-checker.js';
+import { createLogger } from '../../../utils/logger.js';
+const logger = createLogger({ namespace: 'commands:mcp:credential:validate' });
+export default class CredentialValidate extends Command {
+    static description = 'Validate credentials for all enabled MCP servers requiring API keys';
+    static examples = [
+        '<%= config.bin %> mcp credential validate',
+    ];
+    async run() {
+        logger.info('Validating credentials for enabled servers');
+        const configManager = new McpConfigManager();
+        const credentialManager = new McpCredentialManager();
+        const enabledServers = configManager.getEnabledServers();
+        // Filter to servers that require API keys
+        const serversNeedingKeys = enabledServers.filter((s) => s.apiKeyRequired && s.enabled);
+        if (serversNeedingKeys.length === 0) {
+            this.log(chalk.dim('No enabled servers require API keys.'));
+            return;
+        }
+        this.log(chalk.bold('\nValidating MCP Server Credentials\n'));
+        let hasFailures = false;
+        const results = [];
+        for (const server of serversNeedingKeys) {
+            // Load the full template to get env var names
+            let template;
+            try {
+                template = loadServerTemplate(server.name);
+            }
+            catch {
+                results.push({
+                    credentialKey: '?',
+                    error: 'Template not found',
+                    latency: null,
+                    serverName: server.name,
+                    status: 'fail',
+                });
+                hasFailures = true;
+                continue;
+            }
+            const envKeys = template.env ? Object.keys(template.env) : [];
+            if (envKeys.length === 0)
+                continue;
+            for (const envKey of envKeys) {
+                const resolved = credentialManager.resolve(envKey);
+                if (!resolved) {
+                    results.push({
+                        credentialKey: envKey,
+                        error: 'Credential not configured',
+                        latency: null,
+                        serverName: server.name,
+                        status: 'missing',
+                    });
+                    hasFailures = true;
+                    continue;
+                }
+                // Credential resolves — test with health check
+                const spinner = ora({ text: `Checking ${server.name} (${envKey})...`, stream: process.stderr }).start();
+                try {
+                    const healthChecker = new McpHealthChecker(configManager);
+                    const serverWithHealth = {
+                        enabled: true,
+                        healthCheck: {
+                            command: template.health_check.command,
+                            method: template.health_check.method,
+                            timeout: template.health_check.timeout,
+                        },
+                        name: server.name,
+                        useCase: server.useCase,
+                    };
+                    const healthResult = await healthChecker.checkServer(serverWithHealth);
+                    spinner.stop();
+                    if (healthResult.status === 'healthy') {
+                        results.push({
+                            credentialKey: envKey,
+                            error: null,
+                            latency: healthResult.latency,
+                            serverName: server.name,
+                            status: 'pass',
+                        });
+                    }
+                    else {
+                        results.push({
+                            credentialKey: envKey,
+                            error: healthResult.error || `Status: ${healthResult.status}`,
+                            latency: healthResult.latency,
+                            serverName: server.name,
+                            status: 'fail',
+                        });
+                        hasFailures = true;
+                    }
+                }
+                catch (error) {
+                    spinner.stop();
+                    results.push({
+                        credentialKey: envKey,
+                        error: error.message,
+                        latency: null,
+                        serverName: server.name,
+                        status: 'fail',
+                    });
+                    hasFailures = true;
+                }
+            }
+        }
+        // Display results
+        this.log(`${chalk.dim('Server'.padEnd(20))} ${chalk.dim('Key'.padEnd(20))} ${chalk.dim('Status'.padEnd(12))} ${chalk.dim('Latency')}`);
+        this.log(chalk.dim('─'.repeat(70)));
+        for (const r of results) {
+            let statusStr;
+            switch (r.status) {
+                case 'pass': {
+                    statusStr = chalk.green('PASS');
+                    break;
+                }
+                case 'missing': {
+                    statusStr = chalk.yellow('MISSING');
+                    break;
+                }
+                case 'fail': {
+                    statusStr = chalk.red('FAIL');
+                    break;
+                }
+            }
+            const latencyStr = r.latency !== null ? `${r.latency}ms` : '-';
+            this.log(`${r.serverName.padEnd(20)} ${r.credentialKey.padEnd(20)} ${statusStr.padEnd(22)} ${latencyStr}`);
+            if (r.error) {
+                this.log(chalk.dim(`  ${r.error}`));
+            }
+        }
+        this.log('');
+        if (hasFailures) {
+            this.error(chalk.red('Credential validation failed. Fix missing or failing credentials above.'), { exit: 1 });
+        }
+        else {
+            this.log(chalk.green('All credential validations passed.'));
+        }
+    }
+}

package/dist/commands/mcp/list.d.ts

@@ -0,0 +1,17 @@
+/**
+ * MCP List Command
+ *
+ * Displays all configured and available MCP servers with their status,
+ * API key requirements, and use case descriptions.
+ */
+import { Command } from '@oclif/core';
+import type { McpServerConfig } from '../../mcp/types.js';
+/**
+ * Render the server list output
+ */
+export declare function renderServerList(presetName: string, enabledServers: McpServerConfig[], availableTemplates: string[]): string;
+export default class McpList extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/mcp/list.js

@@ -0,0 +1,80 @@
+/**
+ * MCP List Command
+ *
+ * Displays all configured and available MCP servers with their status,
+ * API key requirements, and use case descriptions.
+ */
+import { Command } from '@oclif/core';
+import chalk from 'chalk';
+import { listAvailableTemplates } from '../../mcp/utils/template-loader.js';
+import { McpConfigManager } from '../../services/mcp/mcp-config-manager.js';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'commands:mcp:list' });
+/**
+ * Render the server list output
+ */
+export function renderServerList(presetName, enabledServers, availableTemplates) {
+    const lines = [];
+    // Header with current preset
+    lines.push(chalk.bold('MCP Server Configuration'));
+    lines.push(chalk.dim('========================'));
+    lines.push(`Active preset: ${chalk.cyan(presetName)}`);
+    lines.push('');
+    // Build a map of configured servers
+    const configuredMap = new Map();
+    for (const server of enabledServers) {
+        configuredMap.set(server.name, server);
+    }
+    // Combine: configured servers + available-but-not-configured
+    const allServerNames = new Set([
+        ...enabledServers.map((s) => s.name),
+        ...availableTemplates,
+    ]);
+    if (allServerNames.size === 0) {
+        lines.push(chalk.dim('  No servers configured or available'));
+        return lines.join('\n');
+    }
+    // Table header
+    const maxNameLen = Math.max(...[...allServerNames].map((n) => n.length), 6);
+    const header = `  ${'Name'.padEnd(maxNameLen)}  ${'Status'.padEnd(10)}  ${'API Key'.padEnd(8)}  Use Case`;
+    lines.push(chalk.bold(header));
+    lines.push(chalk.dim(`  ${'─'.repeat(maxNameLen)}  ${'─'.repeat(10)}  ${'─'.repeat(8)}  ${'─'.repeat(40)}`));
+    // Sort by name
+    const sortedNames = [...allServerNames].sort();
+    for (const name of sortedNames) {
+        const configured = configuredMap.get(name);
+        const paddedName = name.padEnd(maxNameLen);
+        if (configured) {
+            const status = configured.enabled
+                ? chalk.green('enabled'.padEnd(10))
+                : chalk.yellow('disabled'.padEnd(10));
+            const apiKey = configured.apiKeyRequired
+                ? chalk.yellow('yes'.padEnd(8))
+                : chalk.dim('no'.padEnd(8));
+            const useCase = configured.useCase || '';
+            lines.push(`  ${paddedName}  ${status}  ${apiKey}  ${useCase}`);
+        }
+        else {
+            const status = chalk.dim('available'.padEnd(10));
+            const apiKey = chalk.dim('—'.padEnd(8));
+            const useCase = chalk.dim('(not configured — run mcp add)');
+            lines.push(`  ${paddedName}  ${status}  ${apiKey}  ${useCase}`);
+        }
+    }
+    return lines.join('\n');
+}
+export default class McpList extends Command {
+    static description = 'List all configured and available MCP servers';
+    static examples = [
+        '<%= config.bin %> mcp list',
+    ];
+    async run() {
+        logger.info('Listing MCP servers');
+        const configManager = new McpConfigManager();
+        const enabledServers = configManager.getEnabledServers();
+        const presetName = configManager.getPresetName();
+        const availableTemplates = listAvailableTemplates();
+        const output = renderServerList(presetName, enabledServers, availableTemplates);
+        this.log(output);
+    }
+}

package/dist/commands/mcp/logs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * MCP Logs Command
+ *
+ * Streams gateway container logs via docker compose logs,
+ * supporting a --follow flag for live tailing.
+ */
+import { Command } from '@oclif/core';
+export default class McpLogs extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        follow: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/mcp/logs.js

@@ -0,0 +1,64 @@
+/**
+ * MCP Logs Command
+ *
+ * Streams gateway container logs via docker compose logs,
+ * supporting a --follow flag for live tailing.
+ */
+import { spawn } from 'node:child_process';
+import { Command, Flags } from '@oclif/core';
+import { dockerComposeFileExists, formatDockerError, getDockerComposeFilePath, isDockerAvailable, } from '../../mcp/utils/docker-utils.js';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'commands:mcp:logs' });
+export default class McpLogs extends Command {
+    static description = 'View MCP gateway container logs';
+    static examples = [
+        '<%= config.bin %> mcp logs',
+        '<%= config.bin %> mcp logs --follow',
+        '<%= config.bin %> mcp logs -f',
+    ];
+    static flags = {
+        follow: Flags.boolean({
+            char: 'f',
+            default: false,
+            description: 'Follow log output (live tail)',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(McpLogs);
+        logger.info('Viewing MCP gateway logs (follow=%s)', flags.follow);
+        // 1. Check Docker availability
+        const dockerCheck = isDockerAvailable();
+        if (!dockerCheck.available) {
+            this.error(formatDockerError(dockerCheck), { exit: 1 });
+            return;
+        }
+        // 2. Verify compose file exists
+        const composePath = getDockerComposeFilePath();
+        if (!dockerComposeFileExists()) {
+            this.error(`Docker Compose file not found at: ${composePath}\nNo logs available — the gateway has not been initialized.`, { exit: 1 });
+            return;
+        }
+        // 3. Build command args
+        const args = ['compose', '-f', composePath, 'logs'];
+        if (flags.follow) {
+            args.push('--follow');
+        }
+        // 4. Spawn docker compose logs and pipe output
+        const child = spawn('docker', args, {
+            stdio: ['ignore', 'inherit', 'inherit'],
+        });
+        await new Promise((resolve, reject) => {
+            child.on('close', (code) => {
+                if (code === 0 || code === null) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`docker compose logs exited with code ${code}`));
+                }
+            });
+            child.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+}

package/dist/commands/mcp/preset.d.ts

@@ -0,0 +1,15 @@
+/**
+ * MCP Preset Command
+ *
+ * Switches the active MCP gateway configuration to a named preset
+ * (minimal, research, full) and displays the resulting server list.
+ */
+import { Command } from '@oclif/core';
+export default class McpPreset extends Command {
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/mcp/preset.js

@@ -0,0 +1,84 @@
+/**
+ * MCP Preset Command
+ *
+ * Switches the active MCP gateway configuration to a named preset
+ * (minimal, research, full) and displays the resulting server list.
+ */
+import { Args, Command } from '@oclif/core';
+import chalk from 'chalk';
+import { McpConfigManager } from '../../services/mcp/mcp-config-manager.js';
+import { McpCredentialManager } from '../../services/mcp/mcp-credential-manager.js';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'commands:mcp:preset' });
+const VALID_PRESETS = ['minimal', 'research', 'full'];
+export default class McpPreset extends Command {
+    static args = {
+        name: Args.string({
+            description: 'Preset name to apply (minimal, research, full)',
+            required: true,
+        }),
+    };
+    static description = 'Switch the active MCP configuration to a named preset';
+    static examples = [
+        '<%= config.bin %> mcp preset minimal',
+        '<%= config.bin %> mcp preset research',
+        '<%= config.bin %> mcp preset full',
+    ];
+    async run() {
+        const { args } = await this.parse(McpPreset);
+        const presetName = args.name;
+        logger.info('Switching to preset: %s', presetName);
+        // Validate preset name
+        if (!VALID_PRESETS.includes(presetName)) {
+            this.error(`Invalid preset '${presetName}'.\n\nAvailable presets: ${VALID_PRESETS.join(', ')}`, { exit: 1 });
+            return;
+        }
+        // Apply preset
+        const configManager = new McpConfigManager();
+        configManager.applyPreset(presetName);
+        this.log(chalk.green(`Switched to '${presetName}' preset`));
+        this.log('');
+        // Display resulting server list
+        const servers = configManager.getEnabledServers();
+        this.log(chalk.bold('Configured servers:'));
+        if (servers.length === 0) {
+            this.log(chalk.dim('  No servers in this preset'));
+        }
+        else {
+            for (const server of servers) {
+                const status = server.enabled ? chalk.green('enabled') : chalk.yellow('disabled');
+                const apiKey = server.apiKeyRequired ? chalk.dim(' (API key required)') : '';
+                this.log(`  ${server.name}: ${status}${apiKey}`);
+            }
+        }
+        // Check for missing credentials
+        const credentialManager = new McpCredentialManager();
+        const missingCredentials = [];
+        for (const server of servers) {
+            if (server.apiKeyRequired) {
+                // Extract env var name from the server template in config
+                const enabledServerConfigs = configManager.getEnabledServers();
+                const serverConfig = enabledServerConfigs.find((s) => s.name === server.name);
+                if (serverConfig) {
+                    // We need to check the env keys — the simple check is by known mapping
+                    const knownEnvKeys = {
+                        apify: 'APIFY_TOKEN',
+                        exa: 'EXA_API_KEY',
+                    };
+                    const envKey = knownEnvKeys[server.name];
+                    if (envKey && !credentialManager.resolve(envKey)) {
+                        missingCredentials.push(envKey);
+                    }
+                }
+            }
+        }
+        if (missingCredentials.length > 0) {
+            this.log('');
+            this.log(chalk.yellow('Missing credentials:'));
+            for (const key of missingCredentials) {
+                this.log(chalk.yellow(`  - ${key}`));
+            }
+            this.log(chalk.dim('\nSet credentials with: bmad-workflow mcp add <server> (will prompt for key)'));
+        }
+    }
+}

package/dist/commands/mcp/remove.d.ts

@@ -0,0 +1,14 @@
+/**
+ * MCP Remove Command
+ *
+ * Removes an MCP server from the active gateway configuration.
+ */
+import { Command } from '@oclif/core';
+export default class McpRemove extends Command {
+    static args: {
+        server: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/mcp/remove.js

@@ -0,0 +1,36 @@
+/**
+ * MCP Remove Command
+ *
+ * Removes an MCP server from the active gateway configuration.
+ */
+import { Args, Command } from '@oclif/core';
+import chalk from 'chalk';
+import { McpConfigManager } from '../../services/mcp/mcp-config-manager.js';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'commands:mcp:remove' });
+export default class McpRemove extends Command {
+    static args = {
+        server: Args.string({
+            description: 'Name of the MCP server to remove',
+            required: true,
+        }),
+    };
+    static description = 'Remove an MCP server from the active gateway configuration';
+    static examples = [
+        '<%= config.bin %> mcp remove exa',
+        '<%= config.bin %> mcp remove apify',
+    ];
+    async run() {
+        const { args } = await this.parse(McpRemove);
+        const serverName = args.server;
+        logger.info('Removing MCP server: %s', serverName);
+        const configManager = new McpConfigManager();
+        const removed = configManager.removeServer(serverName);
+        if (removed) {
+            this.log(chalk.green(`Server '${serverName}' removed from configuration`));
+        }
+        else {
+            this.log(chalk.yellow(`Server '${serverName}' is not configured`));
+        }
+    }
+}

package/dist/commands/mcp/start.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP Start Command
+ *
+ * Launches the Docker MCP gateway via docker compose and polls the
+ * /health endpoint until healthy or 30s timeout is exceeded.
+ */
+import { Command } from '@oclif/core';
+export default class McpStart extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/mcp/start.js

@@ -0,0 +1,80 @@
+/**
+ * MCP Start Command
+ *
+ * Launches the Docker MCP gateway via docker compose and polls the
+ * /health endpoint until healthy or 30s timeout is exceeded.
+ */
+import { execSync } from 'node:child_process';
+import { Command } from '@oclif/core';
+import chalk from 'chalk';
+import { DEFAULT_GATEWAY_URL, HEALTH_CHECK_INTERVAL_MS, HEALTH_CHECK_TIMEOUT_MS, dockerComposeFileExists, formatDockerError, getDockerComposeFilePath, isDockerAvailable, } from '../../mcp/utils/docker-utils.js';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'commands:mcp:start' });
+export default class McpStart extends Command {
+    static description = 'Start the Docker MCP gateway and wait for it to become healthy';
+    static examples = [
+        '<%= config.bin %> mcp start',
+    ];
+    async run() {
+        logger.info('Starting MCP gateway');
+        // 1. Check Docker availability
+        const dockerCheck = isDockerAvailable();
+        if (!dockerCheck.available) {
+            this.error(formatDockerError(dockerCheck), { exit: 1 });
+            return;
+        }
+        // 2. Verify compose file exists
+        const composePath = getDockerComposeFilePath();
+        if (!dockerComposeFileExists()) {
+            this.error(`Docker Compose file not found at: ${composePath}\nRun 'bmad-workflow mcp init' first to generate the gateway configuration.`, { exit: 1 });
+            return;
+        }
+        // 3. Launch gateway
+        this.log(chalk.dim('Starting MCP gateway containers...'));
+        try {
+            execSync(`docker compose -f "${composePath}" up -d`, { stdio: 'pipe', timeout: 60_000 });
+        }
+        catch (error) {
+            const err = error;
+            const stderr = err.stderr ? err.stderr.toString() : err.message;
+            logger.error('Failed to start gateway: %s', stderr);
+            this.error(`Failed to start MCP gateway:\n${stderr}`, { exit: 1 });
+            return;
+        }
+        // 4. Health check polling
+        this.log(chalk.dim('Waiting for gateway to become healthy...'));
+        const healthUrl = `${DEFAULT_GATEWAY_URL}/health`;
+        const startTime = Date.now();
+        while (Date.now() - startTime < HEALTH_CHECK_TIMEOUT_MS) {
+            try {
+                const response = await fetch(healthUrl, { signal: AbortSignal.timeout(5000) });
+                if (response.ok) {
+                    const elapsed = Date.now() - startTime;
+                    this.log('');
+                    this.log(chalk.green.bold(`✓ MCP Gateway started successfully (${elapsed}ms)`));
+                    this.log(chalk.dim(`  Gateway URL: ${DEFAULT_GATEWAY_URL}`));
+                    this.log(chalk.dim(`  Health:      ${healthUrl}`));
+                    logger.info('Gateway healthy after %dms', elapsed);
+                    return;
+                }
+            }
+            catch {
+                // Health endpoint not ready yet — keep polling
+            }
+            await new Promise((resolve) => {
+                setTimeout(resolve, HEALTH_CHECK_INTERVAL_MS);
+            });
+        }
+        // 5. Timeout
+        logger.warn('Health check timed out after %dms', HEALTH_CHECK_TIMEOUT_MS);
+        this.error([
+            `Gateway health check timed out after ${HEALTH_CHECK_TIMEOUT_MS / 1000}s.`,
+            '',
+            'Troubleshooting:',
+            `  1. Check container logs:  bmad-workflow mcp logs`,
+            `  2. Verify port 8080 is free: lsof -i :8080`,
+            `  3. Check Docker status:   docker ps`,
+            `  4. Restart Docker daemon and try again`,
+        ].join('\n'), { exit: 1 });
+    }
+}

package/dist/commands/mcp/status.d.ts

@@ -0,0 +1,30 @@
+/**
+ * MCP Status Command
+ *
+ * Displays a structured dashboard showing gateway health, per-server health
+ * with latency, credential status, and current active preset name.
+ */
+import { Command } from '@oclif/core';
+import type { CredentialEntry, HealthReport } from '../../mcp/types.js';
+/**
+ * Render the status dashboard to the terminal
+ */
+declare function renderDashboard(healthReport: HealthReport, presetName: string, credentials: CredentialEntry[]): string;
+export default class McpStatus extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+    /**
+     * Get credentials status — delegates to McpCredentialManager when available
+     */
+    private getCredentials;
+    /**
+     * Gather health report — delegates to McpHealthChecker when available
+     */
+    private getHealthReport;
+    /**
+     * Get current preset name — delegates to McpConfigManager when available
+     */
+    private getPresetName;
+}
+export { renderDashboard };