Context Tools Plugin - 使用指南

动态目录支持 (v0.8.0+)

好消息： MCP 工具自动适应当前工作目录！

工作原理：

cd /home/user/project-a
# MCP 工具查询/索引 project-a/.claude/repo-map.db

cd /home/user/project-b
# MCP 工具现在查询/索引 project-b/.claude/repo-map.db ✅

行为：

工具在每次调用时检查当前工作目录
如果存在 .claude/repo-map.db：查询它
如果不存在：为当前目录触发索引
日志显示正在查询的目录

好处：

更换项目时无需重启会话
可以在一个会话中使用多个项目
每个项目维护自己的索引
无论你在哪里，工具都能“正常工作”

插件安装和更新

重要提示： 当用户运行 /plugin install 或 /plugin update 时：

MCP 服务器配置会立即更改，但 MCP 服务器本身不会自动重启。新插件功能（特别是 MCP 工具如 search_symbols）在会话重启之前将不可用。

你必须告诉用户：

插件已成功安装/更新。要使用 MCP 工具（search_symbols, get_file_symbols 等），你需要重启会话：

1. 退出此会话（Ctrl+C 或输入 'exit'）
2. 使用以下命令开始新会话：claude continue

MCP 服务器将用新的插件配置重启。

何时给出此指示：

用户运行 /plugin install context-tools 后立即
用户运行 /plugin update context-tools 后立即
用户尝试使用 MCP 工具但它们不可用（你怀疑他们刚刚安装了）

为什么这很重要：

MCP 服务器在 Claude Code 启动时启动
插件安装修改 MCP 服务器配置
更改仅在下一次 Claude Code 启动时生效
如果安装后工具不工作，用户会感到困惑

可用的 MCP 工具

安装后会话重启，以下 MCP 工具可用：

mcprepo-mapsearch_symbols

按名称模式搜索符号（函数、类、方法）。

比 Grep/Search 快 - 使用预构建的 SQLite 索引。

参数：

pattern（必需）：像 get_*, *Handler, Config* 这样的 Glob 模式
kind（可选）：按 "class", "function", 或 "method" 过滤
limit（可选）：最大结果数（默认：20）

示例：

{
  "pattern": "parse_*",
  "kind": "function",
  "limit": 10
}

mcprepo-mapget_file_symbols

获取特定文件中定义的所有符号。

参数：

file（必需）：从项目根目录的相对路径（例如 "src/models/user.py"）

mcprepo-mapget_symbol_content

通过确切名称获取符号的源代码内容。

比 Grep/Search+Read 快 - 直接检索函数/类源代码。

参数：

name（必需）：确切的符号名称（例如 "MyClass", "User.save"）
kind（可选）：如果名称有歧义，按类型过滤

mcprepo-mapreindex_repo_map

触发仓库符号的重新索引。

参数：

force（可选）：即使缓存是最新的，也强制重新索引（默认：false）

mcprepo-maprepo_map_status

获取当前仓库映射索引的状态。

显示：

索引状态：idle, indexing, completed, 或 failed
符号计数
最后索引时间
索引是否过时
索引错误（如果有）

mcprepo-mapwait_for_index

等待索引完成。

参数：

timeout_seconds（可选）：等待时间（默认：60）

注意： 大多数工具自动等待索引完成，因此很少需要这个。

数据库模式（.claude/repo-map.db）

symbols 表：

name（TEXT）：符号名称
kind（TEXT）：class, function, 或 method
file_path（TEXT）：从项目根目录的相对路径
line_number（INTEGER）：起始行（1-索引）
end_line_number（INTEGER）：结束行（可为空）
parent（TEXT）：父类/模块（可为空）
docstring（TEXT）：docstring 的第一行（可为空）
signature（TEXT）：函数/方法签名（可为空）
language（TEXT）：python, cpp, 或 rust

metadata 表（v0.7.0+）：

key（TEXT PRIMARY KEY）：元数据键
value（TEXT）：元数据值

键：

status：idle | indexing | completed | failed
index_start_time：索引开始时的 ISO8601 时间戳
last_indexed：最后一次完成时的 ISO8601 时间戳
symbol_count：索引的总符号数（字符串）
error_message：如果状态=‘failed’，则为错误消息

索引状态和自动等待（v0.7.0+）

首次使用行为：

在首次使用时，索引会在后台自动开始
如果索引正在进行中，工具会自动等待（最多 60 秒）
如果超时，工具会返回有用的错误提示，让用户重试

看门狗（v0.7.0+）：

检测挂起的索引进程（>10 分钟）
自动将状态重置为 ‘failed’
可以使用 reindex_repo_map 手动恢复

多进程架构（v0.8.0+）：

索引在单独的子进程中运行
即使索引挂起，MCP 服务器也保持响应
看门狗可以杀死挂起的子进程，而不影响 MCP 服务器
资源限制（Unix/macOS）：4GB 内存，20 分钟 CPU 时间

何时使用 MCP 工具与其他工具

使用 MCP repo-map 工具时：

按名称模式搜索符号（比 Grep 快）
获取文件中的所有符号（比 Read + 解析快）
获取特定函数/类的源代码（比 Grep + Read 快）
需要跨多种语言（Python, C++, Rust）搜索

使用其他工具时：

搜索文件内容（不是符号名称）- 使用 Grep
读取整个文件 - 使用 Read
需要搜索不是 Python/C++/Rust 的文件
搜索非代码模式（注释、字符串等）

项目特定文件

在会话开始时自动生成：

.claude/project-manifest.json - 项目结构和构建命令
.claude/repo-map.md - 易于阅读的代码结构，具有重复检测
.claude/repo-map.db - SQLite 数据库，用于快速符号查询（MCP 服务器）

可选（手动创建）：

.claude/learnings.md - 项目特定的学习和发现

日志：

.claude/logs/repo-map-server.log - MCP 服务器旋转日志（每个文件 1MB，3 个备份）
- 工具调用和结果
- 索引事件和性能
- 看门狗操作和资源限制违规
- 服务器启动/关闭
会话开始钩子输出也记录在日志中，用于调试