# SonarLint MCP Server

A Model Context Protocol (MCP) server that brings enterprise-grade code analysis to Claude Desktop and other MCP clients using SonarLint's standalone SLOOP backend.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)

## Features

- **🔍 Real-time Code Analysis** - Detect bugs, code smells, and security vulnerabilities
- **🚀 Fast & Standalone** - No IDE or SonarQube server required
- **📦 Multiple Languages** - JavaScript, TypeScript, Python (265+ JS rules)
- **💾 Session Storage** - Results stored in memory for multi-turn conversations
- **🔧 Quick Fixes** - Automated suggestions for common issues
- **🎯 Batch Analysis** - Analyze multiple files efficiently

## Quick Start

### Prerequisites

- Node.js 22 or higher
- Claude Desktop (or any MCP client)

### Installation

No installation required! Use `npx` to run directly:

```bash
npx @nielspeter/sonarlint-mcp-server
```

The SLOOP backend (~70MB) downloads automatically on first run.

#### From Source (for development):

```bash
git clone https://github.com/nielspeter/sonarlint-mcp-server.git
cd sonarlint-mcp-server
npm install  # Auto-downloads SLOOP backend (~70MB)
npm run build
```

### Configure with Claude Code

Use the Claude CLI to add the MCP server:

```bash
claude mcp add --transport stdio sonarlint -- npx -y @nielspeter/sonarlint-mcp-server
```

This automatically updates your Claude Code configuration. No restart needed!

### Configure with Claude Desktop

Add to your `claude_desktop_config.json`:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "sonarlint": {
      "command": "npx",
      "args": ["-y", "@nielspeter/sonarlint-mcp-server"]
    }
  }
}
```

Restart Claude Desktop to apply changes.

## Rule Configuration

Customize SonarLint rules per project by creating a `sonarlint.json` in your project root:

```json
{
  "rules": {
    "typescript:S3776": {
      "level": "on",
      "parameters": {
        "threshold": "20"
      }
    },
    "javascript:S1481": {
      "level": "off"
    }
  }
}
```

- **`level`**: `"on"` (default) or `"off"` to enable/disable a rule
- **`parameters`**: Override rule thresholds and settings (see [configurable rules](./docs/configurable-rules.md))
- **Fallback**: If no `sonarlint.json` is found, `.sonarlint/settings.json` is checked (IDE convention)

Copy `sonarlint.example.json` from this repo as a starting point. Use `list_rules` to discover available rules and their configurable parameters.

## Usage

Once configured, Claude can analyze your code:

```
Analyze my JavaScript file for code quality issues: /path/to/file.js
```

```
Check these files for bugs: src/app.ts, src/utils.ts
```

```
Analyze this code snippet:
function process(data) {
  var result = data;  // Issues with 'var'
  return result;
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `check_quality` | Check a file for code quality issues |
| `check_files` | Check multiple files in one call |
| `check_code` | Check a code snippet (no file on disk needed) |
| `fix_issue` | Automatically fix one specific issue |
| `fix_all_issues` | Automatically fix all fixable issues in a file |
| `list_rules` | List all active code quality rules |
| `health_check` | Check server status and diagnostics |

## Example Analysis Output

```javascript
{
  file: "/path/to/file.js",
  language: "javascript",
  issues: [
    {
      line: 4,
      column: 2,
      severity: "MAJOR",
      rule: "javascript:S3504",
      message: "Unexpected var, use let or const instead.",
      quickFix: {
        message: "Replace with 'const'",
        edits: [...]
      }
    }
  ],
  summary: {
    total: 5,
    critical: 0,
    major: 3,
    minor: 2
  }
}
```

## Supported Languages

| Language | Extensions | Rules |
|----------|------------|-------|
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | 265 |
| TypeScript | `.ts`, `.tsx` | 265 |
| Python | `.py` | ~100 |

## Architecture

```
Claude Desktop
      ↓ MCP Protocol (stdio)
SonarLint MCP Server (this project)
      ↓ JSON-RPC
SLOOP Backend (SonarLint Local Operations)
      ↓ Plugin API
Language Analyzers (JS/TS, Python)
```

The server uses SonarLint's standalone SLOOP backend with:
- **Version:** 10.32.0.82302 (WebStorm-compatible)
- **Bundled JRE:** Java 17
- **Bi-directional RPC:** Client request handlers implemented
- **Session Storage:** Results stored in memory for multi-turn conversations

### SLOOP Integration: Scope Lifecycle

SLOOP requires a specific initialization sequence. Getting this wrong causes analysis to hang:

1. **Pre-register files** — Store file DTOs in `scopeFiles` map before creating the scope. SLOOP calls `listFiles` synchronously during scope creation, so files must already be available.
2. **Create scope** — Send `addConfigurationScope` notification to SLOOP.
3. **Wait for readiness** — SLOOP sends `didChangeAnalysisReadiness` when the scope is ready. Analysis requests before this point will fail silently.
4. **Analyse** — Call `analyzeFilesAndTrack` with the files.

Key design decisions:
- **No directory scanning in `listFiles`** — Only return the specific files requested for analysis. Scanning the project root returned 500+ files on real projects and caused multi-minute hangs.
- **`getBaseDir` returns project root** — Detected via `package.json`, `.git`, etc. SLOOP uses this for `.gitignore` matching and file exclusion patterns.
- **`ideRelativePath` relative to project root** — SLOOP's `WildcardPattern.match` requires this; null values cause NPEs.

## Development

```bash
# Install dependencies (auto-downloads backend)
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode (auto-rebuild)
npm run dev

# Inspect with MCP Inspector
npm run inspect
```

## Testing

```bash
# Run test suite
npm test

# Run with UI
npm run test:ui

# Run with coverage
npm run test:coverage
```

Tests validate:
- SLOOP bridge functionality
- File and content analysis
- JavaScript and Python plugin detection
- Quick fix support
- Error handling

## Documentation

- **[SETUP.md](./SETUP.md)** - Detailed installation guide
- **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)** - Common issues and solutions
- **[docs/configurable-rules.md](./docs/configurable-rules.md)** - All 84 configurable rules with parameters and defaults
- **[docs/SLOOP_RPC_PROTOCOL.md](./docs/SLOOP_RPC_PROTOCOL.md)** - Complete RPC protocol documentation
- **[docs/TESTING.md](./docs/TESTING.md)** - Testing guide

