JetBrains Inspection API

A plugin that exposes JetBrains IDE inspection results via HTTP API for automated tools and AI assistants.

Features

• Real-time HTTP API access to inspection results
• Scope-based filtering (whole project, current file, or specific files)
• Severity filtering (error, warning, weak_warning, info, or all)
• File-specific endpoint for targeted inspection analysis
• Works with all JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, etc.)
• MCP integration for seamless AI assistant access
• Comprehensive inspection framework - mirrors PyCharm's "Inspect Code" functionality
• High performance - < 100 ms response time for full project inspection
• Complete inspection coverage - detects JSCheckFunctionSignatures, ShellCheck, SpellCheck, and all enabled inspections

Quick Start

1. Install Plugin

From Releases:

1. Download the latest .zip file from Releases
2. In your IDE: Settings → Plugins → ⚙️ → Install Plugin from Disk...
3. Select the downloaded file and restart the IDE

Build from Source:

git clone https://github.com/cbusillo/jetbrains-inspection-api.git
cd jetbrains-inspection-api
JAVA_HOME=$(/usr/libexec/java_home -v 21) ./gradlew buildPlugin
# Plugin will be in build/distributions/

2. Configure IDE Built-in Server

1. Open IDE Settings: File → Settings (or IntelliJ IDEA → Preferences on Mac)
2. Navigate to: Build, Execution, Deployment → Debugger
3. In the "Built-in server" section:
   • Port: Set to 63341 (PyCharm), 63340 (IntelliJ), or 8080 (avoid default 63342)
   • ✅ Check: "Can accept external connections"
   • ✅ Check: "Allow unsigned requests"
4. Apply settings and restart IDE

3. Set Up Claude Code MCP

First, clone the repository and install MCP server dependencies:

git clone https://github.com/cbusillo/jetbrains-inspection-api.git
cd jetbrains-inspection-api/mcp-server
npm install

Then add the MCP server using Claude Code CLI:

# For PyCharm (typically port 63341)
claude mcp add-json inspection-pycharm '{"command": "node", "args": ["/path/to/jetbrains-inspection-api/mcp-server/server.js"], "env": {"IDE_PORT": "63341"}}'

# For IntelliJ (typically port 63340)
claude mcp add-json inspection-intellij '{"command": "node", "args": ["/path/to/jetbrains-inspection-api/mcp-server/server.js"], "env": {"IDE_PORT": "63340"}}'

# Verify configuration
claude mcp list

# Restart Claude Code

Replace /path/to/jetbrains-inspection-api with actual location of your cloned repository.

Usage

With Claude Code (Recommended)

# Trigger a full project inspection
inspection_trigger()

# Check inspection status
inspection_get_status()

# Get all problems in project (after triggering)
inspection_get_problems()

# Get problems with severity filtering
inspection_get_problems(severity="error")

# Get problems for currently open files only
inspection_get_problems(scope="current_file")

# Specify which project to inspect (v1.10.5+)
inspection_get_problems(project="MyProject")

# Combine project and severity filtering
inspection_get_problems(project="odoo-ai", severity="error")

Direct HTTP API

# Trigger inspection
curl "http://localhost:63340/api/inspection/trigger"

# Check inspection status
curl "http://localhost:63340/api/inspection/status"

# Get all problems in project
curl "http://localhost:63340/api/inspection/problems"

# Get problems for current file only
curl "http://localhost:63340/api/inspection/problems?scope=current_file"

# Get only error-level problems
curl "http://localhost:63340/api/inspection/problems?severity=error"

# Specify which project to inspect (v1.10.5+)
curl "http://localhost:63340/api/inspection/problems?project=MyProject"

# Trigger inspection for specific project
curl "http://localhost:63340/api/inspection/trigger?project=odoo-ai"

Replace 63340 with your IDE's configured port.

Scopes & Parameters

Scopes

• scope: whole_project (default) | current_file | directory | modules | project | git
• git.base: default HEAD
• git.include_untracked: true|false

Filters

• severity: error|warning|weak_warning|info|grammar|typo|all (default)
• project: optional project name (multi‑project IDEs)
• max_problems: int
• excludes: list of glob patterns

