io.github.ndhkaeru/codeloupe-mcp

codeloupe-mcp

A Model Context Protocol (MCP) server that gives coding agents fast, local-first access to large codebases. It enables LLMs to inspect files, search text, compare directories, read symbols, and apply structured edits through bounded tool responses instead of dumping whole files or repository trees into context.

codeloupe-mcp vs shell tools

This package provides an MCP interface into repository exploration and code editing.

If you are using a coding agent, shell commands are still useful for concise build/test workflows. codeloupe-mcp is most useful when the model needs structured, repeatable, repository-aware code context across a chat session.

• Shell / CLI: best for deterministic commands such as cargo test, npm run lint, project scripts, one-off rg, and build logs that are already compact.
• MCP: best for agent loops that benefit from tool schemas, workspace-aware path resolution, bounded output, persistent indexes, and precise reads such as symbol bodies, snippets, shallow project maps, and directory diffs.

Use codeloupe-mcp when you want an agent to ask for exactly the code context it needs: a line range, a symbol body, a bounded search result, a fuzzy file match, a workspace summary, or a source-directory comparison.

Key Features

• Fast and lightweight. Local Rust server over stdio; no external indexing service, no network calls, no telemetry.
• LLM-friendly output. Tools return bounded JSON/Markdown designed for agent context windows.
• Repository-aware indexing. LMDB path metadata plus optional Tantivy content indexing per workspace.
• Precise code reads. Read focused line ranges, snippets, symbol bodies, imports, exports, call graphs, definitions, and references.
• Scoped search. Literal and regex search with path scopes, include/exclude globs, fallback diagnostics, and large-repo safeguards.
• Directory comparison. Compare two source directories with added/deleted/modified/renamed summaries and bounded diffs.
• Structured edits. Create, edit, convert, delete, batch-edit, and undo files with predictable success/error metadata.

Requirements

• An MCP client that supports local stdio servers.
• Node.js 18 or newer when using npx.
• No Rust toolchain is needed when using the published npm package or a native release binary.
• Rust 1.98.1 is required only when building from source; rust-toolchain.toml installs the pinned toolchain through rustup.

Getting started

First, install the codeloupe-mcp server with your client.

Standard config works in most MCP clients:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

You can also use a native binary from the GitHub Releases page:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "/absolute/path/to/codeloupe-mcp",
      "args": []
    }
  }
}

On Windows native installs, point command to the .exe file, for example C:\path\to\codeloupe-mcp.exe.

"amp.mcpServers": {
  "codeloupe-mcp": {
    "command": "npx",
    "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
  }
}

amp mcp add codeloupe-mcp -- npx -y @ndhkaeru/codeloupe-mcp@latest

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

claude mcp add codeloupe-mcp -- npx -y @ndhkaeru/codeloupe-mcp@latest

claude mcp add codeloupe-mcp -- /absolute/path/to/codeloupe-mcp

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "C:\\path\\to\\codeloupe-mcp.exe",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "codeloupe-mcp": {
      "type": "stdio",
      "command": "npx",
      "timeout": 60,
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"],
      "disabled": false
    }
  }
}

codex mcp add codeloupe-mcp -- npx -y @ndhkaeru/codeloupe-mcp@latest

[mcp_servers.codeloupe-mcp]
command = "npx"
args = ["-y", "@ndhkaeru/codeloupe-mcp@latest"]

{
  "mcpServers": {
    "codeloupe-mcp": {
      "type": "local",
      "command": "npx",
      "tools": ["*"],
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

npx -y @ndhkaeru/codeloupe-mcp@latest

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

droid mcp add codeloupe-mcp "npx -y @ndhkaeru/codeloupe-mcp@latest"

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

npx -y @ndhkaeru/codeloupe-mcp@latest

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codeloupe-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@ndhkaeru/codeloupe-mcp@latest"],
      "enabled": true
    }
  }
}

{
  "servers": {
    "codeloupe-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"codeloupe-mcp","command":"npx","args":["-y","@ndhkaeru/codeloupe-mcp@latest"]}'

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"]
    }
  }
}

Configuration

codeloupe-mcp accepts repeatable --workspace <path> / --workspace=<path> arguments and environment variables in the MCP server process. Explicit CLI and environment workspaces are approved for indexing unless index mode is off. --help and --version print immediately without starting the stdio server; unknown CLI options fail instead of silently starting it.

After upgrading the server, reconnect or restart the MCP client so it fetches the current tools/list schema. Long-running clients such as Claude Code can keep the previous session's tool parameters until they reconnect.

