跳轉到主要內容

訂閱 MCP 相關活動

透過 MCP 連線到 Kanera 的 AI 代理可以在工作發生變化時請求告知，而不是進行輪詢。 Kanera實現草稿的webhook投遞 MCP 活動 extension: 代理的主機註冊 HTTPS 回撥,Kanera 驗證它,從那時起,每個匹配的更改都會作為簽名 JSON 例項釋出到它。

這就是ChatGPT這樣的客戶端中"觀察這個看板並在評論發生時通知我"的機制。 主機擁有回撥;你不需要執行伺服器或在Kanera中貼上URL。

這是給誰的 如果您使用 ChatGPT，請閱讀 觀察 ChatGPT 中的變化 此頁面的其餘部分是執行緒級合同,適用於構建自己的 MCP 主機或自定義整合的人,以及任何想要準確瞭解代理可以和不能被告知的內容的人。 : :

代理可以訂閱什麼​

事件發射時額外欄位 data
card.created在監控範圍內建立一張卡片。title, listId, url
card.updated卡會更改：標題、描述、完成、存檔狀態和其他卡欄位。title, listId, url
card.moved卡片在列表或板內或之間移動。listId （目的地）， fromListId （來源）， prevPosition, url
card.blocked活動卡獲得其第一個開放阻止程式，包括重新開放或恢復。title, listId, url;沒有攔截器詳細資訊
card.unblocked透過完成、存檔、取消連結或刪除攔截器的板或列表，活動卡將丟失其最後開啟的攔截器。title, listId, url;沒有攔截器詳細資訊
schedule.conflict_detected開放式卡牌獲得其第一個排程衝突：開放式阻止程式計劃在其開始時或開始後完成。blockerCardId, days （家屬需要搬家的工作日）
schedule.conflict_resolved開啟的卡會丟失其最後的排程衝突。無額外的時間表欄位
schedule.critical_path_slipped關鍵路徑卡的計劃末端移動較晚，並延遲了其板的預計完成時間。previousProjectedFinish, projectedFinish, days, slipDays
comment.created評論張貼在卡片上。commentId, text （最多 8,000 個字元）， url
priorities.changed你的 接下來 佇列可能已更改。無。 下一條佇列.
my_day.ready是你們時區的一個平日早上。localDate, timeZone。參見 您的早晨簡報.
reminder.due你的一個 卡提醒 到期。reminderId, cardId, remindAt, url。參見 您的卡提醒.

每張卡片和評論發生帶有 workspaceId, boardId, cardId，和一個 actor （見 告訴你自己的寫作分開）。有效負載是有限的摘要：卡片的描述、附件和完整的評論執行緒永遠不會包括在內。代理讀取當前記錄 cards.get 或 comments.list 當它需要更多的時候。

對於卡片,評論和安排事件,訂閱 論點 縮小交付內容的範圍:

論證必要效果
workspaceId是僅此工作區的事件。
boardId沒有僅此論壇的事件。 論壇訪客必填。
listId沒有僅為此工作區列表中的卡片發生事件。 card.moved，進入或離開列表的卡片會匹配，但在列表中重新排序則不會。省略 boardId 觀看每個可訪問的板上的共享列表。
cardId沒有僅此卡片的事件。 需要 boardId.

每次交付時，訪問都遵循連線的身份，而不僅僅是在訂閱時。工作區成員可以觀看整個工作區；跨組織來賓必須指定他們受邀參加的看板；僅限指定物品的客人必須說出他們當前指定的卡片。如果該身份後來失去了對該範圍的訪問許可權，則交付將停止並且訂閱將過期。失去對看板範圍訂閱內的一張卡的訪問許可權只會跳過該事件。

附屬機構的過渡​

card.blocked 以及 card.unblocked 跟隨 卡依賴關係，包括人員、整合、自動化和映象卡的變化。它們不需要自動化規則。新增更多阻止程式或僅清除多個阻止程式中的一個不會重複轉換。每個方向僅限每張卡每次交易一次。

該事件描述了從屬卡,並省略了阻止器詳細資訊以保護私有板。 Read cards.get 檢查當前狀態,然後再執行操作,因為自動化可能已經移動或完成了卡片。

時間表過渡​

