intellij-idea-doctor

intellij-idea-doctor — diagnose the IntelliJ MCP oracle

A responding MCP server is not the same as a usable oracle. The tools can answer while bound to a project that never imported Gradle, or to a different project than the one you are working in — and then search_symbol returns nothing and get_file_problems emits false "Cannot resolve symbol" errors on code that ./gradlew build compiles cleanly. This skill runs the minimal probe set that tells the three states apart and prints a plain verdict.

For the why behind each probe and the fallback rules, see the intellij-idea skill (§ Connection health check). This skill is the runner; that skill is the reference — keep interpretation logic in sync with it.

Procedure

PROJECT=<absolute path to this repository's root> (pass as projectPath on every call). Tool names below are bare — call each as it appears in your own tool list.

Run the probes your agent actually has (see § Tool availability per agent). search_symbol is the portable primary — every IDE-enabled agent has it, and it alone distinguishes all the states. get_project_dependencies is the un-fakeable corroboration, available only to the orchestrator and system-design-expert.

1. Pick a known repo class so the "right project" check is robust to renames. Glob src/main/java/**/*.java, take any one file, and use its simple class name (any @Service, @Entity, @RestController, or other class you can confirm exists). Note its real path — that is what a healthy oracle must echo back.

2. Primary probe — symbol resolution (every IDE-enabled agent has this). search_symbol(q=<known class>, projectPath=PROJECT)

   • Hit whose filePath is under this repo (matches step 1) → the right project is bound and its sources are indexed → healthy.
   • Hit whose filePath is outside this repo → wrong project bound.
   • {"items":[]} → sources not in the model: model not loaded (Gradle not imported) or wrong project — disambiguate with step 3 if you can.
   • Call errors / times out → server not connected.

3. Corroborating probe — dependencies (only if your agent declares it). get_project_dependencies(projectPath=PROJECT)

   • Non-empty (spring-boot-*, jackson-*, …) → Gradle model imported; confirms a healthy search_symbol.
   • {"dependencies":[]} on this Spring project → model not loaded (no classpath). The un-fakeable signal: a Spring app cannot compile without its libraries. Use it to split a [] symbol result into not-loaded vs wrong-project.
   • If your agent cannot call this tool, say so and rely on search_symbol alone — never report a dependency count you did not observe.

4. Do NOT use get_project_modules as a health signal. A bare module lists fine on a broken model — a false green. Run it only for extra detail, never as the verdict.

Tool availability per agent

The IDE tools are partitioned by role, so not every caller can run every probe. search_symbol (with get_symbol_info) is the common denominator — this skill is built around it for that reason.

Caller	search_symbol (primary)	get_project_dependencies (corroboration)
Orchestrator (main loop)	✅	✅
system-design-expert	✅	✅
feature-implementer	✅	❌
code / test / security reviewers	✅	❌
doc-reviewer / coordinator / PRD	❌ (no IDE tools)	❌

A caller with no search_symbol at all cannot run this check — it reports "IDE not consulted (no oracle tools in this agent)" and proceeds on the native + Gradle baseline. A caller with search_symbol but not get_project_dependencies runs the primary probe and marks the corroboration n/a.

Verdict mapping (primary axis = search_symbol)

search_symbol(known class)	get_project_dependencies (if available)	Verdict
call errors / times out	—	NOT CONNECTED
hit, filePath under this repo	populated or n/a	HEALTHY
hit, filePath outside this repo	—	WRONG PROJECT BOUND
[]	[]	CONNECTED — MODEL NOT LOADED (Gradle not imported)
[]	populated	PARTIAL (deps loaded but symbols unindexed — indexing in progress or stale; re-run shortly)
[]	n/a (agent lacks the tool)	NOT USABLE — symbols don't resolve and there's no deps probe to say why. Treat as unusable (fall back to grep + ./gradlew); have the orchestrator or system-design-expert re-run with get_project_dependencies, or check the IDE directly (§ Without Claude Code).

A repo-local search_symbol hit is sufficient for HEALTHY on its own — the dependencies probe corroborates it but is not required. The deps probe earns its keep only on a [] symbol result, where it separates not-loaded from unindexed.

Output format

Print this block verbatim, filled in:

IntelliJ MCP Oracle — Status
  Connection:    <connected | NOT CONNECTED>
  Project model: <loaded (Gradle imported) | NOT LOADED | unknown>
  Right project: <yes — KnownClass resolves at <path> | WRONG project | cannot confirm>
  Verdict:       <HEALTHY | CONNECTED — MODEL NOT LOADED | WRONG PROJECT BOUND | PARTIAL | NOT USABLE | NOT CONNECTED>
  Probes:        search_symbol(<KnownClass>)=<M hits>, get_project_dependencies=<N libs | n/a for this agent>
  Trust oracle?  <YES — use at the chokepoints | NO — fall back to grep + ./gradlew>
  Remedy:        <none | the matching remedy below>

Remedies

• MODEL NOT LOADED — in the IDE the MCP is attached to: Gradle tool window → Reload All Gradle Projects; confirm External Libraries populates under the Project view. Then re-run intellij-idea-doctor.
• WRONG PROJECT BOUND — close the stray project/instance, or ensure only one IDE window is open for this repo; the MCP binds to the running IDE.
• NOT CONNECTED — confirm the IDE is running with the MCP server enabled (IntelliJ: Settings → Tools → AI Assistant / MCP, or the MCP plugin's status indicator). Do not block work on it — fall back to native + Gradle.

Without Claude Code (human-only check)

Anyone can sanity-check from the IDE directly, no agent needed:

1. Connected? IntelliJ Settings → Tools (AI Assistant / MCP) shows the MCP server running.
2. Right project + loaded? The Project view shows this repo, the Gradle tool window lists this project, and External Libraries lists Spring/Jackson jars. If External Libraries is empty or the Gradle tool window is absent, the project was opened as a plain folder — Reload All Gradle Projects (or reopen build.gradle as a project).

Rules

• Read-only. This skill never edits files; it only probes and reports.
• Report only probes you actually ran (see intellij-idea § Report only checks you actually ran). Never narrate a green you did not observe.
• A get_project_modules success is not a passing verdict on its own — the verdict comes from symbol resolution (primary), corroborated by dependencies when the caller has that tool.