Meta Agent Tools
PT

Back to the catalog

io.github.briefroom/mcp

briefroom stdio MCP server — expose the briefroom CLI to Claude Code, Codex, and other agents.

Open source Open in the app JSON README (API)

About

briefroom stdio MCP server — expose the briefroom CLI to Claude Code, Codex, and other agents.

Details

Kind
MCP servers
Topic
Developer tools
Publisher
briefroom
Origin
official
Category
ferramentas
Transport
local
Version
0.3.0
Last push
2026-07-25T01:08:46Z
Repository state
ativo
Language
TypeScript
License
MIT
Added
2026-08-29 03:02:32
Updated
2026-08-29 03:02:32
Origin id
io.github.briefroom/mcp

README

# @briefroom/mcp

> 日本語版 README: [README.ja.md](./README.ja.md)

**briefroom stdio MCP server** — expose the [briefroom](https://briefroom.net) CLI to Claude Code, Codex, Cursor, and other agents so they can deploy HTML and pull reviewer comments without spawning shells themselves.

- **Deploy in one call** — zip a local directory, upload it, get a share URL back.
- **Pull reviewer feedback** — grab comments from the browser as AI-agent-ready Markdown.
- **List your rooms** — enumerate your existing deploys with their share URLs.

<!-- demo.gif placeholder — record a Claude Code / Cursor session driving deploy_html + get_feedback -->

## Add it to Claude Code (one command)

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

Set `BRIEFROOM_TOKEN` in your environment (create a PAT at [briefroom.net/dashboard/settings/tokens](https://briefroom.net/dashboard/settings/tokens)) or run `npx @briefroom/cli login` once to store it in the OS keychain.

## What it gives your agent

| Tool | What it does |
|---|---|
| `deploy_html` | Zip a local directory and upload it to briefroom. Returns a share URL. |
| `get_feedback` | Fetch reviewer comments for a share URL as AI-agent-ready Markdown (default) or JSON. |
| `list_deployments` | List rooms owned by the current PAT with their latest deploy and share URL. |

Internally each tool runs `@briefroom/cli` as a child process (`process.execPath` → `node <cli>/dist/index.js`), so behavior stays identical to the CLI and both packages evolve together.

## Install

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

## Configure

Config file location and `env` interpolation semantics differ per client. Pick the block that matches yours.

### Claude Code

Put `.mcp.json` at your project root. Claude Code expands `${VAR}` against the launching shell's environment:

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

Or register it via the Claude Code CLI:

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

### Codex CLI

Codex reads MCP server definitions from `~/.codex/config.toml` (see the [Codex CLI docs](https://github.com/openai/codex/blob/main/docs/config.md#mcp_servers)):

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

Or omit the `env` block and let the MCP process inherit `BRIEFROOM_TOKEN` from the shell that launched Codex.

### Cursor

Cursor does not expand `${VAR}` inside `env` blocks in its MCP config, so you have to decide up front how to supply the PAT. Options, in preference order:

**Option A — user-wide config with a literal PAT (keeps PAT out of any repo):**

`~/.cursor/mcp.json`:

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

The file lives in your home directory, so there's no path for it to end up in a project's git history.

**Option B — inherit from the parent shell (no PAT in any config file):**

Either `~/.cursor/mcp.json` or the project's `.cursor/mcp.json`, with **no `env` block**:

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

With `env` omitted, the MCP process inherits your shell's environment. If you've run `npx @briefroom/cli login`, the CLI reads the PAT from the OS keychain. Alternatively, launch Cursor from a shell that has `BRIEFROOM_TOKEN=hak_...` exported.

**Not recommended — project `.cursor/mcp.json` with a literal PAT:**

> If you must put a literal PAT in the project's `.cursor/mcp.json`, add that file to `.gitignore` and never commit it. Leaked PATs in public repos are a well-known incident class — prefer options A or B above. Rotate the PAT at [briefroom.net/dashboard/settings/tokens](https://briefroom.net/dashboard/settings/tokens) if you commit one by accident.

### Other stdio-MCP clients (Cline / Roo Code / Continue / …)

The stanza above works verbatim, but consult your client's docs for `${VAR}` interpolation semantics and PAT-in-file safety before adopting it — the same "user-wide file or env inheritance" preference order applies.

## Authentication

Two options — pick whichever fits your setup:

1. **`BRIEFROOM_TOKEN` env var** (recommended for `.mcp.json`): create a PAT at [briefroom.net/dashboard/settings/tokens](https://briefroom.net/dashboard/settings/tokens) and pass it through the `env` block above.
2. **OS keychain** (recommended for local dev): run `npx @briefroom/cli login` once. The MCP server picks up the same credential automatically.

`BRIEFROOM_TOKEN` takes precedence over the keychain when both are set.

`get_feedback` also works without any credentials — comments on a share URL are public API. Auth only unlocks owner-only fields.

## Configuration reference

| Env var | Purpose | Default |
|---|---|---|
| `BRIEFROOM_TOKEN` | Personal Access Token. Skips the keychain lookup. | (unset) |
| `BRIEFROOM_API_URL` | Point the CLI at a different backend (dev / staging). | `https://briefroom.net` |

## Tool reference

### `deploy_html`

```jsonc
{
  "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 — "7d" | "30d" | "never" (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"; "unlisted" clears an existing password
}
```

Returns the raw CLI JSON (`share_url`, `room_id`, `version_number`, `visibility`, …).

Three identifiers that are easy to confuse:

| Field | What it is |
|---|---|
| `name` | Display name shown on the dashboard and in the viewer. Any language. Set it on the first deploy; on a redeploy it updates the room name **only when passed explicitly** (omit it to keep the current name). |
| `room` | Room slug — an ascii kebab-case identifier used only to find the existing room to redeploy into. Never part of the share URL. |
| share URL | Always auto-issued with a random token (`/s/<token>`). Not derived from `name` or `room`. |

### `get_feedback`

```jsonc
{
  "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"
}
```

Returns Markdown by default, formatted so an agent can paste it straight back into context.

### `list_deployments`

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

Returns the raw `/api/v1/rooms` JSON.

## Debugging

Log lines are written to **stderr only** — stdout is reserved for JSON-RPC. To see what the server does:

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

Point the inspector at a running backend with `BRIEFROOM_API_URL=http://localhost:3000` when developing against a local dev server.

## Roadmap

- `resolve_comment` — pending backend PAT support on the comment PATCH endpoint.
- Streamable HTTP transport for hosted usage.

## Contributing

Issues and pull requests are welcome at [github.com/briefroom/mcp](https://github.com/briefroom/mcp). The public repo mirrors the internal source of truth in the briefroom monorepo; changes land upstream first, then are exported here.

Local dev inside this repo:

```bash
npm install
npm run build
npm test
```

## License

MIT © Talent Cloud, Inc.

More