三個 schedule.* 與前面的方法相同。 時間軸檢視 以及 work.schedule。它們需要在有效的組織/工作區設定中啟用時間軸和依賴關係，並且不需要自動化規則。

  • schedule.conflict_detected 是從沒有排程衝突到至少有一個衝突的過渡。 cardId 指定受撫養人, blockerCardId 列出最糟糕的衝突前提, days 是從屬需要移動到右側的週一至週五工作日數。 新增另一個衝突不會重複它。
  • schedule.conflict_resolved 意味著一個開啟的卡片沒有剩下的衝突,例如,在日期變更,阻止器完成,或依賴關係被移除後。 僅清除幾個衝突中的一個不會觸發它,以後的重複可以再次觸發檢測。
  • schedule.critical_path_slipped 需要關鍵卡本身的計劃結束時間推遲,以及板的預計完成時間推遲。 由於間隙而吸收的日期變更不符合資格,僅僅新增新工作也不符合資格。 days 測量投影移動的距離; slipDays 預測可以推遲,而預測的時間範圍可以延長。 slipDays 仍為零。

初始排程評估建立了一個基線,而不是宣佈所有現有的衝突。 work.schedule 當開始觀看或從錯過的交付恢復時,它會顯示當前狀態。 在建議更改之前,在事件上再次閱讀它。 這些警報不會重新安排卡片。

對於自定義主機,請分別訂閱每個事件名稱。 此請求監視一個板上的第一個衝突;替換實際的工作區和板 UUID 以及主機的驗證回撥和簽名密碼:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "events/subscribe",
  "params": {
    "name": "schedule.conflict_detected",
    "arguments": { "workspaceId": "…", "boardId": "…" },
    "delivery": {
      "mode": "webhook",
      "url": "https://receiver.example.com/kanera/events",
      "secret": "whsec_…"
    },
    "ttlMs": 86400000
  }
}

關鍵路徑失誤的發生看起來像這樣（ID 和日期是說明性的）：

{
  "eventId": "evt_…_schedule.critical_path_slipped",
  "name": "schedule.critical_path_slipped",
  "timestamp": "2026-11-02T10:00:00.000Z",
  "data": {
    "workspaceId": "…",
    "boardId": "…",
    "cardId": "…",
    "previousProjectedFinish": "2026-11-06",
    "projectedFinish": "2026-11-09",
    "days": 1,
    "slipDays": 1,
    "actor": { "kind": "user", "userId": "…", "self": false }
  },
  "cursor": null
}

日期為 YYYY-MM-DD;持續時間、寬裕時間和滑動計數不包括週末。卡片和時間表事件可能描述相同的底層編輯，但具有不同的事件 ID。重複資料刪除重試方式 eventId 並檢查 actor.self 在對您自己的更改做出反應之前。 規劃示例.

下一條佇列​

priorities.changed 告訴代理,連線使用者自己的 Up next 佇列可能已發生變化,因此代理可以重新讀取佇列而不是進行投票。 它在每次重新排序佇列或調整佇列大小時都會觸發:

  • 新增、移動或刪除條目,無論是從 Web 應用、API 或其他代理;
  • 佇列中的卡片完成、存檔、恢復或重新分配,從而將其從實時佇列中移除或重新放入。

它不需要引數(透過) {}）並且永遠不會將範圍限定為工作區，因為佇列跨越您工作的每個工作區。事件僅包含更改者：

"data": {
  "targetUserId": "…",
  "actor": { "kind": "user", "userId": "…", "self": false }
}

targetUserId 總是連線的使用者。 沒有列出佇列卡片的任何資訊。 Call priorities.list 當前排名;它適用於您的正常卡片可見性。

你只能看著 你的自己的 沒有引數可用於其他人的佇列,包括可以透過 priorities.list。即使沒有內容的通知也會顯示觀察者看不到的卡片何時以及由誰完成或重新分配。訪客或只讀 API 金鑰也可以監視自己的佇列。

您的早晨簡報​

my_day.ready Kanera 會在您的個人資料中顯示的時區的 08:00 點,即與您的客服人員每天工作時間上午的通知時間同步,每天傳送一次通知。 每日摘要電子郵件。它遵循摘要的設定：當您的每日摘要電子郵件關閉時，不會傳送 ping。無論是否有任何到期的事情都會傳送，因此代理仍然可以報告晴天。

