跳到正文
Ephemeral Sandbox mascot — a Siamese kitten peeking out of its wooden sandbox
浏览文档

接口

运行时 MCP 工具

调用七项运行时工具完成命令会话和文件操作。

本页内容+

调用之前

使用 sandbox-mcp --set runtime 启动一个 stdio 服务器。七项工具都要求 sandbox_id。适配器会把该属性提升为网关范围，并将其余属性作为语义操作参数发送。

服务器进程
sandbox-mcp --set runtime

请保留运行中命令返回的 command_session_id，并按偏移量分页读取输出。省略 workspace_session_id 时，直接文件修改会立即发布。完整流程见文件与命令。

按类别筛选操作

显示 7 / 7 项工具。

命令会话

启动命令、写入输入，并按稳定偏移量分页读取输出。

exec_command

启动沙箱 shell 命令

会话状态

在工作区会话中启动 shell 命令。省略 workspace_session_id 时使用自动的 publish_then_destroy 会话。

何时使用

  1. 仅在已有受管会话时使用 workspace_session_id。
  2. 若 status 为 running，请保留 command_session_id，供 read_command_lines 或 write_command_stdin 使用。
  3. 自动会话中的命令终止后，会先捕获并发布文件系统更改，再销毁会话。

工具参数

属性类型必填说明
sandbox_idstring是目标沙箱 ID（用于选择要查询的守护进程）。
workspace_session_idstring否要在其中运行的现有工作区会话 ID。省略时创建 finalize 策略为 publish_then_destroy 的会话。
cmdstring是Shell 命令文本。
timeout_msinteger否命令超时时间，单位为毫秒。
yield_time_msinteger否首次等待输出的时间，单位为毫秒。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "exec_command",
    "arguments": {
      "sandbox_id": "sbox-example",
      "cmd": "cargo check",
      "yield_time_ms": 1000
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "目标沙箱 ID（用于选择要查询的守护进程）。"
    },
    "workspace_session_id": {
      "type": "string",
      "description": "要在其中运行的现有工作区会话 ID。省略时创建 finalize 策略为 publish_then_destroy 的会话。"
    },
    "cmd": {
      "type": "string",
      "description": "Shell 命令文本。"
    },
    "timeout_ms": {
      "type": "integer",
      "description": "命令超时时间，单位为毫秒。",
      "minimum": 0
    },
    "yield_time_ms": {
      "type": "integer",
      "description": "首次等待输出的时间，单位为毫秒。",
      "minimum": 0
    }
  },
  "required": [
    "sandbox_id",
    "cmd"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "command_session_id": "namespace_execution_42",
      "workspace_session_id": "workspace_17",
      "status": "running",
      "exit_code": null,
      "wall_time_seconds": 0.25,
      "command_total_time_seconds": 0.25,
      "start_offset": 0,
      "end_offset": 2,
      "total_lines": 2,
      "original_token_count": 4,
      "output": "building…\n"
    },
    "isError": false
  }
}

结果约定： status 为 running、ok、error、timed_out 或 cancelled；终态结果可能包含发布字段。

相关操作write_command_stdinread_command_lines

write_command_stdin

向正在运行的命令写入内容

会话状态

向运行中命令会话的 stdin 流追加文本，并返回有界的输出窗口。

何时使用

  1. 使用 exec_command 仍处于 running 状态时返回的 command_session_id。
  2. stdin 会原样写入；面向行的程序需要显式包含换行符。
  3. 结果沿用命令输出结构，写入后可能进入终态。

工具参数

属性类型必填说明
sandbox_idstring是目标沙箱 ID（用于选择要查询的守护进程）。
command_session_idstring是exec_command 返回的命令会话 ID。
stdinstring是要写入 stdin 的文本。
yield_time_msinteger否写入 stdin 后等待输出的时间。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "write_command_stdin",
    "arguments": {
      "sandbox_id": "sbox-example",
      "command_session_id": "namespace_execution_42",
      "stdin": "yes\n",
      "yield_time_ms": 1000
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "目标沙箱 ID（用于选择要查询的守护进程）。"
    },
    "command_session_id": {
      "type": "string",
      "description": "exec_command 返回的命令会话 ID。"
    },
    "stdin": {
      "type": "string",
      "description": "要写入 stdin 的文本。"
    },
    "yield_time_ms": {
      "type": "integer",
      "description": "写入 stdin 后等待输出的时间。",
      "minimum": 0
    }
  },
  "required": [
    "sandbox_id",
    "command_session_id",
    "stdin"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "command_session_id": "namespace_execution_42",
      "workspace_session_id": "workspace_17",
      "status": "ok",
      "exit_code": 0,
      "wall_time_seconds": 0.25,
      "command_total_time_seconds": 0.25,
      "start_offset": 0,
      "end_offset": 4,
      "total_lines": 4,
      "original_token_count": 4,
      "output": "accepted\ndone\n"
    },
    "isError": false
  }
}

