eslint-mcp-server/README.md

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

# ESLint MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-24.2.0-green.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8.3-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.13.1-purple.svg)](https://modelcontextprotocol.io/)

基于 nx + pnpm 的 ESLint MCP (Model Context Protocol) Server 项目

一个功能完整的 MCP 服务器，为 AI 工具提供 ESLint 代码检查和修复功能。支持增量检测、自动修复、环境检查等高级特性。

## 🚀 快速开始

### 安装

```bash
# 克隆仓库
git clone https://github.com/your-username/eslint-mcp-server.git
cd eslint-mcp-server

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev
```

### 在 AI 工具中使用

1. **配置 MCP 服务器**（以 Augment AI 为例）：
   ```json
   {
     "mcpServers": {
       "eslint-fix": {
         "command": "pnpm",
         "args": ["dev"],
         "cwd": "/path/to/eslint-mcp-server"
       }
     }
   }
   ```

2. **开始使用**：
   - "请使用 eslint-fix 工具检查代码质量"
   - "使用增量模式检查并自动修复代码问题"

## 📁 项目结构

```
npm_mcp_server/
├── apps/
│   └── mcp-server/          # MCP Server 应用
│       ├── src/
│       │   └── index.ts     # 主入口文件
│       ├── project.json     # Nx 项目配置
│       └── tsconfig.*.json  # TypeScript 配置
├── issues/                  # 项目计划和问题跟踪
├── nx.json                  # Nx 工作空间配置
├── tsconfig.base.json       # 基础 TypeScript 配置
└── package.json             # 项目依赖和脚本

```

## 技术栈

- **构建工具**: Nx 21.2.1
- **包管理器**: pnpm
- **运行时**: Node.js 24.2.0
- **语言**: TypeScript 5.8.3
- **MCP SDK**: @modelcontextprotocol/sdk 1.13.1

## 开发命令

```bash
# 开发模式运行
pnpm dev

# 构建项目
pnpm build

# 运行构建后的项目
pnpm start

# 运行服务器
pnpm serve
```

## MCP Server 功能

### ESLint 修复工具 (`eslint-fix`)
功能完整的代码检查和修复工具，支持：

**检测模式**：
- `incremental`（默认）：检测git变更的文件
- `full`：检测所有TypeScript/JavaScript文件

**修复功能**：
- 自动修复可修复的ESLint问题
- 支持按行、文件或全量修复
- 生成详细的修复报告

**配置支持**：
- 自动发现项目ESLint配置
- 支持自定义配置文件路径
- 兼容.eslintrc.json、eslint.config.js等格式

**输出格式**：
- `detailed`：详细的问题列表和位置信息
- `summary`：简化的摘要信息

**参数说明**：
```json
{
  "mode": "incremental|full",           // 检测模式
  "autoFix": true|false,               // 是否自动修复
  "configPath": "path/to/config",      // 自定义配置路径
  "targetFiles": ["file1.ts"],         // 指定文件列表
  "fixType": "line|file|all",          // 修复范围
  "outputFormat": "detailed|summary"   // 输出格式
}
```

## 开发指南

1. MCP Server 代码位于 `apps/mcp-server/src/index.ts`
2. 使用 `pnpm dev` 启动开发服务器
3. 修改代码后会自动重新加载
4. 构建输出位于 `dist/apps/mcp-server/`

## 在 AI 工具中使用 MCP

### 快速开始

1. **启动 MCP Server**
   ```bash
   pnpm dev  # 开发模式
   # 或
   pnpm start  # 生产模式
   ```

2. **配置 AI 工具**

   **Claude Desktop 配置** (`~/.claude_desktop_config.json`):
   ```json
   {
     "mcpServers": {
       "eslint-mcp": {
         "command": "node",
         "args": ["dist/apps/mcp-server/index.js"],
         "cwd": "/path/to/npm_mcp_server"
       }
     }
   }
   ```

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

3. **使用示例**

   在 AI 工具中可以这样使用：

   - "请检查当前项目的 ESLint 问题"
   - "使用增量模式检查代码并自动修复"
   - "检查 src/index.ts 文件的代码质量"

### 详细使用指南

查看 [MCP_USAGE_GUIDE.md](./MCP_USAGE_GUIDE.md) 获取完整的使用说明和配置示例。

### 支持的 AI 工具

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

## 🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📝 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🔗 相关链接

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [ESLint](https://eslint.org/)
- [Nx](https://nx.dev/)
- [TypeScript](https://www.typescriptlang.org/)

## 📊 项目状态

- ✅ 核心功能完成
- ✅ 文档完整
- ✅ 测试验证
- 🔄 持续改进中

## 🎯 路线图

- [ ] 添加更多代码质量检查工具
- [ ] 支持更多编程语言
- [ ] 添加单元测试
- [ ] 配置 CI/CD 流程
- [ ] 添加性能优化