Clasp Netlify MCP Guide — Development skill for Claude Code

Clasp 雲端部署 + Netlify MCP 零複製雙向閉環網頁系統：Agent 安裝步驟與避坑指南

本文件為 **AI Coding Agent（如 Antigravity, Claude Code, Cline 等）** 的標準安裝與避坑部署指南。當接收到建立「網頁前端 + Google Sheets 資料庫（經由 GAS Web App API）+ Netlify 部署」之閉環系統需求時，請嚴格遵循以下步驟與安全注意事項，範例程式碼已抽離，聚焦於環境架構之自動化整合。

---

一、 先備條件與安全注意事項

1. 環境依賴：本機必須已安裝 Node.js、npm、git。
2. 帳號準備：使用者須擁有 Google 帳號與 Netlify 帳號。
3. 敏感資料保護（極重要）：
   • 嚴禁將個人的 Netlify Personal Access Token、GITHUB_TOKEN、任何 OAuth 金鑰或 Google 帳號資訊寫入程式碼或提交至公開 Repo。
   • 所有 API 網址、部署 ID 與專案金鑰，必須在執行期間動態生成、填入或透過環境變數傳遞，不得留有任何預設或硬編碼硬傷。

---

二、 本地檔案準備規則

在進行雲端部署前，Agent 必須先在本地工作區建立以下無敏感資料的基礎結構：

1. 後端 GAS 主程式：一個包含 doPost(e) 與 doGet(e) 的後端 JavaScript 檔案（例如 gas_code.js），負責接收前端 API 請求並對接 Google Sheets。
2. GAS 配置文件：一個名稱必須為 appsscript.json 的 GAS Manifest 檔案，其內必須配置 webapp 欄位以允許匿名存取（將執行身分設為 USER_DEPLOYING，存取權設為 ANYONE_ANONYMOUS）。
3. Clasp 過濾清單（避坑關鍵）：在專案根目錄建立 .claspignore，並明確設定規則以排除所有前端網頁檔案（如 index.html、style.css、app.js），僅允許推送 gas_code.js（或後端 gs 檔）與 appsscript.json。
4. 前端網頁檔案：建立遊戲/系統之前端網頁資料夾，內含 HTML、CSS 與 JS 連線程式。連線 JS 必須留有 API 網址的預設預留空字串（如 const GAS_API_URL = "YOUR_GAS_API_URL_HERE";），以便後續動態注入。

---

三、 完整自動化安裝與部署步驟

Agent 應在本地依序執行以下指令，完成雲端與前端的雙向閉環部署：

1. 安裝 Clasp 引擎：
   • 在專案資料夾本地執行：npm install @google/clasp
2. 完成 Google 雲端授權：
   • 啟動登入：npx clasp login
   • Agent 行動：從 terminal 輸出中抓取 🔑 Authorize clasp by visiting this url: ... 的 Google OAuth 授權連結，將連結完整呈現給使用者，引導其點擊並完成瀏覽器授權。
3. 創建 GAS 雲端專案：
   • 在本地資料夾執行：npx clasp create-script --title "專案資料庫" --type standalone
4. 強制推送與發佈 Web App：
   • 執行強推：npx clasp push -f
   • 執行部署：npx clasp create-deployment --description "Production Web App"
5. 動態獲取與注入 API 網址：
   • 執行 npx clasp list-deployments 列出部署。
   • Agent 行動：不要自己拼網址（/macros/s//exec 一定是錯的）。執行 npx clasp open-web-app --json，取 API 回傳的 webApp.url 給使用者。
6. Netlify 全自動網頁發佈：
   • Agent 行動：
     1. 呼叫 `