# 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
