B.5 MCP 伺服器整合:串接 Google Sheets、REST API、資料庫與外部工具

🏆 ERP 旗艦專案・模組 8 延伸:把庫存 Web App 包成 MCP 伺服器 本節產出:一支約 80 行的 MCP 伺服器,讓 Antigravity、Claude Code 等 AI 工具用同一套介面查詢 ERP 庫存,必要時才開放下單。

學完本節,你能夠:

  1. 說出 MCP 的三個角色(Host、Client、Server)與三種能力(Tools、Resources、Prompts),並判斷串接試算表時該選哪一種接法。
  2. 把「讓 AI 查庫存、幫我下單」這句話寫成含權限與例外的規格表。
  3. 安裝並測試一支 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. 安裝與執行

  1. 部署 Web App 並設定密鑰:在第 8.3 節的 ERP 試算表中,點選【擴充功能】→【Apps Script】→【部署】→【新增部署作業】,類型選「網頁應用程式」,執行身分選「我」,存取權選「任何人」。複製結尾為 /exec 的網址。接著在編輯器上方函式選單選 setupApiToken 並按【執行】,複製畫面顯示的密鑰(做法同第 8.3 節;已做過就沿用同一把)。
  2. 建立專案資料夾(終端機操作見附錄 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": "你的密鑰" } } } }

  1. 開放下單(選做):在 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 節 提示注入防禦

本節小結

  1. MCP 讓「一個伺服器、多種 AI 工具」成為可能;Tools 是動作,Resources 是資料,Prompts 是範本。
  2. 串接既有系統時,讓 MCP 伺服器當轉接頭,商業規則留在原系統,不要讓 AI 繞過它。
  3. 權限分級:查詢預設開放,寫入預設關閉,再加數量上限。
  4. 工具失敗時必須回報「失敗」,不能回傳看似正常的預設值。

柒、練習

  1. 改規則(5 分鐘):公司決定 AI 單筆下單上限改為 20 台。你要改哪一行?改完後重做實驗 ②,結果會變成什麼?
  2. 加功能(20 分鐘):請修改第肆段的 Prompt,新增唯讀工具 check_low_stock:回傳「即時庫存 ≤ 安全庫存」的品項。用初始資料驗證:應回傳 B 款(8 ≤ 10)與 C 款(5 ≤ 10)。(提示:可以重用 checkStock 不帶 item 參數時回傳全部品項的行為。)
  3. 管理反思(討論):IT 主管提議「乾脆用 Google 官方的試算表 MCP 伺服器,讓 AI 直接改儲存格,省掉 80 行程式」。請從內部控制、稽核軌跡、換工具成本三個角度評估這個提議。哪些部門適合用官方伺服器,哪些不適合?

國立臺中科技大學 國際貿易系 / 企業管理系 專用教材

《現代軟體工程:商學院的 AI 系統思維與 Agent 實踐》

作者:陳俊智 博士 Dr. Chun-Chih Chen

本書章節架構改編自陳鍾誠教授(金門大學)開源課程《現代軟體工程》(github.com/ccc115a/se,MIT 授權),內容針對商學院全面改寫與擴充。