# MCP

**Model Context Protocol（MCP）** 是一個輕量、以 JSON 為基礎的封裝層，讓客戶端應用程式（例如 Cursor、VS Code 中的 Copilot、Claude for Desktop）不必處理底層 HTTP 細節，就能呼叫 YouCam AI 服務。

主要優勢：只要在 MCP 設定 JSON 檔案中新增一個項目，並提供您的 YouCam API 金鑰，任何支援 MCP 的客戶端（Cursor、VS Code 中的 Copilot、Claude for Desktop）都能立即存取完整的 YouCam AI 服務，包含肌膚檢測、服飾虛擬試穿、髮型造型、時尚渲染，以及更多功能。客戶端會抽象化請求格式、認證處理與非同步輪詢，讓開發者專注於工作流程整合，而非底層 API 機制。

## 整合指南

#### 1. 前置需求

* 已安裝支援 MCP 的客戶端（Claude Desktop、Codex、Cursor、VS Code 中的 Copilot 等）。
* 可網路連通至 YouCam MCP 伺服器，共分為 3 類：
  * `https://mcp-api-01.makeupar.com/mcp/beauty`
  * `https://mcp-api-01.makeupar.com/mcp/fashion`
  * `https://mcp-api-01.makeupar.com/mcp/creators`
* 有效的 **YouCam API key**（見下一節）。


> 客戶端本身已實作請求/回應序列化與輪詢邏輯；開發者無需額外撰寫程式碼。


#### 2. 取得 API Key

