Codeindex MCP

代码索引mcp

内存中 主控程序 用于源代码索引的服务器。一个快速、索引化的替代品 grep 和 find，专为 克劳德代码 以及任何MCP兼容客户端。

为什么？

• 数量级更快 比 grep/find 在大型代码库上--使用预构建的内存索引
• 全文搜索 由Bleve提供支持（单词、精确短语和正则表达式查询）
• 基于Glob的文件搜索 随着 ** 双星支持
• 自动更新 --后台文件监视器使索引与磁盘保持同步
• 可配置的过滤 --尊重 .gitignore, .claudeignore，并自定义排除模式
• 零运行时依赖关系 --单个静态Go二进制文件（~17 MB）

快速开始

# Register for a project (creates .mcp.json)
./codeindex-mcp register project /path/to/your/project

# Or register globally for all projects (updates ~/.claude.json)
./codeindex-mcp register user

就是这样——Claude Code将自动发现并使用索引搜索工具。

安装

先决条件

• 转到1.22+

从源代码构建

git clone https://github.com/lexandro/codeindex-mcp.git
cd codeindex-mcp
go build -o codeindex-mcp .

在Windows上，这会产生 codeindex-mcp.exe.

在克劳德代码中注册

构建后，注册服务器，以便Claude Code可以找到它：

# Project-specific (writes .mcp.json in the target directory)
./codeindex-mcp register project /path/to/your/project

# Global (writes ~/.claude.json — available in all projects)
./codeindex-mcp register user

# With extra server flags
./codeindex-mcp register project . -- --max-file-size 5242880 --exclude "vendor/"

这 register 命令自动检测二进制路径并创建正确的配置条目，包括 cmd /C Windows上的包装器。

运行测试

go test ./...

用法

独立式（用于测试）

./codeindex-mcp --root /path/to/project

服务器使用MCP协议通过stdio（stdin/stdout）进行通信，因此它本身不是交互式的——从MCP客户端使用它。

Claude代码集成

注册服务器最简单的方法是内置 register 子命令：

# Register for a specific project (writes .mcp.json in the project directory)
./codeindex-mcp register project /path/to/project

# Register globally for all projects (writes ~/.claude.json)
./codeindex-mcp register user

# Forward extra flags to the server
./codeindex-mcp register project . -- --max-file-size 5242880 --exclude "vendor/"

或者，手动添加到您的Claude Code MCP设置中。对于特定于项目的配置，请创建 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "codeindex": {
      "command": "/path/to/codeindex-mcp",
      "args": ["--root", "."]
    }
  }
}

对于全局配置，请添加到 ~/.claude.json:

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

Claude Code将自动使用 codeindex_search, codeindex_files, codeindex_read, codeindex_status，以及 codeindex_reindex 工具。

CLI标志

例子

# Index the current directory
./codeindex-mcp

# Specify project root with extra exclusions
./codeindex-mcp --root ~/myproject \
  --exclude "*.generated.go" \
  --exclude "testdata/"

# Force-include log files (overrides the default *.log exclusion)
./codeindex-mcp --root . --force-include "*.log"

# Multiple force-include patterns (additive)
./codeindex-mcp --root . --force-include "*.log" --force-include "vendor/*.go"

# Combine exclude and force-include
./codeindex-mcp --root ~/myproject \
  --exclude "*.generated.go" \
  --force-include "*.log"

# Disable logging entirely (no log file created)
./codeindex-mcp --root . --log-enabled=false

# Debug logging to a specific file
./codeindex-mcp --root . --log-level debug --log-file /tmp/codeindex.log

# Enable periodic sync verification every 5 minutes
./codeindex-mcp --root . --sync-interval 300

# Allow larger files (5 MB)
./codeindex-mcp --root . --max-file-size 5242880

MCP工具

服务器注册了5个工具：

1. codeindex_search --内容搜索

对所有索引文件内容进行全文搜索。

参数：

查询格式：

输出示例：

3 matches in 2 files:
main.go
  4: import "fmt"
  5:
  6: func main() {
  7:     fmt.Println("hello world")
  8: }

server/server.go
  14: func main() {
  15:     startServer()
  16: }

2. codeindex_files --文件搜索

在索引中进行基于全局的文件搜索。

参数：

输出示例：

src/main.go (Go, 2.1 KB, 85L)
src/utils/helper.go (Go, 1.3 KB, 42L)
src/server/handler.go (Go, 4.7 KB, 156L)
src/config/config.go (Go, 892 B, 31L)

3. codeindex_read --从索引读取文件

直接从内存索引中读取文件内容。零磁盘I/O——比内置的读取工具更快。

参数：

输出示例：

1: package main
2:
3: import "fmt"
4:
5: func main() {
6:     fmt.Println("hello")
7: }

4. codeindex_status --指标状态

显示当前索引统计信息。

参数： 无

输出示例：

root: /home/user/myproject
uptime: 45s
files: 1234 (8.5 MB)
memory: 95.2 MB
languages: TypeScript:456, Go:312, JavaScript:189, Python:98

5. codeindex_reindex --强制重新索引

清除索引并从头开始重建。也重新加载 .gitignore 和 .claudeignore 规则。

参数： 无

输出示例：

