604e38cf07
- CLAUDE.md: 紅區治理章節 - Skills 01/03: 版本更新 - ADR/Architecture: 標準化 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
131 lines
4.5 KiB
Markdown
131 lines
4.5 KiB
Markdown
# 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`
|