ESLint MCP

A high-performance Model Context Protocol (MCP) server for ESLint that provides instant linting feedback for LLM agents.

🚀 Quick Start

# Install globally
npm install -g @uplinq/mcp-eslint

# Add to your .mcp.json
{
  "mcpServers": {
    "eslint": { "command": "mcp-eslint" }
  }
}

# Start using ESLint tools in your MCP client!

🎯 Key Features

• ⚡ Lightning Fast: Direct ESLint API usage with in-memory caching
• 🏗️ Monorepo Ready: Automatic workspace detection and per-project ESLint instances
• 🎯 Zero Configuration: Works with any existing ESLint setup
• 📊 Rich Diagnostics: Detailed error reporting with rule IDs and precise locations
• 🔧 Auto-fix Support: Apply ESLint fixes automatically
• 💾 Memory Efficient: Cached ESLint instances per workspace

Performance

• No Process Spawning: Direct ESLint API calls eliminate CLI overhead
• Instant Responses: Cached ESLint instances provide sub-millisecond response times
• Background Processing: True daemon behavior for LLM agents
• Workspace Isolation: Each project gets its own ESLint configuration and cache

Installation

For Development

git clone <repository-url>
cd mcp-eslint
npm install
npm run build

As Package

npm install -g @uplinq/mcp-eslint

Usage

Start the MCP Server

Development:

npm run dev
# or 
node dist/index.js

Installed Package:

mcp-eslint
# or with options
mcp-eslint --workspace /path/to/project

CLI Options

mcp-eslint [options]

Options:
  -V, --version           output version number
  -w, --workspace <path>  workspace path (auto-detected if not specified)
  -c, --config <path>     path to ESLint configuration file
  --timeout <ms>          request timeout in milliseconds (default: 10000)
  --retries <count>       maximum number of retries (default: 2)
  --stdio                 use stdio transport (default)
  --sse [port]            use SSE transport on specified port
  -h, --help              display help for command

MCP Configuration

Add to your .mcp.json:

{
  "mcpServers": {
    "eslint": {
      "command": "mcp-eslint"
    }
  }
}

Available Tools

📋 lint - Get ESLint Diagnostics

{
  "name": "lint",
  "arguments": {
    "filePath": "/absolute/path/to/file.js"
  }
}

Returns detailed ESLint diagnostics with:

• Rule IDs and error messages
• Precise line/column positions
• Severity levels (error/warning)
• Source information

🔧 codeActions - Get Available Fixes

{
  "name": "codeActions",
  "arguments": {
    "filePath": "/absolute/path/to/file.js",
    "line": 0,
    "character": 4
  }
}

Returns available quick fixes:

• Auto-fix all problems
• Disable rules for lines
• Other ESLint-specific actions

⚡ fixAll - Apply All Auto-fixes

{
  "name": "fixAll", 
  "arguments": {
    "filePath": "/absolute/path/to/file.js"
  }
}

Applies all available ESLint auto-fixes to the file.

🔧 fix - Apply Specific Fix

{
  "name": "fix",
  "arguments": {
    "filePath": "/absolute/path/to/file.js",
    "line": 0,
    "character": 4,
    "actionIndex": 0
  }
}

Applies a specific code action by index.

⚙️ validateConfig - Validate ESLint Configuration

{
  "name": "validateConfig",
  "arguments": {
    "configPath": "/path/to/.eslintrc.js"
  }
}

Validates ESLint configuration files.

ESLint Configuration Support

The server automatically detects ESLint configuration files:

• Legacy Config: .eslintrc.js, .eslintrc.cjs, .eslintrc.json, .eslintrc.yml, .eslintrc.yaml
• Flat Config: eslint.config.js, eslint.config.mjs, eslint.config.cjs
• Package.json: eslintConfig field

Monorepo Support

Automatically handles monorepos with multiple ESLint configurations:

monorepo/
├── packages/
│   ├── frontend/
│   │   ├── .eslintrc.json  ← Frontend-specific rules
│   │   └── src/
│   └── backend/
│       ├── .eslintrc.json  ← Backend-specific rules  
│       └── src/

Each package gets its own cached ESLint instance with the correct configuration.

Supported File Types

• JavaScript: .js, .mjs, .cjs
• TypeScript: .ts, .tsx (with @typescript-eslint)
• React/JSX: .jsx, .tsx
• Vue: .vue (with vue-eslint-parser)
• HTML: .html (with @html-eslint/parser)
• Markdown: .md (with eslint-plugin-markdown)

Development

npm install
npm run build
npm run dev

Testing

npm test              # Run test suite (10 tests)
npm run test:coverage # Run with coverage report (56% coverage)
npm run lint          # Run ESLint on codebase
npm run typecheck     # Run TypeScript type checking

Current Test Coverage: 56% overall with comprehensive testing of:

• ESLint integration with real configurations
• Workspace detection and caching
• Auto-fix functionality
• Error handling scenarios
• Basic server integration

Architecture

• ESLint Manager (src/eslint-manager.ts): Core ESLint integration with workspace detection
• Server (src/server.ts): FastMCP server with tool definitions
• Types (src/types.ts): TypeScript interfaces for ESLint integration

How It Works

1. Workspace Detection: For each file, walks up directory tree to find closest ESLint config
2. Instance Caching: Creates and caches ESLint instances per workspace path
3. Direct API: Uses ESLint's JavaScript API directly (no CLI/LSP overhead)
4. Memory Resident: ESLint instances stay in memory for instant subsequent requests

This approach provides true background ESLint processing for LLM agents with instant response times and automatic workspace isolation.

Known Issues

• Complex Monorepo Configurations: In some monorepo setups with workspace-scoped configurations (e.g., configurations that reference workspace dependencies), the MCP may have difficulty resolving ESLint configurations due to module resolution differences between the MCP process and the target workspace. The MCP works correctly with standard ESLint configurations.

  Workaround: Ensure ESLint runs correctly from the target directory using npx eslint <file> before using the MCP. For complex setups, consider using a simpler ESLint configuration that doesn't depend on workspace-specific packages.