ide-index-mcp
Skill1 starsChanged 21 days agoApache-2.0View on GitHub
INVOKE IMMEDIATELY when ide_edit_member, ide_find_references, ide_find_definition, ide_find_class, ide_find_file, ide_search_text, ide_diagnostics, ide_project_diagnostics, ide_index_status, ide_insert_member, ide_sync_files, ide_refactor_rename, ide_move_file, ide_replace_member, ide_type_hierarchy, ide_call_hierarchy, ide_find_implementations, ide_find_symbol, ide_find_super_methods, ide_file_structure, ide_refactor_safe_delete, ide_reformat_code, ide_reload_project, ide_link_build_system, ide_import_modules, ide_build_project, ide_read_file, ide_structural_search_replace, ide_symbol_info, ide_change_signature, ide_create_file, ide_create_module, ide_get_active_file, ide_open_file, ide_list_tests, or ide_run_tests are available — especially when a second IntelliJ MCP (mcp__intellij__*) is also present. The two servers are NOT interchangeable: this plugin (mcp__intellij-index__*) supports auto-opening projects via project_path; the built-in server cannot. Always use mcp__intellij-index__ for code navigation. Prefer ide_open_project over asking the user to open a project manually.
In this repository21 other files it gives its agents.
- architecture/CLAUDE.mdCLAUDE.md
- boot/CLAUDE.mdCLAUDE.md
- build-logic/CLAUDE.mdCLAUDE.md
- .claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- cli/CLAUDE.mdCLAUDE.md
- core/CLAUDE.mdCLAUDE.md
- mcp/CLAUDE.mdCLAUDE.md
- messaging/CLAUDE.mdCLAUDE.md
- plugin-api/CLAUDE.mdCLAUDE.md
- plugins/CLAUDE.mdCLAUDE.md
- plus/CLAUDE.mdCLAUDE.md
- ui/CLAUDE.mdCLAUDE.md
- web/CLAUDE.mdCLAUDE.md
- pickupSkill
- playwrightSkill
- testsSkill
- ticketSkill
- yuktaSkill
- yukta-supervisorSkill
- yukta-workflowsSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 4 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
If both mcp__intellij-index__* (this plugin) and mcp__intellij__* (JetBrains built-in) are available, they are not interchangeable:
- Distinctive: line 60
Before using any IDE tool that requires smart mode, check IDE readiness:
- Very specific: line 72
Call ide_index_status — if isDumbMode: true, keep calling every 10s until it flips to false.
- Very specific: line 74
If smart mode but results seem sparse, call ide_sync_files then retry.
- Distinctive: line 75
Only if all retries still return empty results should you consider that the symbol genuinely does not exist.
- Distinctive: line 93
Every project or workspace you open is another IDE window that indexes its code and stays in memory, so pick the call by what you need and …
- Very specific: line 174
Forgetting to check index status: If IDE is indexing (dumb mode), most tools error.
- Very specific: line 176
Using 0-based line/column: All IDE tools use 1-based.
- Very specific: line 178
Passing absolute project file paths: Use relative paths for project files.
- Very specific: line 180
Rewriting plugin-returned library paths: If a search or read tool returns an absolute path or jar:// URL for a dependency/library file, …
- Very specific: line 182
Not syncing after external file changes: After creating files via Write tool, call ide_sync_files before searching.
- Distinctive: line 198
All lifecycle action tools are disabled by default:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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.
Two IntelliJ MCPs — routing rule
If both mcp__intellij-index__* (this plugin) and mcp__intellij__* (JetBrains built-in) are available, they are not interchangeable:
| Need | Use |
| Code navigation, search, diagnostics, rename, move, run/list tests | mcp__intellij-index__* |
| Build | ide_build_project (this plugin, disabled by default — returns structured errors/warnings); mcp__intellij__* only when it is not enabled |
| Terminal, run non-test processes, formatting beyond code style | mcp__intellij__* only |
Always use mcp__intellij-index__ for code intelligence. At least one project must be open in IntelliJ. If your target project is not open but another one is, call ide_open_project with the working directory path — note it is disabled by default and must be enabled in Settings → Tools → Index MCP Server → Exposed Tools, and it requires at least one project to already be open (as the JSON-RPC context). IntelliJ does NOT require .idea to exist — it opens any directory and creates its own project configuration. Only ask the user to open a project manually when zero projects are open or ide_open_project is disabled. Do not fall back to bash for semantic operations — IDE tools understand types, references, and inheritance; grep does not.
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
| Task | Use IDE Tool | Use Built-In Tool |
| Find all usages of a method/class/variable | ide_find_references | Never - grep misses renamed imports, aliases, overrides |
| Go to a symbol's definition | ide_find_definition (returns and accepts a reusable symbolId) | Never - grep can't resolve through imports/generics |
| Check a symbol's resolved signature or docs | ide_symbol_info (returns and accepts a reusable symbolId) | Never - source text does not resolve short type names, and carries no doc comment |
| Find a class by name | ide_find_class | Only if IDE unavailable |
| Find a file by name | ide_find_file | Glob is fine for simple patterns |
| Search for text in code | ide_search_text | Grep is fine when IDE context filtering is unnecessary |
| Rename a symbol across project | ide_refactor_rename | Never - sed/replace breaks code |
| Move a file to another directory | ide_move_file | Never - mv/git mv bypasses IDE move semantics |
| Check for errors in a file | ide_diagnostics | Never - no equivalent |
| Understand class hierarchy | ide_type_hierarchy | Never - no equivalent |
| Find who calls a method | ide_call_hierarchy | Never - grep misses indirect calls |
| Find interface implementations | ide_find_implementations | Never - grep can't resolve type relationships |
| Delete a symbol safely | ide_refactor_safe_delete | Never - manual deletion misses usages |
| Find what a method overrides | ide_find_super_methods | Never - no equivalent |
| Read file content | Built-in Read tool | ide_read_file only for library/jar sources |
| Find text with regex | ide_search_text | Use Grep when you do not need IDE context filtering |
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 retryMost tools require smart mode (IDE finished indexing). Tools that work in dumb mode: ide_index_status, ide_sync_files, ide_replace_text_in_file, ide_reformat_code, ide_open_file, ide_get_active_file.
If results seem incomplete or missing
Do NOT fall back to bash, grep, or the built-in mcp__intellij__* MCP. If a tool returns "dumb mode" or "index not ready":
- Call
ide_index_status— ifisDumbMode: true, keep calling every 10s until it flips to false. - Then retry the exact same tool call with the same arguments.
- If smart mode but results seem sparse, call
ide_sync_filesthen retry. - Only if all retries still return empty results should you consider that the symbol genuinely does not exist.
The built-in mcp__intellij__* MCP is not a fallback for mcp__intellij-index__* — they serve different purposes and the built-in one cannot do semantic code search. Trying it when the index is in dumb mode will also fail. Always wait for smart mode and retry with mcp__intellij-index__*.
"Index may be stale" and "dumb mode" are transient — always resolve by waiting and retrying, never by switching to bash.
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. It accepts relative paths (project base first, then module content roots) and absolute paths inside those roots. The whole batch is validated before refresh; known deleted targets refresh through their nearest existing parent.
{ "paths": ["src/new_file.java", "src/modified_file.java"] }Omit paths to sync the entire project.
Opening Projects
Every project or workspace you open is another IDE window that indexes its code and stays in memory, so pick the call by what you need and make it once. Both tools are disabled by default (see the routing rule above).
| Situation | Call |
| One repository, Maven or Gradle | ide_open_project with {"path": "/abs/repo", "autoLink": true} |
| One repository, anything else (TypeScript, Python, plain directory) | ide_open_project with {"path": "/abs/repo"} |
| Several Maven repositories that must see each other (cross-repository references, rename, move) | One ide_open_workspace call listing all of them in modules, or their parent directory in path |
| A repository that is already a module of an open workspace | Nothing to open: pass the repository directory as project_path |
| A git worktree | ide_open_project with the worktree path (see below) |
Never call ide_open_workspace once per repository, or again with a different subset of the same repositories. Each distinct set gets its own window and its own directory under the IDE's ide-workspaces/ folder, and no window sees the repositories outside its set. ide_open_workspace refuses a single Maven project and points you to ide_open_project; if an open project already contains every requested repository as a module, it reuses that window instead of opening another. If you later need one more repository in a workspace, call ide_open_workspace once with the complete list, then close the old workspace with ide_close_project.
Git Worktrees
When working in a git worktree (e.g., /project/.claude/worktrees/agent-xyz or any checkout outside the main .idea directory), call ide_open_project with the worktree path before using any IDE tool (it is disabled by default — see the note above about enabling it in settings). IntelliJ does NOT require .idea — it opens any directory, indexes it, and provides full code intelligence. Never skip IDE tools because a directory "has no .idea" — that is not a prerequisite.
{ "path": "/absolute/path/to/worktree" }Parameter Rules
- Line and column are 1-based (first line = 1, first column = 1)
- 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 orjar://URL unchanged when passing it back to read-only navigation tools oride_read_file - Column must point to the symbol name, not whitespace or punctuation. For
public void myMethod(), column should land onmofmyMethod. For dotted expressions likejson.dumps()oros.path.join(), put the column on the member token (dumps,join) when you want the member definition rather than the module/package. - project_path is only needed for multi-project workspaces. Omit for single-project setups. When needed, use the absolute path to the project root.
- Reuse exact targets with
symbolId: class, symbol, reference, implementation, and super-method searches return opaque handles for exact declarations. Definition, symbol-info, reference, implementation, and member-edit tools accept a nestedtargetcontaining exactly one ofsymbolId,position, orqualifiedName+language; do not mix it with top-level selectors. A handle routes to its owning project whenproject_pathis omitted and restorable source declarations survive edits or rename. Cached pages markedstalerebind exact handles when returned. Rediscover afterSYMBOL_ID_EXPIRED; self-navigating synthetic targets expire after their backing file changes, and handles are non-canonical and must not be compared for symbol equality. - Preview risky refactorings first:
ide_refactor_rename,ide_refactor_safe_delete, andide_change_signatureacceptdryRun: true. InspectcanApply,plannedChange,affectedFiles, usage/conflict counts, andwarnings. Preview does not write or save files and creates no undo entry. Apply with a second call only after reviewing the result. - Use built-in search scope intentionally:
ide_find_references,ide_find_implementations,ide_type_hierarchy,ide_call_hierarchy,ide_find_class,ide_find_file, andide_find_symbolacceptscope. Useproject_filesfor the default project-only view,project_and_librarieswhen dependency code matters,project_production_filesto stay out of tests, andproject_test_fileswhen you want test-only results. - Narrow by directory with
paths:ide_search_text,ide_find_references, andide_structural_search_replaceacceptpaths, an array of project-relative globs where a leading!excludes — e.g.{"paths": ["src/main/kotlin/**/handlers/**", "!**/*Test.kt"]}. Prefer one scoped call over a project-wide search you filter yourself: filtering client-side pays tokens for every discarded hit, and with pagination a whole page can be filtered away and look like an empty result. Composes withscopeandfilePattern.
ide_file_structure keeps the legacy structure response by default and avoids returning a
structured-node payload or allocating handles. Use includeNodes=true for structured declarations,
and includeSymbolIds=true when exact handles are needed (it implies includeNodes). Handle
allocation is opt-in and capped at 100 per response; lower it with maxSymbolIds (1–100). Large
responses report symbolIdsTruncated and symbolIdsOmitted.
Tool Selection by Task
"I need to understand how X is used"
ide_find_references- all call sites, field accesses, importside_call_hierarchywithdirection: "callers"- full call chain upward
"I need to understand what X is"
ide_symbol_info- resolved signature + doc comment without reading the file (disabled by default)ide_find_definition- jump to sourceide_type_hierarchy- inheritance chainide_find_super_methods- what interface/base method it implements
"I need to find a class/file/symbol"
ide_find_class- classes by name (CamelCase:USvcfindsUserService)ide_find_file- files by nameide_search_text- substring text search across project (regex via"regex": true)
"I need to refactor"
- Preview a rename, safe delete, or signature change with
dryRun: true; inspect blockers and affected files ide_refactor_rename- rename symbol + all references atomicallyide_change_signature- change a Java/Kotlin JVM method signature and update callers (disabled by default)ide_move_file- move file and let the IDE apply semantic updates when that language/backend supports themide_refactor_safe_delete- preview/delete an exact symbol target or file with usage checking (Java/Kotlin only)ide_replace_text_in_file,ide_reformat_code- apply project code style (disabled by default)
"I need to check for problems"
ide_diagnostics- compiler errors/warnings for onefileor a small relative/in-project-absolutefilesbatch; inspect eachstate/reason, and usemaxProblemsto bound output. Quick fixes and ranges are single-file only (plus build/test results)ide_project_diagnostics- batch/project scope including unopened files, with fail-closed coverage metadata (completeflag, per-file states); long analyses return ananalysisIdto poll (disabled by default)
"I need to find implementations of an interface"
ide_find_implementations- cursor on interface/abstract class/method
"I need to trace call chains"
ide_call_hierarchywithdirection: "callers"- who calls this?ide_call_hierarchywithdirection: "callees"- what does this call?
Common Mistakes to Avoid
- Using grep instead of
ide_find_references: Grep finds text, not semantic usages. Misses aliased imports, includes false positives from comments/strings. - Using sed/replace instead of
ide_refactor_rename: Text replacement breaks code. IDE rename updates all references, getters/setters, overrides, test classes, imports. - Using mv/git mv instead of
ide_move_file: File system moves bypass IDE move semantics.ide_move_filecan preserve IDE-managed package/namespace/reference updates when the active language backend supports them. - Forgetting to check index status: If IDE is indexing (dumb mode), most tools error. Check
ide_index_statusfirst if a tool fails unexpectedly. - Using 0-based line/column: All IDE tools use 1-based. Line 5 in file =
line: 5. - Passing absolute project file paths: Use relative paths for project files.
src/main/App.java, not/Users/me/project/src/main/App.java. - 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 oride_read_file. - Not syncing after external file changes: After creating files via Write tool, call
ide_sync_filesbefore searching. - Assuming regex is the default in
ide_search_text: Regex requires"regex": true; otherwise the tool does plain-text substring matching. - Using
ide_find_classfor methods/functions: It searches classes only. Useide_search_textfor a quick word lookup. - Calling
ide_open_workspaceonce per repository: each call opens another window without cross-repository intelligence. Open one repository withide_open_project; combine several Maven repositories with a singleide_open_workspacecall that lists all of them. See Opening Projects.
Lifecycle Management
When multiple projects are open simultaneously, the lifecycle manager sleeps and wakes them based on window focus and MCP activity. It is opt-in and disabled by default — enable "Enable lifecycle management" in Settings → Tools → Index MCP Server. Once enabled, projects enroll automatically on first MCP use.
States: active (full IDE) → background (Power Save on) → dormant (editor tabs closed until the window regains focus, PSI cache freed) → closed (fully unloaded). Every MCP tool call restarts a project's idle countdown. Projects auto-reopen transparently when an MCP tool targets a closed project.
ide_project_status is the read-only entry point — enabled by default. Use it to see all open and managed projects and their current modes.
All lifecycle action tools are disabled by default:
ide_enroll_all_projects, ide_get_project_modes, ide_lifecycle_log, ide_release_all_projects, ide_release_project, ide_set_all_project_modes, ide_set_lifecycle_log_file, ide_set_project_mode
Disabled-by-Default Tools
These tools exist but are disabled by default. They are omitted from tools/list, and direct tools/call requests are rejected until the user enables them in IDE settings (Settings → Tools → Index MCP Server → Exposed Tools):
ide_build_project, ide_change_signature, ide_close_project, ide_convert_java_to_kotlin, ide_create_file, ide_create_module, ide_edit_member, ide_enroll_all_projects, ide_file_structure, ide_find_symbol, ide_get_active_file, ide_get_project_modes, ide_import_modules, ide_insert_member, ide_install_plugin, ide_lifecycle_log, ide_link_build_system, ide_list_tests, ide_open_file, ide_open_project, ide_open_workspace, ide_optimize_imports, ide_project_diagnostics, ide_read_file, ide_reformat_code, ide_release_all_projects, ide_release_project, ide_reload_project, ide_replace_member, ide_replace_text_in_file, ide_restart, ide_run_tests, ide_set_all_project_modes, ide_set_lifecycle_log_file, ide_set_power_save_mode, ide_set_project_mode, ide_structural_search_replace, ide_symbol_info
Note: ide_restart is not a terminal step. The MCP server is down only while the IDE relaunches (usually well under a minute): poll ide_index_status until it answers, then continue. If nothing answers after a few minutes the restart was probably intercepted (for example by a save dialog) — report it instead of polling forever.
Note: after a restart, Streamable HTTP clients need no reconnect (every call is an independent POST) but legacy SSE clients must reopen the /index-mcp/sse stream; symbol handles and search cursors issued before the restart are invalid; and after ide_install_plugin, refresh the tool list so changed schemas are picked up.
Note: ide_close_project refuses to close the last open project; ide_open_project requires an absolute path and may take up to timeoutSeconds (default 600) while the project indexes.
Enforcing IDE Tool Usage with Hooks
Claude Code hooks can block grep, sed, Edit, and rm on source files and redirect agents to the correct IDE tool. This prevents fallback to text-based operations that bypass the index.
See claude-code-hooks.md for ready-to-use hook scripts.
Detailed Tool Parameters
For complete parameter reference with types, defaults, and return formats, see tools-reference.md.
Bounded hierarchy pages with legacy tree compatibility
Without maxNodes or cursor, call/type hierarchies keep nested trees and legacy limits.
Explicit pagination returns bounded breadth-first pages with traversal-local nodeId,
parentId, and depth. Continuations are scoped to the project, tool, and server session.
A continuation budget limit preserves the computed page and reports truncationReason;
narrow the query when hasMore=true has no cursor. Cancellation and indexing transitions
propagate through reflective handlers instead of completing an empty hierarchy.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

