Skip to content

Fix MCP server to work via npx without pre-installing #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mcowger wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Fix MCP server to work via npx without pre-installing #87

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
}
}
}
Expand All @@ -111,17 +111,17 @@ 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"]
}
}
}
```

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`).
Expand Down
3 changes: 2 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
39 changes: 36 additions & 3 deletions src/cli.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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> {
Expand All @@ -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);
}
Copy link
Copy Markdown
Owner

@Helweg Helweg May 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This breaks the advertised backward-compatibility path for opencode-codebase-index-mcp.

Under normal npm/npx execution, process.argv[0] and process.execPath point to the Node executable, not the invoked bin name, so this check stays false even when the user launched opencode-codebase-index-mcp.

That means the legacy bin will fall into the new --mcp usage error path instead of preserving the old behavior. Please detect the invoked bin from process.argv[1] or use a dedicated wrapper bin, and add a regression test for both entrypoints.


// --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);

Expand Down
Loading