opencode-idea 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.0.3
+
+- **直接暴露 IDEA MCP 工具**:注册 MCP 服务器时设置 `codemode: false`,让 `idea_*` 工具直接出现在原生工具表(而非 Code Mode 的 `tools.idea.*`)。模型可以直接调用并看到完整参数 schema,不再需要先探索、也不会猜错参数名。
+- **引导补充**:明确要求「直接调用工具,不要用 `execute` 包裹」。
+
+## 0.0.2
+
+- **路由引导重写**:system prompt 明确写出项目绝对路径,并要求路径内的检索 / 读文件 / 目录浏览 / 改文件 / 新建文件 / 校验都使用 `idea_*` 工具,逐条点名禁止对应的原生工具(`grep` / `glob` / `read` / `edit` / `write` / `ls` / `find`)。
+- **不再修改任何工具描述**:移除对 IDEA MCP 工具描述的前缀改写(`src/idea-tool-descriptions.js` 已删除),插件不再调用 `ctx.tool.transform`;IDEA 工具与原生工具的描述均保持原样。
+- **引导文案精简**:删除解释性内容和宽泛的「例外」条款,只保留要求与项目内 / 外边界。
+- **移除无用文件**:删除 `skills/`(setup skill)与 `UPGRADING.md`。
+- **安装文档更新**:README 的安装与配置示例改为 V2 的 `plugins` 对象写法。
+
 ## 0.0.1
 
 首个版本（包名 `opencode-idea`，从 `opencode-jetbrains-mcp` 重命名而来）。
@@ -28,5 +41,6 @@
 
 - **纯手动**:启动不探测、不连接 IDE MCP;IDE MCP 注册、环境重读、引导注入全部由 `/open-in-idea` 触发。
 - **根级 `index.js` 转发入口**:使仓库可作为 V2 本地目录插件直接加载(`plugins: [{ "package": "<repo>" }]`)。
+- **发布脚本** (`scripts/release.mjs`):`npm run release` 自动递增 patch、同步版本文件、跑测试并发布。
 - **配置项**:`ports` / `injectEnv` / `injectGuidance` / `openInIde` / `launchCooldownMs` / `launchMaxAttempts` / `mcpProbeTimeoutMs` / `feedback`。
 - 仅支持 **OpenCode V2**;非 JetBrains 项目完全不受影响。

package/README.md

@@ -3,7 +3,7 @@
 OpenCode 插件,面向 JetBrains 项目(IntelliJ IDEA / PyCharm / WebStorm 等),做三件事:
 
 1. **接入 IDE MCP** —— 用 `/open-in-idea` 把当前项目在 IntelliJ IDEA 中打开,并把这个 IDE 的 MCP 服务(60 个工具:检索、读、改、构建、重构、调试、数据库……)注册进 OpenCode。
-2. **优先使用 IDE 工具** —— IDE 可用时,向模型注入"项目内操作默认走 IDE MCP"的系统提示引导 + 能力映射;IDE 不可用时回退原生工具(正常回退,无需声明)。
+2. **优先使用 IDE 工具** —— IDE 可用时,向模型注入"项目内操作优先使用 IDEA MCP"的系统提示引导 + 能力映射;IDE 不可用时回退原生工具(正常回退,无需声明)。
 3. **注入 IDE 环境变量** —— 从 IDE 集成终端读取它实际运行的环境(版本化管理的 Node、goenv 的 Go、SDKMAN 的 Java、Maven……)注入每个 OpenCode shell。
 
 非 JetBrains 项目完全不受影响。**全部手动**:插件启动不探测、不连接 IDE,只有跑 `/open-in-idea` 时才连接。
@@ -95,12 +95,26 @@ IDE MCP 可用时,插件通过两层轻量引导提高模型主动使用 IDEA MC
 
 ## 安装
 
-```json
+推荐用 CLI 安装,它会写入全局配置 `~/.config/opencode/opencode.json`:
+
+```bash
+opencode plugin add opencode-idea
+```
+
+等价的配置写法(V2 使用 `plugins` 数组):
+
+```jsonc
 {
-  "plugin": ["opencode-idea"]
+  "plugins": ["opencode-idea"],
 }
 ```
 
+安装后确认:
+
+```bash
+opencode plugin list
+```
+
 > 仅支持 **OpenCode V2**。若你日常跑的是 1.x 的 `opencode-ai`,它用的是旧插件 API,本插件不会生效;真机验证请用 V2 运行时。
 
 ### 本地开发 / 真机验证
@@ -115,14 +129,6 @@ IDE MCP 可用时,插件通过两层轻量引导提高模型主动使用 IDEA MC
 }
 ```
 
