platter (Script Smith)

大浅盘

*你的电脑，放在盘子里。*

暴露的MCP服务器 阅读, 写, 编辑, Bash, 全局, grep，以及 JavaScript 通过Stdio和StreamableHTTP传输的工具。建于 包子，编译为独立的可执行文件。

设计用于基于浏览器（或任何MCP兼容）的代理，如 哈德良，控制计算机。

工具

快速开始

从发布二进制文件

从以下网址下载适用于您平台的最新二进制文件 发布，或抓住它 curl:

# Download (replace the filename for your platform)
# Available: platter-linux-x64, platter-linux-arm64, platter-darwin-x64, platter-darwin-arm64
curl -fsSL https://github.com/ScriptSmith/platter/releases/latest/download/platter-linux-x64 -o platter
chmod +x platter

./platter          # stdio mode
./platter -t http  # HTTP mode on :3100

码头工人

docker run --rm -i ghcr.io/scriptsmith/platter                                   # stdio mode
docker run --rm -p 3100:3100 ghcr.io/scriptsmith/platter -t http --host 0.0.0.0  # HTTP mode

看 码头工人 下面介绍安装路径、网络、安装额外软件和构建自定义映像。

来源

bun install
bun run dev      # run directly from TypeScript
bun run compile  # build standalone binary for current platform

用法

platter v1.x.x

Your computer, served on a platter.

Usage: platter [options]

Options:
  -t, --transport    Transport mode (default: stdio)
      --tray                     Run the HTTP server with a Linux system tray
                                 (implies --transport=http, persists state
                                 across restarts in ~/.config/platter)
  -p, --port             HTTP port (default: 3100)
      --host            HTTP bind address (default: 127.0.0.1)
      --cwd 
               Working directory for tools (default: current directory)
      --cors-origin      Allowed CORS origin (default: *)
      --auth               Auth mode: oauth, bearer, none (default: oauth)
      --auth-token        Bearer token for HTTP auth (auto-generated if omitted)
      --tls-cert 
          TLS certificate file (PEM) — enables HTTPS
      --tls-key 
           TLS private key file (PEM)

Process management:
      --max-processes    Max concurrent bash processes per session (default: 20)
      --max-sessions     Max concurrent HTTP sessions (default: unlimited)

Restrictions:
      --tools 
             Comma-separated tools to enable (default: all)
                                 Valid: read, write, edit, bash, glob, grep, js
      --allow-path 
        Restrict read/write/edit/glob/grep to this path (repeatable)
                                 Does not restrict bash or js
      --allow-command     Allow bash commands matching this pattern (repeatable)
                                 Pattern must match the entire command string
                                 Applies to bash only; does not restrict js

Sandbox (applies to bash only; the js tool is never sandboxed):
      --sandbox                  Use just-bash sandbox instead of native bash
      --sandbox-fs         Filesystem backend: memory, overlay, readwrite (default: readwrite)
      --sandbox-allow-url   Allow network access to URL prefix (repeatable)

  -h, --help                     Show this help message
  -v, --version                  Show version number

限制

您可以限制注册的工具、文件工具可以访问的文件系统路径以及bash工具可以执行的命令。

工具选择

仅注册特定工具。未注册的工具对MCP客户端完全隐藏：

platter --tools read,glob,grep    # read-only server
platter --tools read,write,edit   # no bash/search/js

路径限制

将文件访问工具（读、写、编辑、glob、grep）限制为一个或多个目录树。路径解析为绝对形式，符号链接解析为 realpath 为防止逃逸：

platter --allow-path /home/user/project
platter --allow-path /home/user/project --allow-path /tmp

命令限制

只允许bash命令 整个 命令字符串至少匹配一个正则表达式模式：

platter --allow-command "git( .*)?"                             # git only
platter --allow-command "git( .*)?" --allow-command "npm( .*)?" # git or npm
platter --allow-command "ls( .*)?" --allow-command "cat .*"     # ls or cat

模式被锚定： --allow-command "git( .*)?" 编译到 ^(?:git( .*)?)$，所以 git status 比赛，但 rm -rf / && git status 没有。

