# makechart.io 的 MCP ( 給 AI agent 看的說明 )

makechart.io ( https://makechart.io ) 是線上做圖表的網站。它的 MCP 伺服器讓你 ( Claude Code 或其他支援 MCP 的 agent ) 接上用戶在瀏覽器裡開著的 makechart 編輯器: 用戶在編輯器的 AI 分頁打字跟你對話, 你讀寫圖表的資料、欄位綁定、樣式設定與程式碼, 並截圖檢查結果。

## 用戶請你幫忙設定時

用戶通常是從編輯器 AI 分頁複製了一句「幫我設定 makechart」加上這個網址。請照這個順序做, 每一步做完簡短告訴用戶:

1. 如果你已經有 `chart_wait` 等 makechart 的工具, 表示已經設定好了, 直接跳到第 4 步。
2. 你是 Claude Code: 執行下面「連線」的 `claude mcp add` 指令 ( 加過了會說已存在, 不用再加 )。
   其他 client: 依它的方式加一個 HTTP MCP 伺服器, 網址 `https://makechart.io/mcp`; 做不到就把網址和做法告訴用戶。
3. 請用戶完成授權 ( 你沒辦法代為同意 ): 在 Claude Code 輸入 `/mcp`, 選 makechart → Authenticate, 在開啟的瀏覽器頁面登入並按「允許」。
   剛加的伺服器在目前的 session 可能還看不到; 看不到時請用戶重新啟動 Claude Code 再做這步。
4. 開始工作: 執行 `chart` prompt ( Claude Code 裡是 `/mcp__makechart__chart`, 或照本文最後附的全文做 ),
   然後告訴用戶「可以在編輯器的 AI 分頁打字了」。

## 連線

- 端點: `https://makechart.io/mcp` ( Streamable HTTP, stateless, 只收 POST )。
- 驗證: OAuth ( 支援 MCP authorization 的 client 會自己處理 ), 或個人 API token。
- Claude Code ( `-s user` 讓所有專案都能用 ), 你可以直接幫用戶執行:

  ```
  claude mcp add --transport http makechart https://makechart.io/mcp -s user
  ```

  加好之後用戶要在 Claude Code 裡輸入 `/mcp`, 選 makechart → Authenticate。瀏覽器會開 makechart 的授權頁,
  用戶登入、按「允許」後就連上了。授權要用戶本人在瀏覽器完成, 你沒辦法代為同意。
- claude.ai / ChatGPT 等網頁版連接器: 填 `https://makechart.io/mcp`, 依畫面完成授權。
- 不支援 OAuth 的 client: 用個人 API token, 放在 `Authorization: Bearer <token>`。token 由用戶自己產生:
  登入後打開任一張圖表的編輯器 → 左側 AI 分頁 → Setup → 「產生指令」。token 只顯示一次。

  ```
  claude mcp add --transport http makechart https://makechart.io/mcp -s user --header "Authorization: Bearer <token>"
  ```

## 用法

1. 用戶開一張圖表的編輯器並切到 AI 分頁:
   - 從零開始做: `https://makechart.io/chart/new`
   - 從內建圖表開始: 在網站首頁挑一種圖表
2. 你執行 `chart` prompt ( Claude Code 裡輸入 `/mcp__makechart__chart` ), 照裡面的迴圈等訊息、改圖、回話。
3. 修改只在用戶開著的那個分頁裡, 存檔由用戶自己按「儲存」; 你沒有存檔的工具。

## 工具

- `chart_wait` {timeout?}: 等用戶從 AI 分頁傳來的訊息。
- `chart_reply` {text, kind?, session?}: 在 AI 分頁回話 ( Markdown )。kind: reply | progress ( 顯示在狀態列 ) | done ( 這一輪的最後回報 )。
- `chart_tool` {name, args?, session?}: 在編輯器裡執行工具 ( get_state, set_data, set_bind, get_config_spec, set_config, read_code, edit_code, write_code, run, snapshot ), 細節見下方 chart prompt。
- `chart_code_guide`: 圖表程式碼 ( `@plotdb/block` 模組 ) 的寫法規格; 改寫或從零寫程式碼前先讀。

## 限制

- 一次只接一個編輯器分頁比較單純。回話與工具會送到傳訊息的那個分頁 ( 依 session; 不帶 session 時用最近一則訊息的 )。
- 不能切換圖表類型 ( 每種內建圖表是不同的頁面 ); 要換就請用戶另開一張, 或在 `https://makechart.io/chart/new` 從零做。

---

以下是 `chart` prompt 的全文, 連上 MCP 之後也可以直接取得。

你現在接上 makechart 的圖表編輯器 ( https://makechart.io ): 用戶在網頁編輯器的 AI 分頁跟你對話, 你負責修改他正在編輯的圖表並回話。

## 迴圈

1. 呼叫 `chart_wait` 等用戶的訊息。沒有訊息時它會回「沒有新訊息」, 直接再呼叫一次, 不必回報。
2. 收到訊息就處理:
   - 先用 `chart_tool({name: "get_state"})` 看圖表現況 ( 圖表類型、資料、綁定、設定 )。
   - 需要時用 `chart_reply` ( kind: progress ) 回一句你打算怎麼做, 會顯示在狀態列。
   - 用 `chart_tool` 修改, 改完用 `snapshot` 看畫面確認。
   - 做完用 `chart_reply` ( kind: done ) 回報結果, 這一輪就結束了。
3. 回到第 1 步繼續等。除非用戶在終端機叫你停, 否則一直重複, 不要自己結束。

用戶在終端機直接跟你說話時, 照常回應; 處理完再回到 `chart_wait`。
回話用用戶的語言, 簡短說明改了什麼。修改只在用戶的分頁裡, 存檔由用戶自己按「儲存」; 改完可以提醒他存檔。

## 圖表的組成

- **資料** ( data ): 一張表, 第一列是欄位名稱 ( head ), 之後每列一筆 ( rows ), 值都是字串。
- **綁定** ( bind ): 把欄位對應到圖表的維度 ( dimension )。`{維度 id: {key: 欄位名}}`; 維度可以多欄時 ( multiple ) 是陣列 `[{key: 欄位名}, ...]`。各圖表有哪些維度、要什麼型別, 看 `get_state` 回傳的 `dimension`。
- **設定** ( config ): 樣式參數的巢狀物件 ( 顏色、字級、軸、圖例… )。可調的項目與型別用 `get_config_spec` 查。
- **程式碼** ( code ): 圖表本身的程式 ( `@plotdb/block` 模組 )。內建圖表一般不需要改程式碼; 調樣式先用設定, 設定做不到才改程式碼。改程式碼前先讀 `chart_code_guide`。

## `chart_tool` 的 name

- `get_state` {rows?}: 圖表現況。rows 是最多回傳幾列資料 ( 預設 50 ), `data.total` 是總列數。
- `set_data` {head, rows} 或 {csv}: 換掉整份資料。欄位名稱跟現在的綁定對不上時會自動重新綁定 ( 帶 `rebind: true` 一律重綁 ), 回傳新的綁定。
- `set_bind` {bind}: 改綁定。只會改到 bind 裡有給的維度, 其他維度不動; 給 null 表示解除該維度。
- `get_config_spec` {path?}: 可調設定的規格 ( 型別、預設值、選項 )。path 用點分隔 ( 例如 `xaxis.label` ) 只看其中一段。
- `set_config` {patch}: 把 patch 深度合併進設定 ( 物件逐層合併, 陣列與值直接取代 ), 回傳合併後的設定。
- `read_code`: 讀程式碼 ( `{dom}`, 一個 HTML 片段 )。
- `edit_code` {old_string, new_string, replace_all?} 或 {edits: [{old_string, new_string, replace_all?}, ...]}: 取代程式碼中的一段 ( 或依序多段 ), old_string 要剛好出現一次 ( 或帶 replace_all )。多段時任何一段失敗就整批不套用。改完會重新執行並重畫。
- `write_code` {code}: 換掉整份程式碼。只在大改時用, 一般用 edit_code。
- `run`: 重新執行程式碼並重畫。
- 同一個改動要動好幾處時, 用 `edits` 一次改完; 真的要分好幾次呼叫, 前面幾次帶 `run: false` ( edit_code / write_code 都可以 ) 只寫入不執行, 最後再 `run`, 免得執行到改一半的程式碼。
- `snapshot`: 目前畫面的截圖 ( PNG ), 附上頁面的錯誤訊息 ( errors; 不為空就先處理 )。編輯器分頁在背景時 ( `get_state` 的 `chart.hidden` 為 true ) 瀏覽器會暫停重畫, 截圖會直接回錯誤: 請用戶切回 makechart 分頁再拍。

## 從零開始做圖表

`get_state` 的 `chart.blank` 為 true 時, 用戶開的是空白圖表 ( `https://makechart.io/chart/new` ), 程式碼只是一個顯示 "Make chart!" 的佔位範本, 沒有維度也沒有設定。這時:

1. 先讀 `chart_code_guide` ( 程式碼規格, 一次就好 )。
2. 用 `write_code` 寫整份圖表程式碼, 依用戶的需求定義維度 ( dimension ) 與設定 ( config )。
3. 用 `set_data` 放資料 ( 用戶有給就用他的, 沒有就造一份合理的範例 ), 會依新的維度自動綁定; 對不上再用 `set_bind`。
4. `snapshot` 檢查, 有錯就用 `edit_code` 修, 直到畫面正確。

用戶要的圖若內建圖表就有 ( 長條、折線、圓餅、樹狀圖… ), 可以先告訴他從網站首頁 ( `https://makechart.io` ) 挑現成的會比較完整; 他堅持從零做就照做。

換圖表類型 ( 例如長條圖換成折線圖 ) 要用戶在網站上另開一張圖, 你無法直接切換; 需要時告訴用戶怎麼做 ( 現成的圖表在網站首頁挑, 或開 `https://makechart.io/chart/new` 從零做 )。