-也可以沿用旧键 `plugin` 的元组写法:
-
-```jsonc
-{
-  "plugin": [["/Users/yutao/Projects/opencode-idea", {}]],
-}
-```
-
 配置保存后 V2 会监听并自动重载(日志里能看到它开始 watch `index.js` / `src/*.js`),无需重启。改插件源码也会触发重载(此时需重跑 `/open-in-idea`)。
 
 另一种零配置方式:在 `~/.config/opencode/plugins/` 放一个转发文件(自动发现,但不能传 options):
@@ -134,31 +140,35 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
 
 ## 配置
 
+用 CLI 安装只会写入包名。要传 options,把 `plugins` 数组里的字符串改成对象:
+
 ```jsonc
 {
-  "plugin": [
-    [
-      "opencode-idea",
-      {
+  "plugins": [
+    {
+      "package": "opencode-idea",
+      "options": {
         "ports": [64342, 6420, 6421, 63342],
         "injectEnv": true,
-        "injectGuidance": true, // IDE 可用时向系统提示注入「默认走 IDE MCP」引导
+        "injectGuidance": true, // IDE 可用时向系统提示注入「优先使用 IDEA MCP」引导
         "openInIde": "idea", // false 关闭;或任意 macOS 应用名(如 "IntelliJ IDEA")
         "launchCooldownMs": 120000, // 启动保护冷却
         "launchMaxAttempts": 5,
         "mcpProbeTimeoutMs": 1000, // 单个 MCP 端口的短探测超时
         "feedback": "message", // "message"(默认,会话通知,AI 只回"收到")| false(静默)
       },
-    ],
+    },
   ],
 }
 ```
 
+不传 options 时全部使用下表默认值。
+
 | 选项                | 类型                 | 默认                         | 说明                                                             |
 | ------------------- | -------------------- | ---------------------------- | ---------------------------------------------------------------- |
 | `ports`             | `number[]`           | `[64342, 6420, 6421, 63342]` | 依次探测的 IDE MCP 端口                                          |
 | `injectEnv`         | `boolean`            | `true`                       | 是否注入 IDE 终端环境变量                                        |
-| `injectGuidance`    | `boolean`            | `true`                       | IDE 可用时是否向系统提示注入「默认走 IDE MCP」引导               |
+| `injectGuidance`    | `boolean`            | `true`                       | IDE 可用时是否向系统提示注入「优先使用 IDEA MCP」引导            |
 | `openInIde`         | `boolean \| string`  | `"idea"`                     | 拉起哪个 IDE;`false` 关闭,`"idea"` 映射到 IntelliJ IDEA          |
 | `launchCooldownMs`  | `number`             | `120000`                     | 启动保护冷却:冷却期内不重复 spawn                                |
 | `launchMaxAttempts` | `number`             | `5`                          | 单次会话内最多 spawn 次数,超出后停止重试                         |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-idea",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "OpenCode plugin that connects to JetBrains IDE MCP servers and prefers IDE tools when the current project is open in the IDE",
   "main": "src/index.js",
   "type": "module",
@@ -15,13 +15,15 @@
     "src/ide-launcher.js",
     "src/ide-guidance.js",
     "src/idea-tool-descriptions.js",
-    "skills",
     "README.md",
