MCP 对接
Model Context Protocol
连接
- 默认：
http://127.0.0.1:3101 - 桌面应用启动时会拉起 MCP；headless 用
npm run serve/npm run acceptance:server
在 Cursor 等客户端里把该地址配成 MCP server（HTTP MCP）。
Agent 自助搭云的首选路径见 skill skills/xbuckle-local-cloud：打开 / 绑定应用仓库里的 *.xbujd 包，按包内 .xbuj 用 services.* 对齐 runtime。
项目包（真相源）
text
app/**/my-app.xbujd/
my-app.xbuj ← 提交
handler.json ← 提交
database/pg.dump ← 已被包内 .gitignore 排除；网盘 / .xbudump 共享，勿 force-add不要在应用仓库根另写 xbuckle.stack.json（legacy）。
控制面：服务生命周期
| Tool | 用途 |
|---|---|
services.register | 安装并启动 catalog 服务（installed + running） |
services.unregister | 卸载（installed=false，stopped） |
services.configure | 写入 per-service config bag |
services.start / services.stop | 启停（start 也会 mark installed） |
services.list / services.describe | 目录、限制、envHints、当前 config |
stack.plan / stack.apply / stack.status | Legacy — 旧 xbuckle.stack.json 客户端；新流程勿用 |
Env 由 Agent / 人类写入应用仓库（Connect 文案或 catalog envHints）。XBuckle 不会代写 .env。
观测
| Tool | 用途 |
|---|---|
observe.tables | 列表（public） |
observe.query | 只读 SQL（单条 SELECT/WITH） |
observe.traffic | 按 serviceId / pathPrefix / since 过滤流量 |
observe.events | mail / queue / functions / edge / billing 等缓冲 |
traffic.recent | 未过滤的最近流量 |
runtime.selftest / compat.check | 健康与分层检查 |
内容突变（数据面仍优先官方 SDK）
| Tool | 用途 |
|---|---|
data.query / data.tables | 控制面 SQL / 表（DDL/DML；应用应走 :5432） |
auth.mint / auth.users.* | 本地用户与 token |
s3.* / queue.* / cache.* / mail.* / flags.* / llm.* / … | 各 vendor face |
故障与 Ship
| Tool | 用途 |
|---|---|
chaos.* / route.override.* | 故障注入与固定响应 |
ship.checklist / env_template / scan / run | 上线检查与密钥注入跑命令 |
Resources
resources/list → xbuckle://agent-guide、catalog、coverage、connect、ship 等。
反模式
- 新建
xbuckle.stack.json当第二份服务清单 - 用
data.query代替应用里的pg客户端 - 把云端 URL 写进本地 env 再跑 destructive 工具
- 假设 S3 / Search / Gateway 等是完整云厂商
- 指望 MCP 写出应用的
.env，或以.xbudump当作活绑定