Legacy codeloupe_mcp_* and CODEBASE_MCP_* names remain supported for compatibility; the uppercase CODELOUPE_MCP_* names take precedence.

Workspace sources are processed in this order: repeatable CLI arguments, explicit workspace environment variables, MCP client roots (workspaceFolders, roots, rootUri, or clientInfo.workspaceRoot), a project-like process current directory, then workspace roots inferred from tool paths. In ask mode, only CLI/environment roots and remembered workspace_index(action="enable") decisions are approved for indexing; client roots, cwd, and tool paths remain candidates. auto indexes eligible candidates within the same protected-path, scan, and disk budgets. off disables indexing and advice. Relative tool paths prefer the current active workspace context, then an active index workspace, a workspace discovered from cwd, cwd itself, other configured workspaces, and finally loaded index workspaces.

Write tools are restricted to the exact MCP client roots and explicit --workspace/workspace-environment roots after canonicalization, the project-like process cwd when no roots were configured, plus CODELOUPE_MCP_WRITE_ROOTS. Discovering an ancestor repository root may expand index/search context, but never expands write authorization beyond the declared root. workspace_index(action="enable") grants indexing only and never grants write access. Canonical path checks reject junction/symlink escapes, and writes anywhere under .git are always blocked.

Example with a custom index directory:

{
  "mcpServers": {
    "codeloupe-mcp": {
      "command": "npx",
      "args": ["-y", "@ndhkaeru/codeloupe-mcp@latest"],
      "env": {
        "CODELOUPE_MCP_INDEX_DIR": "/path/to/cache"
      }
    }
  }
}

Tools

Tools are grouped by purpose. Each response uses the standard MCP content array shape and keeps output bounded for agent context.

The server negotiates supported MCP protocol versions (2024-11-05, 2025-03-26, 2025-06-18, and 2025-11-25), returns an empty object for ping, and never responds to notifications. Notification-form tools/call messages are ignored without execution. notifications/cancelled suppresses the matching active response and propagates cooperative cancellation; multi-file scan tools report cooperative progress and stop early when cancelled. As a server extension, request-form tools/call may set params.timeout_seconds to an integer from 60 through 600; out-of-range or non-integer values return JSON-RPC -32602 instead of being silently adjusted. Timeout responses are structured JSON containing elapsed time, observed scan progress, narrower candidate paths, and conditional index_advice.

Symbol queries accept both Class.method and Class::method, including deeper qualified names. get_symbols returns qualified_name and start_line; read_symbol_body, get_call_graph, and each compare_symbols side accept an optional line selector. An unqualified query with multiple AST matches returns ambiguous: true plus candidates instead of silently selecting the first match. compare_symbols omits same_content and unified_diff when either side is ambiguous.

find_definition uses Tree-sitter for supported languages, matches symbol names case-sensitively, and labels those results with resolution: "ast". Unsupported code extensions use a declaration-regex fallback labeled resolution: "heuristic". find_references performs token matching rather than binding or type resolution; Tree-sitter-supported files return match_kind: "code" | "comment" | "string" with classification: "ast", mark a declaration-name match with is_definition: true, and leave ordinary references unmarked. Unsupported extensions return match_kind: "unknown" with classification: "text_fallback".

find_definition and find_references keep result data plus complete/limit metadata at the top level. Scan counters, path-index/filesystem strategy, fallback counts, skipped-file details, and cancellation state appear under diagnostics only for incomplete results, zero-result filter hints, or when verbose=true. Default per-result metadata is omitted where it can be inferred; for example, ordinary AST code references do not repeat classification: "ast", match_kind: "code", or line_truncated: false.

Code-intelligence outputs use path consistently. Single-file tools return one normalized path, while find_definition and find_references return a shared root plus relative paths for matches and skipped-file details. Ambiguous get_call_graph candidates omit repeated paths because the top-level path applies to every candidate.

compare_directories defaults to an inventory-only JSON result; set include_content_diff=true when unified diffs are needed. compare_symbols returns the unified diff and symbol metadata without repeating both complete symbol bodies in left and right.

Byte-size output fields use the _bytes suffix consistently: size_bytes for one item and left_size_bytes/right_size_bytes for directory comparisons.

Bounded collection outputs use complete, limit_reached, and limit_reason. Bounded nested lists use names such as entries_complete, details_complete, or candidates_complete; truncated is reserved for returned text or byte content that was actually shortened.

Supported languages

AST-backed tools use Tree-sitter for Rust, C, C++, Go, Java, C#, PHP, Ruby, JavaScript, TypeScript, Python, Swift, and Objective-C.

