feat: add npx distribution package for MCP debugger CLI

- Create @debugmcp/mcp-debugger package for npx distribution
- Bundle CLI with esbuild to include all dependencies
- Preserve stdio console silencing logic for MCP compatibility
- Update release workflow to publish CLI package
- Maintain dynamic adapter loading capability

Author: cynarlab

.github/workflows/release.yml

@@ -173,6 +173,14 @@ jobs:
     - name: Install dependencies
       run: npm ci --ignore-scripts
 
+    - name: Set CLI package version from tag
+      run: |
+        VERSION=${GITHUB_REF#refs/tags/v}
+        echo "Setting CLI package version to $VERSION"
+        cd packages/mcp-debugger
+        npm version $VERSION --no-git-tag-version --allow-same-version
+        cd ../..
+    
     - name: Build project
       run: npm run build
 
@@ -181,6 +189,7 @@ jobs:
         npm pack --dry-run -w @debugmcp/shared
         npm pack --dry-run -w @debugmcp/adapter-mock
         npm pack --dry-run -w @debugmcp/adapter-python
+        npm pack --dry-run -w @debugmcp/mcp-debugger
     
     - name: Publish to npm (workspaces)
       run: |
@@ -190,6 +199,7 @@ jobs:
         npm publish -w @debugmcp/shared --access public
         npm publish -w @debugmcp/adapter-mock --access public
         npm publish -w @debugmcp/adapter-python --access public
+        npm publish -w @debugmcp/mcp-debugger --access public
       env:
         NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
@@ -237,16 +247,27 @@ jobs:
         docker pull debugmcp/mcp-debugger:${{ steps.changelog.outputs.VERSION }}
         ```
         
-        **npm:**
+        **npm (global install):**
         ```bash
         npm install -g @debugmcp/mcp-debugger@${{ steps.changelog.outputs.VERSION }}
         ```
         
+        **npx (no install):**
+        ```bash
+        npx @debugmcp/mcp-debugger@${{ steps.changelog.outputs.VERSION }} stdio
+        ```
+        
         **PyPI:**
         ```bash
         pip install debug-mcp-server-launcher==${{ steps.changelog.outputs.VERSION }}
         ```
         
+        **Optional adapters:**
+        ```bash
+        npm install -g @debugmcp/adapter-python
+        npm install -g @debugmcp/adapter-mock
+        ```
+        
         ### 📚 Documentation
         See the [README](https://github.com/debugmcp/mcp-debugger#readme) for usage instructions.
         EOF

packages/mcp-debugger/README.md

@@ -0,0 +1,55 @@
+# @debugmcp/mcp-debugger
+
+Step-through debugging MCP server for LLMs
+
+## Installation
+
+You can use this package without installation via npx:
+
+```bash
+npx @debugmcp/mcp-debugger stdio
+```
+
+Or install it globally:
+
+```bash
+npm install -g @debugmcp/mcp-debugger
+```
+
+## Usage
+
+### STDIO mode (default)
+```bash
+mcp-debugger stdio
+```
+
+### SSE mode
+```bash
+mcp-debugger sse --port 3001
+```
+
+## Optional Adapters
+
+To debug specific languages, install the corresponding adapter packages:
+
+```bash
+# Python debugging support
+npm install -g @debugmcp/adapter-python
+
+# Mock adapter for testing
+npm install -g @debugmcp/adapter-mock
+```
+
+## Options
+
+- `--log-level <level>` - Set log level (error, warn, info, debug)
+- `--log-file <path>` - Log to file instead of console
+- `--port <number>` - Port for SSE mode (default: 3001)
+
+## Documentation
+
+See the [main repository](https://github.com/debugmcp/mcp-debugger) for full documentation.
+
+## License
+
+MIT

packages/mcp-debugger/debugmcp-mcp-debugger-0.15.4.tgz

@@ -0,0 +1,32 @@
+{
+  "name": "@debugmcp/mcp-debugger",
+  "version": "0.15.4",
+  "description": "Step-through debugging MCP server for LLMs",
+  "homepage": "https://github.com/debugmcp/mcp-debugger",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/debugmcp/mcp-debugger.git",
+    "directory": "packages/mcp-debugger"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "mcp-debugger": "./dist/cli.cjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "node scripts/bundle-cli.js",
+    "build:ci": "node scripts/bundle-cli.js",
+    "clean": "rimraf dist && rimraf tsconfig.tsbuildinfo"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/mcp-debugger/package.json

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Bundle the MCP debugger CLI for npx distribution
+ */
+
+import * as esbuild from 'esbuild';
+import fs from 'fs';
+
+async function bundleCLI() {
+  console.log('Bundling MCP debugger CLI...');
+  
+  try {
+    // Bundle the CLI entry point directly from TypeScript source
+    const result = await esbuild.build({
+      entryPoints: ['src/cli-entry.ts'],
+      bundle: true,
+      platform: 'node',
+      target: 'node18',
+      format: 'cjs',
+      outfile: 'dist/cli.cjs',
+      define: {
+        'import.meta.url': JSON.stringify('file:///app/dist/cli.cjs'),
+        '__dirname': JSON.stringify('/app/dist')
+      },
+      external: [
+        // Keep adapter packages external for dynamic loading
+        '@debugmcp/adapter-python',
+        '@debugmcp/adapter-mock',
+        // Keep native modules external
+        'fsevents'
+      ],
+      minify: false, // Keep readable for debugging
+      sourcemap: false,
+      metafile: true,
+      logLevel: 'info',
+      loader: {
+        '.ts': 'ts',
+        '.js': 'js'
+      }
+    });
+
+    // Write metafile for analysis
+    fs.writeFileSync('dist/bundle-meta.json', JSON.stringify(result.metafile));
+    
+    // Make the bundle executable
+    const bundlePath = 'dist/cli.cjs';
+    if (fs.existsSync(bundlePath)) {
+      // Add shebang if not present
+      let bundleContent = fs.readFileSync(bundlePath, 'utf8');
+      if (!bundleContent.startsWith('#!/usr/bin/env node')) {
+        bundleContent = '#!/usr/bin/env node\n' + bundleContent;
+        fs.writeFileSync(bundlePath, bundleContent);
+      }
+      
+      // Make executable on Unix-like systems
+      if (process.platform !== 'win32') {
+        fs.chmodSync(bundlePath, '755');
+      }
+    }
+
+    // Calculate bundle size
+    const stats = fs.statSync(bundlePath);
+    const sizeInKB = (stats.size / 1024).toFixed(2);
+    console.log(`CLI bundle created successfully: ${sizeInKB} KB`);
+    
+    // Show what's included
+    const text = await esbuild.analyzeMetafile(result.metafile, {
+      verbose: false
+    });
+    console.log('\nBundle analysis:');
+    console.log(text);
+    
+  } catch (error) {
+    console.error('Bundle failed:', error);
+    process.exit(1);
+  }
+}
+
+bundleCLI();

packages/mcp-debugger/scripts/bundle-cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * Publishable CLI shim for npx usage.
+ * Preserves critical stdio console silencing and delegates to the existing main() implementation.
+ */
+
+// CRITICAL: Console silencing MUST be first - before ANY imports
+// This prevents stdout pollution in stdio mode which breaks MCP protocol
+(() => {
+  // Handle both quoted and unquoted stdio arguments
+  const hasStdio = process.argv.some(arg =>
+    arg === 'stdio' ||
+    arg === '"stdio"' ||
+    arg === '"\'stdio\'"' ||
+    arg.includes('stdio')
+  );
+
+  // Auto-detect STDIO mode:
+  // 1. Explicit stdio argument
+  // 2. Environment variable set
+  // 3. No transport argument specified (default is STDIO)
+  // 4. stdin is a pipe (typical for MCP STDIO mode)
+  const hasTransportArg = process.argv.some(arg =>
+    arg === '--transport' || arg.includes('transport')
+  );
+  const isStdinPipe = !process.stdin.isTTY;
+  const shouldSilenceConsole = hasStdio ||
+                               process.env.DEBUG_MCP_STDIO === '1' ||
+                               (!hasTransportArg && isStdinPipe);
+
+  if (shouldSilenceConsole) {
+    // Set env flag immediately so any early imports see it
+    if (hasStdio || shouldSilenceConsole) {
+      process.env.DEBUG_MCP_STDIO = '1';
+    }
+    
+    const noop = () => {};
+    console.log = noop;
+    console.error = noop;
+    console.warn = noop;
+    console.info = noop;
+    console.debug = noop;
+    console.trace = noop;
+    console.dir = noop;
+    console.table = noop;
+    console.group = noop;
+    console.groupEnd = noop;
+    console.time = noop;
+    console.timeEnd = noop;
+    console.assert = noop;
+    
+    // Suppress process warnings
+    process.removeAllListeners('warning');
+    process.on('warning', noop);
+  }
+})();
+
+// Clean argv before any code processes it - strip quotes from all arguments
+process.argv = process.argv.map(arg => 
+  typeof arg === 'string' ? arg.replace(/^["'](.*)["']$/, '$1') : arg
+);
+
+// Import and run the existing CLI main from the root source to avoid duplicating logic.
+// esbuild will bundle the referenced source into this package so npx works standalone.
+import { main } from '../../../src/index.js';
+
+Promise.resolve()
+  .then(() => main())
+  .catch((error) => {
+    // In stdio mode, we must not write to console
+    const isStdio = process.argv.includes('stdio') || process.env.DEBUG_MCP_STDIO === '1';
+    if (!isStdio) {
+      console.error('Fatal error:', error);
+    }
+    process.exit(1);
+  });

packages/mcp-debugger/src/cli-entry.ts

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "../..",
+    "outDir": "./dist",
+    "declarationDir": "./dist",
+    "composite": true,
+    "noEmit": false,
+    "declaration": true,
+    "sourceMap": false
+  },
+  "include": ["./src/**/*"],
+  "references": [
+    { "path": "../shared" },
+    { "path": "../../tsconfig.src.json" }
+  ]
+}

packages/mcp-debugger/tsconfig.json

@@ -0,0 +1,38 @@
+import { IAdapterFactory } from '@debugmcp/shared';
+import type { Logger as WinstonLogger } from 'winston';
+export interface ModuleLoader {
+    load(modulePath: string): Promise<Record<string, unknown>>;
+}
+export interface AdapterMetadata {
+    name: string;
+    packageName: string;
+    description?: string;
+    installed: boolean;
+}
+export declare class AdapterLoader {
+    private cache;
+    private logger;
+    private moduleLoader;
+    constructor(logger?: WinstonLogger, moduleLoader?: ModuleLoader);
+    private createDefaultModuleLoader;
+    /**
+     * Dynamically load an adapter by language name
+     */
+    loadAdapter(language: string): Promise<IAdapterFactory>;
+    /**
+     * Check if an adapter is available (and cache it if so)
+     */
+    isAdapterAvailable(language: string): Promise<boolean>;
+    /**
+     * List all potentially available adapters (known list for now)
+     */
+    listAvailableAdapters(): Promise<AdapterMetadata[]>;
+    private getPackageName;
+    /**
+     * Compute a monorepo fallback path to the adapter dist entry.
+     * This supports running from the source tree and inside the Docker image where packages are copied.
+     */
+    private getFallbackModulePath;
+    private getFallbackModulePaths;
+    private getFactoryClassName;
+}