Claude Code Index

克劳德代码索引

一个本地MCP（模型上下文协议）服务器，在整个代码库中提供Claude Code语义搜索。Claude通过以下方式找到代码 意义 （“认证发生在哪里”），而不仅仅是字符串匹配。

专为EWS团队成员在他们自己的机器上设置此功能而编写。约15分钟安装，每台笔记本电脑一次。在那之后，每个项目都是自动的。

______________________________________________________________________

您正在安装什么

• Claude Code作为工具调用的本地Python MCP服务器
• 每个项目的矢量数据库（首次使用时自动创建，存储在 .code_index/ 在你的项目根）
• 几个钩子插进去 ~/.claude/settings.json 所以Claude会自动使用它，并在编辑后在后台重新索引

没有任何东西离开你的机器。嵌入模型在本地运行。数据库是本地SQLite。

支持的语言：

• python (.py)--完整的AST解析：函数、类、方法、装饰器、路由、常量、文档字符串
• JavaScript/TypeScript (.js, .jsx, .ts, .tsx, .mjs, .cjs)--基于正则表达式：函数、箭头fns、类、导出
• PHP (.php, .phtml等）——基于正则表达式：函数、方法、类、接口、特征、枚举、命名空间
• 其他一切 --通用分块：HTML、CSS、JSON、YAML、Markdown、SQL、Ruby、Go、Rust、Java、C/C++、shell、Dockerfiles、配置文件

自动跳过： node_modules, venv, .git, dist, build, __pycache__，锁文件， .min.js, .map, .d.ts二进制文件， old/ 目录、小于10字节或大于500KB的文件，压缩了内容。

______________________________________________________________________

先决条件

• 已安装Claude Code CLI(claude 在您的终端中）
• Python 3.10+可在PATH上使用
• Git
• ~100 MB磁盘空间（主要是嵌入式型号，一次性下载）

适用于Windows（Git Bash或PowerShell）、macOS和Linux。以下路径假定 ~ 是您的主目录——在Windows上通常是 C:\Users\\.

______________________________________________________________________

步骤1——安装Python依赖项

推荐：专用venv 所以它不会干扰其他Python项目。

python -m venv ~/.claude-code-index-venv

# Windows (Git Bash):
source ~/.claude-code-index-venv/Scripts/activate
# macOS / Linux:
source ~/.claude-code-index-venv/bin/activate

pip install "mcp[cli]" sentence-transformers sqlite-vec
deactivate

或者，如果你愿意，可以全局安装——将venv命令替换为：

pip install "mcp[cli]" sentence-transformers sqlite-vec

验证：

python -c "from mcp.server.fastmcp import FastMCP; print('mcp OK')"
python -c "from sentence_transformers import SentenceTransformer; print('sentence-transformers OK')"
python -c "import sqlite_vec; print('sqlite-vec OK')"

第一轮 sentence-transformers 下载 all-MiniLM-L6-v2 型号（约80 MB）。一次。

______________________________________________________________________

步骤2——获取服务器文件

git clone https://github.com/epicwebstudios/claude-code-index.git
mkdir -p ~/.claude/tools/code-indexer/code_index
cp claude-code-index/code_index_server.py ~/.claude/tools/code-indexer/
cp claude-code-index/reindex_cli.py ~/.claude/tools/code-indexer/
cp claude-code-index/progress_gui.py ~/.claude/tools/code-indexer/
cp claude-code-index/code_index/*.py ~/.claude/tools/code-indexer/code_index/

______________________________________________________________________

步骤3——使用Claude Code注册MCP服务器

# If Python is directly on PATH:
claude mcp add --scope user code-index -- python ~/.claude/tools/code-indexer/code_index_server.py

# If you used the dedicated venv:
# Windows (Git Bash):
claude mcp add --scope user code-index -- ~/.claude-code-index-venv/Scripts/python ~/.claude/tools/code-indexer/code_index_server.py
# macOS / Linux:
claude mcp add --scope user code-index -- ~/.claude-code-index-venv/bin/python ~/.claude/tools/code-indexer/code_index_server.py

验证：

claude mcp get code-index

您应该看到服务器及其命令一起列出。

______________________________________________________________________

第四步——接线 ~/.claude/settings.json

将这些合并到您现有的 settings.json。如果您没有，请在以下位置创建 ~/.claude/settings.json.

{
  "permissions": {
    "allow": [
      "mcp__code-index__*"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__code-index__reindex",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'BLOCKED: Do not call mcp__code-index__reindex directly. Run reindex via Bash with run_in_background: true instead.' && exit 1",
            "timeout": 5
          }
        ]
      },
      {
        "matcher": "Read|Grep|Glob",
        "hooks": [
          {
            "type": "command",
            "command": "if [ -f \"$PWD/.code_index/code_index.db\" ] && [ ! -f /tmp/.claude-codeindex-used ]; then echo '[code-index] Reminder: prefer mcp__code-index search tools (search_code, search_symbol, get_file_overview) for broad code exploration. Use Read/Grep/Glob for targeted lookups on known files.'; fi",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "touch /tmp/.claude-reindex-needed",
            "timeout": 5,
            "async": true
          }
        ]
      },
      {
        "matcher": "mcp__code-index__search_code|mcp__code-index__search_symbol|mcp__code-index__get_file_overview",
        "hooks": [
          {
            "type": "command",
            "command": "touch /tmp/.claude-codeindex-used",
            "timeout": 5,
            "async": true
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/.claude-codeindex-used; if [ -f \"$PWD/.code_index/code_index.db\" ] && [ -f /tmp/.claude-reindex-needed ]; then rm /tmp/.claude-reindex-needed && python \"$HOME/.claude/tools/code-indexer/reindex_cli.py\" --quiet > /dev/null 2>&1 & disown && echo '[code-index] Background reindex started.'; fi",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

每个钩子的作用是什么

重要提示： 如果在步骤1中使用了venv路由，请替换 python 在UserPromptSubmit命令中，使用venv Python的完整路径（例如。 $HOME/.claude-code-index-venv/bin/python).

______________________________________________________________________

第5步——告诉克劳德使用它（添加到 ~/.claude/CLAUDE.md)

将此附加到您的全局CLAUDE.md中，以便CLAUDE首先获取索引：

## Code Index (MANDATORY)

Prefer `mcp__code-index` tools (`search_code`, `search_symbol`, `get_file_overview`) over Grep/Glob for broad code searches. Use Grep/Glob for targeted lookups on known files or exact literal string matches.

**Reindexing**: ALWAYS via Bash with `run_in_background: true`. Never block the conversation on reindex.
**Background agents**: Run Explore and research agents with `run_in_background: true`.

______________________________________________________________________

步骤6--安装 /index-project 斜杠命令

这是您每天用来重建或刷新索引的命令。从任何Claude Code会话中运行它。

mkdir -p ~/.claude/skills/index-project
cp skills/index-project/SKILL.md ~/.claude/skills/index-project/

在项目中打开的Claude Code会话中使用：

• /index-project --full — 从头开始完全重新索引 （首次初始化，或彻底重建）
• /index-project --增量重新索引（快速，仅更改文件）

这项技能可以扩展到 ~/.claude/tools/code-indexer/reindex_cli.py 引擎盖下。如果在步骤1中使用了专用venv，请编辑 ~/.claude/skills/index-project/SKILL.md 和交换 python 对于您的venv-Python路径（例如。 ~/.claude-code-index-venv/Scripts/python 在Windows上， ~/.claude-code-index-venv/bin/python 在Mac/Linux上）。

______________________________________________________________________

步骤7--忽略索引

每个项目都有自己的 .code_index/ 目录。全球排除：

echo ".code_index/" >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global

______________________________________________________________________

步骤8——为项目构建初始索引(/index-project --full)

在项目中第一次使用索引时，您需要从头开始构建它。

1. 在项目根目录中打开Claude代码：

   cd ~/path/to/your-project
   claude

1. 在Claude Code提示符下，键入：

   /index-project --full

发生了什么：

1. 弹出一个小型Tk进度窗口（安装了Tk的Windows/macOS/Linux）
2. 您的终端显示实时进度条——文件发现→ 解析→ 嵌入→ store
3. A. .code_index/ 使用SQLite矢量数据库在项目根目录中创建文件夹
4. 小型项目需要10-60秒，大型项目（1000多个文件）需要2-3分钟

当它完成时，你会看到类似的东西：

  ==================================================
  Complete in 42.3s
  Files indexed: 287
  Files skipped: 41 (non-indexable)
  Total chunks:  1,942
  Symbol types:
    function: 612
    class: 84
    method: 443
    ...

/index-project --full vs增量——何时使用哪个

你几乎不需要手动运行增量重新索引—— UserPromptSubmit 每当文件发生更改时，hook都会在提示之间为您执行此操作。 /index-project --full 是你真正要输入的。

回退：直接运行CLI（未安装技能/在Claude Code之外）

如果跳过步骤6或希望在Claude Code会话之外运行索引器，请直接从项目根目录调用CLI：

# If Python is on PATH:
python ~/.claude/tools/code-indexer/reindex_cli.py --full

# If you used the dedicated venv (Step 1):
# Windows (Git Bash):
~/.claude-code-index-venv/Scripts/python ~/.claude/tools/code-indexer/reindex_cli.py --full
# macOS / Linux:
~/.claude-code-index-venv/bin/python ~/.claude/tools/code-indexer/reindex_cli.py --full

掉落 --full 对于增量重新索引。与斜线命令效果相同，只是键入更多。

______________________________________________________________________

步骤9——端到端验证

1. 在您刚刚索引的项目中打开Claude Code会话： cd ~/your-project && claude
2. 问Claude一些需要代码搜索的问题，例如。 *“这个项目的主要切入点是什么？”*
3. 克劳德应该打电话来 mcp__code-index__search_code 或 mcp__code-index__get_file_overview --您将在会话中看到工具调用

如果您没有看到正在使用的索引工具，请检查：

• claude mcp get code-index --服务器是否已注册？
• 您的CLAUDE.md--是否添加了“代码索引（强制）”部分？
• ~/.claude/settings.json --钩子是否存在并且是有效的JSON？
• 是否 .code_index/code_index.db 是否存在于项目根目录中？如果没有，则步骤8没有完成——再次运行

______________________________________________________________________

日常使用

你不应该做任何事情。Claude会自动调用索引工具。编辑文件后，下一个提示会触发后台增量重新索引。你只要继续工作。

何时手动运行 /index-project --full:

• 你拉了一个有巨大差异的分支，搜索感觉很乏味
• 您添加/删除了一堆顶级目录
• mcp__code-index__index_status 报告文件丢失或外观错误
• 您升级了嵌入模型或索引器本身

在项目的Claude Code会话中：

/index-project --full

（如果您需要在不使用斜线命令的情况下运行它，请参阅步骤8的“回退”部分。）

______________________________________________________________________

工具的作用是什么

______________________________________________________________________

故障排除

服务器未连接

1. 重新注册： claude mcp remove code-index 然后重复步骤3
2. 检查依赖关系：从步骤1重新运行验证命令
3. 日志： %LOCALAPPDATA%/claude-cli-nodejs/Cache/*/mcp-logs-code-index/ （Windows）或 ~/.local/share/claude-cli-nodejs/Cache/*/mcp-logs-code-index/ （Mac/Linux）

Python版本错误/导入错误 使用正确Python的完整路径重新注册：

claude mcp remove code-index
claude mcp add --scope user code-index -- /full/path/to/python ~/.claude/tools/code-indexer/code_index_server.py

指数看起来过时了 强制从Claude Code会话进行完全重建： /index-project --full （或奔跑 python ~/.claude/tools/code-indexer/reindex_cli.py --full 如果您没有安装slash命令，则从项目根目录开始）。

钩子没有开火

• JSON必须有效--运行 python -m json.tool ~/.claude/settings.json 检查
• 编辑后重新启动Claude代码 settings.json
• 在Windows上，钩子命令使用Git Bash语法([ -f ... ], touch).确保已安装Git Bash。

______________________________________________________________________

参考——事物所在的地方

______________________________________________________________________

回购结构

claude-code-index/
    code_index_server.py      # MCP server entry point
    reindex_cli.py            # CLI for manual reindexing
    progress_gui.py           # Optional Tk progress window
    code_index/
        __init__.py
        indexer.py            # Build/update orchestrator
        parser.py             # Multi-language code parser
        embeddings.py         # sentence-transformers wrapper
        database.py           # SQLite + sqlite-vec layer
    skills/index-project/
        SKILL.md              # Optional /index-project slash command

______________________________________________________________________

演出

• 首次索引构建：10-60秒，具体取决于项目规模
• 增量重新索引：毫秒到秒（mtime+内容哈希比较）
• 对大型项目（1000+个文件）进行完全重新索引：2-3分钟

______________________________________________________________________

问题——ping肖恩。