fix: add mcp-framework CLI alias and PATH conflict detection (#53)

The "mcp" CLI command can collide with the Python MCP SDK's "mcp" command
on systems where both are installed. This adds an "mcp-framework" bin alias
as a reliable alternative and a startup check that warns users when multiple
"mcp" executables are found on their PATH.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: QuantGeekDev

package.json

@@ -17,6 +17,7 @@
   ],
   "bin": {
     "mcp": "dist/cli/index.js",
+    "mcp-framework": "dist/cli/index.js",
     "mcp-build": "dist/cli/framework/build-cli.js"
   },
   "scripts": {

src/cli/index.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { createRequire } from 'module';
+import { execSync } from 'child_process';
 import { Command } from 'commander';
 import { createProject } from './project/create.js';
 import { addTool } from './project/add-tool.js';
@@ -9,6 +10,31 @@ import { addApp } from './project/add-app.js';
 import { buildFramework } from './framework/build.js';
 import { validateCommand } from './commands/validate.js';
 
+function checkForMcpConflict(): void {
+  try {
+    const isWindows = process.platform === 'win32';
+    const cmd = isWindows ? 'where mcp' : 'which -a mcp';
+    const result = execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    const paths = result.trim().split(/\r?\n/).filter(Boolean);
+    if (paths.length > 1) {
+      console.warn(
+        '\x1b[33m⚠ Warning: Multiple "mcp" executables found on your PATH:\x1b[0m'
+      );
+      for (const p of paths) {
+        console.warn(`  - ${p}`);
+      }
+      console.warn(
+        '\x1b[33mIf you experience unexpected behavior (e.g., from a Python mcp package),\n' +
+          'use \x1b[1mmcp-framework\x1b[0m\x1b[33m instead. For example: mcp-framework create my-project\x1b[0m\n'
+      );
+    }
+  } catch {
+    // Silently ignore — `which`/`where` may not be available
+  }
+}
+
+checkForMcpConflict();
+
 const require = createRequire(import.meta.url);
 const frameworkPackageJson = require('../../package.json');