Examples

• Errors only, whole project: curl "http://localhost:63340/api/inspection/problems?severity=error"
• Changed files since HEAD: curl "http://localhost:63340/api/inspection/problems?scope=git&git.base=HEAD"
• Specific modules (path fragments): curl "http://localhost:63340/api/inspection/problems?scope=modules&modules=addons/product_connect,addons/disable_odoo_online"

Result Schema

Typical response:

{
  "run_id": "2025-09-14T19:12:01Z_abc123",
  "version": "1.10.5",
  "started_at": "2025-09-14T19:12:01Z",
  "duration_ms": 842,
  "counts": { "error": 0, "warning": 2, "weak_warning": 0, "info": 0 },
  "files_scanned": 28,
  "problems": [
    {
      "id": "IJ-PY-12345",
      "rule": "PyUnresolvedReferences",
      "severity": "warning",
      "file": "addons/product_connect/models/product.py",
      "line": 42,
      "col": 12,
      "message": "Unresolved reference 'x'",
      "fixable": false,
      "suggestion": "Import or define 'x' before use"
    }
  ]
}

Exit Behavior (for CLI/MCP consumers)

• Gate mode (recommended): exit 1 if total problems > 0 in the selected scope; else 0.
• Discovery mode: always exit 0; return counts only (consumers decide how to gate).
• Invalid parameters: exit 2 and return an error JSON payload with a hint.

Tips

• Inner loop: scope=changed
• Pre‑commit: scope=git (base=HEAD)
• Full gate: scope=project or whole_project

API Reference

Problems Endpoint

URL: GET /api/inspection/problems

Parameters:

• scope (optional): whole_project (default) | current_file | custom path filter
• severity (optional): error | warning | weak_warning | info | grammar | typo | all (default)
• problem_type (optional): Filter by inspection type (e.g., PyUnresolvedReferencesInspection, SpellCheck, Unused)
• file_pattern (optional): Filter by file path pattern - simple string or regex (e.g., *.py, src/.*\.js$)
• limit (optional): Maximum problems to return (default: 100)
• offset (optional): Number of problems to skip for pagination (default: 0)

Examples:

# Get only Python unresolved reference errors
curl "http://localhost:63340/api/inspection/problems?problem_type=PyUnresolvedReferences&severity=error"

# Get problems in test files only
curl "http://localhost:63340/api/inspection/problems?file_pattern=.*test.*\.py$"

# Paginate through large result sets
curl "http://localhost:63340/api/inspection/problems?limit=50&offset=0"
curl "http://localhost:63340/api/inspection/problems?limit=50&offset=50"

# Combine filters for precise results
curl "http://localhost:63340/api/inspection/problems?severity=error&file_pattern=src/&problem_type=TypeScript"

Trigger Endpoint

URL: GET /api/inspection/trigger

Parameters:

