eslint-mcp-server/AUGMENT_SETUP_GUIDE.md

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

# 在 Augment AI 中使用 ESLint MCP Server

## 快速配置

### 1. 复制配置到 Augment

**推荐配置（最稳定）**：
```json
{
  "mcpServers": {
    "eslint-fix": {
      "command": "pnpm",
      "args": ["dev"],
      "cwd": "d:/code_space/webstrom_project/person/npm_mcp_server"
    }
  }
}
```

**备选配置（如果pnpm不可用）**：
```json
{
  "mcpServers": {
    "eslint-fix": {
      "command": "npx",
      "args": ["ts-node", "apps/mcp-server/src/index.ts"],
      "cwd": "d:/code_space/webstrom_project/person/npm_mcp_server"
    }
  }
}
```

### 2. 验证配置

重启 Augment AI 后，你应该能看到 `eslint-fix` 工具可用。

## 使用示例

### 基础代码检查

**提示词**：
```
请使用 eslint-fix 工具检查当前项目的代码质量，使用增量模式检查最近修改的文件。
```

**工具调用**：
```json
{
  "name": "eslint-fix",
  "arguments": {
    "mode": "incremental",
    "outputFormat": "detailed"
  }
}
```

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

**提示词**：
```
请使用 eslint-fix 工具检查所有文件并自动修复可修复的问题，使用摘要格式显示结果。
```

**工具调用**：
```json
{
  "name": "eslint-fix",
  "arguments": {
    "mode": "full",
    "autoFix": true,
    "outputFormat": "summary"
  }
}
```

### 检查特定文件

**提示词**：
```
请检查 src/index.ts 和 src/utils.ts 文件的代码质量，显示详细的错误信息。
```

**工具调用**：
```json
{
  "name": "eslint-fix",
  "arguments": {
    "targetFiles": ["src/index.ts", "src/utils.ts"],
    "outputFormat": "detailed"
  }
}
```

## 工具参数说明

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

## 预期输出格式

### 详细模式输出示例

```
# 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)
```

### 摘要模式输出示例

```
# 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
```

## 故障排除

### 常见问题

1. **MCP server启动失败**
   - **错误**: "Cannot find module './index.ts'"
   - **解决**: 使用推荐的 `pnpm dev` 配置，或确保工作目录正确

2. **工具未找到**
   - 确保 Augment AI 已重启
   - 检查配置文件路径是否正确
   - 验证 `cwd` 路径指向正确的项目目录

3. **命令执行失败**
   - 确保 Node.js 和 pnpm 已安装
   - 确保项目依赖已安装: `pnpm install`
   - 检查路径中是否包含特殊字符

4. **TypeScript 错误**
   - 确保 ts-node 已安装
   - 检查 TypeScript 配置
   - 尝试使用 `pnpm dev` 而不是直接的 ts-node

### 调试步骤

1. 在终端中手动测试命令：
   ```bash
   cd d:/code_space/webstrom_project/person/npm_mcp_server
   npx ts-node apps/mcp-server/src/index.ts
   ```

2. 检查 Augment 的 MCP 日志

3. 验证工作目录路径正确

## 替代配置

### 使用构建版本（如果构建成功）

```json
{
  "mcpServers": {
    "eslint-fix": {
      "command": "node",
      "args": ["dist/apps/mcp-server/index.js"],
      "cwd": "d:/code_space/webstrom_project/person/npm_mcp_server"
    }
  }
}
```

### 使用 pnpm dev

```json
{
  "mcpServers": {
    "eslint-fix": {
      "command": "pnpm",
      "args": ["dev"],
      "cwd": "d:/code_space/webstrom_project/person/npm_mcp_server"
    }
  }
}
```

## 功能特性

✅ **智能环境检测**：自动检测 ESLint 配置和项目类型  
✅ **增量检测**：基于 git diff 的高效检查  
✅ **自动修复**：修复可自动修复的 ESLint 问题  
✅ **多种输出格式**：详细和摘要两种格式  
✅ **配置建议**：为缺失配置提供设置建议  
✅ **错误处理**：友好的错误信息和故障排除指导