1. 前往 API key 控制台：[https://yce.perfectcorp.com/api-console/en/api-keys/](https://yce.perfectcorp.com/api-console/en/api-keys/)
2. 建立新的金鑰，或複製既有金鑰。
3. 安全儲存金鑰（環境變數、secret 管理器等）。


> **環境變數範例**（依您的部署方式調整）：`YOUR_API_KEY=your-api-key`


#### 3. 設定 MCP 設定 JSON 檔案

MCP 客戶端會讀取名為 `mcp.json` 的 JSON 設定檔。請依下方範例加入 YouCam MCP 伺服器的項目：

* YouCam for Beauty & Skin Care


```json
{
  "mcpServers": {
    "youcam-beauty": {
      "url": "https://mcp-api-01.makeupar.com/mcp/beauty",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

* YouCam for Fashion & Retail


```json
{
  "mcpServers": {
    "youcam-fashion": {
      "url": "https://mcp-api-01.makeupar.com/mcp/fashion",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

* YouCam for Creators


```json
{
  "mcpServers": {
    "youcam-creators": {
      "url": "https://mcp-api-01.makeupar.com/mcp/creators",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

**設定步驟**

| 步驟 | 動作 |
|  --- | --- |
| **1. 建立 MCP 設定 JSON 檔案** | 將檔案放在專案根目錄，或放在該客戶端專用的設定目錄（請參考各客戶端的文件）。 |
| **2. 取代佔位符** | 將 `YOUR_API_KEY` 替換為第 2 節取得的值，或在客戶端支援時引用環境變數（`${YOUR_API_KEY}`）。 |
| **3. 確認連線** | 開啟客戶端介面，確認「YouCam API MCP」出現為可選擇的服務。 |


> 設定為靜態；任何金鑰變更都需要重新載入客戶端。


## MCP 客戶端設定

**與熱門支援 MCP 的客戶端整合**

#### Claude Desktop

1. 下載並安裝 [Node.js 與 npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)。
2. Settings → Developer → Edit config → 開啟 claude_desktop_config.json 檔案
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/claude_mcp_config1_8142d700d0.png)
3. 更新 `mcpServers` 區塊
4. 將 `YOUR_API_KEY` 部分替換為您實際的 api key


```json
{
  "mcpServers": {
    "youcam-beauty": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-api-01.makeupar.com/mcp/beauty",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

1. 執行 **File → Exit** 以重新啟動 claude desktop 應用程式


#### Cursor

1. 開啟 Settings → Tools & MCP → Add Custom MCP
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/cursor_mcp_config2_9f31015370.png)
2. 將設定加入 mcp.json 檔案


```json
{
  "mcpServers": {
    "youcam-beauty": {
      "url": "https://mcp-api-01.makeupar.com/mcp/beauty",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

1. 前往 Cursor Settings → Tools & MCP
2. 在「Installed MCP Servers」區塊中，啟用或停用想要的工具


#### Copilot in VS Code（Visual Studio Code）

**Copilot in VS Code 選項 1：**

1. `> MCP: Add Server`
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/vscode_mcp_setting1_b1f041a72a.png)
2. 選擇 `HTTP`
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/vscode_mcp_setting2_e1d82b494c.png)
3. 輸入伺服器 url
4. 為 mcp 伺服器命名
5. 標頭設定：填入 api token


**Copilot in VS Code 選項 2：**

1. `> MCP: Open User Configuration`
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/vscode_config_img_34fe410c06.png)
2. 將 youcam-beauty 設定更新到 `mcp.json`


```json
{
    "servers": {
        "youcam-beauty": {
            "url": "https://mcp-api-01.makeupar.com/mcp/beauty",
            "type": "http",
            "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
            }
        }
    }
}
```

## MCP 功能

### YouCam for Beauty & Skin Care

YouCam for Beauty & Skin Care 包含下列工具，用於彩妝、護膚分析、臉部強化與外貌轉變：

* YouCam for Beauty & Skin Care


```json
{
  "mcpServers": {
    "youcam-beauty": {
      "url": "https://mcp-api-01.makeupar.com/mcp/beauty",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

#### 臉部與肌膚檢測／強化

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Skin_Analysis` | 評估皺紋、毛孔、痤瘡、油光、黑眼圈、質地與保濕等肌膚問題（HD 與 SD 模式）。 |
| `AI_Skin_simulation` | 視覺化最多 10 項肌膚問題（光澤、痤瘡、斑點等）治療前後的進展。 |
| `AI_Facial_Color_Tones_Analyzer` | 偵測臉部膚色、眼色、眉色、唇色與髮色。 |
| `AI_Aging_Simulation` | 從一張自拍，生成從年輕到老年的系列照片。 |
| `AI_Face_Attributes_and_Ratio_Analyzer` | 分析臉部結構、五官（眼睛、眉毛、嘴唇、鼻子、顴骨）與黃金比例。 |
| `AI_Face_Lift` | 以 AI 進行眼部、臉頰、額頭、臉型與嘴部的細緻修飾，效果自然。 |
| `AI_Face_Reshape` | 以像素級精準控制，重塑眼睛、鼻子、嘴唇、下顎線、下巴與整體臉部結構。 |
| `AI_Fitzpatrick_Skin_Type_Analysis` | 依據黑色素含量與紫外線反應，將膚色分類為 6 種 Fitzpatrick 類型。 |
| `AI_Smile` | 將中性或悲傷的表情轉換為自然的微笑（可含或不含牙齒）。 |
| `AI_Teeth_Whitening` | 自動偵測並提亮牙齒，美白強度可調整。 |


#### 髮型造型與分析

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Hair_Style_Virtual_Try_On` | 使用範本或參考圖片，試穿多種髮型（捲髮、長髮、平頭等）。 |
| `AI_Hair_Type_Detection` | 分析髮絲質地、粗細與捲曲模式，分為 9 種明確類型。 |
| `AI_Hair_Volume_Virtual_Try_On` | 在照片中立即為細軟或稀疏的頭髮增添自然髮量。 |
| `AI_Bangs_Filter_Virtual_Try_On` | 虛擬試穿不同瀏海樣式，找出最適合您臉型的款式。 |
| `AI_Hair_Color_Virtual_Try_On` | 使用預設或自調色盤變換髮色（全染或漸層模式）。 |
| `AI_Wavy_Hair_Virtual_Try_On` | 虛擬體驗波浪、捲曲或螺捲髮型。 |
| `AI_Hair_Density_Detection` | 依據頭皮可見度，將髮量密度評估並分類為 4 個等級。 |
| `AI_Hair_Extension_Virtual_Try_On` | 虛擬試戴長髮至超長接髮，自然融合。 |
| `AI_Hair_Frizziness_Detection` | 使用正面、左側與右側視角的照片，分析髮絲毛躁程度。 |
| `AI_Hair_Length_Detection` | 測量並將髮長分類為 5 個明確階段。 |


#### 身形調整與健身

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Abs_Filter` | 在全身／上半身照片中加入逼真的六塊肌或人魚線腹部線條。 |
| `AI_Body_Reshape` | 纖細、塑形並強化身體比例（腰、手臂、大腿、胸部、身高、等）。 |
| `AI_Breast_Augmentation_Simulator` | 非侵入式的 AI 視覺化，可強化胸部輪廓，強度可調整。 |


#### 彩妝與虛擬試妝

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Makeup_Virtual_Try_On` | 超寫實的虛擬彩妝，可精準控制粉底、腮紅、眼影、唇部等。 |
| `AI_Makeup_Transfer` | 將參考照片的完整彩妝造型，移轉到您的目標自拍上。 |
| `AI_Nail_Virtual_Try_On` | 虛擬試穿指甲油顏色、質地、設計，或穿戴式指甲。 |
| `AI_Eye_Color_Lens_Virtual_Try_On` | 寫實的隱形眼鏡／眼色虛擬模擬，具備不透明度與融合控制。 |
| `AI_Look_Virtual_Try_On` | 透過範本立即套用專業設計的美妝／臉部造型。 |
| `AI_Beard_Style_Generator` | 虛擬試穿不同男性鬍型（短鬍、全鬍、山羊鬍、八字鬍等）。 |


#### 工具、範本與任務管理

| 工具名稱 | 說明 |
|  --- | --- |
| `*_Templates` | 列出瀏海、鬍型、接髮、髮型、髮量與整體造型的預先定義範本。 |
| `*_Detection` | 執行某些塑形／拉提／美白 API 之前所需的偵測／前處理任務。 |
| `File_Upload` | 互動式拖曳上傳元件，可直接從瀏覽器上傳圖片/影片。 |
| `Get_Running_Task_Status` | 檢查狀態並取得先前啟動的 AI 處理任務結果。 |
| `Get_Upload_API_Info` | 回傳特定任務類型的上傳 API 端點，以及請求/回應範例。 |
| `Get_Feature_Cost` | 查詢每個 YouCam API 功能的點數消耗／費用價格。 |


### YouCam for Fashion & Retail

YouCam for Fashion & Retail 包含下列 API 工具，用於時尚、配件與造型應用：

* YouCam for Fashion & Retail


```json
{
  "mcpServers": {
    "youcam-fashion": {
      "url": "https://mcp-api-01.makeupar.com/mcp/fashion",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

#### 服飾與布料

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Clothes_Virtual_Try_On` | 虛擬試衣間，將服飾疊加到您的照片上。支援全身、上半身/下半身、鞋子、外套，或自動偵測。 |
| `AI_Fabric_Virtual_Try_On` | 使用預先定義的範本（例如絲綢、鮮明圖騰），將寫實的布料紋理與印花套用到圖片。 |
| `AI_Fabric_Virtual_Try_On_Templates` | 列出所有可用的預先定義布料紋理/風格範本，供 Fabric VTO 工具使用。 |


#### 鞋類

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Shoes_Virtual_Try_On` | 高擬真 AR 試鞋，視覺化腳上的合腳度、風格與顏色。需要明確的 `gender` 參數。 |


#### 帽類與圍巾

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Hat_Virtual_Try_On` | 針對帽子、棒球帽與髮帶的超寫實 AR 試戴，具備精準對位與風格控制。需要明確的 `gender` 參數。 |
| `AI_Scarf_Virtual_Try_On` | 模擬圍巾在服飾上自然的垂墜、折褶與圖紋流動。需要明確的 `gender` 參數。 |


#### 珠寶與配件

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Bracelet_Virtual_Try_On` | 以單張 2D 圖片進行 AI 手環試戴，位置、陰影與光線皆可調整。 |
| `AI_Earrings_Virtual_Try_On` | 寫實的耳環與虛擬穿孔模擬器，具備動態光線、遮蔽處理與耳側選擇。 |
| `AI_Necklace_Virtual_Try_On` | AR 項鍊試戴，具備精準的頸部/鎖骨追蹤，呈現奢華且符合物理的擺放。 |
| `AI_Ring_Virtual_Try_On` | 虛擬戒指/訂婚戒指試戴，具備手指選擇、指節定位與寫實陰影/光線。 |
| `AI_Watch_Virtual_Try_On` | AR 手錶視覺化，具備錶帶對位、錶殼邊緣偵測與手腕擺放控制。 |
| `AI_Bag_Virtual_Try_On` | 奢華手提包/包包 AR 試背，視覺化背法、背帶長度與服飾搭配。需要明確的 `gender` 參數。 |


#### 工具與任務管理

| 工具名稱 | 說明 |
|  --- | --- |
| `File_Upload` | 互動式拖曳上傳元件，可直接從瀏覽器上傳圖片/影片。 |
| `Get_Running_Task_Status` | 檢查狀態並取得先前啟動的 AI 處理任務結果。 |
| `Get_Upload_API_Info` | 回傳特定任務類型的上傳 API 端點，以及請求/回應範例。 |
| `Get_Feature_Cost` | 查詢每個 YouCam API 功能的點數消耗／費用價格。 |


### YouCam for Creators

YouCam for Creators 提供的 AI 驅動工具，依主要功能分組如下：

* YouCam for Creators


```json
{
  "mcpServers": {
    "youcam-creators": {
      "url": "https://mcp-api-01.makeupar.com/mcp/creators",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

#### AI 影像生成與強化

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Image_Generator_Text_to_Image` | 從文字提示生成高品質影像，具備風格/尺寸控制與智慧提示改寫。 |
| `AI_Image_Generator_Image_to_Image` | 使用文字指示加上最多 3 張參考圖片，轉換或編輯既有影像，以引導姿勢/風格。 |
| `AI_Photo_Colorize` | 將黑白或褪色的照片，立即上色為 4 種獨特鮮明的版本（暖色到冷色調）。 |
| `AI_Color_Correction` | 自動調整飽和度、色溫、色相、曝光與膚色；輸出 4 種專業調色的變化版本。 |
| `AI_Photo_Enhance` | 提升解析度（1x/2x/4x）、修復動態模糊、去除像素化，並強化臉部與細節清晰度。 |
| `AI_Photo_Lighting` | AI 驅動的提亮工具，修復陰影、平衡曝光，並自然地強化低光照片。 |
| `AI_Image_Extender` | 具備脈絡意識的 outpainting，可將圖片無縫擴展為任何自訂比例，同時保留風格與品質。 |


#### 背景處理

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Photo_Background_Removal` | 高精度 AI 主體分離，邊緣乾淨；支援人物、產品、動物、汽車等。 |
| `AI_Photo_Background_Blur` | 套用自然的散景/背景模糊，讓主體更突出；強度可調整（0–100）。 |
| `AI_Photo_Background_Change` & `_Templates` | 在主體分離後，使用自訂文字提示或預先定義的場景範本替換背景。 |
| `AI_Video_Background_Replace` | 使用參考圖片/影片，無縫替換影片背景；支援裁切/拉伸的貼合模式。 |


#### 人像、頭像與形象照創作

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Avatar_Generator` & `_Templates` | 圖片轉圖片的頭像創作，學習臉部特徵並套用藝術/風格化範本。 |
| `AI_Studio_Generator` & `_Templates` | 將隨意的自拍轉換為攝影棚級的專業人像，最佳化光線與構圖。 |
| `AI_Headshot_Generator` & `_Templates` | 使用 AI 風格範本，從一般照片生成精緻的 LinkedIn/商務/模特兒形象照。 |


#### 換臉與物件編輯

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Face_Swap` & `AI_Face_Swap_Face_Detection` | 超寫實的照片換臉，支援多張臉、自訂對應與略過邏輯。 |
| `AI_Video_Face_Swap` | AI 驅動的單臉影片換臉，具備自適應光線、表情追蹤與膚色融合。 |
| `AI_Object_Removal_Pro` | 使用灰階遮罩精準移除不想要的物件/人物；保留細緻的背景細節。 |
| `AI_Video_Object_Removal` | 使用單一張參考遮罩影格，在影片中一致地移除干擾元素。 |
| `AI_Replace` | AI inpainting，移除遮罩區域並依自訂提示生成新的物件/紋理。 |


#### 影片生成與強化

| 工具名稱 | 說明 |
|  --- | --- |
| `AI_Video_Generator_Text_to_Video` | 從文字提示建立動態影片，具備解析度、長寬比、長度與反向提示控制。 |
| `AI_Video_Generator_Image_to_Video` | 使用動態提示與範本最佳化，將靜態圖片動畫成寫實的短影片。 |
| `AI_Video_Enhancer` | 自動修復模糊、銳化邊緣、校正曝光/亮度、降低雜訊，並將低解析度影像提升至 HD。 |
| `AI_Video_Style_Transfer` & `_Templates` | 逐影格套用電影感/AI 濾鏡（波普藝術、復古、動漫等），輸出風格一致的影片。 |


#### 工具與任務管理

| 工具名稱 | 說明 |
|  --- | --- |
| `File_Upload` | 互動式拖曳上傳元件，可直接從瀏覽器上傳圖片/影片。 |
| `Get_Running_Task_Status` | 檢查狀態並取得先前啟動的 AI 處理任務結果。 |
| `Get_Upload_API_Info` | 回傳特定任務類型的上傳 API 端點，以及請求/回應範例。 |
| `Get_Feature_Cost` | 查詢每個 YouCam API 功能的點數消耗／費用價格。 |