Skip to content
Back to search

jetbrains-index-mcp-plugin

A Jetbrains IDE IntelliJ plugin aimed to provide coding agents the ability to leverage intelliJ's indexing of the codebase

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/hechtcarmel/jetbrains-index-mcp-plugin with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/hechtcarmel/jetbrains-index-mcp-plugin'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hechtcarmel--jetbrains-index-mcp-plugin/badge.svg)](/listings/hechtcarmel--jetbrains-index-mcp-plugin)

HTML

<a href="/listings/hechtcarmel--jetbrains-index-mcp-plugin"><img src="/api/listings/hechtcarmel--jetbrains-index-mcp-plugin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Install the plugin** and restart your JetBrains IDE 2. **Open a project** - the MCP server starts automatically with IDE-specific defaults: - IntelliJ IDEA: `intellij-index` on port **29170** - PyCharm: `pycharm-index` on port **29172** - WebStorm: `webstorm-index` on port **29173** - Other IDEs: See [IDE-Specific Defaults](#ide-specific-defaults) 3. **Configure your AI assistant** using the "Install on Coding Agents" button (easiest) or manually 4. **Use the tool window** (bottom panel: "Index MCP Server") to copy configuration or monitor commands 5. **Change port** (optional): Click "Change port, disable tools" in the toolbar or go to <kbd>Settings</kbd> > <kbd>Tools</kbd> > <kbd>Index MCP Server</kbd>

Using the "Install on Coding Agents" Button

