@znmin/claude-remote-cli 0.3.2 → 0.4.1

package/README.md

@@ -25,10 +25,10 @@ npm install -g git+https://github.com/znmin/claude-remote-cli.git
 也可以从已下载的分发包安装：
 
 ```bash
-npm install -g ./znmin-claude-remote-cli-0.3.2.tgz
+npm install -g ./znmin-claude-remote-cli-0.4.1.tgz
 ```
 
-若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.3.2.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
+若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.4.1.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
 
 npm 中不带作用域的 `claude-remote-cli` 属于其他项目。本项目使用独立的 `@znmin/claude-remote-cli` 作用域包名；请安装完整包名，或使用上述 GitHub 地址及本项目分发的 `.tgz` 文件。
 
@@ -175,10 +175,60 @@ Linux 上仍需安装 Playwright 所需的系统共享库，有窗口模式还
 
 启动时使用 `--restricted`、`--tools "WebSearch,WebFetch"`、`--strict-mcp-config`，限定工具和设置来源、关闭普通 hooks。0.2.2 起恢复 `/config`、`/model`、`/help` 等内置交互命令，不再使用禁用整个命令菜单的 `--disable-slash-commands`；通过 `disableSkillShellExecution` 和 `disableBundledSkills` 单独关闭技能内联 shell 和内置技能工作流。恢复菜单不代表所有依赖服务器项目目录或原生工具的命令都适用于本地模式。设置面板修改的是服务器上的 Claude 配置；受限模式仍只加载托管配置和本次 `--settings`，不会恢复读取普通用户/项目 settings.json，因此偏好设置的跨会话持久化仍受该限制影响，可用 `claude --model sonnet` 明确指定启动模型。保留服务器上的订阅认证，不使用跳过 OAuth 的 `--bare`。本地连接失效时不会将文件或命令操作退回服务器执行。支持 `--continue`、`--resume`、`--model`、`--effort`、`--name`、`--fallback-model`、`-p` 和输入/输出格式；`--permission-mode` 支持 `default`、`manual`、`acceptEdits`、`plan`、`auto`、`dontAsk`（受限模式本身拒绝 `bypassPermissions`）。暂不接受替换工具配置、加载插件、切换云会话等参数。
 
+#### 粘贴本机截图（0.4.1）
+
+本地模式下，截图后直接在 Claude 输入框按平时的图片粘贴快捷键（Windows 为 Alt+V，macOS/Linux 为 Ctrl+V），就能粘贴**本机**剪贴板里的图片，和在本机运行 Claude Code 一样显示为 `[Image #1]`。
+
+原理：Linux 版 Claude Code 通过 `xclip -selection clipboard -t TARGETS/image/png -o` 读取剪贴板图片。每个会话在服务器临时目录放一个 `xclip` 替身，只放在本次 Claude 进程的 PATH 最前面。替身通过同一条 SSH 反向隧道向本机工具服务请求剪贴板图片（`GET /clipboard/image`，校验同一个令牌）；令牌以 0600 文件保存，通过 `curl -H @文件` 读取，不出现在服务器进程列表里。其他 `xclip` 调用（读取文本、其他选区）交给服务器上原有的 `xclip`，只有在 Claude 请求图片时才会读取本机剪贴板。退出时替身和令牌文件随临时配置一起删除。
+
+- 快捷键：服务器上的 Linux 版 Claude 默认只认 Ctrl+V，而 Windows 终端会自己处理 Ctrl+V。因此从 Windows 启动时，如果服务器上没有 `~/.claude/keybindings.json`，会自动创建它并加入 `"alt+v": "chat:imagePaste"`（`--restricted` 下同样生效）。已有该文件时不会修改，只在启动时提示需要加入的那一行。
+- 本机读取方式：Windows 用 PowerShell 读取截图或资源管理器中复制的图片文件；macOS 用 `osascript`；Linux 用 `wl-paste` 或 `xclip`。
+- 服务器需要 `curl` 或 `python3`。
+- 服务器模式（`remote`）暂不支持；需要时可将图片保存到项目目录，同步后用 `@文件名` 引用。
+
 本地模式的路由规则、本地 CLAUDE.md 和用户传入的 `--append-system-prompt` 内容合并为一个文件，通过 SSH 标准输入写入服务器临时目录（权限 0600），再用 `--append-system-prompt-file` 加载；用户的追加内容排在路由规则之后，不会替换它。退出时与 MCP 配置一起删除。
 
 这是工具路由约束，不是对 Claude Code 主进程的系统隔离。认证、会话和日志仍在服务器，管理员管理策略继续生效。文件内容、命令结果和截图会经过服务器交给模型，不整体同步不代表数据不离开本机。
 
