trello-use

Trello MCP 服务 — 使用技能

Trello MCP 工具通过操作进行分派（action: "..." 用于选择操作），并严格校验参数：所选操作不会用到的字段会被拒绝，而不是忽略。

1. 先识别当前用户

调用 trelloReadMember，并传入 action: "get_me"，以获取已验证用户的个人资料，包括 prefs.timezone。在请求任何卡片、Inbox 和搜索的相对时间（“今天”“本周”）之前，都要先执行此操作；尤其是在用户以本地时间或相对时间（例如“明天下午 1 点”）提供 due 日期/时间时，在调用 trelloWriteCard/trelloWriteInbox 的 create 或 update 之前，先解析 prefs.timezone，转换为 UTC，再将转换后的时间作为 due 传入。（Planner 事件使用不同的时区来源，见 §3。）

2. ARI ID 格式（重要 — 传入任何 ID 前请阅读）

每个类型为 ID 的参数（cardId、boardId、listId、workspaceId、checklistId、itemId、labelId、plannerCalendarId、providerAccountId）都是 ARI，而不是原始 Trello 对象 ID。大多数 ARI 都限定于工作区，并遵循以下格式：

ari:cloud:trello::<entity>/workspace/<workspaceObjectId>/<entityObjectId>

以下最后四行所列的例外不限定于工作区：action、member 和 planner calendar 不含工作区段，第三方帐户则属于不同的 ARI 命名空间。

实体	格式
board	ari:cloud:trello::board/workspace/<workspaceObjectId>/<boardObjectId>
card	ari:cloud:trello::card/workspace/<workspaceObjectId>/<cardObjectId>
list	ari:cloud:trello::list/workspace/<workspaceObjectId>/<listObjectId>
checklist	ari:cloud:trello::checklist/workspace/<workspaceObjectId>/<checklistObjectId>
check item	ari:cloud:trello::check-item/workspace/<workspaceObjectId>/<itemObjectId>
label	ari:cloud:trello::label/workspace/<workspaceObjectId>/<labelObjectId>
workspace	ari:cloud:trello::workspace/<workspaceObjectId>
action	ari:cloud:trello::action/<actionObjectId>（不含工作区段）
member	ari:cloud:trello::user/<memberObjectId>（不含工作区段）
planner calendar	ari:cloud:trello::planner-calendar/<calendarObjectId>（不含工作区段）
third-party account	ari:third-party:<provider>::account/<providerAccountId>（例如 Google）

规则：

• 始终先通过读取工具获取 ARI，切勿自行构造或猜测。 trelloWriteCard、trelloWriteChecklist、trelloWriteInbox 和 trelloWritePlanner 都会拒绝其 ID 参数中的 Trello URL/短链接（“请勿传入 Trello URL 或短链接；请先使用 trelloReadCard/trelloReadInbox 获取 ARI”）。
• 两个读取工具的 get 操作也接受普通 Trello URL，以提供便利：trelloReadBoard（get）接受 board URL（https://trello.com/b/<shortLink>/...），trelloReadCard（get）接受 card URL（.../c/<shortLink>/...），此外也接受 ARI。其他所有工具以及所有写入工具都只接受 ARI。

3. 日期始终使用 UTC ISO 8601

due（trelloWriteCard、trelloWriteInbox）以及 start/end（trelloWritePlanner）均使用 UTC ISO 8601 格式（"2026-06-01T17:00:00.000Z"）。对于本地时间或相对时间，请按以下方式转换：

• 卡片和 Inbox：trelloReadMember（get_me）→ prefs.timezone
• Planner 事件：trelloReadPlanner（get）→ primaryCalendar.timezone
• 未提供时间 → 默认为本地时间 09:00。

trelloSearch 的截止日期限定符（due:）遵循相同的 UTC 边界规则——请先解析 prefs.timezone。

4. 收件箱不是 Trello 看板

收件箱是一个个人快速记录界面，拥有专用工具：trelloReadInbox / trelloWriteInbox。不要尝试通过 trelloReadBoard/trelloWriteBoard 访问它，而应使用收件箱专用工具。trelloWriteInbox 的 create 不接受 pos——新建的收件箱卡片始终置顶。

5. 按顺序创建

