目前的 MCP 工具可列出、搜尋、閱讀、建立、編輯及顯示 Heptabase 工作區中的內容。互動卡片顯示需要支援 MCP Apps 的用戶端。

瀏覽卡片、標籤與白板

操作	工具與說明
卡片	`list_cards` 列出卡片但不讀取內容。可以依卡片類型、所屬白板或標籤、時間戳記或已知 ID 篩選，也可包含標籤、白板與時間戳記等輕量中繼資料。預設不包含劃記。若要列出劃記，請助理在 `objectTypes` 中包含 `highlightElement`。結果採分頁，預設每次 20 張卡片，最多 100 張。需要完整清單時，請助理繼續讀取每一頁。
標籤	`list_tags` 列出標籤的階層與卡片數量。可以先用它找出標籤 ID，再篩選卡片或讀取標籤資料庫。
白板	`list_whiteboards` 列出白板階層，附有輕量物件數量並支援分頁。

搜尋 Heptabase 工作區

操作	工具與說明
關鍵字	`search_by_keyword` 使用精確關鍵字或短語搜尋標題及支援的文字內容。PDF、影片與音訊卡片只搜尋標題。需要完整內容時，請使用讀取工具。
語意	`search_by_semantic` 使用自然語言查詢，依語意搜尋。相關筆記可能使用不同措辭時很有用。語意搜尋不會搜尋標籤或白板。
物件內文	`search_object_content` 在一個已知物件內搜尋字面文字或正規表示式。回傳含行號的相符片段，也能搜尋 PDF 卡片已儲存的解析內容。

操作	工具與說明
卡片內容	`read_object` 取得其他工具回傳的 ID 後，讀取特定物件。長篇文字可以分段讀取。對 PDF 卡片，此工具回傳中繼資料；頁面內容請使用 `read_pdf`。
白板結構	`read_whiteboard` 讀取白板結構，或白板上物件的內容。
日期範圍	`read_journal_range` 讀取指定日期範圍內現有的每日記錄，包含起迄日並由舊到新排列。每次最多涵蓋 92 天。
資料庫	`read_database` 讀取標籤資料庫的屬性結構、檢視、篩選、排序、選項及關聯目標。
PDF 頁面	`read_pdf` 從已解析的 PDF 卡片讀取指定頁碼範圍，頁碼從 1 起算且包含起迄頁。PDF 必須受支援且已成功解析。
圖片	`read_image` 利用 `read_object` 回傳的圖片引用中的檔案與來源物件資訊，讀取圖片。

MCP 讀取結果目前不包含 PDF 劃記的來源定位資訊。對個別劃記，MCP 不會提供來源 PDF ID、頁碼、劃記區域座標／矩形，或同等精確的深層連結。也沒有包含這些定位資訊的白板範圍匯出功能。如果需要重建這些資訊，目前必須匯出完整帳戶。

操作	工具與說明
顯示卡片	`render_cards` 在支援 MCP Apps 的相容用戶端（如 ChatGPT 或 Codex 應用程式）中，以互動檢視顯示選定的 Heptabase 卡片。支援筆記、日誌、PDF、影片、音訊、圖片、網頁卡片與劃記。每次最多接受 20 個卡片引用，重複引用只顯示一次。可以試著說：「找出我關於再生能源的筆記，摘要最相關的幾篇，並顯示這些卡片。」也可以在助理建立或編輯卡片後，請它顯示卡片。在純文字或終端機用戶端中，助理應改以文字呈現結果。
參考文件	`read_system_manual_page` 閱讀 Heptabase MCP 關於核心概念、富文字語法及資料庫屬性的參考頁面。

操作	工具與說明
建立內容	`create_object` 建立新的筆記卡片，或在指定日期尚無日誌時建立日誌記錄。
附加日誌	`append_to_journal` 將內容附加至既有日誌；如果日誌不存在，則建立該日誌。
編輯內容	`edit_object_content` 在筆記卡片或日誌中尋找並取代精確文字。
修改屬性	`edit_card_properties` 更新既有標籤資料庫中某張卡片的屬性值。
加入標籤	`update_database_card_membership` 將既有卡片加入標籤資料庫。
放到白板	`place_whiteboard_objects` 自動將既有筆記、日誌、PDF、圖片、影片、音訊及網頁卡片放到白板。不提供精確定位、移動、縮放，或編輯區塊、文字元素、心智圖與連線。這些版面操作請使用 Heptabase 應用程式或 Heptabase CLI。

重要：Heptabase MCP 目前可建立筆記卡片與日誌記錄，但不能上傳檔案或建立新的圖片卡片。若要使用圖片，請先在 Heptabase 上傳或貼入。MCP 接著就能找到、閱讀，或將既有圖片卡片放到白板上。如果只需要引用，可建立包含圖片網址的筆記卡片。

典型工作流程會結合多個工具：

瀏覽：使用 list_cards、list_tags 或 list_whiteboards 找出現有內容。
搜尋：使用 search_by_keyword 尋找精確用詞、search_by_semantic 尋找相關想法，或用 search_object_content 搜尋已知物件內部。
閱讀：使用對應讀取工具取得完整內容、白板結構、日期範圍內的日誌、資料庫設定、PDF 頁面或圖片。
建立或編輯：建立卡片、附加日誌內容、編輯卡片內容與屬性、將卡片加入標籤資料庫，或將既有物件放到白板。
顯示：在相容的 MCP Apps 用戶端中，找到或更新卡片後，使用 render_cards 顯示為使用者選定的卡片。