组合示例

# Locked-down: read-only tools, scoped to one directory
platter --tools read,glob,grep --allow-path /home/user/project

# Full tools, but bash restricted to git/npm, files restricted to project
platter --allow-path ./my-project --allow-command "git( .*)?" --allow-command "npm( .*)?"

活动限制在启动时记录到stderr。

认证

被控制 --auth :

OAuth 2.1(--auth oauth)

支持的MCP客户端 RFC 9728 （受保护的资源元数据）可以自动发现盘片的OAuth端点并进行身份验证，而无需手动复制令牌。

流程：

1. 客户端发现 /.well-known/oauth-authorization-server 和 /.well-known/oauth-protected-resource/mcp
2. 客户通过以下方式注册 POST /register (RFC 7591 动态客户端注册）
3. 客户端通过以下方式启动授权码+PKCE流 /authorize
4. A. 验证码 带外显示（打印到stderr，或在托盘模式下显示为桌面通知）
5. 用户看到同意页面，输入确认码，选择要授予的工具，并批准或拒绝请求
6. 客户端在以下地址交换令牌的授权码 /token
7. 后续请求使用 Authorization: Bearer

确认码证明批准请求的人可以访问盘片进程——没有它，可以到达同意页面的远程攻击者就无法批准。代码是一次性的，5分钟后过期，最多尝试5次。

访问令牌在1小时后过期，可以刷新。客户端注册将保留到 ~/.config/platter/clients.json静态承载令牌也被接受为不支持OAuth的客户端的后备方案。

持有者代币(--auth bearer)

随机承载令牌在启动时生成并打印到stderr（或以托盘模式存储在系统密钥环中）。每个请求必须包括 Authorization: Bearer 。您可以提供自己的：

platter -t http --auth bearer --auth-token my-secret-token

无身份验证(--auth none)

完全禁用身份验证（例如，在处理身份验证的反向代理后面）：

platter -t http --auth none

TLS（HTTPS）

要通过HTTPS提供服务，请提供PEM编码的证书和私钥：

platter -t http --tls-cert cert.pem --tls-key key.pem

两者 --tls-cert 和 --tls-key 需要一起。如果提供，服务器将通过HTTPS而不是普通HTTP进行监听。

要生成用于开发或受信任的内部使用的自签名证书，请执行以下操作：

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=myserver'
platter -t http --tls-cert cert.pem --tls-key key.pem

标准模式

用于生成子流程的Claude Desktop、Cursor和其他MCP客户端：

{
  "mcpServers": {
    "platter": {
      "command": "/path/to/platter"
    }
  }
}

HTTP模式（流式HTTP）

对于基于浏览器的代理和远程连接：

platter -t http -p 3100

服务器在以下位置公开了一个端点 /mcp 它处理：

• POST /mcp -JSON-RPC消息（初始化、工具调用）
• GET /mcp -SSE通知流
• DELETE /mcp -会话拆除

默认情况下，所有来源都启用了CORS（反映了请求 Origin).要限制到特定的来源：

platter -t http --cors-origin https://myapp.example.com

会话通过 Mcp-Session-Id 根据StreamableHTTP规范的标头。

服务器验证 Host 标题以防止 DNS重新绑定攻击.何时 --cors-origin 已设置 Origin 标头也在服务器端进行验证（不仅仅是通过CORS响应标头）。

托盘模式（Linux）

使用系统托盘图标将盘片作为持久后台服务运行：

platter --tray

这意味着 --transport=http 并补充道：

• 系统托盘图标 通过DBus（StatusNotifierItem协议），与KDE、GNOME（带AppIndicator扩展）和其他桌面环境兼容。
• 持久配置 在 ~/.config/platter/config.json --身份验证令牌、启用的工具、端口、主机和工作目录在重启后仍然有效。
• 动态工具切换 --在运行时从托盘菜单启用或禁用单个工具。更改会持续存在并立即生效。
• 身份验证令牌管理 --将服务器URL或身份验证令牌复制到剪贴板，或重新生成令牌。令牌在可用时存储在系统密钥环中，回退到配置文件。
• 服务器控件 --从托盘菜单启动、停止和重新启动HTTP服务器。

