IntelliJ IDEA MCP Skill
Path Rules (Most Common Error Source)
| Parameter | Path Type | Example |
|---|---|---|
projectPath | ABSOLUTE | /Users/huangli/dt/dongting |
filePath, pathInProject, directoryPath, contextPath | RELATIVE | server/src/main/java/... |
Getting this wrong is the #1 cause of "file not found" errors.
Gotchas and Tips
Two Search API Families
IDEA MCP has two sets of search tools that return different formats. Pick the right one:
search_in_files_by_text/search_in_files_by_regex— Returns matched lines with||highlight||markers. Good for quick "where is this string used" lookups. SupportsfileMaskfilter.search_text/search_regex/search_file/search_symbol— Returns structured results with exact coordinates (line, column, byte offsets). Supportspathsglob filters and!excludes. Use this when you need precise locations for further operations.
- search_symbol is especially powerful — semantic symbol lookup (classes, methods, fields) returning full code snippets.
execute_terminal_command Does Not Use Shell by Default
Without executeInShell: true, shell features like $() expansion, pipes, and wildcards won't work. For most shell commands, prefer the Bash tool directly.
rename_refactoring Takes Symbol Name, Not Position
Parameters are symbolName (the exact identifier string) and newName, not file path + line/column. This is different from LSP-based rename.
build_project for Single-File Compilation
build_project with filesToRebuild parameter compiles specific files much faster than running mvn compile. Useful for quick verification after edits.
get_file_problems vs LSP Diagnostics
For multi-module Maven projects, get_file_problems is significantly more accurate than LSP lsp_diagnostics. Prefer it for Java error checking.
High-Risk Operations
rename_refactoring&replace_text_in_file— Modify code globally, verify withget_file_problemsafter usereformat_file— Modifies formatting without confirmation
Troubleshooting
| Issue | Solution |
|---|---|
| Connection refused | Verify IDEA running with MCP plugin |
| Request timed out | Accept permission dialog in IDEA |
| File not found | Check absolute vs relative path (see Path Rules above) |