内容
<div align="center">
<img src="static/img/logo.svg" alt="MCP JetBrains 代码检查" width="120" height="120">
</div>
# 🔍 MCP JetBrains 代码检查
[](https://opensource.org/licenses/OSL-3.0)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
[](https://josedacosta.github.io/mcp-jetbrains-code-inspections/)
[](https://github.com/modelcontextprotocol/sdk)
[](https://www.jetbrains.com)
[](https://makeapullrequest.com)
> [!CAUTION]
>
> ## ⚠️ 弃用通知
>
> [](https://github.com/josedacosta/mcp-jetbrains-code-inspections#deprecated-notice)
>
> **该项目已弃用但仍可使用。** 从 2025.2 版本开始，JetBrains IDEs（WebStorm、IntelliJ IDEA、PyCharm 等）现在包含一个内置的 MCP 服务器，提供与外部客户端（如 Claude Desktop、Cursor、VS Code 等）的原生集成。
>
> ### 🔄 迁移选项
>
> | IDE 版本 | 推荐解决方案 | 链接 |
> | -------------------- | -------------------- | --------------------------------------------------------------------------------- |
> | **2025.2+** | 内置 MCP 服务器 | [官方文档](https://www.jetbrains.com/help/webstorm/mcp-server.html) |
> | **早期版本** | JetBrains MCP 插件 | [插件市场](https://plugins.jetbrains.com/plugin/26071-mcp-server) |
>
> ### ✅ 原生集成优势
>
> - **直接 IDE 控制**，无需外部工具
> - **25+ 工具**，全面的工具集
> - **更好的性能**和可靠性
> - **JetBrains 官方支持**
>
> > [!IMPORTANT]
> > 原生 `get_file_problems` 工具需要设置 `errorsOnly: false` 以获得与本项目类似的功能。`get_project_problems` 工具仅返回关键错误。
>
> 📚 **[查看迁移指南和比较 →](https://josedacosta.github.io/mcp-jetbrains-code-inspections/deprecated/jetbrains-native-mcp)**
一个 **模型上下文协议（MCP）** 服务器，提供 JetBrains IDE 代码检查，并具有自动 IDE 选择和适用于所有文件类型的统一检查配置文件。
> [!TIP]
> 📚 **完整文档可用**: 访问我们的综合文档，地址为 [josedacosta.github.io/mcp-jetbrains-code-inspections](https://josedacosta.github.io/mcp-jetbrains-code-inspections/)
## 🎯 快速开始
> [!NOTE]
> 2 分钟即可开始！
```bash
# 克隆仓库
git clone https://github.com/josedacosta/mcp-jetbrains-code-inspections.git
cd mcp-jetbrains-code-inspections
# 安装和构建
yarn install && yarn build
# 使用 MCP 检查器进行测试
yarn inspect
```
然后使用以下 **[配置](#️-configuration)** 配置您的 MCP 客户端（Claude Desktop、Cursor 等）。
## ✨ 功能
<table>
<tr>
<td width="50%">
### 🚀 核心功能
- 🔍 **自动 IDE 检测**
<br>智能选择最佳 JetBrains IDE
- ⚡ **可配置超时**
<br>默认 120s，可调节以适应大型项目
- 🔄 **跨 IDE 兼容**
<br>适用于所有 JetBrains IDE
</td>
<td width="50%">
### 🔧 高级功能
- 📊 **智能输出格式**
<br>适用于 LLMs 的 Markdown，适用于工具的 JSON
- 🎯 **并发执行**
<br>即使在 IDE 打开时也可以运行
- 🌐 **通用配置文件**
<br>适用于所有语言的配置文件
- 💬 **内置提示**
<br>适用于常见任务的预配置提示
- 📚 **服务器资源**
<br>访问配置文件、配置和 IDE 信息
</td>
</tr>
</table>
## 📦 安装
> [!NOTE]
> **前提条件**: Node.js ≥20 和已安装的 JetBrains IDE
### 分步安装
1. **安装依赖**:
```bash
yarn install
```
2. **构建服务器**:
```bash
yarn build
```
3. **配置 MCP** （参见下面的 [⚙️ 配置](#️-configuration) 部分）
> [!TIP]
> 安装后使用 `yarn inspect` 测试服务器与 MCP 检查器
## 🚀 使用
### 📚 MCP 功能
服务器提供三种类型的 MCP 功能：
#### 🔨 工具
- **get_jetbrains_code_inspections**: 对指定文件或目录运行代码检查
#### 💬 提示
- **analyze-project**: 分析项目中的代码质量问题
- **check-file**: 检查特定文件的问题
- **fix-issues**: 获取修复检测问题的建议
#### 📚 资源
- **inspection://profiles**: 可用的检查配置文件列表
- **inspection://config**: 当前 MCP 服务器配置
- **inspection://ides**: 系统上检测到的 JetBrains IDE 列表
### 🏃 运行服务器
> [!TIP]
> 在开发过程中使用 `yarn dev`，它包含热重载以实现更快的迭代。
```bash
# 🔄 在开发模式下运行（带有热重载）
yarn dev
# 📦 运行构建的服务器（生产环境）
yarn start
# 🧪 使用 MCP 检查器进行交互式测试
yarn inspect
```
### ⚙️ 配置
代码检查服务器可以通过 `.mcp.json` 中的环境变量进行配置：
```json
{
"mcpServers": {
"mcp-jetbrains-code-inspections": {
"command": "node",
"args": ["./dist/index.js"],
"env": {
"EXCLUDE_INSPECTIONS": "SpellCheckingInspection"
}
}
}
}
```
### 📝 可用参数
#### 🔧 工具参数（必需）
> [!IMPORTANT]
> 工具仅接受来自 LLM 的一个参数：
| 参数 | 类型 | 描述 | 必需 | 示例 |
| --------- | -------- | --------------------------------- | -------- | ----------------------------- |
| `path` | `string` | 要检查的文件或目录路径 | ✅ 是 | `"src/index.ts"` 或 `"./src"` |
#### 🌍 通过环境变量配置
> [!NOTE]
> 所有配置都通过 `.mcp.json` 中的环境变量进行管理。这些设置控制检查服务器的运行方式。
<details>
<summary><b>📑 可用环境变量</b>（点击展开）</summary>
| 环境变量 | 类型 | 描述 | 默认值 |
| --------------------- | -------------------- | --------------------------------------------------------- | ------------------------- |
| `FORCE_INSPECT_PATH` | `string` | 强制特定的 IDE 检查工具（禁用自动检测） | 自动检测 |
| `FORCE_PROJECT_ROOT` | `string` | 强制项目根目录（禁用自动检测） | 自动检测 |
| `FORCE_PROFILE_PATH` | `string` | 强制检查配置文件路径（禁用默认值） | 项目默认值 |
| `INSPECTION_TIMEOUT` | `number` | 最大分析时间（毫秒） | `120000` |
| `EXCLUDE_INSPECTIONS` | `string` | 要排除的检查代码的逗号分隔列表 | `SpellCheckingInspection` |
| `ONLY_INSPECTIONS` | `string` | 仅包含这些检查代码 | - |
| `RESPONSE_FORMAT` | `'markdown'\|'json'` | 诊断输出格式 | `'markdown'` |
| `DEBUG` | `boolean` | 启用调试日志 | `false` |
</details>
> [!TIP]
> 📚 有关详细配置选项，请参阅 [配置文档](docs/configuration/).
## 🧪 测试
### 1️⃣ 交互式 MCP 测试
```bash
yarn test:mcp
```
这会运行一个交互式测试，允许您直接测试 MCP 服务器功能。
### 2️⃣ 使用 MCP 检查器测试（推荐）
```bash
# 启动检查器（无需安装）
yarn inspect
# 或在开发模式下使用热重载
yarn inspect:dev
```
检查器打开一个 Web 界面，您可以在其中：
- 查看可用的工具、提示和资源
- 交互式测试 `get_jetbrains_code_inspections` 工具
- 使用预配置的提示执行常见任务
- 访问服务器资源（配置文件、配置、检测到的 IDE）
- 实时查看请求/响应
## ⚙️ 工作原理
### 🎯 自动 IDE 选择
> [!NOTE]
> 服务器智能检测并选择最合适的 JetBrains IDE 以满足您的项目。
**优先级顺序：**
1. **IntelliJ IDEA** - 终极 Java/Kotlin IDE
2. **WebStorm** - JavaScript/TypeScript 专家
3. **PyCharm** - Python 开发
4. **PhpStorm** - PHP 开发
5. **GoLand** - Go 编程
6. **Rider** - .NET 开发
7. **CLion** - C/C++ 开发
8. **RubyMine** - Ruby/Rails
9. **DataGrip** - 数据库管理
10. **DataSpell** - 数据科学
11. **AppCode** - iOS/macOS 开发
> [!TIP]
> 使用 `FORCE_INSPECT_PATH` 覆盖自动检测并指定特定 IDE。
### 🔒 隔离配置
> [!IMPORTANT]
> **关键创新**：服务器使用临时隔离配置目录，并使用 `-Didea.config.path` 和 `-Didea.system.path` JVM 属性。这允许检查在 IDE 已打开时运行！
**优势：**
- ✅ 无 IDE 冲突
- ✅ 并行执行支持
- ✅ 清洁、隔离的分析
- ✅ 不干扰您的活动 IDE 会话
### 💻 示例输出
<details>
<summary><b>🔎 查看示例输出</b>（点击展开）</summary>
```console
🔍 搜索可用的 JetBrains IDE 检查工具...
按照以下优先级顺序：IntelliJ IDEA > WebStorm > PyCharm > PhpStorm > GoLand > ...
✅ WebStorm - 已找到并选中！
路径：/Applications/WebStorm.app/Contents/bin/inspect.sh
注意：使用隔离配置 - 即使 IDE 已打开也有效
📊 分析结果：
⚠️ 警告：未使用的变量“config”位于第 42 行
❌ 错误：缺少第 156 行的分号
💡 信息：考虑在第 78 行使用 const 代替 let
```
</details>
## 🛠️ 故障排除
### ❌ “未找到 JetBrains IDE 检查工具”
> [!WARNING]
> 当标准安装位置找不到 JetBrains IDE 时，会出现此错误。
**解决方案：**
- ✅ 验证 `/Applications/` 或 `~/Applications/` 中是否安装了 JetBrains IDE
- ✅ 确保 `inspect.sh` 文件可执行
- ✅ 使用 `FORCE_INSPECT_PATH` 环境变量指定确切路径
### ⚠️ “未找到检查配置文件”
> [!CAUTION]
> 如果没有检查配置文件，该工具无法正确分析您的代码。
**解决方法：**
1. 在 JetBrains IDE 中打开项目
2. 进入 **设置** → **检查**
3. 配置并保存检查配置文件
4. 或者，使用 `FORCE_PROFILE_PATH` 指定自定义配置文件
### ⏱️ 超时问题
> [!TIP]
> 默认超时为 120 秒。大型项目可能需要更多时间。
**解决方案：**
- 🔄 增加超时：设置 `INSPECTION_TIMEOUT=300000`（5 分钟）
- 📊 检查 IDE 是否正在索引
- 📦 对于非常大的项目，考虑检查特定目录
### 🚫 “一次只能运行一个实例”
> [!NOTE]
> ✅ **这不再是问题！** 服务器通过使用隔离配置目录自动处理此问题，允许检查在 IDE 已打开时运行。
## 📚 文档
> [!TIP]
> 🌐 访问我们的综合文档，地址为 [josedacosta.github.io/mcp-jetbrains-code-inspections](https://josedacosta.github.io/mcp-jetbrains-code-inspections/)
**可用章节：**
| 章节 | 描述 |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| 🏁 **[快速入门](https://josedacosta.github.io/mcp-jetbrains-code-inspections/getting-started/)** | 安装和先决条件 |
| ⚙️ **[配置](https://josedacosta.github.io/mcp-jetbrains-code-inspections/configuration/)** | 环境变量和配置文件 |
| 📖 **[使用指南](https://josedacosta.github.io/mcp-jetbrains-code-inspections/usage/)** | 基本和高级用法 |
| 🔬 **[技术细节](https://josedacosta.github.io/mcp-jetbrains-code-inspections/technical/)** | 架构和 IDE 检测 |
| 💡 **[指南](https://josedacosta.github.io/mcp-jetbrains-code-inspections/guides/)** | 最佳实践和故障排除 |
## 📖 JetBrains 文档
> [!TIP]
> 了解更多关于 JetBrains 代码检查和命令行检查工具的信息：
| 资源 | 描述 |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| 📘 **[代码检查概览](https://www.jetbrains.com/help/webstorm/code-inspection.html)** | 了解代码检查、严重性级别和检查配置文件 |
| 🔧 **[命令行代码检查器](https://www.jetbrains.com/help/webstorm/command-line-code-inspector.html)** | 有关使用 inspect.sh/inspect.bat 工具的详细文档 |
## 🤝 贡献
> [!NOTE]
> 我们欢迎贡献！请参阅我们的 [贡献指南](CONTRIBUTING.md) 以获取完整详细信息。
**我们正在寻找：**
- 🐛 错误修复和问题报告
- ✨ 新功能和增强功能
- 📝 文档改进
- 🧪 测试覆盖范围扩展
- 🌍 语言/IDE 支持
### 🚀 贡献者快速入门
> [!IMPORTANT]
> 我们遵循 [Conventional Commits](https://www.conventionalcommits.org/) 并使用 GitHub Flow。
```bash
# 1. 分叉并克隆仓库
git clone https://github.com/YOUR-USERNAME/mcp-jetbrains-code-inspections.git
# 2. 创建功能分支
git checkout -b feat/amazing-feature
# 3. 进行更改并提交
git commit -m 'feat(scope): add amazing feature'
# 4. 推送到您的分叉
git push origin feat/amazing-feature
# 5. 打开拉取请求
```
> [!TIP]
> 查看 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取分支命名、提交消息标准和 PR 指南。
## 🏷️ 关键词
<details>
<summary><b>🔍 SEO 关键词</b>（点击展开）</summary>
**MCP 和 AI 集成：**
`MCP 服务器` • `模型上下文协议` • `Claude Code 集成` • `MCP JetBrains` • `Claude AI 代码检查` • `MCP 工具` • `Claude Code 扩展` • `MCP 检查器` • `Anthropic MCP` • `Claude.ai 代码分析` • `LLM 代码分析` • `AI 代码审查`
**JetBrains IDE：**
`JetBrains 代码检查` • `WebStorm MCP` • `IntelliJ IDEA MCP 集成` • `PyCharm MCP 服务器` • `PhpStorm 代码检查` • `GoLand 分析` • `Rider 代码质量` • `CLion 检查` • `RubyMine 校验` • `DataGrip SQL 分析` • `Android Studio 检查` • `RustRover 分析`
**技术术语：**
`JetBrains 命令行检查器` • `inspect.sh` • `自动化代码检查` • `JetBrains 统一配置文件` • `IDE 代码诊断` • `静态代码分析` • `检查严重性级别` • `检查配置文件` • `Node.js MCP 服务器` • `MCP 环境变量` • `代码问题检测`
</details>
---
<div align="center">
**由 Runtima 团队使用 ❤️ 制作**
[](https://github.com/josedacosta/mcp-jetbrains-code-inspections)
[](https://github.com/josedacosta)
</div>
MCP 市场
