# MCP Internal

元心建材內部 MCP 整合系統 - 雙層架構

## 架構

```
┌─────────────────────────────────────────────────────────────────┐
│  員工電腦                                                        │
│  ┌───────────┐     ┌─────────────────────────────────────────┐  │
│  │ Claude    │────▶│ Thin Client (MCP Server)                │  │
│  │ Code      │     │  - 無 API Keys                          │  │
│  └───────────┘     │  - 只有 FSUID (員工 FX-CRM ID)           │  │
│                    │  - 只做請求轉發                          │  │
│                    └──────────────┬──────────────────────────┘  │
└───────────────────────────────────│─────────────────────────────┘
                                    │ HTTPS + Bearer Token
                                    ▼
┌─────────────────────────────────────────────────────────────────┐
│  Google Cloud (asia-east1)                                      │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Cloud Run (mcp-internal-backend)                         │   │
│  │  1. FSUID 驗證 → 查 FX-CRM PersonnelObj                 │   │
│  │  2. 取得用戶資訊 + mcp_permission__c                    │   │
│  │  3. 權限檢查                                             │   │
│  │  4. API 呼叫 (Odoo/Shopify/GitHub)                      │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

## 專案結構

```
mcp-internal/
├── packages/
│   ├── thin-client/        # 本地 MCP Server
│   ├── cloud-backend/      # Cloud Run 後端
│   └── shared/             # 共用型別
├── infrastructure/         # 部署腳本
└── pnpm-workspace.yaml
```

## 快速開始

### 1. 安裝依賴

```bash
pnpm install
```

### 2. 建置

```bash
pnpm build
```

### 3. 本地開發

```bash
# 設定環境變數
cp .env.example .env
# 編輯 .env 填入必要的值

# 啟動 Cloud Backend (開發模式)
cd packages/cloud-backend
pnpm dev

# 在另一個終端啟動 Thin Client
cd packages/thin-client
pnpm dev
```

## 部署

### Cloud Run Backend

```bash
# 設定 GCP Secrets (首次)
./infrastructure/setup-secrets.sh

# 部署
./infrastructure/deploy.sh
```

### Thin Client (員工設定)

```json
{
  "mcpServers": {
    "mcp-internal": {
      "command": "npx",
      "args": ["-y", "github:jameslai-sparkofy/mcp-internal#master"],
      "env": {
        "FSUID": "FSUID_xxxxx",
        "CLOUD_RUN_URL": "https://mcp-internal-backend-xxx.a.run.app"
      }
    }
  }
}
```

## 認證機制

1. 員工從 FX-CRM 取得自己的 FSUID（格式：`FSUID_xxxxx`）
2. 員工將 FSUID 設定在本地 MCP 環境變數
3. 每次請求帶上 FSUID → Cloud Run 驗證
4. Cloud Run 用 FSUID 查 FX-CRM PersonnelObj → 取得用戶資訊 + 權限

## 環境變數

### Thin Client (本地)

| 變數 | 說明 |
|------|------|
| `FSUID` | 員工 FX-CRM User ID（格式：`FSUID_xxxxx`）|
| `CLOUD_RUN_URL` | Cloud Run Backend URL |

### Cloud Run (GCP Secret Manager)

| 變數 | 說明 |
|------|------|
| `FXCRM_APP_ID` | FX-CRM App ID |
| `FXCRM_APP_SECRET` | FX-CRM App Secret |
| `FXCRM_PERMANENT_CODE` | FX-CRM Permanent Code |
| `FXCRM_CORP_ID` | FX-CRM Corp ID |
| `ODOO_URL` | Odoo URL |
| `ODOO_DB` | Odoo 資料庫名稱 |
| `ODOO_API_KEY` | Odoo API Key |
| `ODOO_USER_ID` | Odoo 用戶 ID |
| `SHOPIFY_STORE` | Shopify 商店名稱 |
| `SHOPIFY_ACCESS_TOKEN` | Shopify Access Token |
| `GITHUB_TOKEN` | GitHub Personal Access Token |
| `GITHUB_OWNER` | GitHub Owner |

## 可用工具

### Odoo
- `odoo_search` - 搜尋記錄
- `odoo_read` - 讀取記錄
- `odoo_count` - 計算記錄數
- `odoo_create` - 建立記錄 (admin/assistant)
- `odoo_update` - 更新記錄 (admin/assistant)
- `odoo_delete` - 刪除記錄 (admin/assistant)

### Shopify
- `shopify_search_products` - 搜尋產品
- `shopify_get_product` - 取得產品
- `shopify_update_product` - 更新產品 (admin/assistant)
- `shopify_update_price` - 更新價格 (admin/assistant)
- `shopify_get_locations` - 取得庫存位置

### 知識庫
- `knowledge_search` - 搜尋知識庫
- `knowledge_get_file` - 讀取檔案
- `knowledge_list_directory` - 列出目錄
- `knowledge_get_price` - 查詢價格
- `knowledge_search_spec` - 搜尋規格

## License

MIT