-    "CHANGELOG.md",
-    "UPGRADING.md"
+    "CHANGELOG.md"
   ],
   "scripts": {
     "test": "vitest run",
+    "release": "node scripts/release.mjs",
+    "release:dry": "node scripts/release.mjs --dry-run",
+    "release:bump": "node scripts/release.mjs --bump",
+    "release:check": "node scripts/release.mjs --check",
     "prepublishOnly": "npm test"
   },
   "keywords": [

package/src/ide-guidance.js

@@ -1,31 +1,41 @@
-// Direct IDEA MCP usage guidance injected into the model's system prompt.
-// The plugin does not modify native OpenCode tools.
+// IDEA MCP routing guidance injected into the model's system prompt.
+//
+// Two rules for this file:
+//   1. State requirements only. No explanations, no asides.
+//   2. The boundary is the project path. Inside it -> idea_* tools.
+//      Outside it -> whatever else is available.
+//
+// The IDE MCP server is registered with `codemode: false`, so every idea_*
+// tool is exposed directly on the provider tool list with its full schema.
+// Parameter names therefore come from the tool definitions; this text only
+// states which tool to use for which operation.
 
-/** The guidance text appended to the system prompt. */
-export const IDE_GUIDANCE = [
-  '## 项目内操作优先使用 IDEA MCP 工具',
-  '当前项目已在 JetBrains IDE 中打开。普通工具调用名称是 `idea_<name>`,例如 `idea_search_text`、`idea_read_file`、`idea_apply_patch`;项目内检索、读文件、改文件、校验和目录浏览优先直接调用这些 IDEA MCP 工具。',
-  '直接调用工具本身,不要为了调用 IDEA MCP 工具再包一层额外的 JavaScript 编排代码。',
-  '',
-  '常用工具与关键参数:',
-  '- 文本 / 正则 / 文件名检索:`idea_search_text` / `idea_search_regex` / `idea_search_file` —— 参数 `q`(不是 `query`),可带 `paths` 收窄。',
-  '- 符号 / 语义:`idea_search_symbol` / `idea_get_symbol_info` / `idea_analyze_calls`(只用 `depth=1`)。',
-  '- 读文件:`idea_read_file`(`file_path` / `offset` / `limit`)。',
-  '- 目录浏览:`idea_list_directory_tree`(代替 `ls` / `find`,`maxDepth` ≥ 2)。',
-  '- 修改已有文件:`idea_apply_patch`(参数 `input`,传 patch 文本)。',
-  '- 新建文件:`idea_create_new_file`(参数 `pathInProject`,可选 `text` / `overwrite`)。',
-  '- 校验:`idea_lint_files` / `idea_get_file_problems` / `idea_build_project`。',
-  '- 重构 / 格式化:`idea_rename_refactoring` / `idea_reformat_file`。',
-  '- 结构 / 依赖:`idea_get_project_modules` / `idea_get_project_dependencies`。',
-  '- 版本状态:`idea_git_status`;终端命令:`idea_execute_terminal_command`。',
-  '',
-  '调用纪律:',
-  '- 直接调用当前工具 schema 中声明的参数,不要猜参数名;工具自身的 description 是参数使用的权威来源。',
-  '- 工具返回 `File already exists` 等业务错误时,先修正调用参数,不要判断成工具不存在。',
-  '- 如果 IDEA MCP 未连接、工具缺失、连接被拒绝或超时,立即提示用户执行 `/open-in-idea`,不要反复探测或长时间等待。',
-  '',
-  '例外(直接使用原生工具):`node_modules/`、`target/` 等 IDE 不索引的目录;`git diff` / `log` / `blame` 等 git 独有语义;`lsof` / `nc` / `ping` 等 MCP 无等价能力;IDE MCP 未连接 / 未注册;项目根之外的文件。',
-].join('\n');
+/** Build the guidance text for one project path. */
+export function buildIdeGuidance(projectPath) {
+  return [
+    `# 项目内操作必须使用 IDEA MCP 工具`,
+    ``,
+    `项目路径: \`${projectPath}\``,
+    ``,
+    `## 强制要求`,
+    `- 路径在 \`${projectPath}\` 内的所有操作,必须使用 \`idea_*\` 工具。`,
+    `- 直接调用工具,不要用 \`execute\` 包裹。`,
+    `- 检索内容用 \`idea_search_text\` / \`idea_search_regex\`,不要用 \`grep\`。`,
+    `- 查找文件名用 \`idea_search_file\`,不要用 \`glob\`。`,
+    `- 读文件用 \`idea_read_file\`,不要用 \`read\`。`,
+    `- 浏览目录用 \`idea_list_directory_tree\`,不要用 \`ls\` / \`find\`。`,
+    `- 修改已有文件用 \`idea_apply_patch\`,不要用 \`edit\` / \`patch\`。`,
+    `- 新建文件用 \`idea_create_new_file\`,不要用 \`write\`。`,
+    `- 改完代码用 \`idea_lint_files\` 或 \`idea_get_file_problems\` 校验。`,
+    `- 看 git 状态用 \`idea_git_status\`。`,
+    `- 工具参数按该工具的 schema 传。`,
+    ``,
+    `## 范围`,
+    `- \`${projectPath}\` 内:只用 \`idea_*\` 工具。`,
+    `- \`${projectPath}\` 外:用其他可用工具。`,
+    `- \`idea_*\` 工具缺失、连接失败或超时:提示用户执行 \`/open-in-idea\`,不要重试。`,
+  ].join('\n');
+}
 
 export const MCP_RECOVERY_GUIDANCE = [
   '### IDEA MCP failure recovery',
@@ -37,11 +47,14 @@ export const MCP_RECOVERY_GUIDANCE = [
  * model request, so it stays idempotent per request.
  *
  * @param {unknown} system
+ * @param {string} projectPath
  */
-export function appendIdeGuidance(system) {
+export function appendIdeGuidance(system, projectPath) {
   if (!Array.isArray(system)) return;
-  if (system.some((part) => part?.text === IDE_GUIDANCE)) return;
-  system.push({ type: 'text', text: IDE_GUIDANCE });
+  if (!projectPath) return;
+  const text = buildIdeGuidance(projectPath);
+  if (system.some((part) => part?.text === text)) return;
+  system.push({ type: 'text', text });
 }
 
 /** @param {unknown} system */

package/src/idea-mcp.js

@@ -37,6 +37,11 @@ const CALL_TIMEOUT_MS = 15000;
 /**
  * Build the OpenCode MCP server config for a given IDE port + project.
  *
+ * `codemode: false` exposes the IDE tools directly on the provider tool list
+ * (as `idea_<tool>`) instead of routing them through Code Mode. Direct exposure
+ * passes each tool's full schema to the model, so parameter names are known
+ * without exploration. The rest of an MCP server's options are unchanged.
+ *
  * @param {number} port
  * @param {string} projectPath
  */
@@ -45,6 +50,7 @@ export function serverConfig(port, projectPath) {
     type: 'remote',
     url: `http://127.0.0.1:${port}${MCP_STREAM_PATH}`,
     headers: { [PROJECT_HEADER]: projectPath },
+    codemode: false,
   };
 }
 
@@ -75,7 +81,7 @@ export async function probePort(port, options = {}) {
         params: {
           protocolVersion: PROTOCOL_VERSION,
           capabilities: {},
-          clientInfo: { name: 'opencode-idea', version: '0.0.1' },
+          clientInfo: { name: 'opencode-idea', version: '0.0.3' },
         },
       }),
       signal: controller.signal,
@@ -145,7 +151,7 @@ export async function callTool(port, projectPath, name, args = {}, options = {})
       params: {
         protocolVersion: PROTOCOL_VERSION,
         capabilities: {},
-        clientInfo: { name: 'opencode-idea', version: '0.0.1' },
+        clientInfo: { name: 'opencode-idea', version: '0.0.3' },
       },
     });
     const response = await post({

package/src/plugin.js

@@ -28,7 +28,6 @@ import {
 import { readIdeTerminalEnv } from './ide-env.js';
 import { currentProjectPath, hasIdeaDirectory } from './project.js';
 import { applyEnv, mergeEnv } from './env.js';
-import { applyIdeaToolGuidance } from './idea-tool-descriptions.js';
 import {
   createLaunchGuard,
   openInIde,
@@ -187,13 +186,10 @@ export default {
     };
 
     const activateIde = async (port) => {
-      const toolRegistration = await ctx.tool.transform((editor) => {
-        applyIdeaToolGuidance(editor);
-      });
       const mcpRegistration = await ctx.mcp.transform((editor) => {
         editor.set(IDEA_SERVER_NAME, serverConfig(port, projectPath));
       });
-      registrations = [toolRegistration, mcpRegistration];
+      registrations = [mcpRegistration];
       activePort = port;
       if (typeof ctx.mcp.reload === 'function') await ctx.mcp.reload();
     };
@@ -356,7 +352,7 @@ export default {
       sessionRegistration = await ctx.session.hook('context', (event) => {
         appendIdeRecoveryGuidance(event?.system);
         if (activePort === undefined) return;
-        appendIdeGuidance(event?.system);
+        appendIdeGuidance(event?.system, projectPath);
       });
     }
 

package/UPGRADING.md

@@ -1,8 +0,0 @@
-# 升级指南
-
-## 0.0.1
-
-初始版本,暂无迁移路径。
-
-> 从旧包名 `opencode-jetbrains-mcp` 迁移:把 OpenCode 配置里的
-> `opencode-jetbrains-mcp` 改为 `opencode-idea`,其余配置项不变。

package/skills/jetbrains-mcp-setup/SKILL.md

@@ -1,36 +0,0 @@
----
-name: jetbrains-mcp-setup
-description: 配置并验证 opencode-idea 插件:开启 JetBrains IDE 的 MCP 服务、找到端口、写入 opencode.json、验证 OpenCode 能连上并优先使用 IDE 工具。当用户要「接入 IDEA/JetBrains 的 MCP」「让 OpenCode 用 IDE 工具编辑/构建」或排查插件不生效时使用。
----
-
-# JetBrains MCP 接入配置
-
-## 步骤
-
-1. **确认 IDE 侧已开启 MCP 服务**
-   - 在 JetBrains IDE 中打开 Settings → Tools → MCP Server(或 AI Assistant 的 MCP 设置),启用。
-   - 让用户在 IDE 里打开要操作的项目。
-
-2. **拿到 MCP 端口**
-   - IDE 通常显示形如 `http://127.0.0.1:<port>/sse` 的地址;记录 `<port>`。
-   - 若用户不确定,可用 `ports` 默认列表让插件自动探测。
-
-3. **在项目 `opencode.json` 注册插件**
-
-   ```jsonc
-   {
-     "plugin": [
-       ["opencode-idea", { "ports": [<port>] }]
-     ]
-   }
-   ```
-
-4. **验证**
-   - 重启 OpenCode(或触发插件重载)。
-   - 让用户确认:当前项目在 IDE 中打开时,OpenCode 是否优先用 IDE 工具;关闭项目后是否回退原生。
-
-## 排查
-
-- 插件不生效:确认 OpenCode 是 **V2**(需要 `ctx.tool` / `ctx.mcp`)。
-- 一直探测失败:确认 IDE MCP 在跑、端口正确、当前项目确实在 IDE 中打开。
-- 判断依据:IDE MCP 的 `tools/call get_project_modules` 在项目打开时成功、未打开时返回 `isError`。

package/src/idea-tool-descriptions.js

@@ -1,39 +0,0 @@
-// Adds concise, direct-call guidance to IDEA MCP tool descriptions.
-//
-// This transform only targets tools whose effective IDs belong to the IDEA MCP
-// namespace. Native OpenCode tools are intentionally left untouched.
-
-const IDEA_TOOL_PREFIX = /^(idea_|idea\.)/;
-const IDEA_EDITING_TOOLS = new Set(['idea_apply_patch', 'idea_create_new_file']);
-
-export const IDEA_DIRECT_NOTE =
-  '【IDEA MCP】项目内操作请直接调用本工具;参数严格按当前工具 schema,不要猜测参数名。';
-
-export const IDEA_EDIT_NOTE =
-  '【IDEA MCP 编辑】项目内文件编辑请直接调用本工具;已有文件使用 idea_apply_patch,新文件使用 idea_create_new_file;不要用 shell 写项目文件。';
-
-const isIdeaTool = (id) => typeof id === 'string' && IDEA_TOOL_PREFIX.test(id);
-
-const noteFor = (id) => IDEA_EDITING_TOOLS.has(id) ? IDEA_EDIT_NOTE : IDEA_DIRECT_NOTE;
-
-/**
- * Prepend direct-call guidance to IDEA MCP tool descriptions only.
- * The transform is idempotent and ignores missing descriptions.
- *
- * @param {{
- *   list: () => ReadonlyArray<{ id?: string }>,
- *   update: (id: string, update: (tool: { description?: string }) => void) => void,
- * }} editor
- */
-export function applyIdeaToolGuidance(editor) {
-  for (const tool of editor.list()) {
-    const id = tool?.id;
-    if (!isIdeaTool(id)) continue;
-    editor.update(id, (draft) => {
-      if (typeof draft.description !== 'string') return;
-      const note = noteFor(id);
-      if (draft.description.startsWith(note)) return;
-      draft.description = note + draft.description;
-    });
-  }
-}