@sylphx/coderag-mcp

MCP server for hybrid codebase search — Did it find the right code?

Monorepo README, benchmark proof, and Discovery status: github.com/SylphxAI/coderag.

Quick Start

Using Claude Desktop, VS Code, Cursor, Claude Code, or other MCP clients.

Standard Config

{
  "mcpServers": {
    "coderag": {
      "command": "npx",
      "args": ["-y", "@sylphx/coderag-mcp", "--root=/path/to/project"]
    }
  }
}

The default coderag-mcp bin launches the Rust rmcp server only (no TypeScript fallback). Platform-native binaries ship as optionalDependencies. Each platform package includes both coderag-mcp-server and coderag-cli so tools/call codebase_search works from a clean npm/npx install without a monorepo Rust build.

| Platform | Package | | --- | --- | | macOS Apple Silicon | @sylphx/coderag-mcp-darwin-arm64 | | macOS Intel | @sylphx/coderag-mcp-darwin-x64 | | Linux x64 (glibc) | @sylphx/coderag-mcp-linux-x64-gnu | | Linux arm64 (glibc) | @sylphx/coderag-mcp-linux-arm64-gnu |

npm installs the matching package automatically. If the native is missing or the host platform is unsupported, the bin exits non-zero (fail-closed). Build from source with bun run build:rust in a clone, or set CODERAG_MCP_RUST_BIN / CODERAG_RUST_CLI.

With Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "coderag": {
      "command": "npx",
      "args": ["-y", "@sylphx/coderag-mcp", "--root=/path/to/project"]
    }
  }
}

With VS Code

Add to your VS Code settings (JSON):

{
  "mcp": {
    "servers": {
      "coderag": {
        "command": "npx",
        "args": ["-y", "@sylphx/coderag-mcp", "--root=${workspaceFolder}"]
      }
    }
  }
}

Or add to .vscode/mcp.json in your project:

{
  "servers": {
    "coderag": {
      "command": "npx",
      "args": ["-y", "@sylphx/coderag-mcp", "--root=${workspaceFolder}"]
    }
  }
}

With Cursor

Add to your Cursor MCP config:

macOS: ~/.cursor/mcp.json Windows: %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "coderag": {
      "command": "npx",
      "args": ["-y", "@sylphx/coderag-mcp", "--root=/path/to/project"]
    }
  }
}

With Windsurf

Add to your Windsurf MCP config:

macOS: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "coderag": {
      "command": "npx",
      "args": ["-y", "@sylphx/coderag-mcp", "--root=/path/to/project"]
    }
  }
}

With Claude Code

claude mcp add coderag -- npx -y @sylphx/coderag-mcp --root=/path/to/project

With Other MCP Clients

Use the standard config format. All MCP-compatible clients should work with:

{
  "mcpServers": {
    "coderag": {
      "command": "npx",
      "args": ["-y", "@sylphx/coderag-mcp", "--root=/path/to/project"]
    }
  }
}

Using bun:

{
  "mcpServers": {
    "coderag": {
      "command": "bunx",
      "args": ["@sylphx/coderag-mcp", "--root=/path/to/project"]
    }
  }
}

Global install:

npm install -g @sylphx/coderag-mcp
# or
bun add -g @sylphx/coderag-mcp

Then use coderag-mcp as the command:

{
  "mcpServers": {
    "coderag": {
      "command": "coderag-mcp",
      "args": ["--root=/path/to/project"]
    }
  }
}

Options

| Option | Default | Description | |--------|---------|-------------| | --root=<path> | Current directory | Codebase root path | | --max-size=<bytes> | 1048576 (1MB) | Max file size to index | | --no-auto-index | false | Disable auto-indexing on startup |

MCP Tool: codebase_search

Search project source files with TF-IDF ranking.

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | query | string | Yes | - | Search query | | limit | number | No | 10 | Max results | | include_content | boolean | No | true | Include code snippets | | file_extensions | string[] | No | - | Filter by extension | | path_filter | string | No | - | Filter by path | | exclude_paths | string[] | No | - | Exclude paths |

Example

{
  "query": "authentication",
  "limit": 5,
  "file_extensions": [".ts", ".tsx"],
  "exclude_paths": ["node_modules", "dist"]
}

Response

LLM-optimized output (minimal tokens, maximum content):

# Search: "authentication" (3 results)

## src/auth/login.ts:15-28
```typescript
15: export async function authenticate(credentials) {
16:   const user = await findUser(credentials.email)

docs/auth.md:42-55 [markdown→typescript]

42: // Embedded code from docs

src/utils/large-file.ts:1-500 [truncated]

1: // First 70% of content shown...

... [1500 chars truncated] ...

490: // Last 20% of content shown

## Usage Tips

**Good queries:**
- `user authentication login`
- `database connection`
- `React form validation`

**Less effective:**
- Single common words like `function`, `const`
- Very long sentences

## Performance

Run the reproducible public benchmark from the monorepo root (after `bun run build`):

```bash
bun run benchmark:public-proof

Details: docs/benchmark.md.

Development

git clone https://github.com/SylphxAI/coderag.git
cd coderag

bun install
bun run build

# Run locally
cd packages/mcp-server
bun run dev

License

MIT

Powered by Sylphx

Built with @sylphx/coderag · @sylphx/mcp-server-sdk