remote-tools

让服务端 Claude Agent SDK agent 安全地操作用户本机：6 个 client__* MCP 工具经 WebSocket 隧道转发到用户桌面端（Plan B：remote-tools-desktop）执行。

设计文档：../docs/remote-tools/2026-09-09-remote-tool-proxy-design.md

宿主集成样例

import { query } from "@anthropic-ai/claude-agent-sdk";
import { TunnelServer, createServerWriteFence } from "remote-tools";      // 根入口不加载 SDK
import { createClientToolsSdkMcp } from "remote-tools/mcp-bridge/sdk";

const tunnel = new TunnelServer({ token: process.env.REMOTE_TOOLS_TOKEN! });
await tunnel.listen(8787);

const codingSession = query({
  prompt: "按 docs/ 里的 Spec 与 Plan 编码",
  options: {
    mcpServers: { client: createClientToolsSdkMcp(tunnel) },
    canUseTool: createServerWriteFence({ docsRoots: ["/data/docs"] }),
    disallowedTools: ["Bash"],            // 服务器不执行；构建调试走 client__bash
    systemPrompt: {
      type: "preset", preset: "claude_code",
      append: "服务器存放需求与技术文档（docs/ 内可读可写）；用户的所有代码、依赖与运行环境"
        + "都在其本机——编码、构建、调试、执行一律使用 client__* 工具。",
    },
  },
});

导出位置：remote-tools 根入口是 SDK-free 的（TunnelServer / createToolHandlers / createServerWriteFence）；依赖 Agent SDK 的两个适配器分别走子路径 remote-tools/mcp-bridge/sdk（6 个 client__* 工具）与 remote-tools/phase/switch（submit_phase 阶段切换）。

阶段切换（submit_phase）与两阶段 options 的组合见设计文档 §10。

Related MCP server: rvn

重要注意事项

• bash 默认超时 120s > SDK 默认 60s 流关闭超时：宿主需设置环境变量 CLAUDE_CODE_STREAM_CLOSE_TIMEOUT（如 180000），否则长构建/测试会被 SDK 提前切断。

• 隧道令牌用 32 字节随机值生成：node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"。

• 客户端桌面端（Tauri）是独立项目 remote-tools-desktop，协议为 src/protocol/envelope.ts 定义的 JSON 信封（TS 与 Rust 仅结构对齐）。

• 集成样例已按当前安装的 Agent SDK 用 tsc 校验：该版本的 Options 没有 appendSystemPrompt 字段，追加指令走 systemPrompt: { type: "preset", preset: "claude_code", append }； 若你的 SDK 版本提供 appendSystemPrompt，两者语义等价。

开发

npm test        # vitest
npm run typecheck