## Technical Highlights

This project demonstrates several key technical achievements:

1. **Standalone SLOOP** - First documented standalone use of SonarLint's SLOOP backend
2. **Bi-directional RPC** - Complete client request handler implementation
3. **MCP Integration** - Full Model Context Protocol implementation with resources
4. **Session Management** - Results storage for multi-turn conversations
5. **Production Ready** - Comprehensive testing, error handling, and monitoring

### Critical Implementation Details

For anyone using SLOOP programmatically:
- `listFiles` must return `ClientFileDto` with file content (not just URIs)
- `isUserDefined: true` is mandatory (SLOOP filters out false values)
- `bundlePath` should be parent directory (SLOOP appends `/package/bin/server.cjs`)
- Client must implement 4 request handlers (listFiles, getBaseDir, etc.)
- `backendCapabilities` required for proper initialization

## Why This Approach?

### Advantages
- ✅ No IDE dependency - runs completely standalone
- ✅ Full API access - all SLOOP services available
- ✅ Better control - configure for specific needs
- ✅ More reliable - direct process communication
- ✅ CI/CD capable - can run in automated environments
- ✅ Faster - no IDE overhead

### Comparison to IDE Integration
We initially investigated connecting to IDE servers (WebStorm port 64120) but discovered:
- IDE server is only for "Open in IDE" from SonarQube Server/Cloud
- Limited API access
- IDE must be running
- Not suitable for programmatic access

## Related Projects

- **[SonarQube MCP Server](https://github.com/SonarSource/sonarqube-mcp-server)** - Official server for SonarQube Server/Cloud APIs
  - Complementary approach requiring server setup
  - This project provides local, standalone analysis

## Contributing

Contributions welcome! Areas for improvement:
- Additional language support (Java, Go, PHP)
- Custom rule development
- Performance optimizations
- CI/CD integrations

## License

MIT License - see [LICENSE](./LICENSE)

## Acknowledgments

- **SonarSource** for building SLOOP and SonarLint
- **Anthropic** for the Model Context Protocol
- **Claude Code** for enabling this development

---

**Status:** ✅ Production Ready - All phases complete with comprehensive testing