Open API 与 Remote MCP

Dessix 提供两种面向外部工具的入口：

• REST API：适合脚本、自动化流程和第三方集成。
• Remote MCP：适合 Cursor、Claude Code、ChatGPT 等支持 MCP 的 AI 客户端。

两者共享同一套后端服务、access token 鉴权和资源归属校验。

可用能力

Open API 和 Remote MCP 面向外部工具开放 Dessix 内容数据能力：

• workspace 列表、当前 workspace、创建和基础信息更新。
• block 的关键词搜索、语义向量搜索、读取、创建、更新、软删除、恢复和移动。
• folder 的创建、重命名、移动、删除和 children 读取。

Access Token

REST API 和 Remote MCP 都使用：

Authorization: Bearer dx_live_xxx

权限模型：

• token 只能访问所属用户自己的数据。
• 外部请求不能传入或覆盖 user_id。
• workspace_id 只是资源定位参数，不是权限凭证。
• 跨用户访问会返回 not found 类错误，避免暴露资源是否存在。
• token 可以在 App 的 workspace settings advanced 面板创建、查看列表和撤销。

REST API 示例

获取 workspace：

curl https://api.dessix.io/v1/open/workspaces \
  -H "Authorization: Bearer dx_live_xxx"

语义搜索 block：

curl "https://api.dessix.io/v1/open/blocks/search?workspace_id=workspace_xxx&semantic=%E9%A1%B9%E7%9B%AE%E5%A4%8D%E7%9B%98&types=Note&limit=5" \
  -H "Authorization: Bearer dx_live_xxx"

创建 block：

curl https://api.dessix.io/v1/open/blocks \
  -H "Authorization: Bearer dx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "workspace_xxx",
    "patch": {
      "type": "Note",
      "title": "API note",
      "content": "Created from REST API"
    }
  }'

Remote MCP

Remote MCP endpoint：

https://api.dessix.io/v1/mcp

Remote MCP 的 tool name 和 input schema 与已有 Local MCP 保持兼容。客户端需要配置 access token 作为 Authorization header。 dessix_search_blocks 的 semantic 参数会走服务端语义向量搜索；query 参数用于关键词搜索。

默认 workspace

如果请求没有传 workspace_id，服务端会使用最近打开的 workspace：

ORDER BY last_opened_at DESC NULLS LAST, updated_at DESC

如果用户没有任何 workspace，读取类请求返回 NO_WORKSPACE_SELECTED。创建内容类请求可以先显式调用创建 workspace。

Folder 删除语义

Folder 删除会和 Dessix App 内保持一致。删除 folder 时：

• 目标 folder 及其子 folder 会被删除。
• 使用这些 folder 的内容 block 会清空 folder 引用并进入 trash。
• root folder 不能删除。

内容大小限制

• read_block 单个 block 内容最多返回 20,000 字符。
• 被截断的内容会带上 content_truncated、content_limit 和 content_original_length。

错误码

常见错误码：

• UNAUTHORIZED
• TOKEN_REVOKED
• TOKEN_EXPIRED
• NO_WORKSPACE_SELECTED
• WORKSPACE_NOT_FOUND
• BLOCK_NOT_FOUND
• FOLDER_NOT_FOUND
• INVALID_ARGUMENT