mcp-api-bridge

MCP API Bridge Server

一個 Model Context Protocol (MCP) 伺服器，用於串接 Google Sheets API、Azure AI API 和 MQTT API。

功能特色

🗃️ Google Sheets API

• 產生新增資料到試算表的程式碼範例
• 產生讀取試算表所有資料的程式碼範例
• 產生更新指定列資料的程式碼範例
• 產生刪除指定列資料的程式碼範例
• 產生覆蓋整張試算表的程式碼範例

🤖 Azure AI API

• 產生使用 Azure AI (GPT-4o-mini) 的程式碼範例
• 支援同步和串流模式的程式碼範例
• WebSocket 程式碼實作範例

📡 MQTT API

• 建立 IoT 裝置連線
• 發布 MQTT 訊息 (同步/非同步)
• 訂閱 MQTT 主題
• 註冊訊息處理器
• 支援 QoS 等級設定

安裝與設定

前置需求

• Node.js 18.0.0 或更高版本
• npm 或 yarn
• Cursor IDE (如果要在 Cursor 中使用)

🚀 快速安裝 (推薦)

1. 全域安裝 MCP API Bridge

npm install -g https://github.com/marty5499/mcp-api-bridge.git

2. 在 Cursor 中設定 MCP

找到並編輯 Cursor 的 MCP 設定檔案：

macOS:

~/.cursor/mcp.json

Linux:

~/.config/cursor/mcp.json

Windows:

%APPDATA%\Cursor\mcp.json

在設定檔案中加入以下配置：

{
  "mcpServers": {
    "api-bridge": {
      "command": "mcp-api-bridge",
      "env": {}
    }
  }
}

3. 重啟 Cursor

重啟 Cursor IDE 使設定生效。

🔄 更新到最新版本

當有新版本發布時，使用以下命令更新：

npm update -g https://github.com/marty5499/mcp-api-bridge.git

🛠️ 開發者安裝 (本地開發)

如果您想要修改或開發此專案：

1. 複製專案

git clone https://github.com/marty5499/mcp-api-bridge.git
cd mcp-api-bridge

2. 安裝依賴套件

npm install

3. 本地測試

# 測試工具列表
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node mcp-api-bridge.js

# 啟動開發模式（檔案監控）
npm run dev

使用方式

✅ 驗證安裝

安裝完成後，您可以在 Cursor 中看到 MCP API Bridge 伺服器已連線，並可使用以下 11 個工具：

• Google Sheets API (5個工具)：產生 API 操作程式碼範例
• Azure AI API (1個工具)：產生 AI 對話程式碼範例
• MQTT API (5個工具)：完整的 IoT 裝置管理功能

可用工具

Google Sheets API 工具

1. google_sheet_append - 產生新增資料的程式碼範例

{
  "url": "https://docs.google.com/spreadsheets/d/your-sheet-id/edit",
  "values": ["張三", "25", "工程師", "2024-01-15"]
}

2. google_sheet_get - 產生讀取資料的程式碼範例

{
  "url": "https://docs.google.com/spreadsheets/d/your-sheet-id/edit"
}

3. google_sheet_update - 產生更新資料的程式碼範例

{
  "url": "https://docs.google.com/spreadsheets/d/your-sheet-id/edit",
  "rowIdx": 2,
  "cols": ["李四", "30", "設計師", "2024-01-16"]
}

4. google_sheet_delete - 產生刪除資料的程式碼範例

{
  "url": "https://docs.google.com/spreadsheets/d/your-sheet-id/edit",
  "rowIdx": 3
}

5. google_sheet_save - 產生覆蓋資料的程式碼範例

{
  "url": "https://docs.google.com/spreadsheets/d/your-sheet-id/edit",
  "rows": [
    ["姓名", "年齡", "職業", "日期"],
    ["王五", "28", "產品經理", "2024-01-17"]
  ]
}

Azure AI API 工具

1. azure_ai_chat - 產生 Azure AI 程式碼範例

{
  "prompt": "我需要一個聊天機器人的程式碼範例",
  "streaming": false
}

MQTT API 工具

1. mqtt_device_create - 建立裝置

{
  "deviceId": "sensor001"
}

2. mqtt_publish - 發布訊息

{
  "deviceId": "sensor001",
  "topic": "server001.data",
  "payload": {
    "temperature": 25.5,
    "humidity": 60.2
  },
  "qos": 0
}

3. mqtt_publish_sync - 同步發布

{
  "deviceId": "client001",
  "topic": "server001.getConfig",
  "payload": {
    "configType": "network"
  },
  "timeout": 10000,
  "qos": 1
}

4. mqtt_register_handler - 註冊處理器

{
  "deviceId": "server001",
  "action": "data",
  "handlerCode": "const { payload } = message; console.log('處理資料:', payload); return { status: 'ok' };"
}

5. mqtt_subscribe - 訂閱主題

{
  "deviceId": "monitor001",
  "topic": "alerts/+",
  "qos": 1
}

