idea-mcp

IntelliJ IDEA MCP 技能

路径规则（最常见的错误来源）

参数	路径类型	示例
projectPath	绝对路径	/Users/huangli/dt/dongting
filePath、pathInProject、directoryPath、contextPath	相对路径	server/src/main/java/...

路径设置错误是导致“找不到文件”错误的首要原因。

注意事项和提示

两类搜索 API

IDEA MCP 有两组搜索工具，返回的格式各不相同。请选择合适的一组：

• search_in_files_by_text / search_in_files_by_regex — 返回包含 ||highlight|| 标记的匹配行。适用于快速查找“此字符串在哪里使用”。支持 fileMask 筛选器。
• search_text / search_regex / search_file / search_symbol — 返回包含精确坐标（行、列、字节偏移量）的结构化结果。支持 paths glob 筛选器和 ! 排除项。当你需要精确位置以便执行后续操作时，请使用这一组。
  • search_symbol 尤其强大 — 可按语义查找符号（类、方法、字段），并返回完整代码片段。

execute_terminal_command 默认不使用 Shell

如果没有设置 executeInShell: true，$() 展开、管道和通配符等 Shell 功能将无法使用。对于大多数 Shell 命令，建议直接使用 Bash 工具。

rename_refactoring 接受符号名称，而非位置

参数为 symbolName（精确的标识符字符串）和 newName，而不是文件路径和行／列。这与基于 LSP 的重命名不同。

使用 build_project 编译单个文件

使用 filesToRebuild 参数的 build_project 可以比运行 mvn compile 更快地编译指定文件。适用于编辑后快速验证。

get_file_problems 与 LSP 诊断的对比

对于多模块 Maven 项目，get_file_problems 的准确性明显高于 LSP lsp_diagnostics。检查 Java 错误时，优先使用它。

高风险操作

• rename_refactoring 和 replace_text_in_file — 会全局修改代码，使用后请通过 get_file_problems 进行验证
• reformat_file — 未经确认就会修改格式

故障排除

问题	解决方案
连接被拒绝	确认 IDEA 正在运行，且已安装 MCP 插件
请求超时	在 IDEA 中接受权限对话框
找不到文件	检查绝对路径与相对路径（参见上方的路径规则）