B.5 MCP 伺服器整合:串接 Google Sheets、REST API、資料庫與外部工具
🏆 ERP 旗艦專案・模組 8 延伸:把庫存 Web App 包成 MCP 伺服器 本節產出:一支約 80 行的 MCP 伺服器,讓 Antigravity、Claude Code 等 AI 工具用同一套介面查詢 ERP 庫存,必要時才開放下單。
學完本節,你能夠:
- 說出 MCP 的三個角色(Host、Client、Server)與三種能力(Tools、Resources、Prompts),並判斷串接試算表時該選哪一種接法。
- 把「讓 AI 查庫存、幫我下單」這句話寫成含權限與例外的規格表。
- 安裝並測試一支 MCP 伺服器,驗證它在唯讀、超量、斷線時都會正確拒絕。
壹、開場情境:AI 能連上 ERP 了,然後呢?
📌 以下為教學情境(依實務改編)。
第 8.3 節,我們把 ERP 試算表部署成 Web App:doGet 用 action=checkStock 查「庫存主檔」,doPost 呼叫 apiSubmitSalesOrder() 建立「銷售訂單」並扣庫存;每個請求都必須帶上存取密鑰 token(存在 Apps Script 指令碼屬性 API_TOKEN),否則一律回覆「未授權」。
營運總監想更進一步:「我不想記網址、也不想自己組 JSON。我希望在 Antigravity 或 Claude Code 裡直接問『A 款鍵盤還有幾台?』,AI 就去查。」
IT 主管則提出兩個疑慮:
| 疑慮 | 具體擔心的事 |
|---|---|
| 工具要接幾次? | 公司同時在用兩、三種 AI 工具,每換一種就要重寫一次串接嗎? |
| AI 會不會亂下單? | 查庫存無所謂,但 doPost 會真的扣庫存。AI 聽錯一句話,倉庫數字就錯了。 |
本節要解決的問題: 用 MCP 把 ERP 包成「AI 工具都看得懂的插座」,同時讓查詢預設開放、下單預設關閉,而且任何失敗都明確回報,不讓 AI 猜答案。
貳、為什麼要用 MCP:一個插座、三種能力
MCP(Model Context Protocol,模型上下文協定)是 Anthropic 在 2024 年 11 月發布的開放標準,第 8.3 節已介紹過它的來由。這裡只整理本節會用到的部分。
1. 三個角色
| 角色 | 是什麼 | 本節的例子 |
|---|---|---|
| Host(主機) | 你操作的 AI 應用程式 | Antigravity、Claude Code |
| Client(用戶端) | Host 內部負責與某一個伺服器連線的元件 | 由 Host 自動建立,你不用寫 |
| Server(伺服器) | 把外部系統包裝成標準介面的小程式 | 本節要寫的 erp-mcp-server.mjs |
伺服器只要寫一次,任何支援 MCP 的 Host 都能接。這就是 IT 主管第一個疑慮的答案。
2. 三種能力與兩種連線方式
| 名稱 | 白話說明 | 例子 |
|---|---|---|
| Tools(工具) | AI 可以呼叫的動作,可能改變資料 | check_erp_inventory、create_sales_order |
| Resources(資源) | AI 可以讀取的資料內容 | 一份產品型錄、一張報表 |
| Prompts(提示範本) | 伺服器預先寫好的作業範本 | 「月底庫存盤點」標準提問 |
| stdio 連線 | Host 在你電腦上啟動伺服器程式,透過標準輸入輸出溝通 | 本節採用 |
| Streamable HTTP 連線 | 伺服器架在網路上,Host 用網址連線 | 雲端服務商提供的 MCP 伺服器 |
訊息格式都是 JSON-RPC 2.0(一種用 JSON 呼叫遠端函式的規格),你不需要手寫,SDK 會處理。
3. 串接 Google 試算表的三條路
| 接法 | 優點 | 缺點 | 適合 |
|---|---|---|---|
| Google 官方 Workspace MCP 伺服器(Sheets 等,目前為開發者預覽) | 不用寫程式,可讀寫任何試算表 | 需設定 Google Cloud 專案與 OAuth;AI 拿到的是「整張表」的權限,商業規則不在裡面 | 個人整理資料 |
| 社群開發的試算表 MCP 套件 | 安裝快 | 品質與維護不一;安裝前先到 npm 或 GitHub 確認套件真的存在,網路文章常寫錯名稱 | 試玩 |
| 自己包 Web App(本節) | 防超賣等規則仍由 GAS 執行;AI 只能做你開放的動作 | 要寫約 80 行程式 | 公司正式系統 |
💡 為什麼選第三條路? 第 8.3 節的
apiSubmitSalesOrder()已經寫好「庫存不足就拒絕」的規則。如果讓 AI 直接改試算表儲存格,等於繞過這道防線。MCP 伺服器只是轉接頭,商業規則留在原本的系統裡。
參、把規則寫下來:AI 能做什麼、不能做什麼
| 主管說的話 | 需要追問的問題 | 寫成規格 |
|---|---|---|
| 「讓 AI 查庫存」 | 查哪些資料?會改資料嗎? | 工具 check_erp_inventory:輸入品名關鍵字,回傳「庫存主檔」的品名、即時庫存、加權單位成本 (EUR)、安全庫存、庫存狀態。唯讀,永遠開放 |
| 「也讓 AI 幫我下單」 | 每個人、每台電腦都要開嗎? | 工具 create_sales_order 預設不註冊;只有設定 ERP_ALLOW_WRITE=true 才出現 |
| 「下單別太誇張」 | 多少算誇張? | 單筆數量 > MAX_ORDER_QTY(50)直接拒絕,請業務人工建單 |
| 「庫存不夠就別出」 | 由誰檢查? | 交給 GAS 端 apiSubmitSalesOrder() 檢查,MCP 伺服器不重複實作 |
| (主管沒說)品名打不完整 | 「A款」算不算「人體工學鍵盤 A款」? | 查詢用關鍵字(部分符合即可);下單必須完全一致,否則由 GAS 回傳「找不到品項」 |
| (主管沒說)網路斷了 | AI 該怎麼回答? | 回傳錯誤訊息「查詢失敗」,不給任何數字;下單失敗時註明「未確認是否寫入」 |
| (主管沒說)Web App 網址與密鑰 | 誰可以知道? | 網址放在環境變數 ERP_WEBAPP_URL、密鑰放在 ERP_API_TOKEN,都不寫進程式碼、不放進 Git;每次呼叫 Web App 都帶上密鑰(與第 8.3 節相同) |
最後兩列最容易被忽略。AI 很擅長「把話說得通順」,如果工具失敗時回傳空白,它可能自己補一個看似合理的庫存數字。工具必須把失敗說清楚,這與第 9.2 節的 fail-safe(失敗時停在安全狀態)是同一個原則。
肆、讓 AI 做出來
1. 最小必要概念
- Node.js:在電腦上執行 JavaScript 的環境。MCP 官方 TypeScript SDK 需要 Node.js 18 以上。
- 工具規格(schema):每個工具都要宣告名稱、說明、輸入欄位與型別。AI 是靠「說明」決定什麼時候用這個工具,所以說明要寫清楚。
isError:工具回傳時標記「這次失敗了」,Host 會讓 AI 知道結果不可用。
2. 給 AI 的 Prompt(直接複製)
你是熟悉 MCP TypeScript SDK(@modelcontextprotocol/sdk)的工程師。請寫一支 Node.js(ESM)stdio MCP 伺服器。
【後端】Google Apps Script Web App,網址從環境變數 ERP_WEBAPP_URL、存取密鑰從 ERP_API_TOKEN 讀取:
- 每個請求都要帶密鑰:GET 放在網址參數 token,POST 放在 JSON 內容的 token 欄位;
密鑰錯誤時回傳 {success:false, error:'未授權…'}。
- GET ?action=checkStock&item=關鍵字&token=密鑰 → {success, data:[{itemName, availableStock, unitCostEur, safetyStock, status}]}
- POST JSON {customer, item, quantity, unitPriceTwd, token} → {success, orderId, remainingStock} 或 {success:false, error}
【工具】
1. check_erp_inventory(item_name: 字串):呼叫 GET,回傳 data;data 為空時回覆「找不到」。
2. create_sales_order(customer, item_name, quantity: 正整數, unit_price_twd: 正數):呼叫 POST。
僅在環境變數 ERP_ALLOW_WRITE 等於 "true" 時才註冊此工具。
【商業規則】quantity 大於常數 MAX_ORDER_QTY(50,宣告在程式最上方)時不呼叫後端,直接回傳錯誤。
【例外處理】未設定網址或密鑰、網路錯誤、HTTP 非 200、回傳不是 JSON、success 為 false:
一律回傳 isError: true 與中文錯誤訊息(附上後端的 error 原文),不得回傳預設值或猜測值;
錯誤訊息中不得出現密鑰。
【輸出要求】單一檔案,使用 registerTool 與 zod 定義輸入欄位,附中文註解。
3. AI 產出的程式碼(已人工驗收)
// erp-mcp-server.mjs:把模組 8 的 GAS Web App 包裝成 MCP 伺服器
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
// ===== 商業規則與權限(經理人只需要改這幾行)=====
const WEBAPP_URL = process.env.ERP_WEBAPP_URL; // GAS 部署後的 /exec 網址
const API_TOKEN = process.env.ERP_API_TOKEN; // 與 Apps Script 指令碼屬性 API_TOKEN 相同的密鑰
const ALLOW_WRITE = process.env.ERP_ALLOW_WRITE === 'true'; // 預設唯讀:不開放下單
const MAX_ORDER_QTY = 50; // AI 單筆下單上限,超過請人工處理
// 共用:呼叫 Web App,失敗就丟出錯誤(不回傳假資料)
async function callWebApp(options = {}, query = '') {
if (!WEBAPP_URL) throw new Error('尚未設定 ERP_WEBAPP_URL');
if (!API_TOKEN) throw new Error('尚未設定 ERP_API_TOKEN,ERP 會拒絕所有請求');
const res = await fetch(WEBAPP_URL + query, options);
if (!res.ok) throw new Error(`Web App 回應 HTTP ${res.status}`);
return res.json(); // 若回傳的不是 JSON(例如登入頁),這裡會直接失敗
}
const server = new McpServer({ name: 'erp-inventory', version: '1.0.0' });
// 工具 1:查庫存(唯讀,永遠開放)
server.registerTool(
'check_erp_inventory',
{
description: '查詢 ERP 試算表「庫存主檔」中商品的即時庫存、加權單位成本(EUR)與安全庫存',
inputSchema: { item_name: z.string().describe('商品名稱關鍵字,例如:鍵盤 A款') },
},
async ({ item_name }) => {
try {
const q = '?action=checkStock&item=' + encodeURIComponent(item_name) +
'&token=' + encodeURIComponent(API_TOKEN);
const result = await callWebApp({}, q);
if (!result.success) throw new Error(result.error || 'Web App 回傳 success=false');
if (result.data.length === 0) {
return { content: [{ type: 'text', text: `庫存主檔中找不到「${item_name}」` }] };
}
return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
} catch (err) {
// fail-safe:查不到就明確告訴 AI「查詢失敗」,讓它停下來回報,而不是猜一個數字
return { isError: true, content: [{ type: 'text', text: '查詢失敗:' + err.message }] };
}
}
);
// 工具 2:建立銷售訂單(會扣庫存,必須明確開啟才註冊)
if (ALLOW_WRITE) {
server.registerTool(
'create_sales_order',
{
description: '在 ERP 建立銷售訂單並扣減庫存。品名必須與庫存主檔完全一致。',
inputSchema: {
customer: z.string(),
item_name: z.string(),
quantity: z.number().int().positive(),
unit_price_twd: z.number().positive(),
},
},
async ({ customer, item_name, quantity, unit_price_twd }) => {
if (quantity > MAX_ORDER_QTY) {
return { isError: true, content: [{ type: 'text',
text: `數量 ${quantity} 超過 AI 下單上限 ${MAX_ORDER_QTY},請改由業務人工建單` }] };
}
try {
// 欄位名稱必須與 ERP_Full_System.js 的 apiSubmitSalesOrder(data) 一致
// 密鑰放在 JSON 內容(GAS 讀不到自訂 HTTP 標頭),不留在網址紀錄裡
const body = { customer, item: item_name, quantity, unitPriceTwd: unit_price_twd, token: API_TOKEN };
const result = await callWebApp({
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(body),
});
return { isError: !result.success, content: [{ type: 'text', text: JSON.stringify(result) }] };
} catch (err) {
return { isError: true, content: [{ type: 'text', text: '下單失敗,未確認是否寫入:' + err.message }] };
}
}
);
}
await server.connect(new StdioServerTransport());
🔍 驗收重點(不懂語法也能檢查) -
create_sales_order是否包在if (ALLOW_WRITE)裡?沒開啟時,AI 連這個工具都看不到,自然無從誤用。 - POST 的欄位是否叫item、quantity、unitPriceTwd?名稱與apiSubmitSalesOrder()不一致,GAS 就找不到品項。 - 每一個catch是否都回傳isError: true,而不是回傳 0 或空陣列? - 密鑰是否從環境變數讀取,查詢與下單都有帶上?
4. 安裝與執行
- 部署 Web App 並設定密鑰:在第 8.3 節的 ERP 試算表中,點選【擴充功能】→【Apps Script】→【部署】→【新增部署作業】,類型選「網頁應用程式」,執行身分選「我」,存取權選「任何人」。複製結尾為
/exec的網址。接著在編輯器上方函式選單選setupApiToken並按【執行】,複製畫面顯示的密鑰(做法同第 8.3 節;已做過就沿用同一把)。 - 建立專案資料夾(終端機操作見附錄 E):
bash
mkdir erp-mcp && cd erp-mcp
npm init -y
npm install @modelcontextprotocol/sdk@1 zod
把程式碼存成 erp-mcp-server.mjs。
3. 註冊到 Claude Code(第 B.8 節):-- 之後是啟動伺服器的指令,路徑請用絕對路徑。
bash
claude mcp add --env ERP_WEBAPP_URL=https://script.google.com/macros/s/你的ID/exec --env ERP_API_TOKEN=你的密鑰 erp -- node /完整路徑/erp-mcp/erp-mcp-server.mjs
進入 Claude Code 後輸入 /mcp,確認 erp 已連線。
4. 註冊到 Antigravity:在 Agent 面板點「…」→【MCP Servers】→【Manage MCP Servers】→【View raw config】,開啟並編輯 mcp_config.json(全域設定檔 mcp_config.json,或專案內 .agents/mcp_config.json;路徑依版本可能調整,以介面開啟的檔案為準),填入同樣的內容。多數工具使用相同的 mcpServers JSON 格式:
json
{
"mcpServers": {
"erp": {
"command": "node",
"args": ["/完整路徑/erp-mcp/erp-mcp-server.mjs"],
"env": {
"ERP_WEBAPP_URL": "https://script.google.com/macros/s/你的ID/exec",
"ERP_API_TOKEN": "你的密鑰"
}
}
}
}
- 開放下單(選做):在
env加上"ERP_ALLOW_WRITE": "true",重新啟動 AI 工具。
⚠️ 設定檔裡有密鑰,不要分享、截圖或上傳到 GitHub。懷疑外流時,重新執行
setupApiToken換一把,再更新這裡的ERP_API_TOKEN。
伍、跑跑看、壞給你看
以 setupERPFullSystem() 初始化後的資料為準(A 款庫存 50 台、B 款 8 台)。每個實驗都直接用自然語言問 AI,再看它呼叫了哪個工具、拿到什麼結果。
| 實驗 | 操作 | 預期結果 | 想想看 |
|---|---|---|---|
| ① 唯讀模式 | 未設定 ERP_ALLOW_WRITE,請 AI「幫德國客戶下 25 台 A 款」 |
工具清單只有 check_erp_inventory,AI 會說它沒有下單工具 |
為什麼「看不到工具」比「看得到但被拒絕」更安全? |
| ② 正常下單 | 開啟寫入,再下同一張單(單價 NT$ 4,200) | 成功,回傳 remainingStock: 25;再查一次 A 款顯示 25 台 |
試算表「銷售訂單」分頁多了哪一列? |
| ③ 超賣與超量 | 請 AI 下 B 款 10 台;再下 A 款 60 台 | B 款被 GAS 拒絕(僅剩 8 台);A 款 60 台被 MCP 伺服器擋下(上限 50),根本沒送到 GAS | 兩道防線分別在哪一層?少了哪一道會出事? |
| ④ 密鑰或網址打錯 | 把 ERP_API_TOKEN 改錯一個字後查詢;再改回來,改錯 ERP_WEBAPP_URL 後查詢 |
密鑰錯:「查詢失敗:未授權:缺少或錯誤的 token(請洽系統管理員)」;網址錯:「查詢失敗:…」。AI 應回報無法取得資料 | 如果工具回傳 0,AI 會怎麼回答總監? |
⚠️ 品名比對不一致:查詢時輸入「A款」查得到(
doGet用部分比對),但下單時品名填「A款」會被拒絕(apiSubmitSalesOrder要求完全一致)。這是刻意的設計:查詢可以寬鬆,動到庫存必須精確。
陸、回到情境
總監現在可以在任何支援 MCP 的 AI 工具裡問庫存;IT 主管的兩個疑慮也有了答案:伺服器寫一次就能接多種工具,下單預設關閉且有數量上限、超賣仍由 GAS 擋下。
這個系統還做不到的事:
| 限制 | 後果 | 在哪一節解決 |
|---|---|---|
| 所有呼叫者共用一把密鑰 | 密鑰外流後,任何人不經過 AI 也能直接下單;也分不出是誰下的單 | 定期換密鑰;第 13.2 節 最小授權;第 9.2 節 權限隔離 |
| AI 下單前不會先問人 | 一句話就扣庫存 | Host 的工具核准設定(B.8 權限模式);第 13.2 節 雙簽 |
| 工具不回傳售價與匯率 | AI 無法正確算出這張單的毛利率 | 練習 2 |
| 客戶訊息裡夾帶惡意指令 | AI 可能被誘導呼叫下單工具 | 第 13.1 節 提示注入防禦 |
本節小結
- MCP 讓「一個伺服器、多種 AI 工具」成為可能;Tools 是動作,Resources 是資料,Prompts 是範本。
- 串接既有系統時,讓 MCP 伺服器當轉接頭,商業規則留在原系統,不要讓 AI 繞過它。
- 權限分級:查詢預設開放,寫入預設關閉,再加數量上限。
- 工具失敗時必須回報「失敗」,不能回傳看似正常的預設值。
柒、練習
- 改規則(5 分鐘):公司決定 AI 單筆下單上限改為 20 台。你要改哪一行?改完後重做實驗 ②,結果會變成什麼?
- 加功能(20 分鐘):請修改第肆段的 Prompt,新增唯讀工具
check_low_stock:回傳「即時庫存 ≤ 安全庫存」的品項。用初始資料驗證:應回傳 B 款(8 ≤ 10)與 C 款(5 ≤ 10)。(提示:可以重用checkStock不帶item參數時回傳全部品項的行為。) - 管理反思(討論):IT 主管提議「乾脆用 Google 官方的試算表 MCP 伺服器,讓 AI 直接改儲存格,省掉 80 行程式」。請從內部控制、稽核軌跡、換工具成本三個角度評估這個提議。哪些部門適合用官方伺服器,哪些不適合?