D5. InsForge 連線研究

記錄一般開發環境下，與 InsForge 後端溝通的各種連線方式。目前已驗證 InsForge CLI 路徑（例如 npx @insforge/cli db tables、npx @insforge/cli db query "SELECT ..."）， 後續再逐步補上 SDK、REST、MCP 等其他連線方式的觀察與限制。

TL;DR

  • CLI 是目前最直接的後端管理路徑： 在 VS Code Terminal 直接打 npx @insforge/cli 即可列表、查詢，不需要打開網頁後台。
  • MCP 也能連：在 .mcp.json 加 @insforge/mcp， 靠 API_KEY + API_BASE_URL 指向雲端專案，AI Agent 即可直接操作後端。

已驗證的連線方式

方式指令／用法範例適用場景限制／觀察
CLI（已驗證）npx @insforge/cli db tables
npx @insforge/cli db query "SELECT count(*) FROM orders"		後端管理、臨時查詢、Migration、RLS 設定需在 Terminal 操作；連線資訊來自本機環境
MCP（已驗證設定方式）在 MCP 設定加 insforge server（npx -y @insforge/mcp@latest）， env 帶 API_KEY + API_BASE_URL讓 AI Coding Agent（Claude Code / Cursor 等）直接呼叫 InsForge 後端需把專案的 API Key 與 Base URL 寫進 MCP 設定；首次連上可用 fetch-docs 驗證（完整工具清單見下方表格）

MCP 連線設定（後台提供的標準步驟）

InsForge 後台的「Connect via MCP」面板會給兩步驟：

  1. Add MCP Configuration — 把下面這段 JSON 加進你的 MCP 設定檔：
{
  "mcpServers": {
    "insforge": {
      "command": "npx",
      "args": ["-y", "@insforge/mcp@latest"],
      "env": {
        "API_KEY": "ik_7a4e81d565d2e8c058260062514b11c8",
        "API_BASE_URL": "https://ddzb7pwa.us-east.insforge.app"
      }
    }
  }
}
  1. Verify Connection — 對 AI Agent 下 prompt：
    "I'm using InsForge as my backend platform, call InsForge MCP's fetch-docs tool to learn about InsForge instructions."

觀察：MCP 路徑跟 CLI 一樣，最終是靠 API_KEY + API_BASE_URL 指向雲端那個專案， 所以同一份 MCP 設定搬到任何專案的 .mcp.json 都會連到同一個後台。 這也呼應了下一段「後端與資料夾解耦」的觀察。

全域 vs 專案級的選擇：依 CLAUDE.md 全域偏好，Insforge MCP 必須放在專案級的 .mcp.json， 不要放全域；每個有 InsForge 後台的專案根目錄要有自己的 .mcp.json，避免不同專案誤用到同一個後台。

Supabase vs InsForge MCP 的設計差異

兩家 MCP 在「連線層級」上有根本差異，不只是工具清單長短：

項目Supabase MCPInsForge MCP
認證方式個人 access token（綁帳號）專案的 API_KEY + API_BASE_URL（綁專案）
可見範圍整個帳號 → 多組織 → 多專案只看得到「這一個」後端
入口工具list_organizations / list_projects（先選樓層再選房間）get-backend-metadata（一進去就是那個房間，沒得選）
類比公司門禁卡 — 可走遍所有組織與專案單一房間的鑰匙 — 進去就是那個房間

設計上的兩個 trade-off：

  1. 權限邊界更窄、更安全：InsForge 的 API Key 一張只對應一個後端， AI Agent 拿到也跨不到別的專案；Supabase 的 access token 一旦外流，整個帳號的所有專案都暴露。
  2. 不需要「選專案」這一步：因為 MCP 設定當下已經指定了 API_BASE_URL， 所以 skill 流程裡的「Phase 1 確認專案」幾乎是橡皮圖章——沒有第二個選項可選。 這也是為什麼 B5 的 insforge-init 比 supabase-init 的 Phase 1 還弱：Supabase 版要列表格停下來等選，InsForge 版只是讀 metadata 確認一下。

MCP 工具清單

連上 InsForge MCP 後，AI Agent 可以使用的工具共 17 個，分為 6 大類：

分類工具名用途
資料庫與資料操作run-raw-sql執行原始 SQL（需 admin 權限；可建表、插入資料、跑 DDL，會直接改動資料，使用要小心）
bulk-upsert從 CSV 或 JSON 大量插入或更新資料（支援以 unique key 做 upsert）
get-table-schema查詢特定資料表的完整結構（欄位、RLS、索引、約束）
檔案存儲 (Storage)list-buckets列出所有儲存空間（Buckets）
create-bucket建立新的儲存空間
delete-bucket刪除儲存空間
Edge Functions (雲端函式)create-function建立新的 edge function（執行於 Deno runtime；程式碼需先寫入檔案以便版本控管）
update-function更新現有 edge function 的程式碼或設定
get-function讀取特定 edge function 的詳細資訊與程式碼
delete-function永久刪除 edge function
專案部署與初始化download-template新專案的強制第一步：下載官方預設範本到暫存目錄，下載後需用提供的指令複製到目前目錄
create-deployment把資料夾的程式碼部署到雲端（支援平行直傳，舊版專案 fallback 為 zip 上傳）
文件與元數據fetch-docs取得 InsForge 文件：instructions 為後端必備設定（MANDATORY FIRST）； 也可指定 database / auth / storage / functions / AI 等特定 SDK 文件
fetch-sdk-docs取得特定 feature × 語言組合的 SDK 文件。 Feature: db / storage / functions / auth / ai / realtime； 語言: typescript / swift / kotlin / rest-api
get-backend-metadata索引（list out）目前後端的所有元數據
安全與調試get-anon-key產生永不過期的匿名 JWT token（需 admin API key；給 client-side 需要 public access 的場景）
get-container-logs取得特定 container / service 的最新日誌，用於除錯

觀察：MCP 工具涵蓋了 DB CRUD、Storage、Edge Functions、部署、文件查詢、debug log 等 幾乎整條後端鏈路，比 CLI 範圍更廣（CLI 主要落在 db query 與 link 綁定）。 這代表 AI Agent 在 MCP 連通後，幾乎可以脫離後台 UI 完成所有日常後端任務。

後端的範圍：專案 vs 雲端

InsForge 的後端是雲端化的，不綁在這個資料夾，但它確實屬於某一個特定的 InsForge 專案（Project）。 可以從兩個角度理解：

  1. 從任何地方都能呼叫同一個後台：只要有兩樣東西就能連——
    • 後端網址（URL）：例如 https://ddzb7pwa....app
    • 匿名金鑰（ANON_KEY）：一串長編碼
    把這兩項填進另一個資料夾、甚至另一台電腦的程式裡，讀到的會是同一份資料。 類比：就像 Google Drive，手機與電腦看到的內容是同步的。
  2. 它與「專案 ID」綁定：當初執行insforge link --project-id 3f4eed73...， 等於把目前資料夾與雲端那個「抽屜」連起來。 之後開新專案時，可以選擇繼續連到同一個抽屜（共用資料），也可以建立新的抽屜。

觀察筆記

  • 「後端」與「資料夾」是解耦的：資料夾只是放著連線設定的 client， 真正的資料庫住在雲端，靠 project-id 指向哪個抽屜。
  • CLI 連線資訊：透過 insforge link 寫入專案；之後 npx @insforge/cli 系列指令會讀這份綁定。
  • （待補：CLI 認證資訊實際存哪個檔案？跨機器要怎麼帶？）