reindexed: 1234 files (8.5 MB) in 1.234s

忽略系统

服务器使用多层过滤系统来确定要索引哪些文件：

1.内置默认模式

自动跳过，无需任何配置：

2. .gitignore 支持

完全尊重 .gitignore 项目根中的模式，包括globs、negation(!important.log)，以及特定于目录的模式。

3. .claudeignore 支持

A. .claudeignore 项目根目录中的文件使用与相同的语法 .gitignore。使用它从git中的索引中排除与AI代码搜索无关的文件。

示例 .claudeignore:

# Generated files
*.generated.go
*.pb.go

# Large test fixtures
testdata/large/

# Archived migrations
migrations/archive/

4.CLI --exclude 模式

通过运行时排除 --exclude 标志：

./codeindex-mcp --exclude "*.generated.go" --exclude "vendor/"

5.CLI --force-include 模式

强制包括模式覆盖 全部 排除规则（内置默认值， .gitignore, .claudeignore，以及 --exclude).多个 --force-include 标志是累加的。二进制检测和文件大小限制仍然适用。

# Index *.log files even though they are excluded by default
./codeindex-mcp --force-include "*.log"

# Force-include vendor Go files while still excluding the rest of vendor/
./codeindex-mcp --force-include "vendor/*.go"

当强制包含模式处于活动状态时，可能包含匹配文件的目录在遍历过程中不会被修剪。这 .git 无论强制包含模式如何，目录都会被跳过。

6.二进制文件检测

扫描每个文件的前512个字节以查找空字节。如果找到，该文件将被视为二进制文件并跳过。这独立于 .gitignore.

7.文件大小限制

可通过以下方式配置 --max-file-size （默认值：1 MB）。大于此值的文件将被跳过。

优先级

过滤器按顺序应用：

1. --force-include 模式 （最高优先级——如果匹配，则无论规则2-5如何，文件都会被包含在内）
2. 内置默认模式
3. .gitignore 规则
4. .claudeignore 规则
5. 命令行界面 --exclude 模式
6. 二进制检测（始终适用，即使是强制包含的文件）
7. 文件大小限制（始终适用，即使是强制包含的文件）

如果强制包含模式匹配，则文件将绕过所有排除规则（2-5）。二进制检测和文件大小限制是始终适用的安全检查。

建筑

MCP Client (stdio)  MCP Server  Index Engine
                                            │
                                    ┌───────┼────────┐
                                    │       │        │
                                  Bleve   FileMap   Watcher
                               (full-text) (path)  (fsnotify)

双指标设计

文件监视器

• 用途 Fsnotify （在Windows上： ReadDirectoryChangesW API
• 递归：在启动时监视所有未被忽略的子目录
• 100ms去抖动窗口：编辑器在保存时生成多个事件——这些事件被合并为一个
• 自动监视新创建的目录
• 自动重新加载忽略规则 .gitignore 或 .claudeignore 变化

启动顺序

1. 解析CLI标志
2. 创建忽略匹配器（内置+.gitignore+.claudeignore+CLI模式）
3. 初始化Bleve内存索引和文件路径索引
4. 使用8个worker goroutines进行并行索引
5. 启动文件监视器
6. 在stdio传输上启动MCP服务器

项目结构

codeindex-mcp/
├── main.go                  # Entry point, CLI flags, component wiring
├── indexing.go              # Directory walking, parallel indexing, watcher events
├── sync.go                  # Periodic background index sync verification
├── server/
│   └── server.go            # MCP server setup, tool registration
├── index/
│   ├── content.go           # Bleve content index (CRUD operations)
│   ├── content_search.go    # Full-text search logic, query parsing
│   ├── content_test.go
│   ├── files.go             # File path index (glob search) + IndexedFile type
│   └── files_test.go
├── watcher/
│   ├── watcher.go           # Recursive fsnotify wrapper
│   └── debouncer.go         # 100ms event collapsing
├── ignore/
│   ├── ignore.go            # .gitignore + .claudeignore + custom patterns
│   ├── ignore_test.go
│   └── defaults.go          # Built-in ignore patterns
├── register/
│   ├── register.go          # Auto-register subcommand for Claude Code config
│   └── register_test.go
├── tools/
│   ├── search.go            # codeindex_search handler
│   ├── files.go             # codeindex_files handler
│   ├── read.go              # codeindex_read handler
│   ├── status.go            # codeindex_status handler
│   ├── reindex.go           # codeindex_reindex handler
│   └── format.go            # Output formatting
└── language/
    ├── detect.go            # Extension → language mapping (70+)
    ├── detect_test.go
    ├── binary.go            # Binary file detection
    └── binary_test.go

依赖项

演出

支持的语言

语言检测可识别70多个文件扩展名，包括：

Go、TypeScript、JavaScript、Python、Rust、Java、Kotlin、C、C++、C#、Swift、Dart、Ruby、PHP、Shell、PowerShell、HTML、CSS、SCSS、Sass、Less、JSON、YAML、TOML、XML、SQL、GraphQL、Protobuf、Terraform、Lua、R、Scala、Elixir、Erlang、Haskell、Zig、Vue、Svelte、Markdown、Dockerfile、Makefile、CMake、Batch等等。

许可证

麻省理工学院