warp-ozbridge

@sena-labs/oz-mcp-server

适用于 Warp™ Oz™ Agent 的独立模型上下文协议服务 — 无需 VS Code。可在终端中运行，并通过 Claude Code、Cursor、Codex 或任何 MCP 客户端驱动 Oz。

OzBridge 是一个独立项目，与 Warp 无关联，也未获得 Warp 的认可或赞助。“Warp”和“Oz”是 Warp, Inc. 的商标，此处仅用于指称，仅为说明互操作性。请参阅下文的商标与免责声明。

此软件包是 OzBridge 扩展的无 VS Code 版本。它通过 stdio 或 Streamable HTTP 提供相同的 MCP 工具接口（六种工具：oz_agent_run、oz_run_list、……），因此任何 MCP 客户端都可以启动并检查 Oz 运行。

---

要求

• Node.js ≥ 22.12
• 已安装 Oz CLI，且位于 PATH 中（或通过 OZ_PATH 指定）。 从 https://www.warp.dev/download 下载 Warp — oz 命令随其附带（在 Linux 上通常位于 ~/.warp/bin/oz）。使用 oz --version 验证。
• 已登录 Warp：在终端中运行一次 oz login。

此服务只会调用文档所述的 oz CLI；不会嵌入、修改或逆向工程任何 Warp 软件。

---

快速开始（stdio — 推荐）

让 MCP 客户端通过 stdio 启动服务 — 无需安装步骤、端口或令牌，也无需保持终端打开。

Claude Code：

claude mcp add oz -- npx -y @sena-labs/oz-mcp-server --stdio

Codex CLI — 添加到 ~/.codex/config.toml：

[mcp_servers.oz]
command = "npx"
args = ["-y", "@sena-labs/oz-mcp-server", "--stdio"]

Cursor / Windsurf / Claude Desktop — 添加到 ~/.cursor/mcp.json（Cursor）、~/.codeium/windsurf/mcp_config.json（Windsurf）或 claude_desktop_config.json（Claude Desktop）：

{
  "mcpServers": {
    "oz": {
      "command": "npx",
      "args": ["-y", "@sena-labs/oz-mcp-server", "--stdio"]
    }
  }
}

HTTP 模式

若要运行可由客户端通过 URL 访问的长期运行服务：

npx -y @sena-labs/oz-mcp-server

它会绑定到 127.0.0.1:3847。保持服务运行，然后将 MCP 客户端指向 Streamable HTTP 端点 http://127.0.0.1:3847/mcp — 请参阅 MCP 客户端配置（HTTP）。旧版 HTTP+SSE 端点 /sse 仍可使用，但已弃用。

固定端口和承载令牌，而不使用默认值：

npx -y @sena-labs/oz-mcp-server --port 3847 --token my-secret

如果不想每次运行时都重新下载，可以全局安装：

npm install -g @sena-labs/oz-mcp-server
oz-mcp-server --help

---

配置

设置按以下顺序解析（优先级从高到低）：

1. CLI 标志
2. 环境变量
3. ./.warp/warp-bridge.yaml（当前工作目录），然后是 ~/.warp/warp-bridge.yaml
4. 编译时默认值

CLI 标志

标志	默认值	用途
--port <n>	3847	监听的 TCP 端口。0 表示由操作系统选择临时端口。
--bind <addr>	127.0.0.1	绑定的接口。绑定到非环回地址需要令牌（请参阅安全性）。
--token <s>	(无)	每个请求都必须提供的承载令牌。留空 = 不进行身份验证。
--cwd <dir>	process.cwd()	用于查找 .warp/warp-bridge.yaml 的工作区根目录。
--help、-h	—	打印用法并退出。

环境变量

变量	映射到	默认值	用途
OZ_PATH	ozPath	oz	Oz CLI 二进制文件的路径。裸写 oz 时会从 PATH 中解析。
OZ_MCP_PORT	port	3847	监听端口。0 = 由 OS 分配临时端口。
OZ_MCP_BIND	bind address	127.0.0.1	要绑定的接口（默认仅限回环接口）。
OZ_MCP_TOKEN	bearer token	(empty)	每个请求都必须提供的 Bearer token。留空则禁用身份验证。
OZ_DEFAULT_MODEL	defaultModel	auto	运行时使用的默认 AI 模型。
OZ_DEFAULT_PROFILE	defaultProfile	Default	默认 Oz Agent 配置文件。
OZ_DEFAULT_ENV	defaultEnvironment	(empty)	默认云环境 ID。
OZ_TIMEOUT_MS	local run timeout	300000	本地运行的硬超时时间（ms）。
OZ_IDLE_TIMEOUT_MS	idle timeout	90000	CLI 无输出达到此时长后中止运行（ms）。0 表示禁用。

OZ_PATH=/usr/local/bin/oz \
OZ_MCP_PORT=3847 \
OZ_MCP_TOKEN=my-secret \
npx -y @sena-labs/oz-mcp-server

在 Windows PowerShell 中，先使用 $env: 设置变量：

$env:OZ_MCP_TOKEN = "my-secret"; npx -y @sena-labs/oz-mcp-server

---

传输方式

服务通过两种传输方式提供 MCP：

