Skip to main content
Glama

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: rig-bridge

重要注意事项

  • 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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agent clients to safely connect to tools and execution resources through MCP with authorization, approvals, audit, chat-context isolation, SSH/Docker access, and long-running command session tracking.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients such as Claude and Cursor to control an isolated cloud machine with a real browser, shell, filesystem, and web access, so agents can navigate pages, click and type, run commands, manage files, and search or fetch web content.
      26
      13 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables authorized remote MCP clients to securely reach local Mac or Windows tools over OAuth, including shell commands, file read/write, background jobs, screenshots, UI control, and clipboard access. It can also expose configured Desktop MCP servers and optional Claude Code task delegation.
      MIT