内容
# IdeSense
一款为JetBrains IDE（IntelliJ IDEA、PyCharm、WebStorm、GoLand、PhpStorm、RustRover等）提供MCP（模型上下文协议）服务器的插件，让Claude、Codex、Cursor、Windsurf等AI编程助手无需人工干预即可使用IDE的代码分析引擎——索引、导航和诊断。
**全面测试**：IntelliJ IDEA、PyCharm、WebStorm、GoLand、RustRover、Android Studio、PhpStorm
**可能适用**（未经测试）：RubyMine、CLion、DataGrip
[](https://www.buymeacoffee.com/vcth4nh)
<!-- 插件描述 -->
**IdeSense**是一款适用于JetBrains IDE（IntelliJ IDEA、PyCharm、WebStorm、GoLand、PhpStorm、RustRover等）的MCP服务器，通过[模型上下文协议（MCP）](https://modelcontextprotocol.io)，让AI编程助手使用IDE自己的代码分析引擎——索引、导航、跨引用、诊断，无需人工干预。保留最小的索引支持的重构（重命名、移动文件）。
### 功能
**多语言支持**
高级工具在多个语言上工作，基于可用的插件：
- **Java & Kotlin** - IntelliJ IDEA、Android Studio
- **Python** - PyCharm（所有版本）、带有Python插件的IntelliJ
- **JavaScript & TypeScript** - WebStorm、IntelliJ Ultimate、PhpStorm
- **Go** - GoLand、带有Go插件的IntelliJ IDEA Ultimate
- **PHP** - PhpStorm、带有PHP插件的IntelliJ Ultimate
- **Rust** - RustRover、带有Rust插件的IntelliJ IDEA Ultimate、CLion
- **Markdown** - 文件结构中的标题大纲，适用于带有捆绑Markdown插件的IDE
**通用工具（所有支持的JetBrains IDE）**
- **查找引用** - 在项目中查找任何符号的所有用法
- **转到定义** - 导航到符号声明
- **代码诊断** - 访问错误、警告和快速修复
- **索引状态** - 检查代码智能是否就绪
- **同步文件** - 在外部文件更改后强制同步VFS/PSI缓存
- **查找类** - 按名称快速搜索类/接口（默认为精确搜索；可选启用驼峰/子字符串匹配）
- **查找文件** - 使用IDE的文件索引按名称快速搜索文件
- **符号搜索** - 按名称查找代码符号，匹配IntelliJ的“转到符号”
- **搜索文本** - 使用IDE预建的单词索引进行文本搜索
- **读取文件** - 按路径或限定名称读取文件内容，包括库源（默认禁用）
**扩展工具（语言感知）**
这些工具基于已安装的语言插件激活：
- **类型层次结构** - 探索类继承链
- **调用层次结构** - 跟踪方法/函数调用关系
- **查找实现** - 发现接口/抽象实现
- **查找超方法** - 导航方法重写层次结构
- **文件结构** - 查看分层文件结构，如IDE的“结构”视图，包括Markdown标题大纲
**重构工具**
- **重命名重构** - 安全重命名，自动相关元素重命名（getter/setter，重写方法）- 跨所有语言工作，全头less（默认禁用）
- **移动文件** - 将文件移动到新目录，带有语言感知引用、导入和包/命名空间更新，当IDE提供语义移动后端时（默认禁用）
### 为什么使用这个插件？
与简单的基于文本的代码分析不同，该插件让AI助手访问：
- **真正的语义理解**，通过IDE的AST和索引
- **跨项目引用解析**，在文件和模块之间工作
- **多语言支持** - 自动检测并使用语言特定的处理程序
- **安全重构操作**，带有自动引用更新和撤销支持
适用于AI辅助开发工作流程的地方，准确性和安全性至关重要。
<!-- 插件描述结束 -->
## 文档
- **[USAGE.md](docs/USAGE.md)** — 完整的工具参考（参数、示例、返回形状）
- **[CONTRIBUTING.md](docs/CONTRIBUTING.md)** — 构建、开发循环、测试、PR检查清单
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** — 设计、后台机制模型、内部结构
- **[CHANGELOG.md](CHANGELOG.md)** — 发布说明和版本历史
- **[Agent skill](src/main/resources/skill/idesense/SKILL.md)** — AI代理在工具选择和约定上的运行时指导
- **[Live-test harness](live-test/README.md)** — 快照回归套件，用于验证工具行为与真实IDE
## 目录
- [可用工具](#可用工具)
- [要求](#要求)
- [安装](#安装)
- [快速入门](#快速入门)
- [客户端配置](#客户端配置)
- [多项目支持](#多项目支持)
- [工具窗口](#工具窗口)
- [错误代码](#错误代码)
- [社区集成](#社区集成)
- [贡献](#贡献)
## 可用工具
该插件提供 **19种MCP工具** — 14种默认启用，5种可选（在 <kbd>设置</kbd> > <kbd>工具</kbd> > <kbd>IdeSense</kbd> 中切换任何工具）。下表显示了每种语言的支持和测试状态；有关参数、示例和返回形状，请参见 **[USAGE.md](docs/USAGE.md)**。
**图例：**
- **✅** 支持且已测试
- **⚠️** 应该有效，但未测试
- **⛔** 不支持
**导航与搜索**
| 工具 | Java | Kotlin | Python | JS | TS | Go | PHP | Rust |
|------|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
| `ide_find_usages` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_find_definition` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_find_class` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_find_symbol` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_find_file` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_search_text` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
**层次结构与结构**
| 工具 | Java | Kotlin | Python | JS | TS | Go | PHP | Rust |
|------|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
| `ide_type_hierarchy` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_call_hierarchy` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_find_implementations` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_find_super_methods` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_file_structure` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
**分析**
| 工具 | Java | Kotlin | Python | JS | TS | Go | PHP | Rust |
|------|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
| `ide_diagnostics` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_explain_symbol` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
**重构**
| 工具 | Java | Kotlin | Python | JS | TS | Go | PHP | Rust |
|------|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
| `ide_refactor_rename` | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ |
| `ide_move_file` | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ |
**项目** — 语言无关（操作项目/IDE，而非特定语言代码）
| 工具 | Java | Kotlin | Python | JS | TS | Go | PHP | Rust |
|------|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
| `ide_index_status` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_install_plugin` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_restart` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_sync_files` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `ide_read_file` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
> **注意：**
> - 重构工具（`ide_refactor_rename`、`ide_move_file`）受支持但未在此处进行实时测试（⚠️）。
> - `ide_search_text`依赖于IDE的单词索引，因此语言关键字（例如Kotlin的`fun`）可能不会被匹配，即使标识符和大多数单词都被匹配。
## 要求
- **JetBrains IDE** 2025.3或更高版本（任何基于IntelliJ平台的IDE）
- **JVM** 21或更高版本
- **MCP协议** 2025-11-25（主要流式HTTP，协商；也支持2025-03-26 / 2024-11-05）
### 支持的IDE
**全面测试：**
- IntelliJ IDEA（社区/终极版）
- Android Studio
- PyCharm（社区/专业版）
- WebStorm
- GoLand
- RustRover
- PhpStorm
**可能适用（未经测试）：**
- RubyMine
- CLion
- DataGrip
> 插件使用标准的IntelliJ平台API，应该可以在任何基于IntelliJ的IDE上运行，但仅在上述IDE上进行了测试。
## 安装
> **注意：** IdeSense尚未在JetBrains市场上线 — 目前，请使用下面的[手动安装](#手动安装)。
### 使用IDE内置插件系统
<kbd>设置/首选项</kbd> > <kbd>插件</kbd> > <kbd>市场</kbd> > <kbd>搜索“IdeSense”</kbd> > <kbd>安装</kbd>
### 使用JetBrains市场
前往 [JetBrains市场](https://plugins.jetbrains.com/) 并通过点击 <kbd>安装到...</kbd> 按钮进行安装。
### 手动安装
下载 [最新版本](https://github.com/vcth4nh/idesense/releases) 并手动安装：
<kbd>设置/首选项</kbd> > <kbd>插件</kbd> > <kbd>⚙️</kbd> > <kbd>从磁盘安装插件...</kbd>
## 快速入门
1. **安装插件** 并重启您的JetBrains IDE
2. **打开项目** - MCP服务器自动启动，IDE特定默认值：
- IntelliJ IDEA：`intellij-idesense`，端口 **29170**
- PyCharm：`pycharm-idesense`，端口 **29172**
- WebStorm：`webstorm-idesense`，端口 **29173**
- 其他IDE：参见 [IDE特定默认值](#ide特定默认值)
3. **配置AI助手**，使用“安装到编码代理”按钮（最简单）或手动配置
4. **使用工具窗口** （底部面板：“IdeSense”）复制配置或监视命令
5. **更改端口** （可选）：在工具栏中单击“更改端口，禁用工具”，或前往 <kbd>设置</kbd> > <kbd>工具</kbd> > <kbd>IdeSense</kbd>
### 使用“安装到编码代理”按钮
配置AI助手的简单方法：
1. 打开“IdeSense”工具窗口（底部面板）
2. 点击工具栏右侧显眼的 **“安装到编码代理”** 按钮
3. 出现一个弹出窗口，包含两个部分：
- **立即安装** - 对于Claude Code CLI和Codex CLI：自动运行安装命令
- **复制配置** - 对于其他客户端：复制JSON配置到剪贴板
4. 对于“复制配置”客户端，将配置粘贴到适当的配置文件中
## 客户端配置
### Claude Code（CLI）
使用工具窗口中的“安装到编码代理”按钮，或运行以下命令（调整名称和端口以适应您的IDE）：
```bash
# IntelliJ IDEA
claude mcp add --transport http intellij-idesense http://127.0.0.1:29170/mcp/streamable-http --scope user
# PyCharm
claude mcp add --transport http pycharm-idesense http://127.0.0.1:29172/mcp/streamable-http --scope user
# WebStorm
claude mcp add --transport http webstorm-idesense http://127.0.0.1:29173/mcp/streamable-http --scope user
```
选项：
- `--scope user` - 为所有项目全局添加
- `--scope project` - 仅添加到当前项目
要删除：`claude mcp remove <server-name>`（例如，`claude mcp remove intellij-idesense`）
### Codex CLI
使用工具窗口中的“安装到编码代理”按钮，或运行以下命令（调整名称和端口以适应您的IDE）：
```bash
# IntelliJ IDEA
codex mcp add intellij-idesense --url http://127.0.0.1:29170/mcp/streamable-http
# PyCharm
codex mcp add pycharm-idesense --url http://127.0.0.1:29172/mcp/streamable-http
# WebStorm
codex mcp add webstorm-idesense --url http://127.0.0.1:29173/mcp/streamable-http
```
要删除：`codex mcp remove <server-name>`（例如，`codex mcp remove intellij-idesense`）
### Cursor
在项目根目录或 `~/.cursor/mcp.json` 中全局添加以下内容（调整名称和端口以适应您的IDE）：
```json
{
"mcpServers": {
"intellij-idesense": {
"url": "http://127.0.0.1:29170/mcp/streamable-http"
}
}
}
```
### Windsurf
在 `~/.codeium/windsurf/mcp_config.json` 中添加以下内容（调整名称和端口以适应您的IDE）：
```json
{
"mcpServers": {
"intellij-idesense": {
"serverUrl": "http://127.0.0.1:29170/mcp/streamable-http"
}
}
}
```
### VS Code（通用MCP）
```json
{
"mcp.servers": {
"intellij-idesense": {
"url": "http://127.0.0.1:29170/mcp/streamable-http"
}
}
}
```
> **注意**：将服务器名称和端口替换为您的IDE默认值。参见 [IDE特定默认值](#ide特定默认值)。
### IDE特定默认值
每个JetBrains IDE都有唯一的默认端口和服务器名称，允许多个IDE同时运行而不会冲突：
| IDE | 服务器名称 | 默认端口 |
|-----|-------------|--------------|
| IntelliJ IDEA | `intellij-idesense` | 29170 |
| Android Studio | `android-studio-idesense` | 29171 |
| PyCharm | `pycharm-idesense` | 29172 |
| WebStorm | `webstorm-idesense` | 29173 |
| GoLand | `goland-idesense` | 29174 |
| PhpStorm | `phpstorm-idesense` | 29175 |
| RubyMine | `rubymine-idesense` | 29176 |
| CLion | `clion-idesense` | 29177 |
| RustRover | `rustrover-idesense` | 29178 |
| DataGrip | `datagrip-idesense` | 29179 |
> **提示**：在工具窗口中使用“安装到编码代理”按钮，它会自动使用适用于您IDE的正确服务器名称和端口。
>
> **注意**：完整的IDE端口列表（包括Aqua、DataSpell和Rider）已在 [ARCHITECTURE.md](docs/ARCHITECTURE.md#ide-specific-defaults) 中记录。Rider当前在插件清单中标记为不兼容，不受支持。
## 多项目支持
当在单个IDE窗口中打开多个项目时，您必须使用 `project_path` 参数指定要使用的项目：
```json
{
"name": "ide_find_usages",
"arguments": {
"project_path": "/Users/dev/myproject",
"file": "src/Main.kt",
"line": 10,
"column": 5
}
}
```
如果省略 `project_path`：
- **单个项目打开**：该项目自动使用
- **多个项目打开**：返回错误，附带可用项目列表
### 工作区项目
插件支持 **工作区项目**，其中单个IDE窗口包含多个子项目作为具有独立内容根的模块。`project_path` 参数接受：
- **工作区根路径**
- **子项目路径**（模块内容根）
- **任意打开项目的子目录**
当发生错误时，响应返回 `available_projects`。默认情况下，这包括工作区子项目，以便AI代理可以发现有效的模块内容根。如果您希望错误负载较小，请在插件设置中将 **错误响应中的项目列表** 切换为 **紧凑**，以仅返回顶级项目根。
## 工具窗口
插件添加了一个“IdeSense”工具窗口（底部面板），显示：
- **服务器状态**：运行指示器，带有服务器URL和端口
- **项目名称**：当前活动项目
- **命令历史记录**：所有MCP工具调用的日志，包含：
- 时间戳
- 工具名称
- 状态（成功/错误/待处理）
- 参数和结果（可展开）
- 执行持续时间
### 工具窗口操作
| 操作 | 描述 |
|--------|-------------|
| 刷新 | 刷新服务器状态和命令历史记录 |
| 复制网址 | 将MCP服务器网址复制到剪贴板 |
| 清除历史记录 | 清除命令历史记录 |
| 导出历史记录 | 将历史记录导出到JSON或CSV文件 |
| **安装到编码代理** | 在AI助手上安装MCP服务器（工具栏上的显眼按钮） |
## 错误代码
### JSON-RPC标准错误
| 代码 | 名称 | 描述 |
|------|------|-------------|
| -32700 | 解析错误 | 无法解析JSON-RPC请求 |
| -32600 | 无效请求 | 无效的JSON-RPC请求格式 |
| -32601 | 方法未找到 | 未知方法名称 |
| -32602 | 无效参数 | 无效或缺失参数 |
| -32603 | 内部错误 | 意外的内部错误 |
### 工具错误（已解析的工具失败）
预调度失败（解析错误、未知方法、缺失参数）使用JSON-RPC数字错误对象。一旦调度工具并失败，它就会返回一个 **正常MCP结果**，带有 `isError: true` 和结构化有效载荷：
```json
{
"error": "<snake_case_code>",
"message": "<human-readable description>"
}
```
常见 `error` 代码：
| 代码 | 何时发生 |
|------|----------------|
| `index_not_ready` | IDE处于空闲模式（索引中） |
| `file_not_found` | 指定文件不存在 |
| `symbol_not_found` | 未找到指定位置的符号 |
| `refactoring_conflict` | 无法完成重构（例如，名称冲突） |
| `invalid_arguments` | 参数验证失败（包含 `violations` 数组） |
| `tool_error` | 常规工具失败 |
| `internal_error` | 意外的服务器错误 |
| `no_project_open` / `project_not_found` / `multiple_projects_open` | 项目解析错误 |
## 设置
在 <kbd>设置</kbd> > <kbd>工具</kbd> > <kbd>IdeSense</kbd> 配置插件：
| 设置 | 默认值 | 描述 |
|---------|---------|-------------|
| 服务器端口 | IDE特定 | MCP服务器端口（范围：1024-65535，变更时自动重启）。参见 [IDE特定默认值](#ide特定默认值) |
| 服务器主机 | `127.0.0.1` | 监听主机。非环回主机（例如 `0.0.0.0` 用于远程/WSL访问）还要求 **允许非环回绑定** — 参见下文 |
| 允许非环回绑定 | false | 承认绑定非环回主机暴露每个启用的工具 — 包括对项目的完全读取访问 — 给任何可以访问该端口的机器，**没有身份验证**。如果不启用，非环回主机将回退到 `127.0.0.1`，服务器继续运行 |
| 最大历史记录大小 | 100 | 历史记录中要保留的最大命令数 |
| 错误响应中的项目列表 | 展开 | 控制 `available_projects` 在无效/缺失 `project_path` 错误时的详细信息。`展开` 包括工作区子项目；`紧凑` 仅返回顶级项目根 |
| 同步外部更改 | false | 在操作前同步外部文件更改（**警告：显著的性能影响**） |
| 禁用工具 | 5个工具 | 每个工具的启用/禁用切换。修改代码或IDE的工具 — 加上 `ide_read_file` — 默认禁用 |
| 响应格式 | `JSON` | 工具结果文本块的格式：`JSON`（默认）镜像结构化JSON；`TOON` 将其转换为适用于旧客户端的紧凑文本对象表示法 |
## 社区集成
- [opencode-jetbrains-index](https://github.com/ineersa/opencode-jetbrains-index) - 使用此插件的第三方OpenCode集成
> **免责声明**：此仓库不由我维护。请为集成特定的问题和支持使用其自己的问题跟踪器。
## 贡献
欢迎贡献！参见 [CONTRIBUTING.md](docs/CONTRIBUTING.md) 获取构建说明、开发循环、测试指南和PR检查清单。
## 许可
该项目在MIT许可下许可 — 参见 [LICENSE](LICENSE) 文件获取详细信息。
## 致谢
IdeSense起源于Carmel Hecht的[jetbrains-index-mcp-plugin](https://github.com/hechtcarmel/jetbrains-index-mcp-plugin)的一个分支，并基于[IntelliJ平台插件模板](https://github.com/JetBrains/intellij-platform-plugin-template)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器