Linux安装程序

这 linux/install.sh 脚本执行用户级安装（否 sudo 必填）：

./linux/install.sh                  # install
./linux/install.sh --uninstall      # remove

这将安装：

• ~/.local/bin/platter --二进制
• ~/.local/share/applications/platter.desktop --桌面启动器条目
• ~/.local/share/icons/hicolor/scalable/apps/platter.svg --应用程序图标
• ~/.config/systemd/user/platter.service --用于自动启动的systemd用户单元

安全

网络（HTTP模式）

• TLS（HTTPS） -可选传输加密，通过 --tls-cert 和 --tls-key.使用Node.js https 带有PEM编码证书和密钥文件的模块。
• OAuth 2.1+PKCE (--auth oauth，默认）-MCP客户端通过授权码流使用PKCE进行身份验证(RFC 7636).支持动态客户端注册(RFC 7591)令牌撤销(RFC 7009).
• 带外同意确认 -OAuth同意页面需要一个仅向盘片操作员显示的确认码（通过stderr或桌面通知）。这可以防止CSRF和跨源攻击自动批准授权请求。同意页面也受到保护 X-Frame-Options: DENY, Sec-Fetch-Site 验证，以及 Origin 标题检查。
• 承载令牌身份验证 -静态承载令牌（RFC 6750）可作为回退 oauth 模式和作为唯一的方法 bearer 模式。启动时会生成一个随机的256位令牌，除非您提供 --auth-token 或设置 --auth none.
• 主机标头验证 -防止 DNS重新绑定攻击本地主机绑定仅接受 127.0.0.1, localhost，以及 ::1；远程绑定只接受指定的 --host.
• 原产地验证 -何时 --cors-origin 设置为特定来源，请求不匹配 Origin 标头被403主动拒绝（不仅仅是通过CORS响应标头过滤）。

限制（尽最大努力）

--tools, --allow-path，以及 --allow-command 是 纵深防御 控制。它们大大提高了标准，但不是沙箱。在威胁模型中依赖以下限制之前，应该先了解它们。

他们擅长什么

• 工具选择 在注册时执行。禁用的工具永远不会通过MCP协议暴露。客户端无法调用或发现它们。
• 路径验证 通过以下方式解析符号链接 realpath() 在比较之前，在目标和每个允许的路径上，防止通过以下路径遍历 ../ 或符号链接目录。对于尚不存在的写入目标，将解析最近的现有祖先。
• 命令验证 锚定正则表达式模式以匹配完整的命令字符串，防止附加等琐碎的绕过 && malicious-command.

已知的限制和旁路

• Bash本质上是不受限制的。 启用bash工具后，一个足够有创意的命令可以绕过 --allow-path 完全（例如。 cat /etc/passwd).如果你设置 --allow-path 无需设置 --allow-command 或从中删除bash --tools，启动时会打印警告。对于强文件访问控制，请禁用bash(--tools read,write,edit,glob,grep)或成对 --allow-path 与一个紧 --allow-command 对抗主义者。
• 这 js 该工具不是安全沙箱。 它在Node.js中运行代码 vm 上下文，其中 明确指出 *不* 一种安全机制——不可信代码可以通过已知技术逃离上下文。即使没有转义，运行时也会暴露 fetch （任意网络访问，包括私有/环回地址）， Buffer和a load() 从下载并执行任意代码的助手 unpkg.com 或任何其他URL --allow-path, --allow-command, --sandbox，或 --sandbox-allow-url 适用于 js 工具——这些标志只影响文件和bash工具。如果 js 工具启用后，将服务器视为具有与不受限制的bash大致相同的爆炸半径。要禁用它： --tools read,write,edit,bash,glob,grep。为了实现强隔离，请在容器或VM内运行盘片。
• 命令正则表达式对原始字符串进行操作。 它不解析shell语法。图案如 --allow-command "git( .*)?" 块 rm && git status （因为完整字符串不匹配），但一个有决心的攻击者可以构造正则表达式匹配但执行意外代码的命令，例如，如果允许的模式太宽。尽可能窄地写模式。
• Symlink 触摸。 路径验证在检查时解析符号链接。如果在检查和实际文件操作之间更改了符号链接目标，则可以绕过验证。这是用户空间路径检查的一个基本限制。
• Glob/grep搜索范围。 --allow-path 验证glob和grep的搜索目录，但该目录树中的结果可能包含指向其外部的符号链接。这些符号链接目标的内容可以在grep输出中返回或由glob列出。
• 没有进程级沙盒。 所有限制都在盘片进程中的应用程序代码中强制执行。它们不使用操作系统级机制（seccomp、命名空间、质押等）。盘片本身、Bun或依赖关系中的漏洞可以绕过所有限制。

