# ADR-001: MCP Protocol 採用

> **狀態**: Accepted
> **日期**: 2026-03-19
> **決策者**: CTO + CEO

## 背景

AWOOOI 的 leWOOOgo Engine 需要與大量外部工具整合 (K8s, SSH, AWS/GCP, Database, Notification 等)。傳統做法是針對每個服務寫專屬 Adapter，耗時且難以維護。

Anthropic 的 **Model Context Protocol (MCP)** 提供標準化的 AI-Tool 溝通協議，已有數百個社群 MCP Server 可直接使用。

## 決策

**採用 MCP 作為 leWOOOgo BRAIN ↔ ACTION 的標準通訊協議**

```
┌─────────────────────────────────────────────────────────────┐
│                    leWOOOgo Engine                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   🧱 INPUT ──→ 🧠 BRAIN ──→ 📢 OUTPUT                      │
│                   │                                         │
│                   ↓ (MCP Protocol)                          │
│              🔧 ACTION ←→ [MCP Servers]                    │
│                   │                                         │
│                   ↓                                         │
│              📊 DATA                                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### MCP Server 分類

| 類別 | 範例 MCP Server | 用途 |
|------|----------------|------|
| **Infrastructure** | kubernetes, docker, ssh | 基礎設施操作 |
| **Cloud** | aws, gcp, azure | 雲端資源管理 |
| **Database** | postgres, redis, mongodb | 資料存取 |
| **Notification** | slack, telegram, email | 訊息發送 |
| **Monitoring** | prometheus, grafana | 監控查詢 |
| **Security** | vault, trivy | 安全掃描 |

### leWOOOgo 整合方式

```typescript
// packages/lewooogo-brain/src/mcp-bridge.ts

interface MCPBridge {
  // 動態載入 MCP Server
  loadServer(serverName: string): Promise<MCPServer>

  // 執行 MCP Tool
  callTool(server: string, tool: string, params: object): Promise<MCPResult>

  // 列出可用工具
  listTools(server: string): Promise<MCPToolDefinition[]>
}
```

## 理由

### 1. 生態系統成熟

| 指標 | 數值 |
|------|------|
| 社群 MCP Server | 300+ |
| 官方維護 Server | 20+ |
| 協議版本 | Stable (2024-11) |

### 2. 與 Claude 深度整合

AWOOOI 使用 Claude 作為主要 LLM，MCP 是 Anthropic 原生協議，整合最順暢。

### 3. 節省開發時間

| 方案 | 預估工時 |
|------|---------|
| 自建 50 個 Adapter | 500+ 小時 |
| 採用 MCP + 自訂 5 個 | 50 小時 |

### 4. 標準化介面

所有工具使用相同的 JSON-RPC 介面，簡化 BRAIN 邏輯。

## 後果

### 優點

- **即時獲得** 數百種工具能力
- **社群維護** 減輕維護負擔
- **標準協議** 簡化架構設計
- **Claude 原生** 最佳 LLM 整合體驗

### 缺點

- **依賴外部** 需信任社群 MCP Server 品質
- **協議鎖定** 若 MCP 標準改變需跟進

### 風險

| 風險 | 緩解措施 |
|------|---------|
| MCP Server 品質不一 | 建立內部審核清單，只允許白名單 Server |
| 安全漏洞 | 所有 MCP 調用經過 Privacy Shield 脫敏 |
| 效能瓶頸 | 關鍵路徑自建 Adapter，非關鍵走 MCP |

### 例外情況

以下場景**不使用**社群 MCP Server，改自建 leWOOOgo Adapter：

1. **核心業務邏輯** - 如 OpenClaw Triage Engine
2. **高頻調用** - 如 Redis Cache (效能考量)
3. **機敏操作** - 如 K8s Delete (需額外授權)

## 實施計畫

| Phase | 任務 | 時程 |
|-------|------|------|
| 0 | 定義 MCPBridge 介面 | Week 1 |
| 1 | 整合 5 個核心 MCP Server | Week 2-3 |
| 2 | 建立 MCP Server 白名單機制 | Week 3 |
| 3 | Privacy Shield 整合 | Week 4 |

## 參考

- [MCP Official Spec](https://spec.modelcontextprotocol.io/)
- [MCP Server Registry](https://github.com/modelcontextprotocol/servers)
- [Anthropic MCP Announcement](https://www.anthropic.com/news/model-context-protocol)
- 會議記錄: `docs/meetings/2026-03-19_FRONTEND_RESTRUCTURE_STRATEGY.md`