# ragic-mcp

讓 AI（Claude Desktop、Claude Code、其他 MCP client）直接操作 [Ragic](https://www.ragic.com/) 的 MCP server。11 個 tool 涵蓋表單探索、讀取、寫入、簽核、上鎖。

權限完全由 Ragic 那邊的 API key 控制——key 是 read-only，寫入類 tool 就會收到 Ragic 的權限錯誤；key 有寫入權限就全用得到。

> AI 怎麼用這個 server 看 [AGENTS.md](./AGENTS.md)。這份檔案只講「給人類的安裝與設定」。

---

## 一、需要的東西

- **Ragic 帳號**與**有效 API key**（Ragic 後台 → 個人設定 → 帳號設定 → API key）
- **Python 3.10+**
- **[uv](https://docs.astral.sh/uv/)**（推薦）：`brew install uv` 或 `pip install uv`

---

## 二、安裝

> **懶人路線**：把這個 repo 網址 `https://github.com/EthanH9977/ragic-mcp` 貼給你的 AI，說「幫我裝這個 MCP」。AI 會照 [AGENTS.md §0](./AGENTS.md) 的 6 步流程自動跑完安裝＋設定＋註冊到 MCP client。下面是手動流程：

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

裝完 `ragic-mcp` 命令會自動在 PATH 裡，任何 terminal 直接跑。確認：

```bash
which ragic-mcp
# 應該回：/Users/<你>/.local/bin/ragic-mcp
```

> 沒裝 uv？`brew install uv`（macOS）或看 [uv 官網](https://docs.astral.sh/uv/getting-started/installation/)。
>
> 本 server 依賴 **mcp 1.x**（`mcp.server.fastmcp`）。mcp 2.0 已移除該模組，新裝會在 import 時崩潰。已驗證的 interpreter 是 **Python 3.12**。若已裝到壞掉的版本，重裝：
>
> ```bash
> uv tool install --force --python 3.12 git+https://github.com/EthanH9977/ragic-mcp.git
> ```

---

## 三、設定 credentials（一次就好）

在 terminal 跑：

```bash
ragic-mcp setup
```

這會：

1. 在 `~/.config/ragic-mcp/config.json` 建立一份模板（**檔案權限自動 0600**，只有你本人能讀）
2. 用你系統預設的文字編輯器（macOS = TextEdit、Windows = Notepad、Linux = `$EDITOR`）打開
3. 你**直接在編輯器裡填三個值**，存檔關閉

模板長這樣，把右邊三個值換成你的：

```json
{
  "RAGIC_SERVER": "ap5.ragic.com",
  "RAGIC_ACCOUNT": "your_account_here",
  "RAGIC_API_KEY": "paste_your_api_key_here"
}
```

| 欄位 | 取自你 Ragic 表單網址 `https://{server}/{account}/{path}/{sheet}` |
|---|---|
| **RAGIC_SERVER** | `ap5.ragic.com`、`www.ragic.com`、`na3.ragic.com`、`eu2.ragic.com` 其中一個 |
| **RAGIC_ACCOUNT** | 網域後第一段 |
| **RAGIC_API_KEY** | Ragic 後台 → 個人設定 → 帳號設定 → API key |

### 其他相關指令

```bash
ragic-mcp show     # 顯示目前設定（API key 自動 mask 成首尾 4 碼）
ragic-mcp clear    # 刪除本機 config
ragic-mcp serve    # 啟動 MCP server（預設行為，給 client 呼叫）
```

如果你不想存到檔案，也可以用環境變數覆蓋（**env var 優先序高於 config 檔**）：

```bash
RAGIC_SERVER=... RAGIC_ACCOUNT=... RAGIC_API_KEY=... ragic-mcp
```

---

## 四、接到 MCP client

### Claude Desktop

打開 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows），加入：

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

> 注意：`command` 要寫成 `ragic-mcp` 可被 PATH 找到。如果你是裝在 venv，要寫絕對路徑，例如：
> `/path/to/your/venv/bin/ragic-mcp`

存檔後重啟 Claude Desktop。

### Claude Code

```bash
claude mcp add --scope user ragic ragic-mcp
```

（如果 `ragic-mcp` 不在 PATH，改成絕對路徑。）

### 其他 MCP client

任何支援 stdio transport 的 client 都行。指令一律是：

```bash
ragic-mcp
```

---

## 五、驗證

在 MCP client 對話視窗問：

> 呼叫 ragic_filter_help 看 cheatsheet

收到一份 Ragic API filter cheatsheet 就表示通了。

接著測讀取——直接讓 AI 自己探索你的表：

> 用 ragic_list_sheets 列出我所有可以讀的表

AI 拿到表清單後就能直接幫你查特定表，不用再貼網址。

---

## 六、提供的 tool（11 個）

| Tool | 動作 | API key 需要的權限 |
|---|---|---|
| `ragic_list_sheets` | 列出帳號下所有可讀的表（含中文名、path、sheet_index） | read |
| `ragic_list_records` | 列表＋過濾＋排序＋分頁 | read |
| `ragic_get_record` | 讀單筆 | read |
| `ragic_search` | 全文檢索 | read |
| `ragic_create_record` | 新增（含子表） | write |
| `ragic_update_record` | 局部更新欄位 | write |
| `ragic_delete_record` | 刪除單筆 | write |
| `ragic_approve` | 簽核（approve／reject） | approval |
| `ragic_lock` | 上鎖 | write |
| `ragic_unlock` | 解鎖 | write |
| `ragic_filter_help` | 取 filter／參數速查表 | — |

每個 tool 的詳細參數、`where` 過濾語法、子表格寫入格式寫在 [AGENTS.md](./AGENTS.md)。

---

## 七、安全設計

| 防線 | 怎麼擋 |
|---|---|
| API key 不入 git | `.env`、`config.json` 都在 `.gitignore`，setup 寫的也不在 repo 內 |
| API key 不外流 | 設定檔權限 `0600`；`ragic-mcp show` 自動 mask 為首尾 4 碼 |
| API key 不入 shell history | `setup` 用編輯器流程，key 由使用者貼進 config 檔，不經過 terminal 輸入 |
| 主機白名單 | client 拒絕非 `*.ragic.com` 主機，防止打錯網址把 Authorization 送到攻擊者 |
| 不跟 redirect | `httpx.AsyncClient(follow_redirects=False)`，防 3xx 把 header 帶到第三方 |
| 寫入錯誤偵測 | Ragic 寫入失敗會回 HTTP 200 + `{"status":"ERROR"}`，client 已轉成例外 |

依然要遵守的最佳實務：
- API key 給最小權限（read-only 就好的場景不要發 write key）
- 不要把 `~/.config/ragic-mcp/config.json` 拷貝到雲端硬碟或截圖外傳
- 懷疑外流時：Ragic 後台 revoke → 重新跑 `ragic-mcp setup`

---

## 八、Ragic 限速

- 同時待處理佇列 50 個
- 持續超過 5 req/sec 會被人工審查

---

## 九、回報問題

[GitHub Issues](https://github.com/EthanH9977/ragic-mcp/issues)

---

---

## 十一、CLI 直接操作資料

除了 MCP server 模式，`ragic-mcp` 也提供 11 個子指令讓你在 terminal 直接讀寫 Ragic，無需 MCP client。

### 安裝

```bash
uv tool install --editable /path/to/ragic-mcp   # 本機開發版
# 或從 GitHub 安裝正式版：
uv tool install git+https://github.com/EthanH9977/ragic-mcp.git
```

設定 credentials 同 MCP 模式（`ragic-mcp setup`），CLI 讀同一份 `~/.config/ragic-mcp/config.json`。

全域選項：`--config <路徑>` 可覆寫設定檔路徑。

### 子指令速查

| 子指令 | 說明 | 防呆 |
|---|---|---|
| `list-sheets` | 列出所有可讀的表 | — |
| `list-records <path> <sheet_index>` | 列表（支援 `--where`、`--limit`、`--order` 等） | — |
| `get-record <path> <sheet_index> <record_id>` | 讀單筆 | — |
| `search <path> <sheet_index> <query>` | 全文搜尋 | — |
| `filter-help` | 顯示 filter／參數速查表 | — |
| `create-record <path> <sheet_index> <fields_json>` | 新增記錄 | — |
| `update-record <path> <sheet_index> <record_id> <fields_json>` | 更新欄位 | — |
| `delete-record <path> <sheet_index> <record_id>` | 刪除記錄 | **需 `--yes`** |
| `approve <path> <sheet_index> <record_id>` | 簽核（`--action approve\|reject`） | **需 `--yes`** |
| `lock <path> <sheet_index> <record_id>` | 上鎖 | — |
| `unlock <path> <sheet_index> <record_id>` | 解鎖 | — |

結果輸出為 JSON（stdout）；錯誤輸出到 stderr 且 exit code 非 0；`delete-record`/`approve` 無 `--yes` 時 exit 2 且不呼叫 API。

範例：
```bash
# 列出所有表
ragic-mcp list-sheets

# 列出前 3 筆（FNAME 欄位名稱）
ragic-mcp list-records sales 1 --limit 3

# 讀單筆
ragic-mcp get-record sales 1 12345

# 全文搜尋
ragic-mcp search sales 1 "Acme Corp"

# 查 filter 語法
ragic-mcp filter-help

# 刪除（需 --yes）
ragic-mcp delete-record sales 1 12345 --yes
```

### 與 MCP 併存

CLI 與 MCP server 完全複用同一份 client 與 config，無需額外設定。若你的 AI assistant 已透過 MCP 連接 Ragic，CLI 仍可在 terminal 獨立使用，兩者不衝突。

---

## 十二、授權

MIT