目前的 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顯示為使用者選定的卡片。