• stdio（--stdio）——主机将服务作为子进程启动，并通过 stdin/stdout 交换 JSON-RPC。推荐用于 Claude Code、Codex、Cursor、Windsurf、Claude Desktop、mcp-proxy 和注册表沙盒（例如 Glama）。无需端口，也无需 token。参见快速开始（stdio，推荐）。
• Streamable HTTP（未传入 --stdio 时的默认方式）——服务监听一个端口，客户端通过 URL 连接到 /mcp。较旧的 HTTP + SSE 传输方式（/sse + /messages）仍为旧版客户端提供服务，但已弃用。

# stdio (spawned by the host)
npx -y @sena-labs/oz-mcp-server --stdio

# HTTP (default) — endpoint http://127.0.0.1:3847/mcp
npx -y @sena-labs/oz-mcp-server --port 3847

MCP 客户端设置（HTTP）

对于基于 URL 的客户端，先以 HTTP 模式启动服务（如上所述），然后将端点添加到客户端。这些代码片段与 docs/MCP.md中的内容一致。

Claude Code

claude mcp add --transport http oz http://127.0.0.1:3847/mcp

Cursor / Windsurf

添加到 ~/.cursor/mcp.json（或 ~/.codeium/windsurf/mcp_config.json）：

{
  "mcpServers": {
    "oz": {
      "url": "http://127.0.0.1:3847/mcp"
    }
  }
}

Codex CLI

添加到 ~/.codex/config.toml：

[mcp_servers.oz]
url = "http://127.0.0.1:3847/mcp"

如果设置了 token

使用 --token / OZ_MCP_TOKEN 时，每个请求都需要带上 Authorization: Bearer <token> 请求头：

• Claude Code：在 claude mcp add 后追加 --header "Authorization: Bearer <token>"。
• Cursor / Windsurf：在 "url" 旁添加 "headers": { "Authorization": "Bearer <token>" }。
• Codex：在 [mcp_servers.oz] 下添加 http_headers = { "Authorization" = "Bearer <token>" }。

---

暴露的工具

工具	用途
oz_agent_run	在本地运行带提示词的 oz agent run。返回完整的运行负载。
oz_agent_run_cloud	启动云端运行。会消耗 Warp 点数。
oz_run_get	按 ID 获取运行状态和输出。只读。
oz_run_list	列出近期运行；可按 all / active / completed / 原始状态筛选，并指定数字型 limit。
oz_list_models	列出账户可用的 AI 模型 ID，并报告当前默认模型。只读。
oz_set_default_model	将 defaultModel 写入工作区 .warp/warp-bridge.yaml，以设置默认 Oz 模型。

每个工具的完整 JSON inputSchema 都会由 tools/list 原样输出。 有关协议详情、原始 curl 速查表和端点参考，请参见 docs/MCP.md。

---

端点

路由	方法	用途
/mcp	POST	可流式 HTTP — 单个 JSON‑RPC 2.0 请求，并在同一个 HTTP 响应中返回答复。请使用此端点。
/sse	GET	旧版（已弃用）。 打开 SSE 流。第一个帧是包含要 POST 到的 sessionId 的 event: endpoint。
/messages?sessionId=<uuid>	POST	旧版（已弃用）。 单个 JSON‑RPC 2.0 请求。服务器以 202 确认；响应通过 /sse 流式返回。
/health	GET	返回 { ok, name, version, tools, sessions }。

快速健康检查：

curl http://127.0.0.1:3847/health

---

安全性

• 默认仅绑定回环地址。 服务绑定到 127.0.0.1；除非你主动选择，否则不会有流量离开本机。
• 绑定到非回环地址时必须提供令牌。 若未设置 --token / OZ_MCP_TOKEN，绑定到 127.0.0.1 / ::1 以外的地址将被拒绝——MCP 工具可以启动 Oz CLI，因此绝不允许未经身份验证的公网绑定。
• 设置令牌后，所有路由（包括 /health）均受 Bearer 身份验证保护； 比较采用恒定时间算法。
• 不持久化数据。 提示词内容和运行输出会转发给 Oz CLI，服务不会存储这些内容。

本服务不提供 TLS 终止——如需 HTTPS，请将服务置于经过身份验证的反向代理之后。

---

商标与免责声明

OzBridge 是由 Ivan Sena 以 Sena Labs 名义开发的独立项目，与 Warp, Inc.、Microsoft、GitHub 或 Visual Studio Code 项目没有任何关联，也未获得其认可或赞助，且并非其官方项目。

Warp™ 和 Oz™ 是 Warp, Inc. 的商标。本项目使用这些名称仅作指称性用途——仅用于说明 OzBridge 可与 Warp Oz 互操作——并不表示获得任何赞助、认可或存在关联。

OzBridge 仅使用 Warp 公开文档中说明的接口——oz 命令行工具和 Model Context Protocol 传输。它不会修改、逆向工程、嵌入 Warp 软件，也不会据此创作衍生作品；它是互补集成，而非竞争产品或服务。

本软件按“原样”提供，不附带任何形式的保证。使用风险由你自行承担。完整内容请参阅 DISCLAIMER.md。

---

许可证

MIT © Sena Labs