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. 安裝依賴

pnpm install

2. 建置

pnpm build

3. 本地開發

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

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

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

部署

Cloud Run Backend

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

# 部署
./infrastructure/deploy.sh

Thin Client (員工設定)

{
  "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