@znmin/claude-remote-cli 0.3.1 → 0.4.0

package/README.md

@@ -25,14 +25,14 @@ npm install -g git+https://github.com/znmin/claude-remote-cli.git
 也可以从已下载的分发包安装：
 
 ```bash
-npm install -g ./znmin-claude-remote-cli-0.3.1.tgz
+npm install -g ./znmin-claude-remote-cli-0.4.0.tgz
 ```
 
-若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.3.1.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
+若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.4.0.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
 
 npm 中不带作用域的 `claude-remote-cli` 属于其他项目。本项目使用独立的 `@znmin/claude-remote-cli` 作用域包名；请安装完整包名，或使用上述 GitHub 地址及本项目分发的 `.tgz` 文件。
 
-依赖按模式准备：本地模式首次启动准备 Playwright Chromium，服务器模式首次启动准备 Mutagen 0.18.1。Mutagen 复用 PATH 中的匹配版本，或从官方 GitHub Release 下载并校验内置 SHA-256。浏览器和同步组件需要网络和额外磁盘空间；npm 安装本身不强制下载这些二进制文件。
+依赖按模式准备：本地模式优先使用本机已安装的 Google Chrome，其次 Microsoft Edge（Windows 10/11 自带），都没有时首次启动下载 Playwright Chromium；服务器模式首次启动准备 Mutagen 0.18.1。Mutagen 复用 PATH 中的匹配版本，或从官方 GitHub Release 下载并校验内置 SHA-256。浏览器和同步组件需要网络和额外磁盘空间；npm 安装本身不强制下载这些二进制文件。
 
 ### Windows（0.3.0）
 
@@ -160,7 +160,7 @@ Git、npm、pnpm、Python、Go、Docker、数据库 CLI、`gh` 等共用本地
 
 0.2.5 起，普通公开资料查询优先使用服务器上的 Claude 原生 `WebSearch` / `WebFetch`，不打开本地浏览器；服务器的文件、终端和浏览器执行工具仍不开放。原生搜索/网页读取是否可用取决于服务器 Claude 的账号、服务商和策略；如果不可用或查询失败，会先说明并征求用户意见，再回退本地浏览器。本地开发页面、localhost/局域网地址、交互测试、截图和交互登录仍使用本地浏览器，不交给服务器 WebFetch。该选择通过工具白名单及提示词约定实现，不是对模型每次路由选择的硬性拦截。
 
-浏览器使用独立窗口和临时上下文，不读取日常 Chrome 的登录态。启动本地模式时准备相应浏览器版本，后续使用缓存；收到浏览器工具调用时才打开窗口。可以打开本机 localhost，填写表单、点击、截图和读取控制台错误。
+浏览器使用独立窗口和临时上下文，即使使用本机 Chrome/Edge 也不读取日常的书签、登录态和 Cookie。默认依次选择本机 Chrome、Edge，都没有时启动本地模式下载 Playwright Chromium 并缓存；可用 `CLAUDE_REMOTE_BROWSER` 指定。自动选择的本机浏览器无法启动时会提示并改用 Chromium。收到浏览器工具调用时才打开窗口。可以打开本机 localhost，填写表单、点击、截图和读取控制台错误。
 
 ```bash
 claude-remote install-browser
@@ -179,6 +179,45 @@ Linux 上仍需安装 Playwright 所需的系统共享库，有窗口模式还
 
 这是工具路由约束，不是对 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
@@ -187,7 +226,7 @@ claude-remote flush                # 等待当前项目完成一次同步
 claude-remote stop                 # 停止当前目录在当前配置服务器上的同步
 claude-remote stop --all           # 停止本工具的所有同步会话
 claude-remote stop --name 名称     # 按 status 中的名称停止旧服务器上的映射
-claude-remote doctor               # 检查本地安装（含 Node 版本、SSH 工具、本地浏览器缓存）和服务器配置，不连接服务器
+claude-remote doctor               # 检查本地安装（含 Node 版本、SSH 工具、使用的本地浏览器）和服务器配置，不连接服务器
 claude-remote install-sync         # 手动重试同步工具准备
 claude-remote --help
 ```
@@ -229,6 +268,7 @@ CLAUDE_REMOTE_DEBUG=1 claude
 | 变量 | 用途 |
 | --- | --- |
 | `CLAUDE_REMOTE_MODE` | 临时选择 `local` 或 `remote` |
+| `CLAUDE_REMOTE_BROWSER` | 本地浏览器：`chrome`、`msedge` 或 `chromium`（Playwright 自带）；未设置时按 Chrome、Edge、Chromium 顺序自动选择 |
 | `CLAUDE_REMOTE_HEADLESS` | `1` 无窗口浏览器，`0` 可见窗口，覆盖配置 |
 | `CLAUDE_REMOTE_HOST` | 临时 SSH 别名或 user@host |
 | `CLAUDE_REMOTE_PORT` | 临时 SSH 端口 |
@@ -256,7 +296,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.1.tgz
+npm install -g ./znmin-claude-remote-cli-0.4.0.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.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",
-    "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.0",
+  "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 开始。');