为了加强隔离，请使用bash沙盒、Docker容器或两者兼而有之。

沙盒模式（仅bash）

选择加入 只是bash，一个带有虚拟文件系统的bash的TypeScript重新实现，用于沙盒命令执行。不生成本地进程；shell完全在Bun运行时中运行。

platter --sandbox                                               # readwrite fs, no network
platter --sandbox --sandbox-fs memory                           # pure in-memory fs
platter --sandbox --sandbox-fs overlay                          # reads from disk, writes ephemeral
platter --sandbox --sandbox-allow-url "https://api.example.com" # allow network to prefix

文件系统模式

网络接入

网络访问是 默认情况下禁用.使用 --sandbox-allow-url （可重复）以允许访问特定的URL前缀。私有/环回IP始终被拒绝。

platter --sandbox --sandbox-allow-url "https://api.github.com" --sandbox-allow-url "https://registry.npmjs.org"

与其他限制的交互

• --allow-path：In readwrite 和 overlay 在模式中，每个允许的路径都被挂载到沙箱中。在 memory 模式， --allow-path 被忽略。
• --allow-command：在沙盒执行命令之前，命令正则表达式验证仍然适用。
• --sandbox 抑制bash+ --allow-path 警告，因为沙盒强制执行文件系统边界。

局限性

• 不是完整的bash。 只是bash是TypeScript的重新实现；一些边缘案例的行为可能与GNU bash不同。
• 没有本机二进制文件。 命令如下 git, node, docker, rg, python 不可用。只有bash内置程序和bash的内置命令集可以工作。
• Beta软件。 justbash正在积极开发中。在生产中依赖工作流之前，先测试一下它。

容器隔离（Docker）

在Docker容器中运行盘片通过Linux命名空间和cgroups提供操作系统级隔离。容器边界限制了bash工具可以访问的内容。即使是不受限制的命令也只能访问容器公开的文件系统和网络。

# Minimal: no host filesystem, no network
docker run --rm -i --network none ghcr.io/scriptsmith/platter

# Read-only project access, no bash
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work:ro \
  ghcr.io/scriptsmith/platter -t http --host 0.0.0.0 --tools read,glob,grep

# Full tools, scoped to a mounted directory
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work \
  ghcr.io/scriptsmith/platter -t http --host 0.0.0.0 --allow-path /work

容器执行什么

• 文件系统边界。 仅显式挂载路径(-v)可见。即使启用了bash，命令也无法读取或写入未挂载的主机路径。
• 网络边界。 --network none 完全禁用网络。没有它，容器可以出站访问，但无法访问仅主机服务，除非 --network host 使用。
• 过程隔离。 容器内的进程无法看到或通知主机进程。
• 资源限制。 Docker的 --memory, --cpus，以及 --pids-limit 标志可以限制资源使用，以防止拒绝服务。

容器与虚拟机

结合沙箱和容器

bash沙箱和Docker容器分别处理不同的层。它们一起使用，可以提供深度防御：

# Maximum isolation: sandbox inside a container, overlay fs, no network
docker run --rm -i --network none \
  -v /home/user/project:/work:ro \
  ghcr.io/scriptsmith/platter --sandbox --sandbox-fs overlay

