@znmin/claude-remote-cli 0.3.2 → 0.4.0

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.0.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.0.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
 
 npm 中不带作用域的 `claude-remote-cli` 属于其他项目。本项目使用独立的 `@znmin/claude-remote-cli` 作用域包名；请安装完整包名，或使用上述 GitHub 地址及本项目分发的 `.tgz` 文件。
 
@@ -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
@@ -257,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.2.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.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.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 开始。');