克劳德代码索引

一个本地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
          }
        ]
      }
    ]
  }
}

每个钩子的作用是什么

挂钩	用途
PreToolUse on `mcp__code-index__reindex`	阻止Claude直接调用reindex——强制它通过Bash运行 `run_in_background: true` 所以谈话不会停顿
PreToolUse on `Read\	Grep\	Glob`	温和地推动使用代码索引工具进行广泛搜索。仅当您在本次会话中尚未使用索引时才会触发
PostTool使用 `Edit\	Write`	放置一个标志，以便下一个提示知道重新索引
PostTool使用 `mcp__code-index__search_*`	将索引标记为已使用，使提醒钩静音
UserPromptSubmit	清除已使用的标志，如果文件发生更改，则启动后台重新索引。从不堵塞

重要提示： 如果在步骤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`)

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

   cd ~/path/to/your-project
   claude

在Claude Code提示符下，键入：

   /index-project --full

发生了什么：

弹出一个小型Tk进度窗口（安装了Tk的Windows/macOS/Linux）
您的终端显示实时进度条——文件发现→ 解析→ 嵌入→ store
A. .code_index/ 使用SQLite矢量数据库在项目根目录中创建文件夹
小型项目需要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增量——何时使用哪个

命令	它的作用	何时运行它
`/index-project --full`	湿巾 `.code_index/` 从头开始重建	第一次在一个项目。此外，每当索引看起来损坏时，你都会进行一次巨大的重构，或者你拉了一个严重分叉的分支
`/index-project`	增量-仅重新处理mtime或内容哈希值发生变化的文件	每天刷新。快速--毫秒到秒。这是后台钩子在提示之间自动运行的内容

你几乎不需要手动运行增量重新索引—— 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——端到端验证

在您刚刚索引的项目中打开Claude Code会话： cd ~/your-project && claude
问Claude一些需要代码搜索的问题，例如。 *“这个项目的主要切入点是什么？”*
克劳德应该打电话来 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的“回退”部分。）

______________________________________________________________________

工具的作用是什么

工具	当克劳德使用它时
`search_code`	语义查询——模式、实现、“X是如何工作的”
`search_symbol`	按名称查找类/函数/接口/特性/路由
`get_file_overview`	在完整读取文件之前，文件中有什么（大令牌保护程序）
`index_status`	确认指数是最新且健康的
`reindex`	编辑后刷新。仅限背景，通过钩子强制执行

______________________________________________________________________

故障排除

服务器未连接

重新注册： claude mcp remove code-index 然后重复步骤3
检查依赖关系：从步骤1重新运行验证命令
日志： %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/tools/code-indexer/`
MCP注册	由管理 `claude mcp add`
权限输入	`~/.claude/settings.json` → `permissions.allow` → `"mcp__code-index__*"`
钩子	`~/.claude/settings.json` → `hooks`
克劳德指令	`~/.claude/CLAUDE.md` → “代码索引（强制性）”部分
按项目指标	`
/.code_index/` （自动创建，gitignored）

______________________________________________________________________

回购结构

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肖恩。

Claude Code Index

快速接入

详细介绍

克劳德代码索引

您正在安装什么

先决条件

步骤1——安装Python依赖项

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

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

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

每个钩子的作用是什么

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

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

步骤7--忽略索引

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

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

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

步骤9——端到端验证

日常使用

工具的作用是什么

故障排除

参考——事物所在的地方

回购结构

演出

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

Claude Code Index

快速接入

详细介绍

克劳德代码索引

您正在安装什么

先决条件

步骤1——安装Python依赖项

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

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

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

每个钩子的作用是什么

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

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

步骤7--忽略索引

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

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

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

步骤9——端到端验证

日常使用

工具的作用是什么

故障排除

参考——事物所在的地方

回购结构

演出

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

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

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

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

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

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