# Sandbox with controlled network access inside a container
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work \
  ghcr.io/scriptsmith/platter -t http --host 0.0.0.0 \
    --sandbox --sandbox-allow-url "https://api.github.com"

为了获得最高的安全性，还可以以非root用户身份运行容器(--user)，放弃所有功能(--cap-drop ALL)，并将文件系统设置为只读(--read-only)使用tmpdir进行任何所需的写入：

docker run --rm -p 3100:3100 \
  --user 1000:1000 \
  --cap-drop ALL \
  --read-only --tmpfs /tmp \
  -v /home/user/project:/work \
  ghcr.io/scriptsmith/platter -t http --host 0.0.0.0 --sandbox

看 码头工人 获取完整的使用说明，包括安装路径、网络和构建自定义映像。

码头工人

Docker镜像基于Debian Bookworm（slim），并包含ripgrep。多拱形图像(linux/amd64, linux/arm64)在每个标记的版本上发布到GitHub容器注册表。

docker pull ghcr.io/scriptsmith/platter        # latest release
docker pull ghcr.io/scriptsmith/platter:1.0.0  # specific version

在stdio模式下运行

通过stdin/stdout传输JSON-RPC消息：

docker run --rm -i ghcr.io/scriptsmith/platter

在HTTP模式下运行

绑定到 0.0.0.0 在容器内部，因此可以从主机访问端口：

docker run --rm -p 3100:3100 ghcr.io/scriptsmith/platter -t http --host 0.0.0.0

安装路径

将主机目录装载到容器中并使用 --cwd 或 --allow-path 要提供盘片访问权限：

# Mount a project directory as the working directory
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work \
  ghcr.io/scriptsmith/platter -t http --host 0.0.0.0

# Mount read-only
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work:ro \
  ghcr.io/scriptsmith/platter -t http --host 0.0.0.0 --tools read,glob,grep

# Mount multiple directories with path restrictions
docker run --rm -p 3100:3100 \
  -v /home/user/project:/project \
  -v /tmp/scratch:/scratch \
  ghcr.io/scriptsmith/platter -t http --host 0.0.0.0 \
    --cwd /project \
    --allow-path /project --allow-path /scratch

网络

默认情况下，容器具有完全的出站网络访问权限。你可以通过Docker的网络选项来限制这一点：

# No network access (file-only tools)
docker run --rm --network none -i ghcr.io/scriptsmith/platter

# Access host services (e.g. a local database)
docker run --rm -p 3100:3100 --network host ghcr.io/scriptsmith/platter -t http --host 0.0.0.0

在运行时安装其他软件

该镜像使用Debian，因此您可以安装带有 apt-get 在运行时。这对于快速实验很有用，但会增加启动延迟。对于生产使用，请构建一个自定义映像（见下文）。

docker run --rm -p 3100:3100 ghcr.io/scriptsmith/platter \
  bash -c "apt-get update && apt-get install -y git nodejs && exec platter -t http --host 0.0.0.0"

或交互式：

docker run --rm -it --entrypoint bash ghcr.io/scriptsmith/platter
# inside the container:
apt-get update && apt-get install -y git python3
platter -t http --host 0.0.0.0

构建自定义映像

在盘片映像之上添加额外的工具，以实现即用型环境：

FROM ghcr.io/scriptsmith/platter:latest

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      git \
      curl \
      python3 \
      nodejs \
      npm \
 && rm -rf /var/lib/apt/lists/*

构建并运行：

docker build -t my-platter .
docker run --rm -p 3100:3100 -v ~/project:/work my-platter -t http --host 0.0.0.0

在当地建立形象

docker build -t platter .
docker run --rm -i platter

构建

bun install
bun run build        # bundle to dist/
bun run compile      # standalone binary for current platform -> ./platter
bun run compile:all  # cross-compile for linux-x64, linux-arm64, darwin-x64, darwin-arm64
bun run format       # format with Biome
bun run format:check # check formatting
bun run lint         # lint with Biome
bun run lint:fix     # lint and auto-fix with Biome
bun run typecheck    # typecheck with TypeScript
bun run test         # run tests

许可证

麻省理工学院