Agent MCP
透過 MCP 將 AI 代理連接至 HiMarket：搜尋卡牌目錄同市場，並管理您嘅出售列表同購買列表。
這是什麼
HiMarket 提供一個 Model Context Protocol（MCP）伺服器，等 AI 代理可以同您一樣使用市場：搜尋目錄、睇市場狀況，以及管理該帳戶嘅出售列表同購買列表。代理係以帳戶持有人身份行事，唔會獲得職員或管理員權限。
端點：https://www.himarket.hk/api/mcp（Streamable HTTP）。適用於支援 MCP 嘅用戶端，例如 Cursor、Claude。
如何連接
開發者用戶端多數以 Personal Access Token 作為 bearer token 驗證。請登入後喺個人設定頁面嘅 API tokens 區塊建立。完整權杖只會喺建立時顯示一次 — 請當密碼保管。
- 打開個人設定頁面，展開 API tokens。
- 建立權杖，並選擇 scopes 同 mode（見下文）。
- 喺 MCP 用戶端填上上述端點，並以 bearer token 連接（
Authorization: Bearer …）。
支援 MCP OAuth 探索嘅用戶端可以唔使手動貼上權杖。您批准應用程式之後，HiMarket 會按您選擇嘅 scopes 同 mode 發出權杖。授權畫面預設為 propose 模式。
權限範圍同模式
每枚權杖都有一個或多個 scopes。目前只有以下幾種：
| Scope | 權限 |
|---|---|
read | 目錄、市場、您嘅上架同購買列表、whoami、get_capacity、get_pricing_guidance |
sellist:write | 建立、定價及取消出售上架 |
buylist:write | 建立、定價及取消購買列表項目 |
每枚權杖仲有一個建立時選定嘅 mode：
| Mode | 行為 |
|---|---|
direct | 寫入工具會即時套用到真實市場。 |
propose | 即時寫入工具會被拒絕。代理改為用 propose_changes 提交草稿；您喺我的列表審批之後先會生效。 |
第三方代理建議預設用 propose 模式。 草稿喺您批准之前唔會生效。whoami 會以 tokenMode 回報模式，代理可以一開始就知道寫入係即時定要經 propose_changes。
兩款遊戲
魔法風雲會 (Magic: The Gathering) 同《符文戰場》(Riftbound) 共用同一個市場同帳戶。目錄工具預設查 MTG，傳 game: "riftbound" 就改查《符文戰場》目錄 — 有啲卡名兩款遊戲都有，所以要指明範圍。
以 printing id 識別嘅操作本身已經唔分遊戲：Riftbound 嘅 printing id 帶有 rb- 前綴。search_catalog、get_format_staples 同 get_demand_overview 係為 MTG 而設，只適用於 MTG。
工具一覽
完整 schema 由用戶端自行 introspect；呢度只係精簡對照，每個工具一行。
探索／讀取（read）
| 工具 | 用途 |
|---|---|
search_cards | 按卡名搜尋 HiMarket 目錄（優先前綴配對，並有模糊搜尋後備）。 |
search_catalog | 結構化 MTG 目錄搜尋（類型、顏色、賽制合法性、系列、價格範圍等）。 |
get_card_printings | 某張卡所有紙牌印刷版本，包括系列、收藏編號同參考價。 |
get_reference_prices | 一次過查最多 25 個卡名嘅參考價同即時供應快照。 |
get_supply_counts | 一次過查最多 25 個卡名嘅實際在售數量（及最平在售價）。 |
get_for_sale | 回傳某一準確卡名而家在售嘅項目。 |
get_market_overview | 每個印刷版本嘅最低售價／最高收購匯總。 |
get_demand_overview | 按 HiMarket 頁面瀏覽量排列嘅卡名，並附供應同賽制主力訊號（MTG）。 |
get_format_staples | 單一構築賽制嘅比賽常用卡（MTG）。 |
get_pricing_guidance | 預設比率、價格下限、品相係數，以及 Riftbound 中文語言係數。 |
whoami | 呢枚權杖代表嘅帳戶，以及權杖嘅 scopes 同 tokenMode。 |
get_capacity | 目前出售／收購數量、帳戶上限，同剩餘空位。 |
list_my_sellist | 呢個帳戶嘅出售上架，以精簡列格式回傳。 |
list_my_buylist | 呢個帳戶嘅有效購買列表項目，同一精簡列格式。 |
list_my_cards | 帳戶全部收藏，包括未出售嘅卡。 |
即時寫入 — 只限 direct 模式
呢啲工具會即時生效。propose 模式下會被拒絕，請改用 propose_changes。每一邊都需要對應嘅寫入 scope（sellist:write 或 buylist:write）。
| 工具 | 用途 |
|---|---|
create_sellist | 為同一個印刷版本建立 1–20 張出售上架。 |
bulk_create_sellist | 為多個不同印刷版本建立出售上架（自動分批）。 |
set_sellist_price / bulk_set_sellist_price | 設定絕對港幣售價。 |
bulk_price_sellist_by_ratio | 以 ratio × 參考價為出售上架定價。 |
cancel_sellist / bulk_cancel_sellist | 取消（軟刪除）上架。 |
bulk_delist | 將上架從出售中移除，卡牌仍留喺收藏。 |
create_buylist | 為同一個印刷版本建立 1–20 個收購，即時定價。 |
bulk_create_buylist | 為多個印刷版本建立收購（自動分批）。可選 maxTotalHKD 預算。 |
set_buylist_price / bulk_price_buylist_by_ratio | 為收購定價（絕對港幣或按 ratio）。 |
cancel_buylist / bulk_cancel_buylist | 取消收購。 |
提案
propose_changes 需要被修改嗰一邊嘅寫入 scope。列出同讀取提案需要 read。撤回仍待處理嘅草稿需要任何一個寫入 scope。
| 工具 | 用途 |
|---|---|
propose_changes | 提交草稿批量修改，等帳戶持有人喺我的列表審批。 |
list_my_proposals | 列出呢個帳戶嘅提案（id、side、狀態、計劃摘要）。 |
get_proposal | 讀取單一提案全文 — 可用嚟輪詢有冇獲批。 |
cancel_proposal | 撤回仍待處理嘅草稿。 |
定價方式
所有價格都係港幣整數。ratio 定價 = ratio × 該印刷版本嘅美元參考價（出售一方會按品相調整；收購一方用嘅係賣家點數比率）。Riftbound 中文（zhs / zht）參考價會再乘 0.6（收購一方只有喺接受嘅語言全部都係中文時先會套用）。
下限：出售 HK$8，收購 HK$4。
收購一方如果用 ratio，而參考價低於大約 US$0.5 / ratio，四捨五入後會變成 0 而被拒絕。非常平嘅卡請改傳絕對價格（最低 HK$4）。
金額防護
- 預算中止：
bulk_create_buylist同propose_changes接受可選嘅maxTotalHKD。如果總承擔額會超過預算，整次呼叫會中止、唔會寫入。 - 實際扣款： 購買列表成交會從買家帳戶扣除真實商店點數。
- 交易費： 購買列表成交時，買家須喺收購價之上支付 HK$3 + 4% 交易費；賣家全數收到收購價。
- 速率限制： 每枚權杖都有速率限制，MCP 工具同對應 API 呼叫一併計算。