API 端點資訊

Google Sheets API

• 基礎 URL: https://hshgpt.webduino.tw/api/sheets/
• 支援操作: append, get, update, del, save

Azure AI API

• WebSocket URL: wss://hshgpt.webduino.tw
• 協定: WebSocket 串流通訊

MQTT API

• Broker URL: wss://mqtt-edu.webduino.io/mqtt
• 認證: username: hsh2025, password: hsh2025

實際應用範例

1. IoT 資料收集系統

// 步驟 1: 建立感測器裝置
await mcp.call('mqtt_device_create', { deviceId: 'temperature_sensor' });

// 步驟 2: 建立資料伺服器
await mcp.call('mqtt_device_create', { deviceId: 'data_server' });

// 步驟 3: 註冊處理器，將資料記錄到 Google Sheets
await mcp.call('mqtt_register_handler', {
  deviceId: 'data_server',
  action: 'logData',
  handlerCode: `
    const { payload } = message;
    // 這裡可以調用 Google Sheets API 記錄資料
    console.log('記錄資料:', payload);
    return { status: 'logged' };
  `
});

// 步驟 4: 感測器發送資料
await mcp.call('mqtt_publish', {
  deviceId: 'temperature_sensor',
  topic: 'data_server.logData',
  payload: {
    temperature: 23.5,
    location: '會議室A',
    timestamp: new Date().toISOString()
  }
});

2. AI 輔助資料分析

// 步驟 1: 讀取試算表資料
const data = await mcp.call('google_sheet_get', {
  url: 'https://docs.google.com/spreadsheets/d/sales-data/edit'
});

// 步驟 2: 產生 Azure AI 分析程式碼
const aiCodeExample = await mcp.call('azure_ai_chat', {
  prompt: '我需要一個分析銷售資料的 AI 程式碼範例',
  streaming: false
});

// 步驟 3: 根據產生的程式碼範例，實作 AI 分析功能
// (這裡需要開發者根據範例程式碼進行實作)
console.log('產生的 AI 程式碼範例:', aiCodeExample.content[0].text);

錯誤處理

所有工具調用都包含錯誤處理機制：

• Google Sheets API: 檢查 URL 格式和 API 回應
• Azure AI API: WebSocket 連線錯誤和逾時處理
• MQTT API: 連線狀態檢查和裝置管理

專案結構

mcp-api-bridge/
├── mcp-api-bridge.js     # 主要 MCP 伺服器檔案
├── lib/
│   └── iotDevice.js      # MQTT IoT 裝置類別
├── examples/
│   └── usage-examples.js # 使用範例
├── docs/
│   └── changelog.md      # 變更日誌
├── package.json          # 專案設定
├── .gitignore           # Git 忽略設定
└── README.md            # 專案說明

📦 GitHub 儲存庫

• 儲存庫 URL: https://github.com/marty5499/mcp-api-bridge
• 授權: MIT License
• 語言: JavaScript (Node.js)

開發指南

新增工具

1. 在 setupToolHandlers() 中定義工具 schema
2. 實作對應的處理函數
3. 新增到 CallToolRequestSchema 的 switch 語句中

測試

# 執行範例
node examples/usage-examples.js

# 測試 MCP 伺服器連線
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node mcp-api-bridge.js

# 測試特定工具 (Google Sheets)
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "google_sheet_get", "arguments": {"url": "https://docs.google.com/spreadsheets/d/test/edit"}}}' | node mcp-api-bridge.js

# 測試全域安裝版本
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | mcp-api-bridge

🔧 疑難排解

問題：Cursor 中看不到 MCP 伺服器

1. 檢查 ~/.cursor/mcp.json 設定檔案格式是否正確
2. 確認已重啟 Cursor IDE
3. 檢查終端機中是否能執行 mcp-api-bridge 命令

問題：工具調用失敗

1. 檢查網路連線狀況
2. 確認 API 端點可正常訪問
3. 查看 MCP 伺服器日誌輸出

問題：更新後功能異常

# 清除 npm 快取並重新安裝
npm cache clean --force
npm uninstall -g mcp-api-bridge
npm install -g https://github.com/marty5499/mcp-api-bridge.git

授權

MIT License

貢獻

歡迎提交 Issues 和 Pull Requests！

更新日誌

v1.0.2 (2025-01-15)

• 🔧 修正 Google Sheets API 工具功能 - 產生程式碼範例而非直接調用 API
• 🚀 支援全域安裝和 Cursor MCP 配置
• 📖 完整的安裝和配置指南
• 🛠️ 疑難排解和測試指南

v1.0.1 (2024-01-20)

• 🔧 修正 Azure AI API 工具功能定位
• 📖 更新相關文件和範例

v1.0.0 (2024-01-20)

• 初始版本發布
• 支援 Google Sheets、Azure AI、MQTT API
• 完整的 MCP 工具實作
• 提供使用範例和文件