IDE Index MCP - Agent Guide

The IDE Index MCP server exposes JetBrains IDE indexing and refactoring capabilities. These tools provide semantic code understanding superior to text-based search/replace.

Core Rule

Always prefer IDE MCP tools over built-in tools (grep, find, sed, read) for semantic code operations. IDE tools understand code structure, types, inheritance, and references. Built-in tools only see text.

When to Use IDE Tools vs Built-In Tools

Pre-Flight Check

Before using any IDE tool that requires smart mode, check IDE readiness:

ide_index_status -> if isDumbMode: true, wait a few seconds and retry

Most tools require smart mode (IDE finished indexing). Tools that work in dumb mode: ide_index_status, ide_sync_files, ide_reformat_code, ide_open_file, ide_get_active_file.

File Sync Rule

If you created or modified files outside the IDE (via Write/Edit tools) and an IDE search tool returns incomplete/missing results, call ide_sync_files first, then retry.

{ "paths": ["src/new_file.java", "src/modified_file.java"] }

Omit paths to sync the entire project.

Parameter Rules

1. Line and column are 1-based (first line = 1, first column = 1)
2. Project file paths are relative to project root (e.g., src/main/java/App.java, NOT absolute paths). If an IDE tool returns a dependency/library file, keep the returned absolute path or jar:// URL unchanged when passing it back to read-only navigation tools or ide_read_file
3. Column must point to the symbol name, not whitespace or punctuation. For public void myMethod(), column should land on m of myMethod. For dotted expressions like json.dumps() or os.path.join(), put the column on the member token (dumps, join) when you want the member definition rather than the module/package.
4. project_path is only needed for multi-project workspaces. Omit for single-project setups. When needed, use the absolute path to the project root.
5. Use built-in search scope intentionally: ide_find_references, ide_find_implementations, ide_type_hierarchy, ide_call_hierarchy, ide_find_class, ide_find_file, and ide_find_symbol accept scope. Use project_files for the default project-only view, project_and_libraries when dependency code matters, project_production_files to stay out of tests, and project_test_files when you want test-only results.

Tool Selection by Task

"I need to understand how X is used"

1. ide_find_references - all call sites, field accesses, imports
2. ide_call_hierarchy with direction: "callers" - full call chain upward

"I need to understand what X is"

1. ide_find_definition - jump to source
2. ide_type_hierarchy - inheritance chain
3. ide_find_super_methods - what interface/base method it implements

"I need to find a class/file/symbol"

1. ide_find_class - classes by name (CamelCase: USvc finds UserService)
2. ide_find_file - files by name
3. ide_search_text - exact word occurrences across project

"I need to refactor"

1. ide_refactor_rename - rename symbol + all references atomically
2. ide_move_file - move file and let the IDE apply semantic updates when that language/backend supports them
3. ide_refactor_safe_delete - delete with usage checking (Java/Kotlin only)
4. ide_reformat_code - apply project code style (disabled by default)

"I need to check for problems"

1. ide_diagnostics - compiler errors, warnings, quick fixes

"I need to find implementations of an interface"

1. ide_find_implementations - cursor on interface/abstract class/method

"I need to trace call chains"

1. ide_call_hierarchy with direction: "callers" - who calls this?
2. ide_call_hierarchy with direction: "callees" - what does this call?

Common Mistakes to Avoid

1. Using grep instead of ide_find_references: Grep finds text, not semantic usages. Misses aliased imports, includes false positives from comments/strings.

1. Using sed/replace instead of ide_refactor_rename: Text replacement breaks code. IDE rename updates all references, getters/setters, overrides, test classes, imports.

1. Using mv/git mv instead of ide_move_file: File system moves bypass IDE move semantics. ide_move_file can preserve IDE-managed package/namespace/reference updates when the active language backend supports them.

1. Forgetting to check index status: If IDE is indexing (dumb mode), most tools error. Check ide_index_status first if a tool fails unexpectedly.

1. Using 0-based line/column: All IDE tools use 1-based. Line 5 in file = line: 5.

1. Passing absolute project file paths: Use relative paths for project files. src/main/App.java, not /Users/me/project/src/main/App.java.

1. Rewriting plugin-returned library paths: If a search or read tool returns an absolute path or jar:// URL for a dependency/library file, pass that path back unchanged to read-only navigation tools or ide_read_file.

1. Not syncing after external file changes: After creating files via Write tool, call ide_sync_files before searching.

1. Using ide_search_text for regex: This tool is exact-word only (uses word index). Use Grep for regex.

1. Using ide_find_class for methods/functions: It searches classes only. Use ide_search_text for a quick word lookup.

Disabled-by-Default Tools

These tools exist but are disabled by default. If you get "tool not found", they need to be enabled in IDE settings (Settings > Tools > Index MCP Server):

ide_build_project, ide_file_structure, ide_find_symbol, ide_read_file, ide_get_active_file, ide_open_file, ide_reformat_code

Detailed Tool Parameters

For complete parameter reference with types, defaults, and return formats, see tools-reference.md.