# Ide Index MCP

> 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.

- Skill: `hechtcarmel/ide-index-mcp` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add hechtcarmel/ide-index-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hechtcarmel/ide-index-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: hechtcarmel (https://skillmd.com/u/hechtcarmel)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hechtcarmel/ide-index-mcp

---


# 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 retry
```

Most 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":

1. Call `ide_index_status` — if `isDumbMode: true`, keep calling every 10s until it flips to false.
2. Then retry the **exact same tool call** with the same arguments.
3. If smart mode but results seem sparse, call `ide_sync_files` then retry.
4. 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.

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

Omit `paths` to sync the entire 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.

```json
{ "path": "/absolute/path/to/worktree" }
```

## 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. **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 nested `target` containing exactly one of `symbolId`, `position`, or `qualifiedName` + `language`; do not mix it with top-level selectors. A handle routes to its owning project when `project_path` is omitted and restorable source declarations survive edits or rename. Cached pages marked `stale` rebind exact handles when returned. Rediscover after `SYMBOL_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.
6. **Preview risky refactorings first**: `ide_refactor_rename`, `ide_refactor_safe_delete`, and `ide_change_signature` accept `dryRun: true`. Inspect `canApply`, `plannedChange`, `affectedFiles`, usage/conflict counts, and `warnings`. Preview does not write or save files and creates no undo entry. Apply with a second call only after reviewing the result.
7. **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.
8. **Narrow by directory with `paths`**: `ide_search_text`, `ide_find_references`, and `ide_structural_search_replace` accept `paths`, 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 with `scope` and `filePattern`.

`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"
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_symbol_info` - resolved signature + doc comment without reading the file (disabled by default)
2. `ide_find_definition` - jump to source
3. `ide_type_hierarchy` - inheritance chain
4. `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` - substring text search across project (regex via `"regex": true`)

### "I need to refactor"
1. Preview a rename, safe delete, or signature change with `dryRun: true`; inspect blockers and affected files
2. `ide_refactor_rename` - rename symbol + all references atomically
3. `ide_change_signature` - change a Java/Kotlin JVM method signature and update callers (disabled by default)
4. `ide_move_file` - move file and let the IDE apply semantic updates when that language/backend supports them
5. `ide_refactor_safe_delete` - preview/delete an exact symbol target or file with usage checking (Java/Kotlin only)
6. `ide_replace_text_in_file`, `ide_reformat_code` - apply project code style (disabled by default)

### "I need to check for problems"
1. `ide_diagnostics` - compiler errors/warnings for one `file` or a small relative/in-project-absolute `files` batch; inspect each `state`/`reason`, and use `maxProblems` to bound output. Quick fixes and ranges are single-file only (plus build/test results)
2. `ide_project_diagnostics` - batch/project scope including unopened files, with fail-closed coverage metadata (`complete` flag, per-file states); long analyses return an `analysisId` to poll (disabled by default)

### "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.

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

3. **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.

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

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

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

7. **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`.

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

9. **Assuming regex is the default in `ide_search_text`**: Regex requires `"regex": true`; otherwise the tool does plain-text substring matching.

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

## 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` terminates the MCP connection — reconnect your client after calling it.
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](https://github.com/hechtcarmel/jetbrains-index-mcp-plugin/blob/main/docs/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](references/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.