结果约定： 响应只包含有界的输出窗口。

相关操作exec_commandread_command_lines

read_command_lines

分页读取命令输出

只读

使用稳定的行偏移量读取命令会话已经渲染的输出。

何时使用

  1. 从偏移量 0 开始，随后从 end_offset 继续，直到它等于 total_lines。
  2. 命令可能仍在运行；status 和偏移量只是调用时刻的快照。
  3. 读取输出不会延长或触发工作区会话生命周期行为。

工具参数

属性类型必填说明
sandbox_idstring是目标沙箱 ID（用于选择要查询的守护进程）。
command_session_idstring是exec_command 返回的命令会话 ID。
start_offsetinteger否；默认值 0开始读取的第一行偏移量，默认为 0。
limitinteger否；默认值 200最多返回的输出行数，默认为 200，最大为 1000。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "read_command_lines",
    "arguments": {
      "sandbox_id": "sbox-example",
      "command_session_id": "namespace_execution_42",
      "start_offset": 2,
      "limit": 200
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "目标沙箱 ID（用于选择要查询的守护进程）。"
    },
    "command_session_id": {
      "type": "string",
      "description": "exec_command 返回的命令会话 ID。"
    },
    "start_offset": {
      "type": "integer",
      "description": "开始读取的第一行偏移量，默认为 0。",
      "minimum": 0,
      "default": 0
    },
    "limit": {
      "type": "integer",
      "description": "最多返回的输出行数，默认为 200，最大为 1000。",
      "minimum": 0,
      "default": 200
    }
  },
  "required": [
    "sandbox_id",
    "command_session_id"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "command_session_id": "namespace_execution_42",
      "workspace_session_id": "workspace_17",
      "status": "ok",
      "exit_code": 0,
      "wall_time_seconds": 0.25,
      "command_total_time_seconds": 0.25,
      "start_offset": 2,
      "end_offset": 4,
      "total_lines": 4,
      "original_token_count": 4,
      "output": "accepted\ndone\n"
    },
    "isError": false
  }
}

结果约定： original_token_count 描述应用渲染边界前、未截断的源内容。

相关操作exec_commandwrite_command_stdin

文件与归因

读取快照、发布文件修改，并检查逐行归属。

file_read

读取 UTF-8 文本窗口

只读

从已发布快照或在线会话中，按仓库相对路径或工作区根目录绝对路径读取 UTF-8 文本窗口。

何时使用

  1. 省略 workspace_session_id 读取已发布快照；提供该值则读取尚未提交的会话内容。
  2. 当 truncated 为 true 时，沿 next_offset 继续分页读取长文件。
  3. 仅支持 UTF-8 普通文件。

工具参数

属性类型必填说明
sandbox_idstring是目标沙箱 ID（用于选择要查询的守护进程）。
pathstring是要读取的仓库相对路径或工作区根目录绝对路径。
offsetinteger否；默认值 1开始读取的行号，从 1 计数，默认为 1。
limitinteger否；默认值 2000最多读取的行数，默认为 2000，必须在 1..=2000 范围内。
workspace_session_idstring否要在其中读取的现有工作区会话 ID。省略时读取快照。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_read",
    "arguments": {
      "sandbox_id": "sbox-example",
      "path": "README.md",
      "offset": 1,
      "limit": 40
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "目标沙箱 ID（用于选择要查询的守护进程）。"
    },
    "path": {
      "type": "string",
      "description": "要读取的仓库相对路径或工作区根目录绝对路径。"
    },
    "offset": {
      "type": "integer",
      "description": "开始读取的行号，从 1 计数，默认为 1。",
      "minimum": 0,
      "default": 1
    },
    "limit": {
      "type": "integer",
      "description": "最多读取的行数，默认为 2000，必须在 1..=2000 范围内。",
      "minimum": 0,
      "default": 2000
    },
    "workspace_session_id": {
      "type": "string",
      "description": "要在其中读取的现有工作区会话 ID。省略时读取快照。"
    }
  },
  "required": [
    "sandbox_id",
    "path"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "path": "README.md",
      "content": "# Example\n\nProject overview…\n",
      "start_line": 1,
      "num_lines": 3,
      "total_lines": 3,
      "bytes_read": 31,
      "total_bytes": 31,
      "next_offset": null,
      "truncated": false
    },
    "isError": false
  }
}

结果约定： 还有下一个窗口时，next_offset 不为 null。

相关操作file_writefile_editfile_blame

file_write

创建或覆盖文件

修改状态

在在线会话中把内容写入路径；未提供会话时，发布一个带归因的新层。

何时使用

  1. 仅在明确要覆盖整个目标文件时使用。
  2. 会话范围内的写入在会话解决前保持私有。
  3. 未提供会话时，运行时发布一个归属为 operation:<request_id> 的层。