它不需要引數(透過) {}）並且只描述你自己的一天。該事件沒有任何作用：

"data": {
  "targetUserId": "…",
  "localDate": "2026-10-12",
  "timeZone": "Europe/London",
  "actor": { "kind": "system", "userId": null, "self": false }
}

代理商然後呼叫 work.my_day 與此同時 timeZone。一次呼叫即可返回您的逾期卡、未來 7 天內到期的卡、包含逾期清單專案的卡、閒置 14 天或更長時間的指定卡以及下一個佇列的頂部，所有這些都會根據您當前的訪問許可權進行檢查。

簡報還回來 schedule.conflicts, schedule.critical, 和 schedule.lateToStart：您分配的有衝突的卡、沒有衝突的關鍵路徑卡以及計劃開始時間已過但從未進入進度的卡。後期啟動檢查需要進行時間跟蹤和進行中列表，並排除已經逾期的卡。

訂閱每次重新整理最多持續 24 小時，因此客戶端必須不斷重新整理才能接收第二天早上的 ping。 ChatGPT 在任務處於活動狀態時執行此操作。

您的卡提醒​

reminder.due 當您的客戶之一 卡提醒 提醒是透過卡片上的警報按鈕設定的,或者由具有相應的語音識別功能的代理人設定的。 cards.set_reminder。它不需要任何引數（透過 {}）並且僅涵蓋您自己的提醒；沒有人可以訂閱別人的。

Kanera 每隔30秒檢查一次是否有到期提醒,並且每次傳送一次提醒。 重新安排已經觸發的提醒會重新啟動它,下一次觸發是新的提醒。 提醒會給卡片命名,但不會包含任何內容:

"data": {
  "targetUserId": "…",
  "reminderId": "…",
  "cardId": "…",
  "remindAt": "2026-10-16T07:00:00.000Z",
  "url": "https://board.kanera.app/o/…/c/MKT-42",
  "actor": { "kind": "system", "userId": null, "self": false }
}

代理人打電話 cards.get 與 cardId 交付檢查您是否仍然可以看到卡片;卡片上的提醒自此已存檔,或您無法再訪問,但不會觸發通知或事件。

觀察 ChatGPT 中的變化​

使用下面的命令安裝並連線 Kanera 外掛 ChatGPT設定指南，然後在支援事件驅動任務的工作對話中選擇它。相容主機自動發現事件功能。對於自定義 MCP 連線，請在中開啟它 外掛 並選擇 重新整理 已釋出的外掛工具更新遵循 OpenAI 的審查流程。

在附加了 Kanera 應用的對話中,詢問您想要發生什麼:

Watch the Product board in Kanera. When a new comment appears on any card, summarise it for me and suggest a reply.
Tell me whenever a card moves into the Done list on the Launch board.
Whenever my Up next queue changes, tell me what is now at the top.
Every weekday morning, brief me on what is overdue, what is due this week, and what is at the top of my Up next queue.
Watch the Launch board for scheduling conflicts and critical-path slips. Read the current schedule when one appears, tell me which cards and dates are affected, and propose a repair. Tell me when conflicts clear. Do not change dates.

ChatGPT 在其自己託管的回撥上建立訂閱，在任務處於活動狀態時重新整理訂閱，並在您停止任務時結束訂閱。 Kanera 永遠不會將您的工作傳送到任何 ChatGPT 尚未證明其控制的地方（請參閱 回撥驗證).

更多的工作例子,包括回答卡上的問題,分類新的工作,並保護一個單一的卡,在 使用示例.

寫任務時要知道兩件事:

  • 避免迴圈。 每個例項都會指定其演員的名稱,以及訂閱連線是否引起了該例項。 actor.self 再寫之前,或者它會自行回答。
  • 寫作之前先讀一讀。 請求任務先讀取卡片,並使用工具的等位鍵來進行可重複的更改。

