# Jetbrains Ide MCP

> Use JetBrains IDE MCP for coding tasks when a JetBrains project is open. Trigger for implementing features, fixing bugs, exploring code, editing or refactoring symbols, checking problems, building, testing, running, or debugging. Prefer IDE semantic operations over plain-text and shell approximations while keeping precise patch and command-line fallbacks.

- Skill: `narylr350/jetbrains-ide-mcp` (Agent Skill)
- Install (CLI): `npx skillmds@latest add narylr350/jetbrains-ide-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/narylr350/jetbrains-ide-mcp/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Narylr350 (https://skillmd.com/u/narylr350)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/narylr350/jetbrains-ide-mcp

---


# JetBrains IDE MCP

## 定位

IDE 可用时，优先利用 JetBrains 的项目索引、PSI、Inspection、运行配置和调试器理解并修改代码，而不是把代码当作普通文本处理。

核心原则：**IDE-first，不是 IDE-only。** 语义操作必须优先使用 IDE；复杂且确定的文本修改可以使用精确 patch；命令行用于 Git、项目原生命令、验证补充和连接失败时降级。

## 前置检查

1. 确认当前目录对应 JetBrains 中打开的项目。
2. 确认 JetBrains MCP 工具可调用。
3. 已知项目路径时，后续每次调用显式传入同一个绝对 `projectPath`。
4. 先读取项目指令和 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. 即时检查

每完成一个逻辑批次：

1. 对修改文件调用 `get_file_problems(errorsOnly=false)`。
2. 确认目标问题消失，并检查是否新增 warning/error。
3. 需要格式化时调用 `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。