# 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](https://cursor.sh/) (如果要在 Cursor 中使用)
### 🚀 快速安裝 (推薦)
#### 1. 全域安裝 MCP API Bridge
```bash
npm install -g https://github.com/marty5499/mcp-api-bridge.git
```
#### 2. 在 Cursor 中設定 MCP
找到並編輯 Cursor 的 MCP 設定檔案：
**macOS:**
```bash
~/.cursor/mcp.json
```
**Linux:**
```bash
~/.config/cursor/mcp.json
```
**Windows:**
```bash
%APPDATA%\Cursor\mcp.json
```
在設定檔案中加入以下配置：
```json
{
"mcpServers": {
"api-bridge": {
"command": "mcp-api-bridge",
"env": {}
}
}
}
```
#### 3. 重啟 Cursor
重啟 Cursor IDE 使設定生效。
### 🔄 更新到最新版本
當有新版本發布時，使用以下命令更新：
```bash
npm update -g https://github.com/marty5499/mcp-api-bridge.git
```
### 🛠️ 開發者安裝 (本地開發)
如果您想要修改或開發此專案：
1. 複製專案
```bash
git clone https://github.com/marty5499/mcp-api-bridge.git
cd mcp-api-bridge
```
2. 安裝依賴套件
```bash
npm install
```
3. 本地測試
```bash
# 測試工具列表
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** - 產生新增資料的程式碼範例
```json
{
"url": "https://docs.google.com/spreadsheets/d/your-sheet-id/edit",
"values": ["張三", "25", "工程師", "2024-01-15"]
}
```
2. **google_sheet_get** - 產生讀取資料的程式碼範例
```json
{
"url": "https://docs.google.com/spreadsheets/d/your-sheet-id/edit"
}
```
3. **google_sheet_update** - 產生更新資料的程式碼範例
```json
{
"url": "https://docs.google.com/spreadsheets/d/your-sheet-id/edit",
"rowIdx": 2,
"cols": ["李四", "30", "設計師", "2024-01-16"]
}
```
4. **google_sheet_delete** - 產生刪除資料的程式碼範例
```json
{
"url": "https://docs.google.com/spreadsheets/d/your-sheet-id/edit",
"rowIdx": 3
}
```
5. **google_sheet_save** - 產生覆蓋資料的程式碼範例
```json
{
"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 程式碼範例
```json
{
"prompt": "我需要一個聊天機器人的程式碼範例",
"streaming": false
}
```
#### MQTT API 工具
1. **mqtt_device_create** - 建立裝置
```json
{
"deviceId": "sensor001"
}
```
2. **mqtt_publish** - 發布訊息
```json
{
"deviceId": "sensor001",
"topic": "server001.data",
"payload": {
"temperature": 25.5,
"humidity": 60.2
},
"qos": 0
}
```
3. **mqtt_publish_sync** - 同步發布
```json
{
"deviceId": "client001",
"topic": "server001.getConfig",
"payload": {
"configType": "network"
},
"timeout": 10000,
"qos": 1
}
```
4. **mqtt_register_handler** - 註冊處理器
```json
{
"deviceId": "server001",
"action": "data",
"handlerCode": "const { payload } = message; console.log('處理資料:', payload); return { status: 'ok' };"
}
```
5. **mqtt_subscribe** - 訂閱主題
```json
{
"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 資料收集系統
```javascript
// 步驟 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 輔助資料分析
```javascript
// 步驟 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 語句中
### 測試
```bash
# 執行範例
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 伺服器日誌輸出
#### 問題：更新後功能異常
```bash
# 清除 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 工具實作
- 提供使用範例和文件