交付是使用有限重試視窗的最大努力(參見 交付和重試）。如果 ChatGPT 的回撥無法到達的時間超過該時間，則錯過該事件；任務透過讀取當前狀態來恢復。

議定書​

事件僅在託管的 HTTP 端點上可用, https://mcp.kanera.app/mcp 或是你自己的部署 /mcp，並且僅適用於當前 MCP 協議上的客戶端，這就是新增事件訂閱的原因。 kanera mcp over stdio 不提供它們:本地 stdio 主機沒有託管回撥來傳遞。

server/discover 宣傳兩者下的能力 capabilities.events （ChatGPT 今天讀到的內容）和 capabilities.extensions["io.modelcontextprotocol/events"] （擴充套件提案放置的位置）。接下來是三個請求方法，其身份驗證與工具呼叫完全相同，並使用 OAuth 訪問令牌或 API 金鑰作為承載。以下示例僅顯示方法引數；客戶端庫新增協議的每個請求標頭和後設資料。

events/list​

返回上面的目錄,其中包含每個事件的引數和有效載荷的 JSON 架構。 目錄是一個單一頁面; cursor 必須是空白的。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "events/list",
  "params": {}
}

events/subscribe​

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "events/subscribe",
  "params": {
    "name": "comment.created",
    "arguments": { "workspaceId": "…", "boardId": "…" },
    "delivery": {
      "mode": "webhook",
      "url": "https://receiver.example.com/kanera/events",
      "secret": "whsec_…"
    },
    "ttlMs": 86400000
  }
}
外地規則
delivery.mode只有 webhook 任何其他模式都會返回 -32014 Unsupported 與 data.feature = "deliveryMode".
delivery.urlHTTPS,URL 中無憑據,無片段,必須解析為公共地址,拒絕迴環、私有、連結本地、雲後設資料和 IPv4 對映或過渡 IPv6 地址。
delivery.secretwhsec_ 然後是24到64位元組的base64,Kanera將其加密儲存,並用它簽署每次交付。
ttlMs預設值和最大值為 24 小時;如果正值較短,則會被接受,如果較長,則會被拒絕。 null （無有效期）上限為 24 小時。
cursor, maxAgeMs因相容性而接受。 Kanera 不提供重播： cursor 總是返回為 null，並且非空請求遊標被報告為 truncated: true.

答覆：

{
  "id": "sub_…",
  "refreshBefore": "2026-10-07T13:00:00.000Z",
  "cursor": null,
  "truncated": false,
  "deliveryStatus": {
    "active": true,
    "lastDeliveryAt": "2026-10-06T12:58:10.000Z",
    "lastError": null
  }
}

