Appwrite MCP 使用文档

懒猫微服 · 自托管后端云 · AI 原生接口 —— 所有命令与配置均可一键复制

一、连接 MCPAI 自动发现

本应用通过懒猫「本地资源」机制导出了 MCP provider，装好应用的 Box 上，AI 会话可自动发现。手动连接时使用以下端点：

# 应用间访问（同 Box 内 AI 会话/其他应用，推荐）
http://app.dev.vito.appwrite.lzcx/mcp?view=default

# 公网入口（走懒猫 SSO 鉴权，适合已登录用户会话内使用）
https://appwrite.<box-user>.heiyu.space/mcp

懒猫细节：应用间访问走 .lzcx 域，由平台资源发现机制（/lzcsys/run/pkgm/resources/mcp-providers/）注册；公网 /mcp 路径受懒猫 SSO 保护。

协议握手（Streamable HTTP，JSON-RPC 2.0）

curl -X POST "http://app.dev.vito.appwrite.lzcx/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# 列出全部工具
curl -X POST "http://app.dev.vito.appwrite.lzcx/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

二、认证：API Key 双通道

匿名可用：health_check、get_wiring_card（基础版）。其余工具需要 API key，两种传法：

通道	方式	适用
工具参数	`"apiKey": "<key>"`（每次调用传入，优先级高）	AI 会话中临时使用
环境变量	LPK 安装参数注入 `APPWRITE_MCP_KEY`	固定部署

创建 API Key（控制台一次性操作）

控制台 → 组织 → 项目 → API 密钥 → 创建：填名称 → Select all → Create → 复制 standard_... 开头的 secret。

关键：修复 scope（上游 2.2.0 缺陷，懒猫部署必做）重要

Appwrite 2.2.0 的 REST 端点鉴权检查 collections.* / documents.* 等旧 scope 名，但建 key 的界面已不再发放它们（标记 deprecated，勾选也会被静默丢弃）——不修这一步，key 调不动数据库层。修复在数据层完成，零镜像改动、升级安全。

# 1) 给 key 补上旧 scope（Box 上执行；把 like 条件换成你的 key 名称）
/lzcsys/bin/lzc-docker exec devvitoappwrite-postgresql-1 sh -c \
  "PGPASSWORD=\$(printenv POSTGRES_PASSWORD) psql -U user -d appwrite -c \
   \"update appwrite._console_keys set scopes = scopes || '[\\\"collections.read\\\",\\\"collections.write\\\",\\\"documents.read\\\",\\\"documents.write\\\",\\\"attributes.read\\\",\\\"attributes.write\\\"]'::jsonb where name like 'MCP%'\""

# 2) 清 scope 缓存（必须！不清不生效）
/lzcsys/bin/lzc-docker exec devvitoappwrite-redis-1 redis-cli flushall

注意容器名前缀 devvitoappwrite- 对应包名 dev.vito.appwrite，按实际部署调整。验证：curl .../v1/databases/.../collections/.../documents -H "X-Appwrite-Key: ..." -H "X-Appwrite-Project: ..." 返回 200。

三、工具清单（10 个）

工具	作用	需 key
`health_check`	API 健康与版本	否
`get_wiring_card`	接线卡：endpoint + 项目/库/表清单聚合	可选（有则列资源）
`docs`	返回本文档地址与快速指引	否
`create_project`	组织下建项目（控制台 API 做不到的场景）	是
`create_table`	一步建表：库+表+列+RLS+安全权限	是
`set_table_security`	角色权限矩阵 + RLS 开关	是
`describe_table`	表结构与安全配置	是
`list_documents`	列出文档	是
`create_document`	插入文档（支持行级权限）	是
`api_probe`	任意 REST 调用（逃生舱）	可选

一步建表（最常用）

curl -X POST "http://app.dev.vito.appwrite.lzcx/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": { "name": "create_table", "arguments": {
      "apiKey": "standard_xxx",
      "projectId": "6aafe49d0024c316c2f8",
      "databaseId": "mydb",
      "databaseName": "我的库",
      "tableId": "tasks",
      "tableName": "任务表",
      "columns": [
        { "key": "title", "type": "string", "size": 256, "required": true },
        { "key": "done",  "type": "boolean", "default": false },
        { "key": "priority", "type": "integer" }
      ]
    }}
  }'

完成后表已带 RLS（行级安全）与 users 可 create 的表级权限——控制台里要点十几次的配置一步到位。

写一条文档

{
  "name": "create_document",
  "arguments": {
    "apiKey": "standard_xxx",
    "projectId": "6aafe49d0024c316c2f8",
    "databaseId": "mydb",
    "tableId": "tasks",
    "data": { "title": "你好懒猫", "done": false, "priority": 1 }
  }
}

四、SDK 应用接线卡给要接入的前端/应用

// Appwrite Web SDK（npm 包当前大版本 27；CDN 产物路径是 dist/iife/sdk.js）
const { Client, Account, Databases, Query, Permission, Role } = Appwrite;
const client = new Client()
  .setEndpoint("https://appwrite.<box-user>.heiyu.space/v1")
  .setProject("<projectId>")
  .setEndpointRealtime("wss://appwrite.<box-user>.heiyu.space/v1"); // WS 不受 CORS 限制，直连

const account = new Account(client);
const db = new Databases(client);
// 登录：await account.createEmailPasswordSession(email, password);
// 行级权限写法（不要手写 "read(\"user:x\")" 字符串）：
await db.createDocument(dbId, tableId, "unique()", data, [
  Permission.read(Role.user(me.$id)),
  Permission.update(Role.user(me.$id)),
  Permission.delete(Role.user(me.$id)),
]);

<projectId> 用 get_wiring_card 工具一次拿全（含库/表清单）。

五、懒猫设备调用细节（避坑清单）

场景	结论
服务端 / 脚本 / native SDK	直连 `https://appwrite.<box-user>.heiyu.space/v1` 即可（LPK 已配置 `public_path: /v1`，API 面不经过懒猫 SSO）
浏览器跨源页面调 API	懒猫网关会剥掉 OPTIONS 预检的 CORS 响应头（平台已知问题）——开发时用本地反代（同源化 + cookie 域改写），参考应用内示例 `examples/todo-app/dev-server.cjs`
WebSocket 实时	不受 CORS 限制，直连即可（`setEndpointRealtime`）
REST 路径术语	2.x 界面显示 tables/rows，但 REST 路径全部是旧名：`/collections`、`/documents`、`/attributes`；body 字段 `collectionId / documentSecurity`，建文档 body 需要 `documentId: "unique()"`
session 与项目	session cookie 按项目隔离：换 project 头请求会被当作 guest；项目级 key 调平台级接口（如列全平台项目）需带 project 头
平台白名单	Web 平台的 hostname 精确匹配（localhost ≠ 127.0.0.1），前端实际访问的 host 要注册进控制台 → 应用

六、完整示例在线试用

直接体验：应用内置了 Todo 示例（与本应用同域部署，无需任何本地环境）：

https://appwrite.<box-user>.heiyu.space/examples/todo-app/

打开即用：注册一个账号 → 添加待办 → 勾选/删除 → 多开一个标签页看实时同步。示例覆盖认证、数据库 CRUD、行级权限（每人只见自己的待办）、Realtime 四大能力。

本地二次开发：浏览器另存示例页为 index.html，配本地反代（同源化 /v1，绕开预检 CORS 问题）后调试。

本文档随 LPK 打包发布（/lzcapp/pkg/content/mcp-doc/），应用更新时同步更新。反馈问题请附 health_check 输出。