Codeloupe

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, and delete 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 stable is required only when building from source.

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 is configured with environment variables in the MCP server process.

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.

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.

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.

Index storage

The server keeps one index per canonical workspace root.

• 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\

Workspace roots are dynamic: the server uses client-provided workspaceFolders, roots, rootUri, or clientInfo.workspaceRoot; if none are provided, it falls back to the process current directory when that directory looks like a workspace root.

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.
• npm/npx: @ndhkaeru/codeloupe-mcp publishes a small JavaScript launcher plus native binaries from the matching GitHub Release.

Release checklist:

1. Update versions in Cargo.toml, Cargo.lock, packages/npm/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 and npm publish workflows succeed.
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.