• project (optional): Project name to target when multiple projects are open
• scope (optional):
  • whole_project (default)
  • current_file (inspect the currently selected editor file)
  • directory (requires dir, directory, or path)
  • files (inspect only the provided file list)
  • changed_files (inspect the files changed in VCS
• dir | directory | path (optional): Directory to inspect. Relative paths resolve from the project root; absolute paths are accepted.
• file (repeatable, optional): File path when scope=files. Can be repeated multiple times.
• files (optional): Comma or newline‑separated list of file paths when scope=files.
• include_unversioned (optional): true|false when scope=changed_files (default true).
• changed_files_mode (optional): all|staged|unstaged (best‑effort; falls back to all).
• max_files (optional): Positive integer to cap files inspected for responsiveness.
• profile (optional): Name of inspection profile to use; falls back to current profile if not found.

Examples:

# Whole project (default)
curl "http://localhost:63340/api/inspection/trigger"

# Current editor file only
curl "http://localhost:63340/api/inspection/trigger?scope=current_file"

# A specific directory (relative to project)
curl "http://localhost:63340/api/inspection/trigger?scope=directory&dir=src"

# A specific directory (absolute path)
curl "http://localhost:63340/api/inspection/trigger?scope=directory&dir=/full/path/to/addons/hr_employee_name_extended"

# Only files you specify
curl "http://localhost:63340/api/inspection/trigger?scope=files&file=src/app.py&file=tests/test_app.py"
curl "http://localhost:63340/api/inspection/trigger?scope=files&files=src/a.py,src/b.py"

# Only changed files (fast inner loop)
curl "http://localhost:63340/api/inspection/trigger?scope=changed_files&include_unversioned=true&max_files=50"

# Use a lighter inspection profile by name
curl "http://localhost:63340/api/inspection/trigger?profile=LLM%20Fast%20Checks"

Response:

{
  "status": "triggered",
  "message": "Inspection triggered. Wait 10-15 seconds then call /api/inspection/problems",
  "scope": "directory",
  "directory": "src"
}

Status Endpoint

URL: GET /api/inspection/status

Response:

{
  "project_name": "project-name",
  "is_scanning": false,
  "has_inspection_results": true,
  "clean_inspection": false,
  "inspection_in_progress": false,  
  "time_since_last_trigger_ms": 5000,
  "indexing": false,
  "problems_window_visible": true
}

Key Status Fields:

• clean_inspection: NEW - true when inspection completed with no problems
• is_scanning: true if inspection is currently running
• has_inspection_results: true when problems were found and are available
• time_since_last_trigger_ms: Time since last inspection was triggered

Proper Usage Workflow

Important: Always check inspection status before retrieving problems to ensure accurate results.

Recommended Pattern

# 1. Trigger inspection
curl "http://localhost:63340/api/inspection/trigger"

# 2. Wait for completion (check every 2-3 seconds)
while true; do
  STATUS=$(curl -s "http://localhost:63340/api/inspection/status")
  IS_SCANNING=$(echo $STATUS | jq -r '.is_scanning')
  HAS_RESULTS=$(echo $STATUS | jq -r '.has_inspection_results')
  
  if [ "$IS_SCANNING" = "false" ] && [ "$HAS_RESULTS" = "true" ]; then
    echo "✅ Inspection complete!"
    break
  else
    echo "⏳ Waiting for inspection to complete..."
    sleep 2
  fi
done

# 3. Get problems when ready
curl "http://localhost:63340/api/inspection/problems?severity=all"

Understanding Status Response

The status endpoint now includes a clean_inspection field that makes it crystal clear:

{
  "is_scanning": false,
  "has_inspection_results": false,
  "clean_inspection": true, 
  "time_since_last_trigger_ms": 15000
}

Status Indicators:

• is_scanning: true → Inspection running, wait
• clean_inspection: true → Inspection complete, no problems found
• has_inspection_results: true → Problems found, retrieve with /problems
• All false → No recent inspection, trigger one first

MCP Server Details

The included MCP (Model Context Protocol) server provides seamless integration with Claude Code:

Tools Provided

• inspection_trigger(scope?, dir?) - Triggers an inspection (whole project by default; supports scope=current_file or scope=directory&dir=...)
  • Also supports scope=files with file=... (repeat) or files=[...], and scope=changed_files with include_unversioned and max_files.
• inspection_get_status() - Checks inspection status
• inspection_get_problems(scope?, severity?, problem_type?, file_pattern?, limit?, offset?) - Gets inspection problems with filtering and pagination

Requirements

• Node.js 18.0.0+
• JetBrains IDE with this plugin installed
• IDE built-in server enabled and configured

Debugging

# Test the MCP server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node mcp-server/server.js

# Set custom port
IDE_PORT=63340 node mcp-server/server.js

Development Workflow Example

Add this to your project's CLAUDE.md:

## Code Quality Checks

### JetBrains Inspection API

**Usage**: Use MCP tools for inspection results:

- `inspection_trigger()` - Trigger a full project inspection
- `inspection_trigger(scope="current_file")` - Trigger for the active file only
- `inspection_trigger(scope="directory", dir="src")` - Trigger for a specific directory
- `inspection_trigger(scope="files", files=["src/a.py","src/b.py"])` - Trigger for specific files
- `inspection_trigger(scope="changed_files", max_files=50)` - Trigger for changed files only
- `inspection_get_status()` - Check if inspection is complete
- `inspection_get_problems()` - Get all project problems (paginated)
- `inspection_get_problems(scope="current_file")` - Get problems in open files only
- `inspection_get_problems(severity="error")` - Get only error-level problems
- `inspection_get_problems(problem_type="Unused")` - Get specific inspection types
- `inspection_get_problems(file_pattern="*.test.js")` - Get problems in matching files
- `inspection_get_problems(limit=50, offset=0)` - Paginate through results

**Handling Large Results**: When you encounter token limit errors, use filtering:
- Filter by severity: `severity="error"` (most critical issues only)
- Filter by problem type: `problem_type="PyUnresolvedReferences"`
- Filter by file pattern: `file_pattern="src/"`
- Use pagination: `limit=50` then increment `offset`

**Features**:
- Trigger and monitor inspections
- Supports Kotlin, Java, JavaScript, TypeScript, Python
- Returns detailed problems with description, category, and severity
- Use for project-wide code quality assessment before commits

## Development Workflow

1. Make code changes
2. Check real-time results with `inspection_get_problems()`
3. Fix any critical issues found
4. Run tests
5. Commit changes

Known Limitations

Inspection Detection Coverage

• Some inspections may not be detected: The plugin extracts results from the IDE's inspection tree, but certain inspection categories (particularly "Entry Points" and some Java-specific inspections) may not be captured
• IDE-specific variations: Detection completeness may vary between different JetBrains IDEs (IntelliJ IDEA vs. PyCharm vs. WebStorm)
• Workaround: For complete coverage, manually review the IDE's "Problems" view in addition to API results
• Future improvement: Enhanced tree traversal logic is planned to improve detection rates

This limitation primarily affects Java projects in IntelliJ IDEA. PyCharm users should see more complete results.

Testing

Automated IDE Testing

# Run complete automated test cycle
./test-automated.sh

This will automatically:

• Build the plugin
• Stop any running IDE
• Install the plugin
• Start the IDE with your test project
• Run comprehensive API tests
• Report results

Unit Tests

# Run unit tests
JAVA_HOME=$(/usr/libexec/java_home -v 21) ./gradlew test

Version History

v1.10.10 (Latest)

• ✅ New trigger scopes: files, changed_files for fast inner loop
• ✅ New params: file/files, include_unversioned, changed_files_mode, max_files, profile
• ✅ MCP updates: Concise tool/param docs to reduce token usage
• ✅ Status detection: Unified across Problems and Inspection Results windows; clears stale results before runs
• ✅ Docs cleanup: Clarified setup and usage across README/CLAUDE.md
• ✅ Changed files mode: staged / unstaged best‑effort (Git) filtering implemented

v1.7.5

• ✅ Complete inspection framework - Full GlobalInspectionContext and AnalysisScope implementation
• ✅ Performance optimization - < 100 ms response time for full project inspection
• ✅ Comprehensive test suite - 53 passing tests with extensive error handling coverage
• ✅ Thread safety - Proper ReadAction usage for all inspection operations
• ✅ Enhanced detection - JSCheckFunctionSignatures, ShellCheck, SpellCheck, PyUnresolvedReferences

v1.6.0

• ✅ Inspection framework transition - Replaced highlighting API with a proper inspection framework
• ✅ Error handling - Comprehensive exception handling and graceful degradation
• ✅ MCP server updates - Improved descriptions reflecting inspection framework capabilities

v1.5.0

• ✅ File-specific endpoint - Target inspection analysis to individual files
• ✅ Severity filtering - Filter by error, warning, weak_warning, info levels
• ✅ Improved descriptions - Better extraction of inspection issue details
• ✅ Code quality improvements - Eliminated duplication, enhanced maintainability

v1.4.0

• ✅ Real-time inspection - No manual triggering required
• ✅ Scope filtering - Whole project or current file only
• ✅ JetBrains 2025.x compatibility - Latest IDE support
• ✅ Universal file support - All IDE-supported file types
• ✅ Comprehensive coverage - Including spell check and info-level inspections

v1.1.0

• Updated for JetBrains 2025.x compatibility
• Replaced internal APIs with public alternatives

License

MIT License: see LICENSE file for details.