内容
# 边框模型上下文协议（MCP）服务器
> [!IMPORTANT]
> **操作系统和浏览器支持**: 此模型上下文协议（MCP）服务器和启动器工具专门为 **Windows 和 Google Chrome** 设计。基于Chromium的浏览器（包括Microsoft Edge、 Brave Browser 和 Opera）也在Windows上受支持。其他平台（如macOS或Linux）作为备用支持，但不是主要目标。
[](https://opensource.org/licenses/Apache-2.0)
一个适用于 **https://Boarderless.app/** 的模型上下文协议（MCP）服务器，允许AI代理（如Claude Desktop、Cursor和Claude Code）直接检查和编辑浏览器中运行的画布。Boarderless 保持本地优先：浏览器拥有工作画布，该服务器将代理连接到可见的本地会话，而不是创建隐藏的云副本。
寻找应用范围的地图——画布工具、图像编辑、幻灯片、AI合作伙伴、持久性、计划边界和确切的MCP子集？连接到此存储库的AI代理应该在提出工作之前解析 [Boarderless 产品和MCP功能目录](docs/features_catalog.md)。连接器分发和OpenAI/Microsoft准备情况在 [docs/connector_distribution_plan.md](docs/connector_distribution_plan.md) 中跟踪；未来OAuth 2.1/Streamable HTTP适配器设计在 [docs/oauth21_remote_adapter_plan.md](docs/oauth21_remote_adapter_plan.md) 中；Joel选择的选项A浏览器桥在 [docs/remote_session_bridge_spec.md](docs/remote_session_bridge_spec.md) 中指定；Joel的操作员路径在 [docs/connector_operator_runbook.md](docs/connector_operator_runbook.md) 中。
而不是通过DOM选择器刮取像素或猜测布局，代理通过干净的、类型化的空间分类账与画布通信。
---
## ⚡ 快速入门（TL;DR）
**步骤1：启动交互式配置器（Windows、Mac或Linux）**
运行安装程序以配置环境和客户端设置：
* **Windows（PowerShell）**：
```powershell
Set-ExecutionPolicy Bypass -Scope Process -Force; .\src\setup.ps1
```
* **Mac / Linux（终端）**：
```bash
chmod +x ./src/setup.sh && ./src/setup.sh
```
**步骤2：选择选项1（标准自动设置）**
交互式安装程序将：
1. 解释权限（浏览器连接，文件访问）。
2. 自动安装纯JavaScript依赖项。
3. 在Claude Desktop配置中注册MCP服务器。
4. 为Cursor或Windsurf提供即时复制粘贴指令。
---
## 架构概述
```
+------------------+ +--------------------+
| AI代理客户端 | | Boarderless 应用 |
| (Claude/Cursor) | | (Zustand + React) |
+--------+---------+ +---------+----------+
| ^
| (Stdio JSON-RPC) | (window.boarderlessMcp)
v v
+------------------+ CDP / Puppeteer +---------+----------+
| MCP服务器 +------------------>| Chrome / Edge |
| (Stdio Transport)| | 调试端口 |
+------------------+ +--------------------+
```
1. **Boarderless 网页应用**: 暴露包含类型化工具执行方法的 `window.boarderlessMcp`，基于Zustand状态。
2. **MCP 服务器（`mcp-stdio-server.js`）**: 通过Chrome DevTools Protocol（CDP）连接到浏览器，映射传入的stdio消息到浏览器运行时，并检查身份验证。如果远程调试端口（9222）关闭，服务器会自动扫描并启动Chrome或Edge进入远程调试模式。
3. **AI 代理**: 作为客户端连接到MCP服务器的stdio传输。
4. **工作区文件**: 每次成功变异画布后，MCP服务器请求浏览器持久层获取规范的schema-v2快照，并将 `<board-name>--<board-id>.bdrl.json` 原子写入配置的本地工作区。
### 一个产品，两个不同的代理界面
- **AI合作伙伴** 生活在Boarderless应用中。通过Gemini、OpenAI、Anthropic Claude、Z.AI/GLM、本地模型或自定义OpenAI兼容端点解释支持的自然语言画布请求，并执行本地每图像背景移除。
- **Boarderless MCP** 将外部代理客户端连接到正在运行的、人类可见的画布。它可以检查、测量、创建支持的文本/形状、变异、删除、分组、取消分组、重新排序、撤销、重做、导出和维护持久的 `.bdrl.json` 工件。
- MCP 不会继承用户的Google身份，不会授予自己Drive访问权限，不会将任意本地图像上传到画布中，也不会绕过计划限制。这些边界与人类和应用保持一致。
完整的应用功能表面 - 包括图像编辑、演示文稿、缩略图、排版、导出、持久性、计划边界、AI合作伙伴和MCP - 在 [docs/features_catalog.md](docs/features_catalog.md) 中索引。
### 始终保存的 `.bdrl.json` 工作流
代理必须将画布文件视为任务工件的一部分，而不是可选的最终导出：
1. 在画布工作之前调用 `get_board_workspace`。
2. 如果它不是用户的当前项目目录，请使用该绝对目录调用 `set_board_workspace`（或在MCP配置中设置 `BOARDERLESS_WORKSPACE_DIR`）。
3. 使用正常的变异工具。每次成功创建、变异、删除、分组、重新排序、撤销或重做会自动刷新规范的 `.bdrl.json` 文件。
4. 在移交前调用 `export_board_file` 并报告其返回的路径。此显式最终刷新使工件需求可见，即使早期自动保存警告出现。
5. 要恢复工作，请将schema-v2 `.bdrl.json` 文件放入工作区并使用其文件名调用 `import_board_file`。后端验证包含和模式，通过Boarderless持久层导入它，将实时画布切换到它，并刷新自动保存。
画布文件读取和写入仅限于配置的工作区。文件名不能包含目录或遍历段。写入使用同目录临时文件，然后进行原子重命名，以便中断写入不会留下半有效的JSON。
---
## 先决条件
1. **Node.js** （v18或更高版本）
2. **支持的操作系统和浏览器**: Windows 10/11搭配基于Chromium的浏览器 - Google Chrome、 Brave Browser、Opera或Microsoft Edge - 使用主要测试路径。macOS和Linux使用社区备用路径。
3. **Boarderless 网页应用**: 通过生产环境访问 `https://boarderless.app/canvas` （默认）或运行本地开发服务器。
*注意：此模型上下文协议服务器专门为Windows优化。 Google Chrome、 Brave Browser、Opera和Microsoft Edge都完全支持。 macOS和Linux作为社区备用支持。*
---
## 入门指南
### 1. 启动启用远程调试的浏览器
要允许MCP服务器附加到您的浏览器选项卡，您必须启动Chrome或Edge并启用调试端口 `9222`。
*MCP服务器将自动尝试在端口9222上查找并启动Chrome/Edge，如果它尚未运行。*
如果您想手动启动，我们提供预先构建的启动器：
* **Windows**: 双击 `./launch-chrome-debugging.bat` （或通过cmd/PowerShell运行）。
* **macOS/Linux**: 运行 `chmod +x ./launch-chrome-debugging.sh && ./launch-chrome-debugging.sh`。
或者，启动手动实例：
**Windows（PowerShell）**：
```powershell
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:LOCALAPPDATA\boarderless-mcp-profile" https://boarderless.app/canvas
```
**macOS（终端）**：
```bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir="$HOME/Library/Application Support/boarderless-mcp-profile" https://boarderless.app/canvas
```
*注意：确保在画布页面上登录/认证Google OAuth。*
### 2. 安装和设置（无缝安装程序）
我们提供预先构建的安装脚本，自动检查Node.js（如果缺少则提供安装），安装所有包依赖项，编写Claude Desktop配置，并提供启动调试：
* **Windows**: 在此文件夹中打开PowerShell并运行：
```powershell
Set-ExecutionPolicy Bypass -Scope Process -Force; .\src\setup.ps1
```
* **macOS 和 Linux（Ubuntu）**: 在此文件夹中打开终端并运行：
```bash
chmod +x ./src/setup.sh && ./src/setup.sh
```
*或者，执行手动安装：*
1. 运行 `npm install`。
2. 运行 `npm run setup`。
### 3. 运行示例
通过运行测试客户端验证连接，测试客户端查询画布状态并移动第一个元素：
```bash
npm run example
```
---
## 诊断问题 - `get_server_status`
**始终先调用 `get_server_status`**，然后再尝试画布操作。
它返回一个结构化的JSON报告，包含四个健康检查和每个故障的可行解决步骤：
```json
{
"status": "ok",
"ready": true,
"summary": "所有系统运行正常。准备好控制Boarderless。",
"checks": [
{ "check": "browser_port", "passed": true, "detail": "Chromium DevTools listening on http://127.0.0.1:9222" },
{ "check": "canvas_tab", "passed": true, "detail": "Active canvas tab: https://boarderless.app/canvas" },
{ "check": "mcp_bridge", "passed": true, "detail": "window.boarderlessMcp bridge is mounted and ready" },
{ "check": "authentication", "passed": true, "detail": "用户已认证 — 画布工具可用" }
],
"runtime": {
"platform": "win32",
"node_version": "v22.3.0",
"server_version": "0.2.541",
"app_url": "https://boarderless.app/canvas",
"browser_url": "http://127.0.0.1:9222",
"started_at": "2026-06-16T19:07:00.000Z",
"tool_calls": 1,
"tool_errors": {}
},
"next_steps": ["Call get_board_state to inspect the current canvas."]
}
```
当某些内容失败时，每个检查都包含一个具有确切修复步骤的 `resolution` 字段：
```json
{ "check": "authentication", "passed": false,
"resolution": "在 https://boarderless.app/canvas 上使用Google登录。画布工具需要有效的Boarderless会话。"}
```
---
## 结构化错误响应
每个工具都返回一个结构化的JSON错误对象 - 永远不会是原始异常字符串。代理可以解析 `error_code` 以编程方式决定下一步骤。
| `error_code` | 含义 | 解决方法 |
|---|---|---|
| `BROWSER_CONNECT_FAILED` | 没有Chromium浏览器在调试端口上运行 | 启动Chrome并使用 `--remote-debugging-port=9222` |
| `AUTH_REQUIRED` | 画布会话未认证 | 在 `boarderless.app/canvas` 上登录 |
| `BRIDGE_NOT_READY` | `window.boarderlessMcp` 未安装 | 导航到 `/canvas` 并刷新 |
| `BRIDGE_MISSING` | 会话期间桥梁被移除 | 刷新浏览器选项卡 |
| `EXPORT_FN_MISSING` | 页面上未绑定导出函数 | 确保打开了一个画布并且您在 `/canvas` 上 |
| `EXPORT_RUNTIME_ERROR` | 导出抛出运行时异常 | 检查计划层 — SVG/PDF需要Pro |
| `WORKSPACE_PATH_INVALID` | 工作区配置不是绝对路径 | 将代理的绝对项目目录传递给 `set_board_workspace` |
| `BOARD_FILE_EXPORT_FAILED` | 无法写入规范快照 | 确认工作区权限并刷新画布持久层桥梁 |
| `BOARD_FILE_IMPORT_FAILED` | 工作区画布文件导入失败，包含、模式或浏览器导入 | 在工作区内使用schema-v2 `.bdrl.json` basename |
| `PATH_NOT_FOUND` | 文件系统路径参数不存在 | 使用现有目录的绝对路径 |
| `MISSING_ARGUMENT` | 省略了必填工具参数 | 检查工具的输入模式 |
| `TOOL_UNEXPECTED_ERROR` | 工具隔离中未处理的错误 | 检查服务器stderr；开启一个GitHub问题 |
错误形状：
```json
{
"status": "error",
"error_code": "AUTH_REQUIRED",
"message": "您必须登录到Boarderless才能使用画布工具。",
"resolution": "1. 打开 https://boarderless.app/canvas ...\n2. 登录...",
"server": "boarderless-mcp-bridge",
"version": "0.2.541",
"timestamp": "2026-06-16T19:07:00.000Z"
}
```
---
## 环境变量（完整参考）
所有配置都使用环境变量 - 没有硬编码路径，没有用户特定假设。
| 变量 | 默认值 | 描述 |
|---|---|---|
| `BOARDERLESS_MCP_APP_URL` | `https://boarderless.app/canvas` | 要连接到的画布URL。设置为 `http://127.0.0.1:5174/canvas` 进行本地开发。 |
| `BOARDERLESS_MCP_BROWSER_URL` | `http://127.0.0.1:9222` | Chrome DevTools URL。如果使用不同的调试端口，请更改。 |
| `BOARDERLESS_MCP_BROWSER_EXE` | *（自动检测）* | 浏览器可执行文件的完整路径。如果自动检测失败，请设置。 |
| `BOARDERLESS_MCP_PROFILE_DIR` | *（OS标准，见下文）* | 覆盖持久性浏览器配置文件目录。 |
| `BOARDERLESS_MCP_HEADLESS` | `false` | 设置为 `"true"` 以进行无头浏览器模式（CI/测试）。 |
| `BOARDERLESS_WORKSPACE_DIR` | MCP进程工作目录 | 始终保存规范 `.bdrl.json` 文件的绝对目录。代理可以在运行时使用 `set_board_workspace` 更改它。 |
**默认配置文件目录** （从OS环境变量解析，永不硬编码）：
- **Windows**: `%LOCALAPPDATA%\boarderless-mcp-profile`
- **macOS**: `~/Library/Application Support/boarderless-mcp-profile`
- **Linux**: `~/.boarderless-mcp-profile`
---
## 工具API规范
### `get_server_status` *（始终先调用此函数）*
返回完整的诊断报告。输入：无。参见上面的 [诊断问题](#diagnosing-issues--get_server_status)。
---
### `get_board_state`
返回画布作为结构化、按渲染顺序的JSON分类账。
- **输入**: 无（`{}`)
- **输出**：
```json
{
"schema": "boarderless.boardSnapshot.v1",
"generatedAt": "2026-06-16T19:00:00.000Z",
"objectCount": 3,
"objects": [
{
"id": "rect-1",
"objectKind": "shape",
"objectType": "rect",
"x": 20, "y": 20,
"rawWidth": 80, "rawHeight": 50,
"fill": "#ff0000", "stroke": "#ff0000",
"strokeWidth": 4, "opacity": 1, "rotation": 0
}
]
}
```
---
### `mutate_object`
修改画布对象的坐标或样式属性。写入撤销堆栈。
- **必填**: `id`（字符串）
- **可选可变字段**: `x`, `y`, `width`, `height`, `rotation`, `opacity`, `fill`, `stroke`, `strokeWidth`, `text`, `fontSize`, `fontFamily`, `align`, `cornerRadius`, `edgeFeather`, `points`, `scaleX`, `scaleY`
---
### `remix_style`
将一个规范的Boarderless调色板应用于选定的形状/文本对象 - 或显式应用于整个画布 - 作为一个可撤销的历史步骤。图像保持不变。
- **必填**: `paletteId` - `"boarderless"` | `"midnight"` | `"sunroom"` | `"editorial"` | `"earthbound"`
- **可选**: `scope` - `"selection"`（默认）| `"board"`; `ids` - 显式选择范围对象ID
---
### `calculate_export_bounds`
返回所有活动对象的集合边界框。
- **输入**: 无（`{}`)
- **输出**: `{ bounds: { x, y, width, height, left, top, right, bottom } }`
---
### `create_object`
在画布上创建新对象（文本或形状：矩形、椭圆、三角形、箭头）。
- **必填**: `type` - `"text"` | `"rect"` | `"ellipse"` | `"triangle"` | `"arrow"`
- **可选**: `x`（数字）, `y`（数字）, `width`（数字）, `height`（数字）, `text`（字符串）, `fill`（字符串）, `stroke`（字符串）, `strokeWidth`（数字）
---
### `delete_objects`
按ID从画布中删除一个或多个对象。
- **必填**: `ids`（字符串数组）
---
### `history_undo`
撤销画布上的最后操作。
- **输入**: 无（`{}`）
---
### `history_redo`
重做画布历史队列中的下一次操作。
- **输入**: 无（`{}`）
---
### `group_objects`
在唯一的`groupId`下分组多个画布对象。
- **必填**: `ids`（字符串数组）
---
### `ungroup_objects`
取消分组属于特定`groupId`的对象。
- **必填**: `groupId`（字符串）
---
### `reorder_object`
重新排序对象的z-index层级（置于前方、发送到后方、向前、向后）。
- **必填**: `id`（字符串）, `action` - `"front"` | `"back"` | `"forward"` | `"backward"`
---
### `get_board_workspace`
返回活动的文件系统目录、自动保存状态和文件名模式。代理应该在第一次画布变异之前调用此函数。
---
### `set_board_workspace`
设置用于板件工件的绝对项目目录。该目录在必要时创建。
- **必填**: `directory`（绝对路径）
---
### `export_board_file`
刷新浏览器的当前画布，并将其完整的schema-v2快照写入磁盘，包括JSON安全的图像资产。
- **可选**: `filename` - 以 `.bdrl.json` 结尾的单个文件名；省略它将使用稳定的自动保存名称。
---
### `import_board_file`
从配置的工作区读取、验证、导入和打开一个画布。
- **必填**: `filename` - 工作区中的单个 `.bdrl.json` 文件名
---
### `export_board`
将当前画布导出为PNG、PDF或SVG。
- **必填**: `format` - `"png"` | `"pdf"` | `"svg"`
- **可选**: `mode` - 默认 `"canvas"` | `"selection"`，`filename` - 输出名称覆盖
- **注意**: SVG和PDF需要Pro计划。错误响应将清楚地指示这一点。
---
### `graduation_rename_photos`
将本地目录中的照片文件重命名为顺序格式。**无需浏览器**。
- **必填**: `seniorsDir`（绝对路径）, `mode`（`"sequential"` | `"gap_fill"`）
---
### `graduation_standardize_images`
将渐进式JPEG和HEIC文件转换为基线RGB JPEG。**无需浏览器**。
- **必填**: `seniorsDir`（绝对路径)
---
## 连接到AI客户端
(无翻译内容)
### Claude 桌面版
将以下内容添加到 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）或 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）。
```json
{
"mcpServers": {
"boarderless": {
"command": "node",
"args": ["/absolute/path/to/boarderless.app_MCP/src/mcp-stdio-server.js"],
"env": {
"BOARDERLESS_MCP_APP_URL": "https://boarderless.app/canvas",
"BOARDERLESS_MCP_BROWSER_URL": "http://127.0.0.1:9222",
"BOARDERLESS_WORKSPACE_DIR": "C:\\absolute\\path\\to\\your\\project"
}
}
}
}
```
运行 `npm run setup` 将自动写入此配置。
### Hermes / OpenClaw（本地 AI 网关）
在 `openclaw.json` 的 `mcp.servers` 下添加以下内容：
```json
"mcp": {
"servers": {
"boarderless": {
"command": "node",
"args": ["/absolute/path/to/boarderless.app_MCP/src/mcp-stdio-server.js"],
"env": {
"BOARDERLESS_MCP_APP_URL": "https://boarderless.app/canvas",
"BOARDERLESS_MCP_BROWSER_URL": "http://127.0.0.1:9222",
"BOARDERLESS_WORKSPACE_DIR": "/absolute/path/to/your/project"
}
}
}
}
```
### Cursor / Windsurf
请查看 `npm run setup` 生成的 `mcp-config.json` 文件，以获取确切的配置块。
### VS Code / GitHub Copilot 及连接目录
VS Code / GitHub Copilot 可以通过 `.vscode/mcp.json` 使用 Boarderless 作为本地 stdio MCP 服务器。
### 主机 OpenAI 和 Microsoft 状态
Joel 选择了**选项 A：浏览器中介可见会话桥**，以便未来远程就绪。Boarderless 不会托管用户数据或服务器端板块；用户数据保持用户管理、用户拥有和用户控制。参见 [docs/remote_session_bridge_spec.md](docs/remote_session_bridge_spec.md)。
`@boarderless/mcp-server` v0.2.541 不是托管的 ChatGPT 应用或 Microsoft Copilot Studio 连接器。npm 只分发本地 `stdio` 连接器。
- **OpenAI 待完成：** 公共 HTTPS MCP 资源服务器，OAuth 2.1 授权码流程与 PKCE，保护资源和授权服务器发现元数据，ChatGPT 客户端注册/回调，范围令牌验证，以及从托管服务到用户可见 Boarderless 浏览器会话的安全中继。
- **Microsoft 待完成：** 公共 Streamable HTTP MCP 端点，OAuth 2.0 通过 DCR/发现或手动客户端注册，Copilot 回调注册，范围令牌验证/刷新/吊销，以及相同的安全远程到可见画布中继。
- **共享待完成：** 远程安全工具策略，显式写入控制，速率限制，审计日志，隐私/保留规则，秘密管理，安全审查，端到端测试和平台提交/审查。
OAuth 识别并授权用户；它不使云服务能够访问用户的本地浏览器或 Chrome DevTools 端口。所选路径是用户批准的绑定到可见标签/画布的 outbound 浏览器桥，而不是隐藏的云板块。参见 [完整的托管连接器检查清单](docs/connector_distribution_plan.md#outstanding-hosted-openai-work--not-included-in-v0126)，[仅限文档的远程适配器计划](docs/oauth21_remote_adapter_plan.md)，[浏览器桥规范](docs/remote_session_bridge_spec.md)，和 [操作员门控](docs/connector_operator_runbook.md#phase-c-hosted-openai-and-microsoft-adapters-later)。
---
## 隐私政策
Boarderless MCP 是本地连接器。完整的 Boarderless 隐私政策发布在 **<https://boarderless.app/privacy>**（也声明在 `manifest.json` 的 `privacy_policies` 中）。
MCP 服务器处理数据的摘要：
- **数据收集：** 服务器本身收集 no 分析数据和发送 no 遥测数据。它从您自己的已登录、人类可见的 Boarderless 浏览器标签中读取画布状态，通过 `127.0.0.1:9222` 上的 Chrome DevTools 协议。
- **使用和存储：** 板块快照（`.bdrl.json`）和导出仅写入您配置的本地工作区目录。MCP 服务器不会将任何内容上传到 Boarderless 服务器。
- **第三方共享：** 无。服务器仅与您的本地浏览器和您登录的 Boarderless 画布页面通信。它不会继承您的 Google 身份或 Google Drive 访问权限。
- **数据保留：** 本地板块文件保留在您的机器上，由您控制；您可以随时删除它们。服务器不会保留任何数据库、队列或服务器端副本。
- **联系方式：** 问题或疑虑 - 在 <https://github.com/CrackenReleased/boarderless.app_MCP/issues> 上打开问题或使用 <https://boarderless.app/privacy> 中列出的联系渠道。
---
## 贡献
此 MCP 服务器在 Apache 2.0 许可证下开源。欢迎贡献！
- **错误报告：** 打开问题，描述您收到的 `error_code` 和 `get_server_status` 输出。
- **新工具：** 工具应作为 `mcp-stdio-server.js` 中的独立处理程序添加，带有结构化的 `makeError` / `makeSuccess` 响应。每个新工具都必须有一个对应的回归测试。
- **平台支持：** 如果您的浏览器或操作系统未被检测到，请打开一个 PR，将其路径添加到 `getBrowserCandidates()` - 所有路径都必须使用 OS 环境变量，从不硬编码用户名。
### 生产版本同步
在初始 npm 发布获得批准后，每个生产 MCP 版本都必须交付到 GitHub 和 npm 下相同的版本号。在 `npm test` 和 `npm publish --dry-run --access public` 通过、Git 提交被推送、`npm publish --access public` 成功以及 `npm view @boarderless/mcp-server version` 返回确切版本号之前，生产版本不完整。仅文档提交且不更改 MCP 包版本号，不需要 npm 发布。
---
## 许可证
在 Apache 许可证，版本 2.0 下授权。有关详细信息，请参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器