+### 项目 MCP 与内网 MCP（0.4.0）
+
+本地模式下，项目或用户自己配置的 MCP 由本机启动或从本机连接，再通过同一条 SSH 反向隧道提供给服务器上的 Claude。因此服务器不需要访问内网，也不需要安装这些 MCP 的依赖：
+
+```
+服务器 Claude ──> 127.0.0.1:隧道端口 ──SSH -R──> 本机网关 ─┬─ /mcp        内置本地工具
+                                                          ├─ /mcp/jira   本机连接内网 http://10.x.x.x/mcp
+                                                          └─ /mcp/db     本机启动的 stdio 程序
+```
+
+配置来源与 Claude Code 相同，同名时优先级为 local > project > user：
+
+| 范围 | 存储位置 | 生效范围 |
+| --- | --- | --- |
+| `local`（默认） | `~/.config/claude-remote/mcp.json`，按项目目录区分 | 仅当前项目，仅本机 |
+| `project` | 项目根目录 `.mcp.json`，可提交到仓库 | 当前项目 |
+| `user` | `~/.config/claude-remote/mcp.json` | 本机所有项目 |
+
+```bash
+# stdio：命令在本机运行，工作目录为项目根目录，继承本机终端环境
+claude-remote mcp add db -e DB_URL='${DB_URL}' -- npx -y some-db-mcp
+# HTTP/SSE：从本机连接内网地址
+claude-remote mcp add -t http -s project -H 'Authorization: Bearer ${JIRA_TOKEN}' jira https://jira.corp.local/mcp
+claude-remote mcp add-json -s user docs '{"type":"sse","url":"http://10.0.0.8/sse"}'
+claude-remote mcp list
+claude-remote mcp get jira
+claude-remote mcp remove jira
+claude-remote mcp reset-project-choices   # 重新询问是否启用 .mcp.json 中的 MCP
+```
+
+默认模式为 `local` 时，`claude mcp …` 等同于 `claude-remote mcp …`；服务器模式下 `claude mcp` 仍管理服务器上的配置。
+
+- **服务名称不变**：服务器上看到的工具名仍是 `mcp__jira__search` 这种形式，项目文档和权限规则无需修改。MCP 的 tools、resources 和 prompts 都会转发。
+- **凭据不离开本机**：`${VAR}` 和 `${VAR:-默认值}` 在本机启动时用本机环境变量展开。内网地址、请求头和环境变量只在本机网关中使用，服务器上的临时配置只包含 `127.0.0.1` 隧道地址和本次会话的随机令牌。
+- **项目配置需要确认**：`.mcp.json` 可以在本机运行任意命令，首次启动时会逐个显示命令或 URL，询问是否启用。选择按项目记住，配置内容变化后重新询问。非交互运行时，未确认的 MCP 会被跳过并给出提示。通过 `claude-remote mcp add -s project` 添加的条目视为本机已确认。
+- **连接失败不影响启动**：每个 MCP 最多等待 30 秒，失败时打印原因（stdio 程序会附带最后几行错误输出），本次会话不提供该 MCP。stdio 程序的错误输出不会显示在终端上，避免打乱远程界面，`CLAUDE_REMOTE_DEBUG=1` 时才显示。stdio 程序在会话中意外退出时，下次调用会自动重启。退出时停止所有 MCP 程序（Windows 上包括 `npx` 等通过 `cmd.exe` 启动的整个进程树）。
+- **结果大小有上限**：与内置工具相同，单次结果超过约 4 万字符时会截断较长的文本，图片等二进制内容保持不变。为此不向服务器提供工具的 `outputSchema`。单次调用最长 3 分钟，MCP 发送进度通知时会重新计时。
+- **暂不支持**：需要 OAuth 登录或 `headersHelper` 的 MCP，以及 `ws` 类型；请改用固定请求头（可引用本机环境变量）。MCP 在会话中发送的列表变更通知不会转发，修改配置后请重新启动 `claude`。服务器模式（`remote`）仍由服务器自己读取同步过去的 `.mcp.json`。
+
 ## 同步管理（仅服务器模式）
 
 ```bash
@@ -257,7 +307,7 @@ npm run test:windows   # Windows 上运行的客户端测试（CI 在 windows-la
 CLAUDE_REMOTE_INTEGRATION=1 CLAUDE_REMOTE_BROWSER_TEST=1 npm test
 
 npm pack
-npm install -g ./znmin-claude-remote-cli-0.3.2.tgz
+npm install -g ./znmin-claude-remote-cli-0.4.1.tgz
 
 # 确定包名、版本和使用条款后，使用有发布权限的 npm 账号发布
 npm login

package/THIRD_PARTY_NOTICES.md

@@ -1,16 +1,16 @@
-# Third-party components
-
-The npm package contains the JavaScript CLI source and depends on `proper-lockfile` (MIT), the official `@modelcontextprotocol/sdk` (MIT), `zod` (MIT), `playwright` (Apache-2.0), and their npm-managed dependencies. Their license files are included in their respective npm packages.
-
-Playwright downloads its matching Chromium/browser components on first local-mode preparation. These components remain subject to their upstream licenses. A separate local browser context is used; this wrapper does not include the user's browser profile.
-
-Mutagen binaries are **not bundled in this npm package**. At setup/first use, the tool can reuse an existing Mutagen 0.18.1 installation, or download the matching v0.18.1 archive from the official release repository. SHA-256 values are pinned in `src/installer.js` from the official release's `SHA256SUMS` file.
-
-- Mutagen project: https://github.com/mutagen-io/mutagen
-- Pinned release: https://github.com/mutagen-io/mutagen/releases/tag/v0.18.1
-- Release checksums: https://github.com/mutagen-io/mutagen/releases/download/v0.18.1/SHA256SUMS
-- Upstream license: https://github.com/mutagen-io/mutagen/blob/v0.18.1/LICENSE
-
-The upstream license states that, from v0.17 onward, official release builds include SSPL-licensed code by default; other source is generally MIT or as indicated upstream. Mutagen and the automatically deployed remote agents remain subject to the upstream terms independently of this JavaScript wrapper.
-
-Claude Code is a separate product installed and authenticated on the user's server. This project does not bundle Claude Code and is not affiliated with or endorsed by Anthropic.
+# Third-party components
+
+The npm package contains the JavaScript CLI source and depends on `proper-lockfile` (MIT), the official `@modelcontextprotocol/sdk` (MIT), `zod` (MIT), `playwright` (Apache-2.0), and their npm-managed dependencies. Their license files are included in their respective npm packages.
+
+Playwright downloads its matching Chromium/browser components on first local-mode preparation. These components remain subject to their upstream licenses. A separate local browser context is used; this wrapper does not include the user's browser profile.
+
+Mutagen binaries are **not bundled in this npm package**. At setup/first use, the tool can reuse an existing Mutagen 0.18.1 installation, or download the matching v0.18.1 archive from the official release repository. SHA-256 values are pinned in `src/installer.js` from the official release's `SHA256SUMS` file.
+
+- Mutagen project: https://github.com/mutagen-io/mutagen
+- Pinned release: https://github.com/mutagen-io/mutagen/releases/tag/v0.18.1
+- Release checksums: https://github.com/mutagen-io/mutagen/releases/download/v0.18.1/SHA256SUMS
+- Upstream license: https://github.com/mutagen-io/mutagen/blob/v0.18.1/LICENSE
+
+The upstream license states that, from v0.17 onward, official release builds include SSPL-licensed code by default; other source is generally MIT or as indicated upstream. Mutagen and the automatically deployed remote agents remain subject to the upstream terms independently of this JavaScript wrapper.
+
+Claude Code is a separate product installed and authenticated on the user's server. This project does not bundle Claude Code and is not affiliated with or endorsed by Anthropic.

package/bin/claude-remote.js

@@ -1,3 +1,3 @@
-#!/usr/bin/env node
-import { entry } from '../src/cli.js';
-await entry(false);
+#!/usr/bin/env node
+import { entry } from '../src/cli.js';
+await entry(false);

package/bin/claude.js

@@ -1,3 +1,3 @@
-#!/usr/bin/env node
-import { entry } from '../src/cli.js';
-await entry(true);
+#!/usr/bin/env node
+import { entry } from '../src/cli.js';
+await entry(true);

package/package.json

@@ -1,67 +1,67 @@
-{
-  "name": "@znmin/claude-remote-cli",
-  "version": "0.3.2",
-  "description": "Run Claude Code on an SSH server from macOS, Linux or Windows with local filesystem, terminal and browser tools, or remote bidirectional sync",
-  "type": "module",
-  "license": "UNLICENSED",
-  "engines": {
-    "node": ">=20.11"
-  },
-  "os": [
-    "darwin",
-    "linux",
-    "win32"
-  ],
-  "cpu": [
-    "x64",
-    "arm64"
-  ],
-  "bin": {
-    "claude": "bin/claude.js",
-    "claude-remote": "bin/claude-remote.js"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "scripts/postinstall.js",
-    "README.md",
-    "THIRD_PARTY_NOTICES.md"
-  ],
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "lint": "eslint .",
-    "test": "node --test test/*.test.js",
-    "test:windows": "node --test test/windows.test.js test/local-tools.test.js test/browser-choice.test.js",
-    "prepublishOnly": "npm run lint && npm test"
-  },
-  "keywords": [
-    "claude",
-    "ssh",
-    "remote",
-    "cli",
-    "sync"
-  ],
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "1.32.2",
-    "playwright": "1.64.1",
-    "proper-lockfile": "4.1.2",
-    "zod": "4.6.7"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/znmin/claude-remote-cli.git"
-  },
-  "homepage": "https://github.com/znmin/claude-remote-cli#readme",
-  "bugs": {
-    "url": "https://github.com/znmin/claude-remote-cli/issues"
-  },
-  "devDependencies": {
-    "@eslint/js": "9.39.5",
-    "eslint": "9.39.5",
-    "globals": "17.14.0"
-  }
-}
+{
+  "name": "@znmin/claude-remote-cli",
+  "version": "0.4.1",
+  "description": "Run Claude Code on an SSH server from macOS, Linux or Windows with local filesystem, terminal and browser tools, or remote bidirectional sync",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20.11"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "bin": {
+    "claude": "bin/claude.js",
+    "claude-remote": "bin/claude-remote.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/postinstall.js",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "lint": "eslint .",
+    "test": "node --test test/*.test.js",
+    "test:windows": "node --test test/windows.test.js test/local-tools.test.js test/browser-choice.test.js test/mcp-proxy.test.js",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "keywords": [
+    "claude",
+    "ssh",
+    "remote",
+    "cli",
+    "sync"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "playwright": "1.64.1",
+    "proper-lockfile": "4.1.2",
+    "zod": "4.6.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/znmin/claude-remote-cli.git"
+  },
+  "homepage": "https://github.com/znmin/claude-remote-cli#readme",
+  "bugs": {
+    "url": "https://github.com/znmin/claude-remote-cli/issues"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.5",
+    "eslint": "9.39.5",
+    "globals": "17.14.0"
+  }
+}

package/scripts/postinstall.js

@@ -1,11 +1,11 @@
-import { ensureMutagen } from '../src/installer.js';
-
-if (process.env.CLAUDE_REMOTE_PREPARE_SYNC === '1' && process.env.CLAUDE_REMOTE_SKIP_DOWNLOAD !== '1') {
-  try {
-    await ensureMutagen();
-  } catch (error) {
-    // Offline installation and npm --ignore-scripts remain supported: retry at first use.
-    console.warn(`CLI 已安装，同步工具准备未完成：${error.message}\n首次连接时会重试。`);
-  }
-}
-console.log('安装完成，运行 claude 开始。');
+import { ensureMutagen } from '../src/installer.js';
+
+if (process.env.CLAUDE_REMOTE_PREPARE_SYNC === '1' && process.env.CLAUDE_REMOTE_SKIP_DOWNLOAD !== '1') {
+  try {
+    await ensureMutagen();
+  } catch (error) {
+    // Offline installation and npm --ignore-scripts remain supported: retry at first use.
+    console.warn(`CLI 已安装，同步工具准备未完成：${error.message}\n首次连接时会重试。`);
+  }
+}
+console.log('安装完成，运行 claude 开始。');