briefroom

@briefroom/mcp

日文版 README：README.ja.md

briefroom stdio MCP 服务 — 将 briefroom CLI 提供给 Claude Code、Codex、Cursor 和其他 Agent，让它们无需自行启动 shell 即可部署 HTML 并获取审阅者评论。

• 一次调用即可部署 — 将本地目录打包成 zip 并上传，获取分享 URL。
• 获取审阅反馈 — 从浏览器获取评论，并转换为适用于 AI Agent 的 Markdown。
• 列出你的房间 — 列出你现有的部署及其分享 URL。
• 仅供自己使用 — 直接部署到私人房间，只有登录后才能打开。

将其添加到 Claude Code（一条命令）

claude mcp add briefroom -- npx -y @briefroom/mcp

在环境中设置 BRIEFROOM_TOKEN（在 briefroom.net/dashboard/settings/tokens 创建 PAT），或运行一次 npx @briefroom/cli login 将其保存到操作系统密钥链。

它能为你的 Agent 提供什么

工具	功能
deploy_html	将本地目录打包成 zip 并上传到 briefroom。返回分享 URL。
get_feedback	获取分享 URL 对应的审阅者评论，返回适用于 AI Agent 的 Markdown（默认）或 JSON。
list_deployments	列出当前 PAT 所属的房间，以及每个房间的最新部署和分享 URL。

在内部，每个工具都会将 @briefroom/cli 作为子进程运行（process.execPath → node <cli>/dist/index.js），因此行为与 CLI 保持一致，两个包也会协同演进。

安装

npm i -g @briefroom/mcp
# or use it via npx (recommended for .mcp.json)

配置

配置文件位置和 env 插值语义因客户端而异。选择与你使用的客户端相符的配置块。

Claude Code

在项目根目录放置 .mcp.json。Claude Code 会根据启动 shell 的环境展开 ${VAR}：

{
  "mcpServers": {
    "briefroom": {
      "command": "npx",
      "args": ["-y", "@briefroom/mcp"],
      "env": {
        "BRIEFROOM_TOKEN": "${BRIEFROOM_TOKEN}"
      }
    }
  }
}

或者通过 Claude Code CLI 注册：

claude mcp add briefroom -- npx -y @briefroom/mcp

Codex CLI

Codex 从 ~/.codex/config.toml 读取 MCP 服务定义（参见 Codex CLI 文档）：

[mcp_servers.briefroom]
command = "npx"
args = ["-y", "@briefroom/mcp"]
env = { BRIEFROOM_TOKEN = "hak_your_pat_here" }

也可以省略 env 块，让 MCP 进程继承启动 Codex 的 shell 环境中的 BRIEFROOM_TOKEN。

Cursor

Cursor 不会展开 MCP 配置中 env 块里的 ${VAR}，因此你需要预先决定如何提供 PAT。选项按推荐顺序排列：

选项 A — 使用包含明文 PAT 的用户级配置（避免 PAT 出现在任何仓库中）：

~/.cursor/mcp.json：

{
  "mcpServers": {
    "briefroom": {
      "command": "npx",
      "args": ["-y", "@briefroom/mcp"],
      "env": { "BRIEFROOM_TOKEN": "hak_your_pat_here" }
    }
  }
}

该文件位于你的主目录中，因此不会进入项目的 git 历史记录。

选项 B — 继承父 shell 环境（配置文件中不含 PAT）：

使用 ~/.cursor/mcp.json 或项目的 .cursor/mcp.json，并且不包含 env 块：

{
  "mcpServers": {
    "briefroom": {
      "command": "npx",
      "args": ["-y", "@briefroom/mcp"]
    }
  }
}

省略 env 后，MCP 进程会继承 shell 的环境。如果你运行过 npx @briefroom/cli login，CLI 会从操作系统密钥链读取 PAT。或者，从已导出 BRIEFROOM_TOKEN=hak_... 的 shell 启动 Cursor。

不推荐 — 项目 .cursor/mcp.json 中包含明文 PAT：

如果必须在项目的 .cursor/mcp.json 中放入明文 PAT，请将该文件添加到 .gitignore，并且绝不要提交。PAT 泄露到公开仓库是众所周知的一类安全事件——优先选择上面的选项 A 或 B。如果不慎提交了 PAT，请在 briefroom.net/dashboard/settings/tokens 轮换该 PAT。

其他 stdio-MCP 客户端（Cline / Roo Code / Continue / …）

上面的配置段可以原样使用，但采用前请查阅客户端文档，了解 ${VAR} 插值语义以及在文件中保存 PAT 的安全性——同样应优先选择“用户级文件或继承环境变量”。

