内容
# BeFree Bubble MCP
面向开发者的本地优先Bubble自动化工具包，提供更安全、更准确的代理辅助Bubble工作。
该项目正在从Befree/Aria中提取为一个独立的开源平台。该软件包可安装，并公开了一个带有本地配置文件、上下文工具、规划工具和身份验证Bubble编辑器写入执行的stdio MCP服务器：
```bash
pipx install befree-bubble-mcp
bubble-mcp init
bubble-mcp-server
```
用于本地检查开发：
```bash
python3.11 -m venv .venv
. .venv/bin/activate
python scripts/install_local.py --extras browser,dev
```
如果可编辑安装被中断，控制台脚本无法再导入`bubble_mcp`，请运行：
```bash
python scripts/install_local.py --repair --extras browser,dev
```
## 当前功能
- 面向Bubble的CLI。
- 用于代理客户端的MCP服务器。
- 通过MCP公开的完整Aria Bubble MCP工具目录，目录调用通过打包的Aria兼容运行时分派，只要存在匹配的运行时命令。
- 内置MCP工具覆盖率报告，显示原生、直接运行时、运行时别名、自定义适配器、编译器回退和未覆盖类别。
- 内置MCP目录质量门控，用于面向代理的描述、模式、注释、资源、提示和覆盖率。
- 单命令就绪检查，用于健康、覆盖率、目录质量、代理路由和可选配置文件烟雾验证。
- 配置文件状态检查，结合配置文件映射、会话元数据、上下文新鲜度和下一操作，返回只读响应。
- 本地配置文件管理。
- 从 `.bubble`/consolelog/crawler工件和成功的本地MCP写入中，紧凑的上下文加载、搜索、导入、新鲜度报告和本地突变叠加层合并。
- 具有打包路由语料库、语义验证器、结构执行验证和操作快照的确定性规划器，用于代理。
- HTML到Bubble导入：保守计划转换器和Aria的先进`create-from-html`运行时。
- 本地会话导入/列出Bubble编辑器凭证。
- 通过CLI和MCP进行身份验证的`/appeditor/write`执行。
- 支持的视觉/模式/工作流/样式计划步骤编译为可执行的Bubble写入有效载荷。
- 通过可选的Playwright支持进行浏览器辅助会话登录。
- 评估托管，带有聚焦的重试、解析器/回退诊断、令牌估计和编辑器捕获导出。
- 用于HTML/Figma/Bubble转换回归门的轻量级视觉快照比较。
- 扩展内核基础，带有声明性扩展包、本地验证、协商学习记录、本地Bubble手动知识缓存、声明性技能契约验证和本地工具创作会话。
- 用于Befree Figma插件的本地Figma桥。Figma侧集成代码故意在存储库之外。
## 计划功能
- 跨Bubble编辑器系列的更广泛的公共评估语料库。
- 超出当前本地声明性基础的、适合贡献者的工具系列扩展脚手架。
- 更多视觉一致性验证器，用于HTML和设计桥转换。
- 通过现有的知识源接口，在卫生GitBook MCP回退后面进行远程Bubble手动刷新。
## 扩展内核文档
扩展内核在专注的指南中有文档记录：
- [扩展包](docs/extension-packs.md)：本地包布局、清单契约、验证、启用/禁用状态和预览/执行边界。
- [学习](docs/learning.md)：追加协商学习记录、范围、CLI/MCP用法和安全限制。
- [知识源](docs/knowledge-sources.md)：本地Bubble手动缓存v1、净化、搜索/获取/指导工具和远程文档回退边界。
- [工具创作](docs/tool-authoring.md)：引导工具创作会话、捕获写入分类、有效载荷示例和安全测试工作流。
## 每个Bubble项目所需的设置
在MCP客户端可以安全地改变Bubble应用之前，每个Bubble项目都需要一个本地配置文件、一个捕获的编辑器会话和一个检测到的项目上下文。针对每个Bubble应用运行这些步骤，并在Bubble会话过期或应用结构更改时重复`会话登录`或`上下文检测`。
### 1. 初始化本地设置
```bash
bubble-mcp init
```
这会创建本地配置目录，默认为：
```text
~/.config/bubble-mcp
```
在需要不同配置位置时使用`BUBBLE_MCP_CONFIG_DIR`。
### 2. 添加项目配置文件
选择一个简短的配置文件名，您的MCP客户端和提示将使用它来引用Bubble项目。
```bash
bubble-mcp profile add my-app --app-id my-bubble-app
```
可选元数据：
```bash
bubble-mcp profile add my-app \
--app-id my-bubble-app \
--appname my-bubble-app \
--editor-url "https://bubble.io/page?id=my-bubble-app" \
--app-version test
```
确认配置文件存在：
```bash
bubble-mcp profile list
```
对于一次性CLI设置/就绪响应，请使用：
```bash
bubble-mcp profile bootstrap my-app --app-id my-bubble-app
```
MCP客户端可以通过调用`bubble_project_bootstrap`并带有`profile`、`app_id`和可选的`app_version`、`appname`、`editor_url`、`app_json_path`或`consolelog_json_path`来完成相同的设置。仅当客户端需要较低级别的本地设置写入时，才使用`bubble_profile_add`。
### 3. 捕获Bubble编辑器会话
如果尚未安装浏览器扩展，请安装：
```bash
python -m pip install "befree-bubble-mcp[browser]"
python -m playwright install chromium
```
对于本地检查，优先使用：
```bash
python scripts/install_local.py --repair --extras browser,dev
python -m playwright install chromium
```
然后捕获会话：
```bash
bubble-mcp session login --profile my-app --app-id my-bubble-app --wait-seconds 180
```
MCP客户端可以在就绪检查报告配置文件没有存储会话时触发相同的交互式浏览器捕获，使用`bubble_session_login`。
命令打开一个本地Chromium窗口。登录到Bubble并保持编辑器选项卡打开，直到终端打印：
```text
[bubble-mcp session] 检测到会话cookie。您可以关闭浏览器了；CLI将保存最新捕获的会话。
```
出现此消息后，可以安全地关闭浏览器。最终命令输出是一个编辑过的JSON对象。对于自动化脚本，请传递`--quiet`以隐藏进度消息，同时保留JSON输出：
```bash
bubble-mcp session login --profile my-app --app-id my-bubble-app --wait-seconds 180 --quiet
```
管理捕获的会话：
```bash
bubble-mcp session list
bubble-mcp session inspect --profile my-app
```
`session inspect`从不打印原始cookie。使用它来确认cookie存在并且可以计算Bubble写入头。MCP客户端可以使用相同的只读检查，使用`bubble_session_inspect`。
### 4. 检测项目上下文
在要求代理创建、更新、导入或检查应用结构之前，需要此步骤。它下载/处理Bubble项目上下文并为选定的配置文件本地存储。
```bash
bubble-mcp context detect --profile my-app --app-id my-bubble-app --force
```
要将紧凑的上下文保存在已知路径中以进行检查：
```bash
bubble-mcp context detect \
--profile my-app \
--app-id my-bubble-app \
--force \
--output ./my-bubble-app.context.json
bubble-mcp context summary --file ./my-bubble-app.context.json
```
如果您的应用使用非默认的Bubble版本，请包含它：
```bash
bubble-mcp context detect \
--profile my-app \
--app-id my-bubble-app \
--app-version test \
--force
```
在从其他工具导入、创建页面/元素或代理无法解析页面、可重用元素、样式、工作流、数据类型或路径后，请刷新上下文。
对于例行配置文件缓存刷新，请优先使用更高级别的命令。它映射到`bubble_profile_cache_refresh` MCP工具，并避免代理发现本地上下文路径或较低级别的CLI内部细节：
```bash
bubble-mcp profile refresh-cache --profile my-app
```
### 5. 验证配置文件就绪状态
在从MCP客户端使用配置文件之前，请确认配置文件、会话和上下文的就绪状态：
```bash
bubble-mcp profile status --profile my-app
```
当配置文件存在、存储的会话目标是相同的Bubble应用，并且紧凑的上下文可加载且新鲜时，`ready`标志为真。如果设置不完整，`next_actions`会告诉您是否运行交互式会话登录、显式会话导入或上下文检测。
### 6. 在MCP客户端中使用配置文件
在`profile add`、`session login`和`context detect`完成后，在MCP客户端提示中引用配置文件名：
```text
使用befree-bubble-mcp，配置文件为my-app，创建一个名为mcp-01的页面。
```
对于直接CLI检查：
```bash
bubble-mcp plan "创建一个文本，内容为Hello，位于索引页" --context index
bubble-mcp session inspect --profile my-app
```
## 代理运行时行为
MCP客户端应直接调用公开的MCP工具。它们不需要发现shell命令、检查存储库或手动重建Bubble有效载荷。
在MCP `initialize`期间，stdio服务器返回紧凑的操作指令，因此遵循服务器指令的客户端将被引导至`bubble_profile_status`、`bubble_task_runbook`和`execute=false`预览，然后再进行实际写入。
当客户端有用户任务并且需要下一个MCP调用时，请使用任务/配置文件/上下文/父级/执行值调用`bubble_task_runbook`。它返回路由意图、排序的配方步骤、安全防护、紧凑的匹配工具元数据和可选的配置文件就绪状态在一个调用中。仅当客户端需要这些较小的部分用于诊断或狭窄的后续操作时，才使用`bubble_agent_guide`、`bubble_task_recipe`和`bubble_tool_search`。
CLI为终端和仅具有shell访问权限的代理公开相同的紧凑发现层：
```bash
bubble-mcp tools runbook --task "将来自URL的HTML选择器转换为Bubble页面" --profile my-app --context index
bubble-mcp tools guide --task "将来自URL的HTML选择器转换为Bubble页面"
bubble-mcp tools search --query "html selector import" --limit 5
bubble-mcp tools recipe --task "将来自URL的HTML选择器转换为Bubble页面" --profile my-app --context index
bubble-mcp tools coverage
bubble-mcp tools quality
bubble-mcp readiness --profile my-app --context index
bubble-mcp profile status --profile my-app
```
支持资源和提示的MCP客户端还可以读取`bubble://docs/agent-runtime`、`bubble://catalog/summary`和`bubble://recipes/summary`，读取特定配方，例如`bubble://recipes/html_import`，读取配置文件就绪状态，例如`bubble://profiles/my-app/status`，读取一个完整的工具模式，例如`bubble://tools/create_from_html`，或请求`bubble-task-runbook`、`bubble-html-import`和`bubble-quality-gate`提示。改用一个工具模式资源，而不是在代理已经选择工具后加载完整的`tools/list`响应。
当目录工具以`profile`调用时，服务器解析存储的配置文件、会话、上下文和本地突变叠加层，然后尝试执行匹配的打包Aria兼容运行时方法。这使元素创建、更新、样式同步、工作流、数据、分支、更改日志、Figma桥和HTML导入行为与Aria使用的成熟的Bubble有效载荷约定保持一致。
带有`execute=false`或不带`execute`的调用仍然通过相同的运行时路径编译（如果可能），但Bubble写入被拦截并作为预览返回。带有`execute=true`的调用使用捕获的本地Bubble会话并写入`/appeditor/write`。
从MCP客户端使用`bubble_tool_coverage`，或从CLI使用`bubble-mcp tools coverage`，以验证当前目录覆盖率。公开的目录和Aria兼容子集应报告`uncovered_count: 0`。默认情况下，覆盖率是紧凑的；仅当需要每工具分类时，才在MCP中使用`include_details=true`或在CLI中使用`--include-tools`。
从MCP客户端使用`bubble_catalog_quality`，或从CLI使用`bubble-mcp tools quality`，以验证目录对代理保持高效：无缺失描述、未文档化的输入字段、无效注释、损坏的资源/提示或未覆盖的公开工具。
使用`bubble_runtime_smoke`或`bubble-mcp smoke runtime`进行操作检查。`coverage`套件运行本地目录覆盖率和目录质量检查。`agent-routing`套件验证代表性的自然语言Bubble请求与`bubble_task_runbook`、`bubble_agent_guide`、`bubble_task_recipe`和`bubble_tool_search`；它包括HTML导入、页面创建、Figma/样式同步、分支/更改日志、设置/上下文刷新、交互式会话登录和工作流提示，并且不会将更改发布到Bubble。
`visual-repair`套件验证视觉一致性请求是否产生可行的`bubble_visual_audit`修复计划，而不会将更改发布到Bubble。
`preview-write`套件编译具有`execute=false`的代表性突变；它不会将更改发布到Bubble。
`family-preview`套件在不发布更改的情况下，演练代表性的视觉、容器、输入、模式、工作流、样式、HTML导入、分支和更改日志路径。
使用MCP客户端的`bubble_readiness_check`或CLI的`bubble-mcp readiness`，当您想要推荐的紧凑序列在一个调用：健康、覆盖率/目录质量、代理路由、配置文件状态就绪（如果提供配置文件）和可选的配置文件安全读取或家族预览烟雾。详细的嵌套烟雾输出是可选的，参数为`include_details=true`或`--include-details`。
对于经过身份验证的真实写入烟雾测试，请使用显式的`execute-write`套件。只有当存在`--execute`时，它才会创建临时页面和代表性元素：
```bash
bubble-mcp smoke runtime --suite execute-write --profile my-app --execute --report ./runtime-smoke.json
```
添加`--verify-context`，当您希望烟雾在写入后刷新Bubble上下文并在临时页面/元素不存在时失败。如果还设置了`--cleanup`，则在删除临时页面之前进行验证，然后在清理后再次刷新上下文。
对于转换保真度检查，请使用结构化视觉快照：
```bash
bubble-mcp eval capture-visual \
--source https://example.com/page.html \
--selector '#hero' \
--output /tmp/hero-reference.json
bubble-mcp eval capture-bubble-visual \
--profile my-app \
--page mcp-01 \
--selector '#hero' \
--output /tmp/hero-actual.json
bubble-mcp eval visual \
--reference /tmp/hero-reference.json \
--actual /tmp/hero-actual.json \
--require-images
```
当代理应该诊断和修复支持的视觉漂移时，请使用可行的审计而不是简单的比较：
```bash
bubble-mcp eval visual-audit \
--reference /tmp/hero-reference.json \
--actual /tmp/hero-actual.json \
--profile my-app \
--context mcp-01 \
--parent gp_home \
--app-id my-bubble-app \
--require-images \
--output-plan /tmp/hero-repair-plan.json
```
仅当您希望生成的修复计划被编译并通过存储的会话写入Bubble时，才添加`--execute`。审计还可以包括用于多模态LLM审查的截图：
```bash
bubble-mcp eval visual-audit \
--reference-screenshot /tmp/source.png \
--actual-screenshot /tmp/bubble.png \
--screenshot-task "检查排版、图像大小、渐变方向和最大宽度。"
```
仅截图输入生成LLM-ready比较有效载荷，不会改变Bubble。使用结构化快照时，您希望可执行的修复步骤。
## Codex MCP设置
在MCP配置中使用虚拟环境Python模块路径：
```json
{
"mcpServers": {
"befree-bubble-mcp": {
"command": "/absolute/path/to/befree-bubble-mcp/.venv/bin/python",
"args": ["-m", "bubble_mcp.server.stdio"],
"env": {
"BUBBLE_MCP_CONFIG_DIR": "/Users/me/.config/bubble-mcp"
}
}
}
}
```
`bubble-mcp-server`控制台脚本也被安装，但Python模块形式是桌面MCP客户端最可靠的选择，它们不会继承激活的虚拟环境或受到本地macOS执行策略的影响。
## Figma桥
当使用Befree Figma插件时，从存储库克隆启动本地桥：
```bash
BUBBLE_MCP_CONFIG_DIR=/Users/me/.config/bubble-mcp npm run figma:bridge
```
如果省略`BUBBLE_MCP_CONFIG_DIR`，则桥使用与Python CLI/MCP服务器相同的默认路径：`~/.config/bubble-mcp`。使用实际本地路径，如`/Users/pedroduarte/.config/bubble-mcp`或`~/.config/bubble-mcp`；示例`/Users/me/...`仅为占位符。桥监听`http://localhost:3333`，公开`/health`、`/profiles`和`/sync`，在`tmp/bridge_data`下保存传入的插件有效载荷，并通过本地Bubble会话运行Aria派生的Figma到Bubble运行时，然后返回成功。`/profiles`响应包括`config_dir`和`settings_path`，以便插件日志显示读取的确切设置文件。
## 扩展内核基础
扩展内核 v1 是本地优先和声明式的。扩展包、学习记录、缓存知识记录、技能合约和工具创作捕获存储在 `BUBBLE_MCP_CONFIG_DIR` 或默认的 `~/.config/bubble-mcp` 目录下。
扩展包被导入到“待定”状态。只有在本地验证成功后，扩展包才能被启用，而已启用的扩展工具模式在通过 MCP 工具目录公开之前会重新验证。验证拒绝工具名称与内置/本地工具的冲突、包内重复名称、符号链接或路径逃逸以及可能的秘密。扩展包仅为 JSON 合约；v1 不执行任意 Python、Node、shell 或来自包的捆绑代码。声明式扩展工具模式在 v1 中可见于目录，但其配方/模板执行运行器尚未实现；调用它返回 `extension_tool_execution_not_implemented`。
当添加声明式执行时，变异扩展工具必须继承与原生 Bubble MCP 目录相同的预览优先合约。它们应默认为 `execute=false`；调用者必须明确选择 `execute=true` 才能进行任何 Bubble 写入。
本地学习记录仅供参考。它们可以为规划、排名、警告和文档提供信息，但不能执行写入、绕过验证或自动确认破坏性操作。本地知识指导也是建议性的：官方 Bubble 文档可以解释 Bubble 概念，但它们永远不会证明当前项目状态。项目状态仍然来自本地配置文件、捕获的会话、检测到的上下文和最新的 Bubble 读取。
Chrome 扩展伴侣位于 `chrome-extension/` 目录中。它必须保持本地-only，不能使用 Aria 电子邮件/密码身份验证，不能依赖 Aria 远程中继或身份验证服务器，其 UI 应仅限于服务状态、事件摘要、本地端口/密钥配置和本地启用/禁用切换开关。通过 `bubble-mcp extension companion serve --port 3847` 或从此检查点运行 `npm run chrome:companion` 来运行其本地监听器。
重点文档：
- [扩展包](docs/extension-packs.md)
- [学习](docs/learning.md)
- [知识源](docs/knowledge-sources.md)
- [工具创作](docs/tool-authoring.md)
- [Chrome 扩展伴侣](chrome-extension/README.md)
## 安全默认值
- 此存储库中不包含任何实际项目数据。
- 变异命令需要本地会话和明确的 `execute=true`/`--execute`。
- 未执行选择加入时，写入命令会预览规范化的请求。
- `bubble_execute_plan` 在写入之前运行结构验证，并为代理返回 `operation_snapshot.next_user_action`。
- 会话凭证保持本地。
- 敏感值在日志或报告之前被编辑。
- 扩展包仅为声明式，不在 v1 中运行任意代码。
- 导入的扩展包处于待定状态；激活需要本地验证。
- 本地扩展、学习、知识和工具创作状态保留在 `BUBBLE_MCP_CONFIG_DIR` 下。
## 状态
早期 alpha 版本。提供有效的本地会话和确切的 Bubble `/appeditor/write` 有效载荷时，支持真正的 Bubble 编辑器写入。生成的计划如果尚未包含 `write_payload`，则可以预览但不会自动应用。扩展内核 v1 是声明式本地包、建议性记录和捕获写入分类的基础；它不会自动生成、激活、重放或执行新工具。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器