訂閱 id 對於連線、回撥 URL、事件名稱和引數(對於 priorities.changed, my_day.ready, 和 reminder.due，連線的使用者），所以呼叫 events/subscribe 是同一條路。 重新整理: 延伸了 refreshBefore，接受一個新的 secret （新舊密籤均交付五分鐘），並返回 deliveryStatus 對於仍然處於活動狀態的訂閱。 deliveryStatus 首次訂閱和到期後續訂時省略。 重新整理前 refreshBefore;稍後續訂的過期訂閱從續訂時間開始重新開始，不會重播錯過的內容。

active 總是 true：Kanera 絕不會因傳送失敗而暫停訂閱。相反，它限制每次發生的重試，並透過以下方式報告端點的執行狀況： lastError （其中之一 connection_refused, timeout, tls_error, http_4xx, http_5xx, challenge_failed）和 failedSince，在端點持續失敗時出現。

一個連線最多可以容納 100 個活動訂閱。第101次迴歸 -32013 ResourceExhausted.

events/unsubscribe​

採取相同的 name, arguments, 和 delivery.url，毫無秘密。只有建立訂閱的連線才能結束它；另一個憑證的請求是空操作。取消訂閱是冪等的。

錯誤​

Kanera 使用錯誤程式碼來草擬文件的事件。 訂閱失敗結構化 data 所以主機可以在不解析訊息的情況下對它們採取行動。

程式碼姓名何時
-32011NotFoundname 您訪問的頁面不存在data.kind = "event").
-32012Forbidden身份無法看到請求的作用域,或者憑據不是 API 金鑰或 OAuth 連線。
-32013ResourceExhausted訂閱限制 (data.max）或速率限制。
-32014Unsupported除以下以外的交付方式 webhook (data.feature, data.value).
-32015CallbackEndpointError核實失敗。 data.reason 是其中之一 connection_refused, timeout, tls_error, http_4xx, http_5xx, 或 challenge_failed。被拒絕的目的地報告為 challenge_failed，因此錯誤響應不能用於對映專用網路。
-32602InvalidParams格式錯誤的請求、無效的金鑰或 URL、工作區、看板或卡片 arguments 404 - 頁面不存在 頁面不存在. priorities.changed, my_day.ready, 或 reminder.due.

回撥驗證​

在儲存訂閱之前，Kanera 會證明回撥是您的。它將驗證請求釋出到 delivery.url，使用您提供的秘密進行簽名：

{ "type": "verification", "challenge": "…" }

端點必須回答 2xx 使用一個能夠準確反映挑戰的 JSON 主體:

{ "challenge": "…" }

其他任何內容都會導致訂閱失敗 -32015 成功的驗證會被快取五分鐘,每次連線和回撥URL,所以重新整理或更改驗證結果會導致重定向失敗。 arguments 沒有重複挑戰。

驗證執行時使用與交付相同的嚴格目標策略:僅公共 HTTPS 地址,解析一次併為連線固定,以便在檢查和請求之間的 DNS 更改無法重定向。

交付和重試​

每次發生都是一次 POST 返回到頂部 Content-Type: application/json:

{
  "eventId": "evt_…",
  "name": "comment.created",
  "timestamp": "2026-10-06T12:58:09.412Z",
  "data": {
    "workspaceId": "…",
    "boardId": "…",
    "cardId": "…",
    "commentId": "…",
    "text": "Can we ship this on Thursday?",
    "url": "https://board.kanera.app/o/3F2A9C1D7B4E6A08/c/PROJ-123",
    "actor": { "kind": "user", "userId": "…", "self": false }
  },
  "cursor": null
}
頭條內容
webhook-id該 eventId。重試後保持穩定；使用它使處理程式冪等。
webhook-timestamp當這次嘗試被簽名時, Unix 秒鐘。 每次重試時重新整理。
webhook-signature一個或多個空格分隔 v1,<base64> 簽名(秘密輪換期間有兩個)。
X-MCP-Subscription-Id訂閱 id.

實體位元組在每次嘗試中都是相同的;只有時間戳和簽名會發生變化。

回應 2xx 要承認。 Kanera 下面是例子:

回應行為
2xx送達，屍體被忽略
410, 413，以及其他 4xx此例項將被丟棄。 訂閱將繼續;未來的例項仍將交付。
408, 425, 429, 5xx、超時、TLS 或連線失敗重試同樣的 eventId：總共五次嘗試，時間大約為 0 秒、30 秒、1.5 分鐘、3.5 分鐘和 7.5 分鐘。之後該事件就會被刪除。

超過 4 KiB 的響應體將被丟棄，不影響結果。超過 256 KiB 的事件永遠不會被髮送。 Kanera 保留交貨記錄 14 天。

活動訂閱的交付會在 Kanera 次重新啟動後繼續進行。 在每次嘗試之前都會重新檢查授權,因此斷開連線的代理、撤銷的金鑰、刪除的成員或丟失分配的賓客在下一次嘗試時停止接收資料,而不是在下一次重新整理時停止接收資料。

priorities.changed 由於佇列不與單個工作區繫結,因此在佇列更改儲存的那一刻就會排隊,而不是從卡片事件使用的持久變更日誌中排隊。 在罕見的情況下,如果Kanera在此時重新啟動,則可能會丟失一條通知;下一條通知將在該工作區中傳送。 priorities.list read 總是當前的。

驗證簽名​

這個方案是 標準Webhooks 後來,他又回到了家裡。 whsec_ 從base64,HMAC-SHA256字串的字首 {webhook-id}.{webhook-timestamp}.{body}，並在恆定時間內與標頭中的每個簽名進行比較：

import crypto from "node:crypto";
import express from "express";

const app = express();
const key = Buffer.from(process.env.KANERA_MCP_EVENT_SECRET!.slice("whsec_".length), "base64");

app.post("/kanera/events", express.raw({ type: "application/json" }), (req, res) => {
  const body = req.body.toString("utf8");
  const payload = JSON.parse(body) as { type?: string; challenge?: string };
  const id = req.header("webhook-id") ?? "";
  const timestamp = req.header("webhook-timestamp") ?? "";
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64");
  const digest = Buffer.from(expected);
  const valid = (req.header("webhook-signature") ?? "").split(" ").some((entry) => {
    const received = Buffer.from(entry.replace(/^v1,/, ""));
    return received.length === digest.length && crypto.timingSafeEqual(received, digest);
  });
  if (!valid) return res.status(401).send("invalid signature");
  // Verification challenge: echo it back.
  if (payload.type === "verification") return res.json({ challenge: payload.challenge });
  // Occurrence: handle it idempotently by webhook-id.
  res.sendStatus(204);
});

始終對照原始身體進行驗證。拒絕交貨 webhook-timestamp 從現在開始,我就不再想著你了 。 ”

告訴你自己的寫作分開​

透過寫回對事件做出反應的代理將看到自己的寫入作為事件出現。 userId 單獨不能將它們分開:個人 API 金鑰或 OAuth 代理作為其使用者,因此代理釋出的評論和釋出者釋出的評論具有相同的屬性。 userId.

因此，每次發生都包括：

"actor": { "kind": "apiKey", "userId": "…", "self": true }
外地意義
kinduser （網路應用程式）， apiKey, agent （互動式 OAuth 代理）， support, automation, 或 system.
userId使用者作為更改。 null 用於自動化和系統變更。
selftrue 只有當訂閱連線本身進行更改時:相同的 OAuth 代理授權、直接使用的相同 API 金鑰或相同的無人值守服務連線。

自動化效果報告為 automation 即使代理人自己的寫入觸發了它們,因此在代理人評論後新增標籤的規則不會被讀作代理人的寫入。

該 title 以及 text 欄位是使用者內容,應將其視為資料,而不是代理的指令。

直接呼叫同一個API​

MCP 方法轉發到三個公共 API 路由,這些路由接受相同的載體憑據以及相同的請求和響應主體。 從擁有 API 金鑰並希望在不使用 MCP 的情況下訂閱事件的整合中使用這些方法:

路線MCP法
GET /api/v1/mcp-eventsevents/list
POST /api/v1/mcp-events/subscribeevents/subscribe
POST /api/v1/mcp-events/unsubscribeevents/unsubscribe

失敗將作為帶有程式碼的公共 API 問題文件返回 MCP_EVENT_NOT_FOUND, MCP_EVENT_UNSUPPORTED, MCP_SUBSCRIPTION_LIMIT, 和 MCP_CALLBACK_ENDPOINT，MCP 層將其對映到上面的誤差表。

對於應該超越任何一個連線並覆蓋整個事件目錄的團隊整合,請使用 Webhook MCP 事件訂閱屬於建立它們的憑據,除非重新整理,否則將在 24 小時內過期,並且僅涵蓋四個卡片和評論事件以及您自己的 Up next 佇列。 Webhook 不會傳遞 Up next 更改,因為佇列是個人資料,而不是工作區資料。

故障排除​

問題要檢查什麼
客戶端不提供活動。必須連線到託管的 /mcp 關於當前的終點 MCP 客戶端中,伺服器的重新掃描; stdio 透過 kanera mcp 從不提供事件。
events/subscribe 回返 -32015 與 challenge_failed.回撥沒有回應挑戰,回應了非 2xx 狀態,重定向,或者是私有、迴路或後設資料地址。 Kanera 故意以相同的方式報告所有這些。
-32012 Forbidden 點選訂閱。身份不能看到工作區、白板或卡片。 白板訪客必須透過 boardId;僅指定物品的客人必須透過指定的 cardId。會話cookie無法訂閱；使用 OAuth 連線或 API 金鑰。
交付停止,但訂閱仍然重新整理。檢查 deliveryStatus.lastError 以及 failedSince 如果憑據已被撤銷或使用者失去了訪問許可權,則訂閱已過期,並且重新整理返回無。 deliveryStatus.
代理不斷對自己的評論作出反應。檢查 data.actor.self 寫作之前。
-32602 訂閱時 priorities.changed.空轉 arguments。一個 targetUserId 或者任何其他引數被拒絕:只有您自己的佇列才能被觀察。
停機後錯過的更改。重試在大約 7.5 分鐘後停止,並且不會重播。 cards.list, cards.get, comments.list, 或 priorities.list.