创建多个必须保持特定顺序的项目时——列表、卡片、卡片上的检查清单，或检查清单中的检查项——请将 pos 设为不同的连续整数（1, 2, 3, …），并按照预期顺序排列。排序范围按父级划分：卡片按列表排序，列表按看板排序，检查清单按卡片排序，检查项按检查清单排序。不同的值可以固定顺序，不受哪个调用先完成的影响，因此可以并行创建。pos 在支持该字段的地方也接受 "top"/"bottom"。

示例——在新看板上创建 3 个列表，顺序很重要（To Do → In Progress → Done）：

[
  {
    "tool": "trelloWriteList",
    "action": "create",
    "boardId": "ari:cloud:trello::board/workspace/<workspaceObjectId>/<boardObjectId>",
    "name": "To Do",
    "pos": 1
  },
  {
    "tool": "trelloWriteList",
    "action": "create",
    "boardId": "ari:cloud:trello::board/workspace/<workspaceObjectId>/<boardObjectId>",
    "name": "In Progress",
    "pos": 2
  },
  {
    "tool": "trelloWriteList",
    "action": "create",
    "boardId": "ari:cloud:trello::board/workspace/<workspaceObjectId>/<boardObjectId>",
    "name": "Done",
    "pos": 3
  }
]

这 3 个列表都可以并行创建——pos 的范围是整个看板，不同的值（1/2/3）可以固定顺序，不受哪个调用先完成的影响。

示例——在一个列表中创建 3 张卡片，顺序很重要（Step 1 → Step 2 → Step 3）：

[
  {
    "tool": "trelloWriteCard",
    "action": "create",
    "listId": "ari:cloud:trello::list/workspace/<workspaceObjectId>/<listObjectId>",
    "name": "Step 1",
    "pos": 1
  },
  {
    "tool": "trelloWriteCard",
    "action": "create",
    "listId": "ari:cloud:trello::list/workspace/<workspaceObjectId>/<listObjectId>",
    "name": "Step 2",
    "pos": 2
  },
  {
    "tool": "trelloWriteCard",
    "action": "create",
    "listId": "ari:cloud:trello::list/workspace/<workspaceObjectId>/<listObjectId>",
    "name": "Step 3",
    "pos": 3
  }
]

此处的 pos 作用范围仅限该列表——在另一个列表中创建 pos: 1 的卡片，与此列表的 pos: 1 相互独立。

**反例——顺序不重要：**直接创建项目，不设置 pos（或设置为 "bottom"）。用户没有要求特定顺序时，不要擅自编造连续编号——这会引入未经要求的精确顺序。

6. 分页

用于列出集合的读取工具采用游标分页（输入 cursor，输出 pageInfo.endCursor/nextCursor 和 hasNextPage/hasMore）。当 hasNextPage/hasMore 为 true 时，继续分页，不要假设第一页就是全部结果——尤其是在 trelloReadBoard 的 list/list_by_workspace 中按 visibility 筛选时，这一点很重要（筛选由服务端逐页执行，而非在分页前对全部结果进行筛选）。

7. 嵌入字段是预览

嵌套子对象的字段——看板上的 lists、卡片上的 labels/comments、列表上的 cards——在 get 和 list_* 响应中都只是有限预览。<field>HasMore: true 表示内容已截断：listsHasMore、labelsHasMore、checklistsHasMore、commentsHasMore。

要获取数量、所有 X、筛选结果，或回答「这就是全部了吗？」，都需要获取所有子项。使用匹配的操作获取数据，并翻页直到响应显示没有下一页（§6），然后根据这些页面作答。

需要完整获取的子项	使用
看板上的列表	trelloReadList list_by_board
列表中的卡片	trelloReadCard list_by_list
卡片上的检查清单及其条目	trelloReadChecklist list_by_card
看板上的标签	trelloReadBoard list_labels
卡片上的评论	trelloReadCard list_comments — 受限：如果公布的操作中没有此操作，则无法获取评论；请明确说明
卡片自身的标签或成员	不存在限定于卡片的操作——预览就是上限，因此应说明数据不完整

示例——「这个看板有多少个列表？」 trelloReadBoard get 返回了 lists，且 listsHasMore: true。从该响应中获取看板 ARI，并传入列表操作；沿游标翻到最后一页，然后统计收集到的列表：

{
  "tool": "trelloReadList",
  "action": "list_by_board",
  "boardId": "ari:cloud:trello::board/workspace/<workspaceObjectId>/<boardObjectId>",
  "cursor": "<endCursor/nextCursor from the previous page>"
}