Narylr350 JetBrains IDE MCP
定位
IDE 可用时，优先利用 JetBrains 的项目索引、PSI、Inspection、运行配置和调试器理解并修改代码，而不是把代码当作普通文本处理。
核心原则：IDE-first，不是 IDE-only。 语义操作必须优先使用 IDE；复杂且确定的文本修改可以使用精确 patch；命令行用于 Git、项目原生命令、验证补充和连接失败时降级。
前置检查
- 确认当前目录对应 JetBrains 中打开的项目。
- 确认 JetBrains MCP 工具可调用。
- 已知项目路径时，后续每次调用显式传入同一个绝对
projectPath。 - 先读取项目指令和 Git 状态，再开始代码操作；IDE 状态不能替代仓库事实。
IDE 未运行、项目未打开或 MCP 不可用时，先尝试确认连接状态。无法恢复时再按“降级策略”继续，不要假装执行过 IDE Inspection 或语义重构。
工作区已使用 jetbrains-workspace-setup 时，当前任务应只加载一套统一的 mcp__jetbrains__* 工具。配置或 IDE 选择发生变化后新建或重启任务；不要声称能在当前任务中热切换整套 MCP。
工具路由
| 任务 | 首选工具 | 说明 |
|---|---|---|
| 查看项目结构 | list_directory_tree |
优先于 shell 目录遍历 |
| 按文件名找文件 | find_files_by_name_keyword / find_files_by_glob |
已知名称片段时优先前者 |
| 读取代码 | read_file |
按行、缩进块或范围读取，避免无目的加载整文件 |
| 找类、函数、字段 | search_symbol |
找不到时再扩大到外部依赖 |
| 查符号定义、类型和文档 | get_symbol_info |
用于确认 API 和类型语义 |
| 搜索普通文本或错误消息 | search_text / search_regex |
文本内容不必强行走符号搜索 |
| 重命名程序符号 | rename_refactoring |
必须优先于字符串替换 |
| 精确局部替换 | replace_text_in_file |
仅用于语义明确的局部文本修改 |
| 创建文件 | create_new_file |
遵循现有目录和命名风格 |
| 格式化代码 | reformat_file |
只格式化本轮修改文件 |
| 检查 warning/error | get_file_problems(errorsOnly=false) |
修改前可定位问题，修改后用于回归检查 |
| 编译项目或模块 | build_project |
修改后必须调用；可用 filesToRebuild 缩小范围 |
| 查找并运行入口 | get_run_configurations + execute_run_configuration |
优先复用已有运行配置 |
| 诊断运行时 bug | xdebug_* |
用断点、调用栈和变量值提供运行时证据 |
| 数据库操作 | list_database_* / execute_sql_query |
先确认连接和 schema，避免猜表结构 |
| Notebook | runNotebookCell |
修改或验证 notebook 时使用 |
IDE-first 工作流
1. 探索
- 用
list_directory_tree确认相关模块。 - 用
search_symbol、get_symbol_info和引用搜索理解符号关系。 - 只读取任务直接相关的文件和代码块。
- 需要判断真实运行路径时，查看运行配置或使用调试器，不只靠静态猜测。
2. 编辑
按语义风险选择工具：
- 符号重命名、跨文件引用更新：使用
rename_refactoring。 - 小范围确定性替换：使用
replace_text_in_file。 - 大段、多处或结构化修改：先用 IDE 定位语义和影响范围，再使用精确 patch；不要把大量代码塞进脆弱的字符串替换。
- 新文件：使用
create_new_file，然后重新格式化和检查。 - 不修改无关文件，不借 IDE 自动能力扩大重构范围。
3. 即时检查
每完成一个逻辑批次：
- 对修改文件调用
get_file_problems(errorsOnly=false)。 - 确认目标问题消失，并检查是否新增 warning/error。
- 需要格式化时调用
reformat_file，然后重新检查。
4. 构建和运行验证
完成编辑后必须调用 build_project。如果项目或语言不提供完整构建诊断，再运行项目原生验证命令。
按改动选择附加验证：
- 行为或业务逻辑变化：运行相关测试或运行配置。
- 公共 API、接口、类型或依赖变化：构建受影响模块或整个项目。
- 难复现 bug：使用调试器验证原始症状和修复后的运行时状态。
- Python 等解释型项目：以 Inspection、测试和项目原生命令为主，不把 limited build diagnostics 当作完整验证。
5. Git 核验
IDE 检查完成后仍要查看 Git diff，确认：
- 修改范围与用户需求一致。
- 语义重构没有带入无关文件。
- 自动格式化没有扩大 diff。
- 没有临时文件、生成物或调试残留。
projectPath 规则
已知项目路径时，每次调用都显式传入绝对 projectPath，避免多项目环境误操作。
只有项目路径未知且工具支持自动发现时才允许暂时省略。发现正确项目后，后续调用固定使用同一个路径。文件参数如 filePath、pathInProject 通常使用相对项目根的路径，按具体工具 schema 传递。
调试器纪律
- 先确认存在可执行的运行配置或入口。
- 启动调试前至少设置一个预期会命中的断点。
- 每次暂停后重新获取当前 stack/frame，不复用执行位置变化前的 frame index。
- 用变量值和调用栈验证假设，不把推理描述成运行时事实。
- 调试完成后停止会话，移除本轮创建的临时断点，不保持无用进程运行。
降级策略
JetBrains MCP 不可用时，按能力降级：
| IDE 能力 | 降级方式 |
|---|---|
| Inspection | 项目 lint、类型检查或编译器 |
| Build | Maven、Gradle、npm、Cargo、Go 等项目原生命令 |
| 符号搜索 | 代码搜索 + 人工核对声明和引用 |
| 语义重命名 | 精确编辑 + 全仓引用搜索 + 构建验证 |
| 运行配置 | 项目已有测试或启动命令 |
| 调试器 | 日志、最小复现和针对性测试 |
降级后明确记录实际使用的验证方式，不声称获得了 IDE 级证据。
Related Skills
jetbrains-code-review— 使用 IDE Inspection、构建和 Git diff 生成证据化审查报告。jetbrains-code-fix— 按问题清单分类修复，并逐批重新检查和构建。jetbrains-workspace-setup— 为 Codex、opencode 或 Claude Code 工作区注册单一 JetBrains MCP，并在连接前启动用户选择的 IDE。