ragic-mcp: Instructions file for Codex

AGENTS.md — ragic-mcp 給 AI 的操作指南

如果你（AI）看到這份檔案，代表你正在透過 ragic-mcp 操作 Ragic。先把這份讀完再開始下指令，能省你很多次來回試錯。

---

0. AI 自助安裝流程（user 第一次叫你裝時跑這個）

User 第一次叫你「裝 ragic-mcp」或貼這個 repo URL 給你時，照以下順序跑。每一步跑完才進下一步，不要平行。

0.1 檢查工具鏈

which uv          # 沒裝就先：brew install uv（macOS）
which ragic-mcp   # 已裝 → 跳 0.3；沒裝 → 0.2

0.2 安裝 ragic-mcp 到全域

uv tool install git+https://github.com/EthanH9977/ragic-mcp.git

裝完用 which ragic-mcp 確認回 ~/.local/bin/ragic-mcp。

0.3 檢查 credentials 是否已設

ragic-mcp show

• 回 (no config — run ragic-mcp setup first) → 進 0.4
• 已顯示 mask 過的 key → 跳 0.5

0.4 取得 user 的 credentials 並寫入 config

先問 user 兩件事（不要猜）：

1. 「請貼一張你 Ragic 表單的網址」（用來解 server 與 account）
2. 「請給我你的 Ragic API key」（Ragic 後台 → 個人設定 → 帳號設定 → API key）

從 URL https://<server>/<account>/<path>/<sheet>?... 抓出 <server> 與 <account>，再跑：

ragic-mcp setup --server <server> --account <account> --api-key <api_key>

例如 user 給的是 https://ap5.ragic.com/mycompany/sales/1 與 key XXX：

ragic-mcp setup --server ap5.ragic.com --account mycompany --api-key XXX

config 會寫到 ~/.config/ragic-mcp/config.json，權限 0600。寫完 ragic-mcp show 再驗一次，看到 mask 過的 key 才算成功。

安全提醒：API key 出現在你給 user 的命令列裡 → 會進 shell history。跑完 setup 後主動建議 user 在 terminal 跑 history -d $(history 1) 把該行從歷史移掉，或 revoke 重發。

0.5 把 ragic 註冊到 MCP client

判斷 user 用哪個 client：

• Claude Code（terminal 裡有 claude 命令）：

  claude mcp add --scope user ragic ragic-mcp
  

• Claude Desktop：告訴 user 編輯 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows），加入：

  {
    "mcpServers": { "ragic": { "command": "ragic-mcp" } }
  }
  

  然後重啟 Claude Desktop。

0.6 驗證

請 user 重啟對話視窗，下次他開新 session 時你會看到 ragic_* 工具集。先呼叫 ragic_list_sheets() 拿到他所有可讀表的樹，這時就能開工。

---

1. 這個 MCP server 是什麼

把 Ragic（中文表單型資料庫）的 HTTP API 包成 10 個 MCP tool。你呼叫 tool，server 幫你打 Ragic。讀／寫／簽核都可以。