From b5ab5515d551adb62d06140d44b60e0c11efe027 Mon Sep 17 00:00:00 2001
From: Matt Cowger <matt@cowger.us>
Date: Sat, 16 May 2026 20:30:56 -0700
Subject: [PATCH] fix: add bin alias so MCP server works via npx without
 pre-install

Add 'opencode-codebase-index' as a second bin entry pointing to the
same dist/cli.js, so that  resolves
the package on npm and starts the MCP server in one step -- no separate
npm install required.

The old  bin is preserved for backwards
compatibility; it auto-starts MCP mode without requiring the --mcp
flag. The new bin requires --mcp to avoid accidentally launching the
server when the user just runs the bare command.
---
 README.md    | 10 +++++-----
 package.json |  3 ++-
 src/cli.ts   | 39 ++++++++++++++++++++++++++++++++++++---
 3 files changed, 43 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 7a5d6ce..dbcbce6 100644
--- a/README.md
+++ b/README.md
@@ -99,7 +99,7 @@ Use the same semantic search from any MCP-compatible client. Index once, search
      "mcpServers": {
        "codebase-index": {
          "command": "npx",
-         "args": ["opencode-codebase-index-mcp", "--project", "/path/to/your/project"]
+         "args": ["opencode-codebase-index", "--mcp", "--project", "/path/to/your/project"]
        }
      }
    }
@@ -111,7 +111,7 @@ Use the same semantic search from any MCP-compatible client. Index once, search
      "mcpServers": {
        "codebase-index": {
          "command": "npx",
-         "args": ["opencode-codebase-index-mcp", "--project", "/path/to/your/project"]
+         "args": ["opencode-codebase-index", "--mcp", "--project", "/path/to/your/project"]
        }
      }
    }
@@ -119,9 +119,9 @@ Use the same semantic search from any MCP-compatible client. Index once, search
 
 3. **CLI options**
    ```bash
-   npx opencode-codebase-index-mcp --project /path/to/repo    # specify project root
-   npx opencode-codebase-index-mcp --config /path/to/config   # custom config file
-   npx opencode-codebase-index-mcp                            # uses current directory
+   npx opencode-codebase-index --mcp --project /path/to/repo    # specify project root
+   npx opencode-codebase-index --mcp --config /path/to/config   # custom config file
+   npx opencode-codebase-index --mcp                            # uses current directory
    ```
 
 The MCP server exposes all 9 tools (`codebase_search`, `codebase_peek`, `find_similar`, `call_graph`, `index_codebase`, `index_status`, `index_health_check`, `index_metrics`, `index_logs`) and 4 prompts (`search`, `find`, `index`, `status`).
diff --git a/package.json b/package.json
index 8f4fe55..809a48c 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,8 @@
     }
   },
   "bin": {
-    "opencode-codebase-index-mcp": "dist/cli.js"
+    "opencode-codebase-index-mcp": "dist/cli.js",
+    "opencode-codebase-index": "dist/cli.js"
   },
   "license": "MIT",
   "author": "Kenneth",
diff --git a/src/cli.ts b/src/cli.ts
index f285adc..f3251a1 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -7,19 +7,25 @@ import { handleEvalCommand } from "./eval/cli.js";
 import { createMcpServer } from "./mcp-server.js";
 import { loadMergedConfig } from "./config/merger.js";
 
-function parseArgs(argv: string[]): { project: string; config?: string } {
+function parseArgs(argv: string[]): { help: boolean; mcp: boolean; project: string; config?: string } {
+  let help = false;
+  let mcp = false;
   let project = process.cwd();
   let config: string | undefined;
 
   for (let i = 2; i < argv.length; i++) {
-    if (argv[i] === "--project" && argv[i + 1]) {
+    if (argv[i] === "--help" || argv[i] === "-h") {
+      help = true;
+    } else if (argv[i] === "--mcp") {
+      mcp = true;
+    } else if (argv[i] === "--project" && argv[i + 1]) {
       project = path.resolve(argv[++i]);
     } else if (argv[i] === "--config" && argv[i + 1]) {
       config = path.resolve(argv[++i]);
     }
   }
 
-  return { project, config };
+  return { help, mcp, project, config };
 }
 
 async function main(): Promise<void> {
@@ -29,6 +35,33 @@ async function main(): Promise<void> {
   }
 
   const args = parseArgs(process.argv);
+
+  // Show help and exit early (before trying to load native module)
+  if (args.help) {
+    console.log(`Usage:
+  npx opencode-codebase-index --mcp --project PATH    Start MCP server
+  npx opencode-codebase-index --help                   Show this help
+  npx opencode-codebase-index eval ...                 Run evaluation
+
+Aliases:
+  npx opencode-codebase-index-mcp  (equivalent to --mcp)
+`);
+    process.exit(0);
+  }
+
+  // --mcp flag required when using opencode-codebase-index bin
+  // (opencode-codebase-index-mcp bin defaults to MCP mode for backwards compatibility)
+  const isMcpBin = process.argv[0]?.endsWith("codebase-index-mcp") || process.execPath.includes("codebase-index-mcp");
+  const shouldRunMcp = args.mcp || isMcpBin;
+
+  if (!shouldRunMcp) {
+    console.error("Usage: npx opencode-codebase-index --mcp --project PATH");
+    console.error("       npx opencode-codebase-index eval ...");
+    console.error("\nNote: Use '--mcp' flag to start the MCP server.");
+    console.error("Or use 'npx opencode-codebase-index-mcp' for backwards compatibility.");
+    process.exit(1);
+  }
+
   const rawConfig = loadMergedConfig(args.project);
   const config = parseConfig(rawConfig);