工具参数

属性类型必填说明
sandbox_idstring是目标沙箱 ID（用于选择要查询的守护进程）。
pathstring是要写入的仓库相对路径或工作区根目录绝对路径。
contentstring是要写入的文件内容。
workspace_session_idstring否要在其中写入的现有工作区会话 ID。省略时发布一个层。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_write",
    "arguments": {
      "sandbox_id": "sbox-example",
      "path": "notes.txt",
      "content": "new content\n"
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "目标沙箱 ID（用于选择要查询的守护进程）。"
    },
    "path": {
      "type": "string",
      "description": "要写入的仓库相对路径或工作区根目录绝对路径。"
    },
    "content": {
      "type": "string",
      "description": "要写入的文件内容。"
    },
    "workspace_session_id": {
      "type": "string",
      "description": "要在其中写入的现有工作区会话 ID。省略时发布一个层。"
    }
  },
  "required": [
    "sandbox_id",
    "path",
    "content"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "type": "update",
      "path": "notes.txt",
      "bytes_written": 12
    },
    "isError": false
  }
}

结果约定： 新路径的 type 为 create；已有普通文件的 type 为 update。

相关操作file_readfile_editfile_blame

file_edit

按顺序应用精确替换

修改状态

在在线会话中按顺序执行精确字符串替换；未提供会话时，发布一个带归因的层。

何时使用

  1. 每项都需要 old_string 和 new_string；replace_all 默认为 false。
  2. 未启用 replace_all 时，old_string 必须恰好出现一次；空值、缺失、歧义和无变化编辑都会失败。
  3. 编辑按数组顺序执行；省略会话会立即发布一个持久层。

工具参数

属性类型必填说明
sandbox_idstring是目标沙箱 ID（用于选择要查询的守护进程）。
pathstring是要编辑的仓库相对路径或工作区根目录绝对路径。
editsarray是按顺序执行的 { old_string, new_string, replace_all? } JSON 数组。
workspace_session_idstring否要在其中编辑的现有工作区会话 ID。省略时发布一个层。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_edit",
    "arguments": {
      "sandbox_id": "sbox-example",
      "path": "notes.txt",
      "edits": [
        {
          "old_string": "draft",
          "new_string": "ready",
          "replace_all": true
        }
      ]
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "目标沙箱 ID（用于选择要查询的守护进程）。"
    },
    "path": {
      "type": "string",
      "description": "要编辑的仓库相对路径或工作区根目录绝对路径。"
    },
    "edits": {
      "type": "array",
      "description": "按顺序执行的 { old_string, new_string, replace_all? } JSON 数组。"
    },
    "workspace_session_id": {
      "type": "string",
      "description": "要在其中编辑的现有工作区会话 ID。省略时发布一个层。"
    }
  },
  "required": [
    "sandbox_id",
    "path",
    "edits"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "type": "edit",
      "path": "notes.txt",
      "edits_applied": 1,
      "replacements": 2,
      "bytes_written": 26
    },
    "isError": false
  }
}

结果约定： edits_applied 统计编辑对象数量；replacements 统计被替换的出现次数。

相关操作file_readfile_writefile_blame

file_blame

检查已发布内容的逐行归属

只读

根据最新审计事件，返回已发布路径中每一行的所有者。

何时使用

  1. 在命令、写入或编辑产生审计事件后使用。
  2. 范围从 1 开始，并完整覆盖最新的已知文件内容。
  3. 将 owner 字符串视为不透明值；没有审计记录时返回 not_found。

工具参数

属性类型必填说明
sandbox_idstring是目标沙箱 ID（用于选择要查询的守护进程）。
pathstring是要检查归因的仓库相对路径。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_blame",
    "arguments": {
      "sandbox_id": "sbox-example",
      "path": "notes.txt"
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "目标沙箱 ID（用于选择要查询的守护进程）。"
    },
    "path": {
      "type": "string",
      "description": "要检查归因的仓库相对路径。"
    }
  },
  "required": [
    "sandbox_id",
    "path"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "path": "notes.txt",
      "ranges": [
        {
          "start_line": 1,
          "line_count": 4,
          "owner": "original"
        },
        {
          "start_line": 5,
          "line_count": 2,
          "owner": "operation:request-id"
        }
      ]
    },
    "isError": false
  }
}

结果约定： owner 可以是 workspace_session:<id>、operation:<id>、original 或 unknown。

相关操作file_readfile_writefile_edit

会话与结果约定

服务器不会流式发送 MCP 进度。命令调用返回有界的首个输出窗口；请用 read_command_lines 和 write_command_stdin 继续。每次调用都返回空的 content 数组、位于 structuredContent 的网关 envelope，以及表示工具级失败的 isError。

18 个结果