# Jetbrains Workspace Setup

> Configure Codex, opencode, or Claude Code workspaces to load exactly one JetBrains IDE MCP, read or initialize the IDE's fixed MCP port, maintain reusable machine-local IDE profiles, and start the selected IDE before MCP connection. Use when registering JetBrains installations and fixed ports, reusing an IDE profile in another project, removing duplicate global JetBrains tool schemas, or diagnosing why the correct JetBrains tools are unavailable at task startup.

- Skill: `narylr350/jetbrains-workspace-setup` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add narylr350/jetbrains-workspace-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/narylr350/jetbrains-workspace-setup/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Narylr350 (https://skillmd.com/u/narylr350)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/narylr350/jetbrains-workspace-setup

---


# JetBrains Workspace Setup

## 定位

为一个工作区注册一套 JetBrains IDE MCP。项目类型不决定 IDE；使用用户明确选择的 IDE、可执行文件和固定端口。

目标是让每个任务只加载一个统一名称 `jetbrains`，避免同时加载多套重复工具 schema。支持 Codex（`.codex/config.toml`）、opencode（`.opencode/opencode.json`）和 Claude Code（`~/.claude.json` local scope）三种 agent。

## 关键边界

- 支持任意 JetBrains IDE 或兼容产品，不把 Rider、IDEA、PyCharm 等少数产品写成固定枚举。
- 不根据语言、框架或文件扩展名替用户决定 IDE。
- IDE MCP 端口必须在 IDE 设置中固定，并且不同运行中的 IDE 实例不能占用同一端口。
- 当前任务不能热切换整套 MCP。修改配置后新建或重启对应工作区任务。
- `SessionStart` Hook 晚于 MCP 初始化，不能为当前任务动态增加工具或补救未连接的 IDE。启动 IDE 必须发生在 MCP 启动命令中。
- Codex：项目级 `.codex/config.toml` 是本机执行配置，默认加入 `.git/info/exclude`，不修改项目的 tracked `.gitignore`。
- opencode：项目级 `.opencode/opencode.json` 同理，默认加入 `.git/info/exclude`。
- Claude：写用户级活动状态文件 `~/.claude.json`（`projects["<path>"].mcpServers`），不产生项目内文件，无需 exclude。脚本整体读改写这个文件，注册前先关闭对应项目的 Claude Code 会话，避免与 Claude 自身回写互相覆盖。

## 本机 IDE Profiles

可复用的 IDE 安装信息保存在：

```text
codex:    $CODEX_HOME/jetbrains-ide-profiles.json
opencode: ~/.config/opencode/jetbrains-ide-profiles.json
claude:   ~/.claude/jetbrains-ide-profiles.json
```

它是本机目录，不进入 skill 仓库或用户项目。每个 profile 记录 IDE 名称、可执行文件、JetBrains 用户配置目录和固定端口；profile id 只是本机别名，不代表 skill 支持范围的固定枚举。

注册或更新一个 profile，并初始化 IDE 固定端口：

```powershell
& "<skill-directory>\scripts\Register-JetBrainsIdeProfile.ps1" `
  -ProfileId "<local-id>" `
  -IdeName "<display-name>" `
  -ExecutablePath "<ide-executable>" `
  -Port <port> `
  -Agent <codex|opencode|claude>
```

注册脚本通过 IDE 安装目录中的 `product-info.json` 定位 `<JetBrains-config>/options/mcpServer.xml`。IDE 已经保存固定端口时应省略 `-Port`，脚本会读取该值。传 `-Port` 只用于尚未保存固定端口的首次初始化；发现已有不同端口时必须停止，不能静默覆盖。确实要改端口时，关闭对应 IDE，并显式增加 `-UpdateExistingPort`。使用自定义配置目录时传 `-IdeConfigPath <directory>`。如果设置文件不存在、MCP Server 未启用或只有默认/动态端口而没有保存 `mcpServerPort`，读取模式必须停止并要求初始化，不能把 profile 中的旧值当成 IDE 当前值。

同一个固定端口不能分配给两个不同 profile。IDE 版本、安装路径、用户配置目录或端口变化后先更新 profile，再重新注册受影响的工作区；脚本不会暗中批量改写已有项目配置。

## 注册工作区

注册时先确认项目绝对路径、IDE 实际打开的目标和要使用的本机 profile。没有可复用 profile 时，再确认 IDE 名称、可执行文件绝对路径和固定 MCP 端口，并优先用 profile 注册脚本同步 IDE 自身设置。

`-Agent` 参数决定配置格式和位置：
- `codex`（默认）：写 `<project>/.codex/config.toml`（TOML）
- `opencode`：写 `<project>/.opencode/opencode.json`（JSON）
- `claude`：写入 `~/.claude.json` 的 `projects["<path>"].mcpServers`（local scope）

优先复用本机 profile：

```powershell
& "<skill-directory>\scripts\Register-JetBrainsWorkspace.ps1" `
  -ProjectPath "<project-root>" `
  -OpenPath "<directory-or-project-entry>" `
  -IdeProfile "<local-id>" `
  -Agent <codex|opencode|claude>
```

一次性或尚未登记的 IDE 也可以直接传值，但这种直接模式不读写 IDE 设置，调用方必须已确认传入端口与 IDE 一致：

```powershell
& "<skill-directory>\scripts\Register-JetBrainsWorkspace.ps1" `
  -ProjectPath "<project-root>" `
  -OpenPath "<directory-or-project-entry>" `
  -IdeName "<display-name>" `
  -ExecutablePath "<ide-executable>" `
  -Port <port> `
  -Agent <codex|opencode|claude>
```

脚本会：

- 通过 profile 或直接参数解析 IDE 名称、可执行文件和端口；
- 把通用桥接脚本复制到 `<agent-home>/bin/jetbrains-mcp-bridge.ps1`；
- 在项目目录写入受管理的 MCP 配置（Codex: `.codex/config.toml`，opencode: `.opencode/opencode.json`）；
- 使用 stdio 启动命令先检查端口，必要时用 `OpenPath` 打开 IDE；
- 端口就绪后通过脚本中固定版本的 `mcp-remote` 桥接 IDE 的 `http://127.0.0.1:<port>/stream`；
- 对 Git 仓库把对应配置目录加入 `.git/info/exclude`。

`OpenPath` 省略时默认为 `ProjectPath`。如果 IDE 打开目录会出现解决方案或项目选择框，应显式注册能直接打开的入口文件；不要在脚本中按产品名硬编码猜测。

已有项目配置时只新增或替换 jetbrains MCP 条目，不覆盖其他配置。Codex 用受标记块管理；opencode 用 JSON key 级合并。若文件已在受标记块外定义 `mcp_servers.jetbrains`（Codex）或 `mcp.jetbrains`（opencode），脚本会停止；先人工审查并解决冲突。

## 迁移全局配置

只有在目标工作区都已注册后，才删除用户级重复 JetBrains MCP。

Codex：

```powershell
codex mcp list
codex mcp remove <legacy-name>
```

opencode：手动编辑全局 `~/.config/opencode/opencode.json`，删除 `mcp.intellij` / `mcp.pycharm` 等重复 JetBrains 条目。

也可以在注册最后一个工作区时显式传入（仅 Codex）：

```powershell
-RemoveGlobalMcpName <name1>,<name2>
```

不要删除非 JetBrains MCP，也不要把当前机器上的 server 名称写成 skill 默认值。

## 验证

1. Codex / opencode：`git status --short` 不应出现 `.codex/` 或 `.opencode/`。Claude：配置写入 `~/.claude.json`，不产生项目内文件，无需此检查。
2. 读取 profile 的 `ideConfigPath/options/mcpServer.xml`，确认 `enableMcpServer=true` 且 `mcpServerPort` 与 profile 一致。
3. 读取项目配置，确认只有一个 jetbrains MCP 条目：
   - Codex：读 `<project>/.codex/config.toml`，确认受管理块内只有一个 `[mcp_servers.jetbrains]`。
   - opencode：读 `<project>/.opencode/opencode.json`，确认 `mcp.jetbrains` 存在且只有一条。
   - Claude：读 `~/.claude.json`，确认 `projects["<path>"].mcpServers.jetbrains` 存在且只有一条。
4. 检查用户级重复 JetBrains MCP：Codex 用 `codex mcp list`；opencode 检查全局 `~/.config/opencode/opencode.json`；Claude 检查 `~/.claude.json` 顶层 `mcpServers` 无重复 JetBrains 条目。
5. 关闭对应 IDE 后新建该工作区任务，确认 IDE 被启动且只出现一套 `mcp__jetbrains__*` 工具。
6. 第一次实际调用 IDE MCP 时，始终显式传入同一绝对 `projectPath`，并核对 IDE 返回的打开项目。

验证只覆盖实际注册和启动过的工作区，不把一个 IDE 的成功外推为所有产品都已实测。