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 安装信息保存在：

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 固定端口：

& "<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：

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

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

& "<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：

codex mcp list
codex mcp remove <legacy-name>

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

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

-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 的成功外推为所有产品都已实测。