身份验证

有两种方式，可根据你的设置选择：

1. BRIEFROOM_TOKEN 环境变量（推荐用于 .mcp.json）：在 briefroom.net/dashboard/settings/tokens 创建 PAT，并通过上方的 env 块传入。
2. OS 钥匙串（推荐用于本地开发）：运行一次 npx @briefroom/cli login。MCP 服务会自动读取同一凭据。

同时设置时，BRIEFROOM_TOKEN 的优先级高于钥匙串。

存储在钥匙串中的登录信息与签发它的 API 源站绑定，绝不会发送到其他源站。如果你设置了 BRIEFROOM_API_URL（开发／预发布环境），请运行 npx @briefroom/cli login --api-url <url> 登录该源站，或传入 BRIEFROOM_TOKEN。BRIEFROOM_TOKEN 仅通过 https 发送（仅 localhost 允许使用纯 http）。

get_feedback 无需凭据也能使用——分享 URL 上的评论属于公开 API。身份验证仅用于解锁仅所有者可见的字段。

配置参考

环境变量	用途	默认值
BRIEFROOM_TOKEN	个人访问令牌。跳过钥匙串查找。	（未设置）
BRIEFROOM_API_URL	将 CLI 指向其他后端（开发／预发布环境）。	https://briefroom.net

工具参考

deploy_html

{
  "path": "./mockups",        // required — directory to deploy
  "room": "demo-a",           // optional — room slug: ascii identifier of the room to redeploy into
  "name": "企画書 v2",         // optional — room display name, 1-100 chars, any language
  "expires": "7d",            // optional — "24h" | "7d" | "30d" | "90d" | "never" (Free: 24h / 7d only, private rooms exempt; also updates the existing link on redeploy)
  "new": false,               // optional — start a brand new room
  "password": "s3cret",       // optional — password-protect the link (Pro+ plans; passed to the CLI via env, never argv)
  "visibility": "unlisted",   // optional — "unlisted" | "password_protected" | "email_invite_only"; "unlisted" clears an existing password
  "private": false,           // optional — true is shorthand for visibility "email_invite_only": only you, signed in, can open the room
  "allow_comments": true,     // optional — false hides the comment sidebar (viewers see the page + header only); every plan
  "display_mode": "review"    // optional — "review" (header + comment sidebar) | "live" (chrome-less full-screen page); every plan
}

返回原始 CLI JSON（share_url、room_id、version_number、visibility、allow_comments、 display_mode，……）。

重新部署时，只有显式传入 expires／password／visibility／allow_comments／display_mode，才会将其应用到现有分享链接（同一 URL）。省略某个字段则保留该设置不变。

以下三个标识符容易混淆：

字段	含义
name	显示在仪表板和查看器中的显示名称。可使用任何语言。首次部署时设置；重新部署时，只有显式传入才会更新房间名称（省略则保留当前名称）。
room	房间 slug——仅用于查找要重新部署到的现有房间的 ASCII kebab-case 标识符。绝不会出现在分享 URL 中。
分享 URL	始终自动生成并带有随机令牌（/s/<token>）。不会根据 name 或 room 生成。

get_feedback

{
  "share": "https://briefroom.net/s/aB3xQ2mK9pNvR4", // URL or bare token
  "status": "all",             // optional — "open" | "resolved" | "all"
  "since": "2026-07-01T00:00Z",// optional ISO 8601 for delta pulls
  "format": "prompt",          // optional — "prompt" (Markdown) | "json"
  "locale": "ja"               // optional — "ja" | "en"
}

默认返回 Markdown，格式适合 Agent 直接粘贴回上下文中。

list_deployments

{
  "limit": 20,     // optional — 1-100, default 20
  "archived": false
}

返回原始的 /api/v1/rooms JSON。

调试

日志仅写入 stderr——stdout 保留用于 JSON-RPC。要查看服务的运行情况：

BRIEFROOM_TOKEN=$YOUR_PAT npx @modelcontextprotocol/inspector \
  npx -y @briefroom/mcp

在针对本地开发服务进行开发时，将检查器指向正在运行的后端，并设置 BRIEFROOM_API_URL=http://localhost:3000。

路线图

• resolve_comment——等待后端支持评论 PATCH 端点的 PAT。
• 用于托管场景的 Streamable HTTP 传输。

参与贡献

欢迎通过 github.com/briefroom/mcp 提交问题和拉取请求。公开仓库与 briefroom 单体仓库中的内部权威源保持同步；更改先在上游合入，再导出到此处。

此仓库中的本地开发：

npm install
npm run build
npm test

许可证

MIT © Talent Cloud, Inc.