MCP 服务器

MCP Internal

A secure two-layer MCP integration system that connects local thin clients to a Google Cloud backend for authenticated access to internal corporate tools. It enables users to manage Odoo ERP records, Shopify products, and internal knowledge bases through natural language commands.

README

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

認證機制

員工從 FX-CRM 取得自己的 FSUID（格式：FSUID_xxxxx）
員工將 FSUID 設定在本地 MCP 環境變數
每次請求帶上 FSUID → Cloud Run 驗證
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