eslint-mcp-server/MCP_USAGE_GUIDE.md

A comprehensive ESLint MCP Server for AI tools with incremental detection and auto-fix capabilities

# ESLint MCP Server 使用指南

## 概述

这是一个基于 Model Context Protocol (MCP) 的 ESLint 工具服务器，可以集成到支持 MCP 的 AI 工具中，提供代码检查和修复功能。

## 功能特性

### 🔍 代码检查功能
- **增量检测**：基于 git diff 检查变更的文件
- **全量检测**：检查项目中的所有相关文件
- **环境检查**：自动检测 ESLint 配置和项目类型
- **智能建议**：为缺失配置提供设置建议

### 🛠️ 修复功能
- **自动修复**：修复可自动修复的 ESLint 问题
- **修复范围**：支持按行、文件或全量修复
- **修复报告**：详细的修复结果反馈

### 📊 输出格式
- **详细模式**：完整的错误信息和环境状态
- **摘要模式**：简化的问题概览

## 安装和配置

### 1. 项目设置

```bash
# 克隆或下载项目
cd npm_mcp_server

# 安装依赖
pnpm install

# 构建项目（可选）
pnpm build
```

### 2. 启动 MCP Server

```bash
# 开发模式
pnpm dev

# 或使用构建版本
pnpm start
```

### 3. MCP Server 配置信息

- **协议**: JSON-RPC over stdio
- **工具名称**: `eslint-fix`
- **传输方式**: stdio (标准输入输出)

## 在 AI 工具中使用

### Claude Desktop 配置

在 Claude Desktop 的配置文件中添加：

```json
{
  "mcpServers": {
    "eslint-mcp": {
      "command": "node",
      "args": ["path/to/npm_mcp_server/dist/apps/mcp-server/index.js"],
      "cwd": "path/to/your/project"
    }
  }
}
```

### Cursor 配置

在 Cursor 的 MCP 设置中添加：

```json
{
  "name": "ESLint MCP",
  "command": ["pnpm", "dev"],
  "cwd": "path/to/npm_mcp_server",
  "env": {}
}
```

### 其他 AI 工具

对于支持 MCP 的其他工具，使用以下配置：

- **命令**: `node dist/apps/mcp-server/index.js` 或 `pnpm dev`
- **工作目录**: MCP server 项目根目录
- **协议**: stdio

## 工具参数说明

### eslint-fix 工具参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `mode` | string | `incremental` | 检测模式：`incremental`(增量) 或 `full`(全量) |
| `autoFix` | boolean | `false` | 是否自动修复问题 |
| `configPath` | string | - | 自定义 ESLint 配置文件路径 |
| `targetFiles` | array | - | 指定要检查的文件列表 |
| `fixType` | string | `all` | 修复范围：`line`、`file` 或 `all` |
| `outputFormat` | string | `detailed` | 输出格式：`detailed` 或 `summary` |

## 使用示例

### 1. 基础检查

```json
{
  "name": "eslint-fix",
  "arguments": {
    "mode": "incremental",
    "outputFormat": "detailed"
  }
}
```

### 2. 全量检查并自动修复

```json
{
  "name": "eslint-fix", 
  "arguments": {
    "mode": "full",
    "autoFix": true,
    "outputFormat": "summary"
  }
}
```

### 3. 检查特定文件

```json
{
  "name": "eslint-fix",
  "arguments": {
    "targetFiles": ["src/index.ts", "src/utils.ts"],
    "autoFix": false,
    "outputFormat": "detailed"
  }
}
```

### 4. 使用自定义配置

```json
{
  "name": "eslint-fix",
  "arguments": {
    "configPath": ".eslintrc.custom.json",
    "mode": "full",
    "outputFormat": "detailed"
  }
}
```

## 输出格式示例

### 详细模式输出

```
# ESLint Results (incremental mode)

## Environment
- ESLint package: ✅ Installed
- TypeScript: ✅ Available
- Project type: typescript
- Config file: eslint.config.js

## Summary
- Files processed: 2
- Errors: 3
- Warnings: 1
- Fixable issues: 2

## Issues Found

### src/index.ts
Errors: 2, Warnings: 0

❌ Line 15:5 - 'unusedVar' is assigned a value but never used (no-unused-vars) (fixable)
❌ Line 23:1 - Missing semicolon (semi) (fixable)

### src/utils.ts  
Errors: 1, Warnings: 1

❌ Line 8:10 - Unexpected console statement (no-console)
⚠️ Line 12:5 - Prefer const over let (prefer-const) (fixable)
```

### 摘要模式输出

```
# ESLint Results (full mode)

## Summary
- Files processed: 5
- Errors: 8
- Warnings: 3
- Fixable issues: 6

## Issues Found

- index.ts: 3 errors, 1 warnings
- utils.ts: 2 errors, 0 warnings
- config.ts: 1 errors, 1 warnings
```

## 故障排除

### 常见问题

1. **ESLint 包未找到**
   ```
   ❌ ESLint package not found. Please install ESLint:
   pnpm install --save-dev eslint
   ```

2. **配置文件缺失**
   - 工具会自动检测并提供配置建议
   - 支持多种配置格式：eslint.config.js、.eslintrc.*

3. **TypeScript 解析错误**
   - 确保安装了 @typescript-eslint/parser
   - 检查 ESLint 配置是否支持 TypeScript

### 调试模式

启动时查看详细日志：

```bash
# 开发模式会显示详细的服务器日志
pnpm dev
```

## 开发和扩展

### 添加新功能

1. 修改 `apps/mcp-server/src/index.ts`
2. 更新工具参数 schema
3. 实现新的功能逻辑
4. 测试并提交

### 自定义配置

可以根据项目需求修改：
- ESLint 规则配置
- 文件过滤逻辑  
- 输出格式
- 错误处理

## 支持的 AI 工具

- ✅ Claude Desktop
- ✅ Cursor
- ✅ 其他支持 MCP 的 AI 工具

## 技术栈

- **框架**: Nx + TypeScript
- **MCP SDK**: @modelcontextprotocol/sdk
- **ESLint**: 9.x + TypeScript 支持
- **Git 集成**: simple-git
- **包管理**: pnpm