list_imports and list_exports currently support Rust, JavaScript/TypeScript, Swift, and Objective-C. File/search/workspace tools work on any text file regardless of language.

Shared file limits

File-content limits are named centrally in src/limits.rs and are reported in schemas or responses where they affect results.

Scan tools that skip oversized files return bounded path/size/limit details plus an omitted-detail count when needed.

Large repository guidance

• Scope paths to the smallest useful subtree.
• Prefer literal text_search when possible so Tantivy can shortlist files.
• Use concrete basenames or path tokens with fuzzy_find.
• Keep project_map shallow, for example max_depth <= 2.
• Use recursive excludes such as third_party/**, node_modules/**, target/**, dist/**, and out/**.
• Use read_snippets after search results instead of reading whole files.

text_search, compare_directories, and content indexing share the same generated/vendor directory policy, including build, dist, obj, out, target, node_modules, vendor, and third_party. bin is treated as build output only for recognized .NET/Java workspaces so Node, Ruby, and similar source bin/ directories remain searchable. Directly scoping text_search to an excluded directory bypasses these defaults.

Index storage

The server keeps one index per canonical approved workspace root. Nested client roots may share an inferred ancestor index/search workspace, and discovery prefers an ancestor with a VCS marker (.git, .hg, or .svn) over a nested language manifest. Inferred ancestors do not become declared roots; writes elsewhere in that repository receive the medium-risk warning described above. Index approval decisions are stored in the human-readable index-v2/workspaces.json; enabled workspaces reload across sessions, while declines suppress advice for 30 days.

• Windows: %LOCALAPPDATA%\codeloupe-mcp\index-v2\<workspace_hash>\
• Linux/macOS: $XDG_CACHE_HOME/codeloupe-mcp/index-v2/<workspace_hash>/ or ~/.cache/codeloupe-mcp/index-v2/<workspace_hash>/
• Custom root: <CODELOUPE_MCP_INDEX_DIR>\index-v2\<workspace_hash>\
• Tantivy sidecar: <workspace_index_dir>\tantivy-content\
• Last-used sidecar: <workspace_index_dir>\last-used

<workspace_hash> is a stable FNV-1a hash of the normalized canonical root, so changing Rust toolchains does not rename every cache directory. When a matching pre-1.0 cache directory is found by its meta.json, it is renamed to the stable hash before opening.

At startup, index GC removes missing-workspace indexes after a 7-day grace period, removes indexes unused for 90 days, and enforces a 2 GiB total cap by least-recently-used order. The same total-size and free-space budgets are checked before new index writes. Metadata scans stop at the configured entry or time budget and persist too_large without creating a workspace index directory. Loaded or cross-process-locked indexes are never deleted. Tantivy stores searchable fields and file metadata, but not file content or path-token payloads.

Workspace roots are dynamic: explicit CLI/environment roots are approved first; client roots, a project-like process current directory, and workspace roots inferred from tool paths update the active context. Index loading runs in background so initialization and unrelated requests remain responsive; tools fall back to bounded filesystem access while a runtime is loading. Loaded runtimes use an in-memory LRU budget and can be reopened from their on-disk indexes after eviction. Recognized manifests include Rust, Node, Python, Go, Java/Gradle, Bazel, .NET (*.sln, *.slnx, global.json, Directory.Build.props), CMake, PHP Composer, Ruby, Elixir, and Scala/SBT projects. Tool paths without a recognized workspace marker still work through bounded filesystem access but never receive index advice. Explicit client roots remain valid active contexts even without markers; whether they index depends on CODELOUPE_MCP_INDEX_MODE or a persisted approval.

Shipping

Releases are distributed through two channels:

• GitHub Releases: a semver tag such as v1.0.0 builds native archives/installers for macOS, Linux, and Windows on x64/arm64. Linux archives use static musl targets so they do not require a recent glibc and can run on musl-based distributions such as Alpine.
• npm/npx: @ndhkaeru/codeloupe-mcp is a small JavaScript launcher. npm installs one OS/CPU-specific optional package containing only the matching native binary instead of downloading all six platforms.

Release checklist:

1. Update versions in Cargo.toml, Cargo.lock, packages/npm/package.json, every packages/npm-platforms/*/package.json, and server.json.
2. Run the checks from rust.yml: format, clippy, tests, audit, deny, and typos.
3. Push main, then check GitHub Actions for failures.
4. Push a semver tag such as v1.0.0.
5. Confirm release assets, all six platform npm packages, and the launcher npm package publish successfully.
6. Smoke test npx -y @ndhkaeru/codeloupe-mcp@<version>.

Development

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test --release

License

Apache-2.0. See LICENSE.