The easiest way to configure your AI assistant: 1. Open the "Index MCP Server" tool window (bottom panel) 2. Click the prominent **"Install on Coding Agents"** button on the right side of the toolbar 3. A popup appears with two sections: - **Install Now** - For Claude Code CLI and Codex CLI: Runs the installation command automatically - **Copy Configuration** - For other clients: Copies the JSON config to your clipboard 4. For "Copy Configuration" clients, paste the config into the appropriate config file

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 622 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # IDE Index MCP Server
  2. ![Build](https://github.com/hechtcarmel/jetbrains-index-mcp-plugin/workflows/Build/badge.svg)
  3. [![Version](https://img.shields.io/jetbrains/plugin/v/29174.svg)](https://plugins.jetbrains.com/plugin/29174-ide-index-mcp-server)
  4. [![Downloads](https://img.shields.io/jetbrains/plugin/d/29174.svg)](https://plugins.jetbrains.com/plugin/29174-ide-index-mcp-server)
  5. A JetBrains IDE plugin that exposes an **MCP (Model Context Protocol) server**, enabling AI coding assistants like Claude, Codex, Cursor, and Windsurf to leverage the IDE's powerful indexing and refactoring capabilities.
  6. **Fully tested**: IntelliJ IDEA, PyCharm, WebStorm, GoLand, RustRover, Android Studio, PhpStorm
  7. **May work** (untested): RubyMine, CLion, DataGrip
  8. **Not supported**: Rider (its ReSharper backend does not expose the IntelliJ PSI APIs this plugin relies on; see [#167](https://github.com/hechtcarmel/jetbrains-index-mcp-plugin/issues/167))
  9. [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/hechtcarmel)
  10. <!-- Plugin description -->
  11. **IDE Index MCP Server** provides AI coding assistants with access to the IDE's powerful code intelligence features through the Model Context Protocol (MCP).
  12. ### Features
  13. **Multi-Language Support**
  14. Advanced tools work across multiple languages based on available plugins:
  15. - **Java & Kotlin** - IntelliJ IDEA, Android Studio
  16. - **Python** - PyCharm (all editions), IntelliJ with Python plugin, including symbol-based definition/reference lookup
  17. - **JavaScript & TypeScript** - WebStorm, IntelliJ Ultimate, PhpStorm
  18. - **Go** - GoLand, IntelliJ IDEA Ultimate with Go plugin
  19. - **PHP** - PhpStorm, IntelliJ Ultimate with PHP plugin
  20. - **Rust** - RustRover, IntelliJ IDEA Ultimate with Rust plugin, CLion
  21. - **Scala** - IntelliJ IDEA with the Scala plugin (Scala 2 sources)
  22. - **Markdown** - heading outlines in file structure for IDEs with the bundled Markdown plugin
  23. **Universal Tools (All Supported JetBrains IDEs)**
  24. - **Find References** - Locate all usages of any symbol across the project
  25. - **Go to Definition** - Navigate to symbol declarations
  26. - **Code Diagnostics** - Access errors, warnings, and quick fixes
  27. - **Index Status** - Check if code intelligence is ready
  28. - **Sync Files** - Force sync VFS/PSI cache after external file changes
  29. - **Reload Project** - Refresh linked Maven/Gradle build models after dependency or build-file changes (disabled by default)
  30. - **Import Modules** - Import external Maven project directories as modules for cross-project code intelligence and refactoring (disabled by default)
  31. - **Open Workspace** - Scan a root directory for Maven projects, or provide an explicit list of Maven project paths, and open them all in one IntelliJ window with full cross-project code intelligence (disabled by default)
  32. - **Build Project** - Trigger IDE build with structured error/warning output (disabled by default)
  33. - **Find Class** - Fast class/interface search by name with camelCase matching
  34. - **Find File** - Fast file search by name using IDE's file index
  35. - **Symbol Search** - Find code symbols by name with IntelliJ Go to Symbol matching (disabled by default)
  36. - **Search Text** - Text search using IntelliJ Find in Files (substring and regex matching)
  37. - **Read File** - Read file content by path or qualified name, including library sources (disabled by default)
  38. - **Open File** - Open a file in the editor with optional navigation (disabled by default)
  39. - **Get Active File** - Get currently active editor file(s) with cursor position (disabled by default)
  40. **Extended Tools (Language-Aware)**
  41. These tools activate based on installed language plugins:
  42. - **Type Hierarchy** - Explore class inheritance chains
  43. - **Call Hierarchy** - Trace method/function call relationships
  44. - **Find Implementations** - Discover interface/abstract implementations
  45. - **Find Super Methods** - Navigate method override hierarchies
  46. - **File Structure** - View hierarchical file structure like IDE's Structure view, including PHP Structure View trees and Markdown heading outlines; shows start and end line for each element (disabled by default)
  47. **Refactoring Tools**
  48. - **Rename Refactoring** - Safe renaming with automatic related element renaming (getters/setters, overriding methods) - works across ALL languages, fully headless
  49. - **Move File** - Move files with IDE-aware reference and package updates when supported
  50. - **Reformat Code** - Reformat using project code style with import optimization (disabled by default)
  51. - **Optimize Imports** - Remove unused imports and organize imports without reformatting (disabled by default)
  52. - **Edit Member** - Replace an entire member declaration (signature + body) with new content (Java/Kotlin, disabled by default)
  53. - **Insert Member** - Insert a new member at a structural position (Java/Kotlin, disabled by default)
  54. - **Replace Member** - Replace method body or field initializer only, preserving the signature (Java/Kotlin, disabled by default)
  55. - **Safe Delete** - Remove code with usage checking (Java/Kotlin only)
  56. - **Java to Kotlin Conversion** - Convert Java to Kotlin using Intellij's built-in converter (Java only)
  57. **Project Lifecycle Management**
  58. When working across many projects simultaneously, idle ones consume memory unnecessarily and leave editors open for no reason. Lifecycle management sleeps and wakes projects based on window focus and MCP activity. It is opt-in — disabled by default; turn on "Enable lifecycle management" in Settings → Tools → Index MCP Server, after which no further configuration is required.
  59. - **Automatic sleep/wake** - Projects move from active → background (Power Save on) → dormant (editor tabs closed, PSI cache freed) → closed (fully unloaded), and auto-reopen transparently on the next MCP call. Every MCP tool call restarts a project's idle countdown, and the tabs a dormant transition closed reopen when you return to the project window
  60. - **`ide_project_status`** - Combined snapshot of every open and managed project
  61. - **`ide_set_project_mode`** / **`ide_get_project_modes`** - Explicit mode control
  62. - **`ide_release_project`** - Unenroll a project from lifecycle management
  63. - **`ide_lifecycle_log`** - Timestamped event log with trigger reasons, for diagnosing unexpected behaviour. The ring buffer is always active; file output enables via Help → Diagnostic Tools → Debug Log Settings
  64. ### Why Use This Plugin?
  65. Unlike simple text-based code analysis, this plugin gives AI assistants access to:
  66. - **True semantic understanding** through the IDE's AST and index
  67. - **Cross-project reference resolution** that works across files and modules
  68. - **Multi-language support** - automatically detects and uses language-specific handlers
  69. - **Headless and remote development support** - starts in regular IDE windows, JetBrains remote development sessions, and headless automation runs
  70. - **Safe refactoring operations** with automatic reference updates and undo support
  71. Perfect for AI-assisted development workflows where accuracy and safety matter.
  72. ### Security
  73. The server binds to `127.0.0.1` with no authentication — any local process can call its
  74. tools with your IDE's file access. On a single-user dev machine that's the same trust
  75. boundary your shell already has; on a shared machine, it's worth weighing before you
  76. enable the write tools.
  77. <!-- Plugin description end -->
  78. ## Table of Contents
  79. - [Installation](#installation)
  80. - [Quick Start](#quick-start)
  81. - [Community Integrations](#community-integrations)
  82. - [Client Configuration](#client-configuration)
  83. - [Exposed Tools](#exposed-tools)
  84. - [Multi-Project Support](#multi-project-support)
  85. - [Lifecycle Management](#lifecycle-management)
  86. - [Tool Window](#tool-window)
  87. - [Error Codes](#error-codes)
  88. - [Settings](#settings)
  89. - [Requirements](#requirements)
  90. - [Architecture](#architecture)
  91. - [Contributing](#contributing)
  92. - [License](#license)
  93. ## Installation
  94. ### Using the IDE built-in plugin system
  95. <kbd>Settings/Preferences</kbd> > <kbd>Plugins</kbd> > <kbd>Marketplace</kbd> > <kbd>Search for "IDE Index MCP Server"</kbd> > <kbd>Install</kbd>
  96. ### Using JetBrains Marketplace
  97. Go to [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/29174-ide-index-mcp-server) and install it by clicking the <kbd>Install to ...</kbd> button.
  98. ### Manual Installation
  99. Download the [latest release](https://plugins.jetbrains.com/plugin/29174-ide-index-mcp-server/versions) and install it manually:
  100. <kbd>Settings/Preferences</kbd> > <kbd>Plugins</kbd> > <kbd>⚙️</kbd> > <kbd>Install plugin from disk...</kbd>
  101. ## Quick Start
  102. 1. **Install the plugin** and restart your JetBrains IDE
  103. 2. **Open a project** - the MCP server starts automatically with IDE-specific defaults:
  104. - IntelliJ IDEA: `intellij-index` on port **29170**
  105. - PyCharm: `pycharm-index` on port **29172**
  106. - WebStorm: `webstorm-index` on port **29173**
  107. - Other IDEs: See [IDE-Specific Defaults](#ide-specific-defaults)
  108. 3. **Configure your AI assistant** using the "Install on Coding Agents" button (easiest) or manually
  109. 4. **Use the tool window** (bottom panel: "Index MCP Server") to copy configuration or monitor commands
  110. 5. **Change port** (optional): Click "Change port, disable tools" in the toolbar or go to <kbd>Settings</kbd> > <kbd>Tools</kbd> > <kbd>Index MCP Server</kbd>
  111. ### Using the "Install on Coding Agents" Button
  112. The easiest way to configure your AI assistant:
  113. 1. Open the "Index MCP Server" tool window (bottom panel)
  114. 2. Click the prominent **"Install on Coding Agents"** button on the right side of the toolbar
  115. 3. A popup appears with two sections:
  116. - **Install Now** - For Claude Code CLI and Codex CLI: Runs the installation command automatically
  117. - **Copy Configuration** - For other clients: Copies the JSON config to your clipboard
  118. 4. For "Copy Configuration" clients, paste the config into the appropriate config file
  119. ## Community Integrations
  120. - [opencode-jetbrains-index](https://github.com/ineersa/opencode-jetbrains-index) - a third-party integration for OpenCode that uses this plugin
  121. > **Disclaimer**: This repository is not maintained by me. Please use its own issue tracker for integration-specific issues and support.
  122. ## Client Configuration
  123. ### Claude Code (CLI)
  124. Use the "Install on Coding Agents" button in the tool window, or run this command (adjust name and port for your IDE):
  125. ```bash
  126. # IntelliJ IDEA
  127. claude mcp add --transport http --scope user intellij-index http://127.0.0.1:29170/index-mcp/streamable-http
  128. # PyCharm
  129. claude mcp add --transport http --scope user pycharm-index http://127.0.0.1:29172/index-mcp/streamable-http
  130. # WebStorm
  131. claude mcp add --transport http --scope user webstorm-index http://127.0.0.1:29173/index-mcp/streamable-http
  132. ```
  133. Options:
  134. - `--scope user` - Adds globally for all projects
  135. - `--scope project` - Adds to current project only
  136. To remove: `claude mcp remove <server-name>` (e.g., `claude mcp remove intellij-index`)
  137. ### Codex CLI
  138. Use the "Install on Coding Agents" button in the tool window, or run this command (adjust name and port for your IDE):
  139. ```bash
  140. # IntelliJ IDEA
  141. codex mcp add intellij-index --url http://127.0.0.1:29170/index-mcp/streamable-http
  142. # PyCharm
  143. codex mcp add pycharm-index --url http://127.0.0.1:29172/index-mcp/streamable-http
  144. # WebStorm
  145. codex mcp add webstorm-index --url http://127.0.0.1:29173/index-mcp/streamable-http
  146. ```
  147. To remove: `codex mcp remove <server-name>` (e.g., `codex mcp remove intellij-index`)
  148. ### Cursor
  149. Add to `.cursor/mcp.json` in your project root or `~/.cursor/mcp.json` globally (adjust name and port for your IDE):
  150. ```json
  151. {
  152. "mcpServers": {
  153. "intellij-index": {
  154. "url": "http://127.0.0.1:29170/index-mcp/streamable-http"
  155. }
  156. }
  157. }
  158. ```
  159. ### Windsurf
  160. Add to `~/.codeium/windsurf/mcp_config.json` (adjust name and port for your IDE):
  161. ```json
  162. {
  163. "mcpServers": {
  164. "intellij-index": {
  165. "serverUrl": "http://127.0.0.1:29170/index-mcp/streamable-http"
  166. }
  167. }
  168. }
  169. ```
  170. ### VS Code (Generic MCP)
  171. ```json
  172. {
  173. "mcp.servers": {
  174. "intellij-index": {
  175. "url": "http://127.0.0.1:29170/index-mcp/streamable-http"
  176. }
  177. }
  178. }
  179. ```
  180. > **Note**: Replace the server name and port with your IDE's defaults. See [IDE-Specific Defaults](#ide-specific-defaults) below.
  181. ### IDE-Specific Defaults
  182. Each JetBrains IDE has a unique default port and server name to allow running multiple IDEs simultaneously without conflicts:
  183. | IDE | Server Name | Default Port |
  184. |-----|-------------|--------------|
  185. | IntelliJ IDEA | `intellij-index` | 29170 |
  186. | Android Studio | `android-studio-index` | 29171 |
  187. | PyCharm | `pycharm-index` | 29172 |
  188. | WebStorm | `webstorm-index` | 29173 |
  189. | GoLand | `goland-index` | 29174 |
  190. | PhpStorm | `phpstorm-index` | 29175 |
  191. | RubyMine | `rubymine-index` | 29176 |
  192. | CLion | `clion-index` | 29177 |
  193. | RustRover | `rustrover-index` | 29178 |
  194. | DataGrip | `datagrip-index` | 29179 |
  195. | Aqua | `aqua-index` | 29180 |
  196. | DataSpell | `dataspell-index` | 29181 |
  197. > **Tip**: Use the "Install on Coding Agents" button in the tool window - it automatically uses the correct server name and port for your IDE.
  198. ## Exposed Tools
  199. The plugin provides **52 MCP tools** organized by availability. Tools marked *(disabled by default)* can be enabled in <kbd>Settings</kbd> > <kbd>Tools</kbd> > <kbd>Index MCP Server</kbd> > <kbd>Exposed Tools</kbd>.
  200. ### Universal Tools
  201. These tools work in all supported JetBrains IDEs.
  202. | Tool | Description |
  203. |------|-------------|
  204. | `ide_find_references` | Find all references to a symbol across the entire project, optionally restricted to path globs via `paths` |
  205. | `ide_find_definition` | Find the definition/declaration location of a symbol; accepts top-level `symbolId`, position, or qualified-name selectors plus an equivalent nested `target`, and returns a reusable `symbolId` |
  206. | `ide_symbol_info` | Resolved signature and documentation for a symbol — accepts the same flat or nested targets as `ide_find_definition`; parameter and return types expanded to fully qualified names (Java), structured `parameters`, modifiers, containing declaration, and the doc comment as plain text, without reading the file *(disabled by default)* |
  207. | `ide_find_class` | Search for classes/interfaces by name with camelCase/substring/wildcard matching |
  208. | `ide_find_file` | Search for files by name using IDE's file index |
  209. | `ide_find_symbol` | Search for symbols (classes, methods, fields, functions) by name with IntelliJ Go to Symbol matching *(disabled by default)* |
  210. | `ide_search_text` | Text search using IntelliJ Find in Files with context filtering (substring and regex matching), optionally restricted to path globs via `paths` |
  211. | `ide_diagnostics` | Analyze one `file` or up to 100 supplied `files` under one shared timeout budget, with per-file coverage states and configurable `maxProblems`; accepts relative or in-project absolute paths, plus optional build/test results; intentions are best-effort and single-file only |
  212. | `ide_project_diagnostics` | Batch/project-scope diagnostics for many files including unopened ones, with fail-closed coverage metadata: a `complete` flag plus per-file `analyzed`/`timed_out`/`failed`/`skipped`/`not_analyzed` states, so an empty result can never be mistaken for a clean project. Long analyses return an `analysisId` to poll; `fileTimeoutSeconds` can extend large-file analysis up to 600 seconds within the run deadline *(disabled by default)* |
  213. | `ide_index_status` | Check if the IDE is in dumb mode or smart mode |
  214. | `ide_sync_files` | Force sync IDE's virtual file system and PSI cache for relative or in-project absolute paths, including deleted targets via their nearest existing parent |
  215. | `ide_reload_project` | Force-reload Maven or Gradle build model after modifying `pom.xml`/`build.gradle` *(disabled by default)* |
  216. | `ide_link_build_system` | Link an unlinked Maven/Gradle project for dependency resolution *(disabled by default)* |
  217. | `ide_import_modules` | Import external Maven project directories as modules into the current IntelliJ window *(disabled by default, requires Maven plugin)* |
  218. | `ide_open_workspace` | Scan a root directory for Maven projects, or provide an explicit module list, and open them all in one IntelliJ window with full cross-project code intelligence. Call once with every repository; a single repository belongs in `ide_open_project` *(disabled by default, requires Maven plugin)* |
  219. | `ide_build_project` | Build project using IDE's build system (JPS, Gradle, Maven, CMake (CLion)) with structured errors. Long builds return a `buildId` to poll, so the MCP client's request timeout is never hit *(disabled by default)* |
  220. | `ide_run_tests` | Run tests via the IDE's run configuration infrastructure; structured pass/fail results with per-test console output, read from the IDE's test runner (works with any framework — JUnit, TestNG, pytest, Jest, Go test, PHPUnit). Class/method **FQN targeting is Java/Kotlin-only**; other languages pass an existing run-config name. Long runs return a `runId` to poll, so the MCP client's request timeout is never hit; each poll reports the failures so far *(disabled by default)* |
  221. | `ide_read_file` | Read file content by path or qualified name, including library/jar sources *(disabled by default)* |
  222. | `ide_get_active_file` | Get the currently active file(s) in the editor with cursor position *(disabled by default)* |
  223. | `ide_open_file` | Open a file in the editor with optional line/column navigation *(disabled by default)* |
  224. | `ide_set_power_save_mode` | Enable or disable IDE Power Save Mode — suspends background inspections while keeping the index and all code intelligence operational *(disabled by default)* |
  225. | `ide_close_project` | Close an open project window and free its memory — refuses to close the last open project *(disabled by default)* |
  226. | `ide_create_module` | Add a directory as an IntelliJ module with a content root, enabling code intelligence for non-Maven projects (TypeScript, plain directories, etc.) *(disabled by default)* |
  227. | `ide_open_project` | Open a project by absolute path and wait until indexing completes (configurable timeout); returns immediately if already open *(disabled by default)* |
  228. | `ide_install_plugin` | Install a plugin zip into the IDE, replacing any existing version — auto-detects `build/distributions/*.zip` when no path is given *(disabled by default)* |
  229. | `ide_restart` | Restart the IDE — the MCP server is down only while the IDE relaunches; poll `ide_index_status` until it answers, then continue. Call after `ide_install_plugin` *(disabled by default)* |
  230. | `ide_refactor_rename` | Preview with `dryRun`, or rename a symbol by `symbolId`/position (or a file) and update all references across the project (all languages; use `targetType` for explicit file mode) |
  231. | `ide_move_file` | Move a file to a new directory, applying language-aware reference/package updates when the IDE provides a semantic move backend |
  232. | `ide_reformat_code` | Reformat code using project code style with import optimization *(disabled by default)* |
  233. | `ide_optimize_imports` | Optimize imports without reformatting code *(disabled by default)* |
  234. | `ide_structural_search_replace` | Pattern-based code search and transformation using IntelliJ's Structural Search and Replace engine, optionally restricted to path globs via `paths` (Java, Kotlin) *(disabled by default)* |
  235. | `ide_create_file` | Create a new source file with content, immediately indexed by IntelliJ — use instead of Write for `.java`, `.kt`, `.ts`, `.tsx`, `.py` files *(disabled by default)* |
  236. | `ide_replace_text_in_file` | Find and replace text in a file using IntelliJ's Document API — changes immediately visible to index and PSI without `ide_sync_files` *(disabled by default)* |
  237. | `ide_change_signature` | Preview or change a Java/Kotlin JVM method signature by exact/nested target, updating callers automatically *(disabled by default)* |
  238. | `ide_edit_member` | Replace an entire member declaration (signature + body) with new content (Java, Kotlin) *(disabled by default)* |
  239. | `ide_insert_member` | Insert a new member at a structural position in a class or file (Java, Kotlin) *(disabled by default)* |
  240. | `ide_replace_member` | Replace a method body or field initializer only, preserving the signature (Java, Kotlin) *(disabled by default)* |
  241. ### Extended Tools (Language-Aware)
  242. These tools activate based on available language plugins:
  243. | Tool | Description | Languages |
  244. |------|-------------|-----------|
  245. | `ide_type_hierarchy` | Get a bounded, cursor-paginated type hierarchy in deterministic breadth-first order, accepting and returning `symbolId` | Java, Kotlin, Python, JS/TS, Go, PHP, Rust, Scala |
  246. | `ide_call_hierarchy` | Analyze callers or callees in bounded, cursor-paginated breadth-first order, accepting and returning `symbolId` | Java, Kotlin, Python, JS/TS, Go, PHP, Rust, Scala |
  247. | `ide_find_implementations` | Find all implementations of an interface or abstract method | Java, Kotlin, Python, JS/TS, PHP, Rust, Scala |
  248. | `ide_find_super_methods` | Find the full inheritance hierarchy of methods that a method overrides/implements | Java, Kotlin, Python, JS/TS, PHP, Scala |
  249. | `ide_file_structure` | Get legacy file structure text; opt into structured nodes and exact handles with `includeNodes`/`includeSymbolIds` *(disabled by default)* | Java, Kotlin, Python, JS/TS, PHP, Markdown, Scala |
  250. PHP file structure support requires the PHP plugin and is available in PhpStorm or IntelliJ IDEA Ultimate with the PHP plugin enabled.
  251. ### Bounded hierarchy pages with legacy tree compatibility
  252. Without `maxNodes` or `cursor`, call/type hierarchies keep nested trees and legacy limits.
  253. Explicit pagination returns bounded breadth-first pages with traversal-local `nodeId`,
  254. `parentId`, and `depth`. Continuations are scoped to the project, tool, and server session.
  255. A continuation budget limit preserves the computed page and reports `truncationReason`;
  256. narrow the query when `hasMore=true` has no cursor. Cancellation and indexing transitions
  257. propagate through reflective handlers instead of completing an empty hierarchy.
  258. ### Java-Specific Tools
  259. | Tool | Description |
  260. |------|-------------|
  261. | `ide_list_tests` | List all test methods/classes discovered by the IDE's test framework extension points (JUnit, TestNG, etc.) *(disabled by default, requires Java plugin)* |
  262. | `ide_convert_java_to_kotlin` | Convert Java files to Kotlin using IntelliJ's built-in converter *(disabled by default, requires Java + Kotlin plugins)* |
  263. | `ide_refactor_safe_delete` | Preview or safely delete an exact/nested symbol target or file after checking usages (Java/Kotlin only) |
  264. > **Note**: Applied refactorings modify source files and support undo via
  265. > <kbd>Ctrl/Cmd+Z</kbd>. `dryRun: true` previews do not modify files or create an undo command.
  266. ### Symbol handles across navigation and member editing
  267. Class, symbol, reference, implementation, and super-method searches return opaque `symbolId`
  268. handles for exact declarations. Reference and implementation searches plus `ide_edit_member` and
  269. `ide_replace_member` accept the same nested `target` variants as definition and symbol-info tools.
  270. Cached search pages remain marked `stale: true` after PSI edits and materialize handles only for
  271. the returned page from exact smart pointers. Deleted declarations and handles from another project
  272. or server session are rejected; successful member edits return current declaration metadata.
  273. `ide_file_structure` keeps the legacy `structure` response by default and avoids returning a
  274. structured-node payload or allocating handles. Use `includeNodes=true`
  275. for structured declarations, and `includeSymbolIds=true` when exact handles are needed (it implies
  276. `includeNodes`). Handle allocation is opt-in and capped at 100 per response; lower it with
  277. `maxSymbolIds` (1–100). Large responses report `symbolIdsTruncated` and `symbolIdsOmitted`.
  278. ### Project Lifecycle Management Tools
  279. `ide_project_status` is enabled by default. All other lifecycle tools are disabled by default — enable them in Settings → Tools → Index MCP Server.
  280. | Tool | Description | Default |
  281. |------|-------------|---------|
  282. | `ide_project_status` | Combined snapshot: every open project and every managed project with open/managed/mode per row | Enabled |
  283. | `ide_set_project_mode` | Set a project's lifecycle mode: `active`, `background`, `dormant`, or `closed` | Disabled |
  284. | `ide_get_project_modes` | List all managed projects and their current modes, including closed ones | Disabled |
  285. | `ide_set_all_project_modes` | Set all managed projects to the same mode at once (active/background/dormant) | Disabled |
  286. | `ide_enroll_all_projects` | Enroll every currently open project in lifecycle management | Disabled |
  287. | `ide_release_project` | Unenroll a project from lifecycle management | Disabled |
  288. | `ide_release_all_projects` | Release every managed project (including closed ones) from lifecycle management | Disabled |
  289. | `ide_lifecycle_log` | Query recent lifecycle events from a ring buffer; each event has a `trigger` field explaining the cause | Disabled |
  290. | `ide_set_lifecycle_log_file` | Enable or disable writing lifecycle events to `mcp-lifecycle.log` | Disabled |
  291. **Lifecycle modes** — transitions are automatic, driven by window focus and MCP activity:
  292. | Mode | Power Save | Editors | PSI Cache | Auto-transition |
  293. |------|-----------|---------|-----------|-----------------|
  294. | `active` | off | open | loaded | focus lost for N min → background |
  295. | `background` | on | open | loaded | N min idle → dormant |
  296. | `dormant` | on | closed (reopen on next focus) | freed | N min idle → closed |
  297. | `closed` | — | — | freed | next MCP call → background (auto-reopens) |
  298. "Idle" means no MCP tool call: every call on a managed project restarts its background → dormant countdown, and the countdown only runs while the project window is unfocused (an `active` project has no countdown). A `dormant` transition closes the editor tabs but remembers them — across IDE restarts too — and reopens them the moment the window regains focus (or the project is released); an MCP wake leaves them closed, since the agent does not need them.
  299. Timing thresholds are configurable in Settings. Lifecycle management is opt-in (disabled by default); once "Enable lifecycle management" is turned on in Settings → Tools → Index MCP Server, projects enroll automatically on first MCP use and auto-reopen when an MCP tool targets a closed project — existing tools require no changes.
  300. **MCP availability guarantee:** the lifecycle manager never closes below the configurable minimum of open managed projects (default 4) — projects at the floor stay in `dormant` (memory mostly freed, MCP still reachable) instead of closing. If all projects are somehow closed (e.g., the user manually closes the last window), any MCP tool call without a `project_path` automatically reopens a managed-closed project to restore access.
  301. ### Tool Availability by IDE
  302. **Fully Tested:**
  303. | IDE | Universal | Navigation | Refactoring |
  304. |-----|-----------|------------|-------------|
  305. | IntelliJ IDEA | ✓ all universal tools | ✓ 6 tools | ✓ rename + move + reformat + optimize imports + safe delete + Java→Kotlin |
  306. | Android Studio | ✓ all universal tools | ✓ 6 tools | ✓ rename + move + reformat + optimize imports + safe delete + Java→Kotlin |
  307. | PyCharm | ✓ all universal tools | ✓ 6 tools | ✓ rename + move + reformat + optimize imports |
  308. | WebStorm | ✓ all universal tools | ✓ 6 tools | ✓ rename + move + reformat + optimize imports |
  309. | GoLand | ✓ all universal tools | ✓ 4 tools | ✓ rename + move + reformat + optimize imports |
  310. | RustRover | ✓ all universal tools | ✓ 5 tools | ✓ rename + move + reformat + optimize imports |
  311. | PhpStorm | ✓ all universal tools | ✓ 6 tools | ✓ rename + move + reformat + optimize imports |
  312. **May Work (Untested):**
  313. | IDE | Universal | Navigation | Refactoring |
  314. |-----|-----------|------------|-------------|
  315. | RubyMine | ✓ all universal tools | ✓ 2 Markdown tools | ✓ rename + move + reformat + optimize imports |
  316. | CLion | ✓ all universal tools | ✓ 2 Markdown tools | ✓ rename + move + reformat + optimize imports |
  317. | DataGrip | ✓ all universal tools | ✓ 2 Markdown tools | ✓ rename + move + reformat + optimize imports |
  318. > **Note**: Navigation tools activate when language plugins are present. Markdown adds heading search and file-structure support when the bundled Markdown plugin is enabled. With the Scala plugin enabled, Scala 2 sources get type hierarchy, call hierarchy, implementations, super methods, and file structure; Java and Kotlin declarations those results reach are reported with their own language. Go and Rust do not expose `ide_find_super_methods` due to language semantics, and Go does not expose `ide_find_implementations`. Rename, move, reformat, and optimize-imports tools work across all languages. `ide_convert_java_to_kotlin` is available only in IntelliJ IDEA and Android Studio, requires both Java and Kotlin plugins, and is disabled by default.
  319. For detailed tool documentation with parameters and examples, see [USAGE.md](USAGE.md).
  320. For Claude Code users: [hooks](docs/claude-code-hooks.md) that enforce IDE tool usage over bash/grep/sed fallbacks.
  321. For agent-heavy workflows: [recommended IDE settings](docs/recommended-ide-settings.md) that prevent modal dialogs from blocking headless MCP sessions.
  322. ## Multi-Project Support
  323. When multiple projects are open in a single IDE window, you must specify which project to use with the `project_path` parameter:
  324. ```json
  325. {
  326. "name": "ide_find_references",
  327. "arguments": {
  328. "project_path": "/Users/dev/myproject",
  329. "file": "src/Main.kt",
  330. "line": 10,
  331. "column": 5
  332. }
  333. }
  334. ```
  335. If `project_path` is omitted:
  336. - **Single project open**: That project is used automatically
  337. - **Multiple projects open**: An error is returned with the list of available projects
  338. ### Workspace Projects
  339. The plugin supports **workspace projects** where a single IDE window contains multiple sub-projects as modules with separate content roots. The `project_path` parameter accepts:
  340. - The **workspace root** path
  341. - A **sub-project path** (module content root)
  342. - A **subdirectory** of any open project
  343. When an error occurs, the response returns `available_projects`. By default this includes workspace sub-projects so AI agents can discover valid module content roots. If you want smaller error payloads, switch **Project list in error responses** to **Compact** in plugin settings to return only top-level project roots.
  344. ## Lifecycle Management
  345. When you use the plugin across multiple projects simultaneously — common when an AI agent is working across a monorepo — open projects compete for memory even when they're not being actively used. Lifecycle management handles this, but it is opt-in: enable "Enable lifecycle management" in Settings → Tools → Index MCP Server (disabled by default).
  346. Once enabled, projects enroll on their first MCP tool call and are notified via balloon. From that point, transitions happen based on focus and MCP activity:
  347. 1. **Focus lost** → after 2 minutes, Power Save Mode on (`background`)
  348. 2. **No MCP calls** → after 2 more minutes, editor tabs close and PSI cache is freed (`dormant`). Every MCP call restarts this countdown. The closed tabs come back when the window regains focus
  349. 3. **Still idle** → after 10 minutes, project window closes entirely (`closed`)
  350. 4. **Next MCP call** → project reopens automatically, indexes, and responds normally
  351. No changes are needed in existing MCP tools — `ProjectResolver` handles the reopen transparently. The auto-reopen typically takes 5–15 seconds on first open; subsequent opens are faster.
  352. The lifecycle manager never closes below the configurable minimum of open managed projects (default 4): projects at the floor stay dormant (memory mostly freed, MCP still reachable) instead of closing. If all projects are closed by other means, any tool call automatically reopens one managed project to restore MCP access.
  353. Use `ide_project_status` to see the current state of all projects at a glance, and `ide_lifecycle_log` to see what happened and why — useful when a project closed unexpectedly. Each log event has a `trigger` field: `timer:inactivity`, `timer:close`, `focus_gained`, `mcp_call`, `auto_open`, `user`, etc., and a `detail` where it helps — e.g. how long a project had no MCP call when the inactivity timer fired, or how many editor tabs a dormant transition closed.
  354. Timing thresholds are configurable in Settings → Tools → Index MCP Server → Project Lifecycle Management.
  355. ## Tool Window
  356. The plugin adds an "Index MCP Server" tool window (bottom panel) that shows:
  357. - **Server Status**: Running indicator with server URL and port
  358. - **Project Name**: Currently active project
  359. - **Command History**: Log of all MCP tool calls with:
  360. - Timestamp
  361. - Tool name
  362. - Status (Success/Error/Pending)
  363. - Parameters and results (expandable)
  364. - Execution duration
  365. ### Tool Window Actions
  366. | Action | Description |
  367. |--------|-------------|
  368. | Refresh | Refresh server status and command history |
  369. | Copy URL | Copy the MCP server URL to clipboard |
  370. | Clear History | Clear the command history |
  371. | Export History | Export history to JSON or CSV file |
  372. | **Install on Coding Agents** | Install MCP server on AI assistants (prominent button on right) |
  373. ## Error Codes
  374. ### JSON-RPC Standard Errors
  375. | Code | Name | Description |
  376. |------|------|-------------|
  377. | -32700 | Parse Error | Failed to parse JSON-RPC request |
  378. | -32600 | Invalid Request | Invalid JSON-RPC request format |
  379. | -32601 | Method Not Found | Unknown method name |
  380. | -32602 | Invalid Params | Invalid or missing parameters |
  381. | -32603 | Internal Error | Unexpected internal error |
  382. ### Tool Errors
  383. Since v5.0.0, tool-level failures (index not ready, file not found, symbol not found, refactoring conflicts) are returned as MCP tool results with `isError: true` and a descriptive message — not as custom JSON-RPC error codes. JSON-RPC error codes are reserved for transport-level protocol violations handled by the MCP SDK.
  384. ## Settings
  385. Configure the plugin at <kbd>Settings</kbd> > <kbd>Tools</kbd> > <kbd>Index MCP Server</kbd>:
  386. | Setting | Default | Description |
  387. |---------|---------|-------------|
  388. | Server Port | IDE-specific | MCP server port (range: 1024-65535, auto-restart on change). See [IDE-Specific Defaults](#ide-specific-defaults) |
  389. | Server Host | `127.0.0.1` | Listening host. Change to `0.0.0.0` for remote/WSL access |
  390. | Max History Size | 100 | Maximum number of commands to keep in history |
  391. | Project List in Error Responses | Expanded | Controls `available_projects` detail for invalid/missing `project_path` errors. `Expanded` includes workspace sub-projects; `Compact` returns only top-level project roots |
  392. | Sync External Changes | false | Sync external file changes before operations (**WARNING: significant performance impact**) |
  393. | Response Format | JSON | Tool response serialization: JSON or TOON |
  394. | Disabled Tools | Tool-specific | Per-tool enable/disable toggles on the Exposed Tools sub-page. Disabled tools stay hidden and cannot be called until enabled |
  395. | **Lifecycle Management** | | |
  396. | Enable lifecycle management | false | Master toggle for the automatic sleep/wake state machine — no automatic sleep/wake happens until this is enabled |
  397. | Active → Background (minutes) | 2 | Focus-loss grace period before switching to Power Save Mode |
  398. | Background → Dormant (minutes) | 2 | MCP-idle time before closing editors and freeing PSI caches |
  399. | Dormant → Closed (minutes) | 10 | Idle time before fully closing the project window |
  400. | Minimum open projects | 4 | Floor of managed projects kept open (1-20); projects at the floor stay dormant instead of closing |
  401. | Event log buffer size | 500 | How many events `ide_lifecycle_log` retains in memory (100–10,000) |
  402. ## Requirements
  403. - **JetBrains IDE** 2025.3 or later (any IDE based on IntelliJ Platform)
  404. - **JVM** 21 or later
  405. - **MCP Protocol** 2025-03-26 (primary Streamable HTTP), with 2024-11-05 legacy SSE compatibility
  406. ### Supported IDEs
  407. **Fully Tested:**
  408. - IntelliJ IDEA (Community/Ultimate)
  409. - Android Studio
  410. - PyCharm (Community/Professional)
  411. - WebStorm
  412. - GoLand
  413. - RustRover
  414. - PhpStorm
  415. **May Work (Untested):**
  416. - RubyMine
  417. - CLion
  418. - DataGrip
  419. **Not Supported:**
  420. - Rider — the plugin is declared incompatible with Rider (`com.intellij.modules.rider`) because its ReSharper backend does not provide the IntelliJ PSI APIs the tools depend on. Rider support is tracked in [#167](https://github.com/hechtcarmel/jetbrains-index-mcp-plugin/issues/167).
  421. > The plugin uses standard IntelliJ Platform APIs and should work on any IntelliJ-based IDE other than Rider, but has only been tested on the IDEs listed above.
  422. ## Architecture
  423. The plugin runs a **custom embedded Ktor CIO HTTP server** with **dual MCP transports**:
  424. ### Streamable HTTP Transport (Primary, MCP 2025-03-26)
  425. ```
  426. AI Assistant ──────► POST /index-mcp/streamable-http (initialize or request)
  427. ◄── JSON-RPC response or HTTP 202 Accepted
  428. ──────► POST /index-mcp/streamable-http (follow-up requests/notifications)
  429. ◄── JSON-RPC response or HTTP 202 Accepted
  430. ```
  431. The plugin uses stateless Streamable HTTP for the primary MCP transport. It does not
  432. issue `Mcp-Session-Id` headers, does not require session resumption, and does not
  433. implement or advertise authentication capabilities.
  434. ### Legacy SSE Transport (MCP Inspector, older clients)
  435. ```
  436. AI Assistant ──────► GET /index-mcp/sse (establish SSE stream)
  437. ◄── event: endpoint (receive POST URL with sessionId)
  438. ──────► POST /index-mcp?sessionId=x (JSON-RPC requests)
  439. ◄── HTTP 202 Accepted
  440. ◄── event: message (JSON-RPC response via SSE)
  441. ```
  442. This dual approach:
  443. - **Primary MCP transport** - Streamable HTTP per MCP `2025-03-26`
  444. - **MCP Inspector compatible** - Legacy SSE transport per MCP `2024-11-05`
  445. - **Configurable port** - IDE-specific default port, changeable in settings
  446. - Works with any MCP-compatible client
  447. - Single server instance across all open projects
  448. ## Contributing
  449. Contributions are welcome! Please:
  450. 1. Fork the repository
  451. 2. Create a feature branch
  452. 3. Make your changes
  453. 4. Run tests: `./gradlew test`
  454. 5. Submit a pull request
  455. ### Development Setup
  456. ```bash
  457. # Build the plugin
  458. ./gradlew build
  459. # Run IDE with plugin installed
  460. ./gradlew runIde
  461. # Run tests — everything, ~40s. Use -Ptier=unit for the fast headless tier only.
  462. ./gradlew test
  463. # Run plugin verification
  464. ./gradlew verifyPlugin
  465. ```
  466. See [CONTRIBUTING.md](CONTRIBUTING.md) for the test tiers and assertion rules.
  467. ## License
  468. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  469. ---
  470. Plugin based on the [IntelliJ Platform Plugin Template](https://github.com/JetBrains/intellij-platform-plugin-template).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.