# ai-to-agent-jev-mcp

**ai-to-agent-jev-mcp — TypeSafe Jev 標準 MCP server**  
版本：**1.0.0**｜發布日期：**2026-09-22**｜語言：繁體中文

把 **TypeSafe Jev**（System One 決策模型）包裝成標準 MCP server，讓 Claude Code Agent 可以直接呼叫它做「判斷題」。

**AI Coach 益力康陳董 × CGM Coach 血糖教練｜2026 AI to Agent**

---

## 為什麼需要這個

Jev 不生成文字、不寫程式、不聊天。它只做一件事：**給它一個狀態 + 一組型別化問題，回傳結構化答案**。

這正好補上 Agent 架構裡最缺的一塊——**決策層**。

| | 沒有 Jev | 有 Jev |
|---|---|---|
| 分流判斷 | Agent 呼叫 LLM 問「請回答 A/B/C」，慢、貴、偶爾漂移 | 一次呼叫回傳選項 + 機率 + 信心值，可重現 |
| 評分判斷 | 寫死 if/else 規則，或每次問 LLM | 依評分階梯回傳加權分數，直接在程式裡設門檻 |
| 真偽判斷 | 脆弱的「請回傳 JSON」prompt | 型別化回傳，不會格式錯亂 |

**定位**：Jev 是 Agent 手上的一個新工具，跟 Whisper、ffmpeg 平行——專門處理「判斷題」而非「生成題」。它**不是**用來取代 Claude Code 背後的模型。

---

## 安裝

### 1. 取得 API 金鑰

到 [console.typesafe.ai](https://console.typesafe.ai) 申請，也可以先在 Playground 試玩不寫程式。

### 2. 安裝依賴

```bash
pip install "mcp>=1.2" httpx
```

### 3. 掛進 Claude Code

```bash
claude mcp add ai-to-agent-jev-mcp \
  --env TYPESAFE_API_KEY=sk-your-key-here \
  -- python3 /絕對路徑/ai-to-agent-jev-mcp/jev_mcp_server.py
```

或手動寫進設定檔（`~/.claude.json` 或專案的 `.mcp.json`）：

```json
{
  "mcpServers": {
    "ai-to-agent-jev-mcp": {
      "command": "python3",
      "args": ["/絕對路徑/ai-to-agent-jev-mcp/jev_mcp_server.py"],
      "env": {
        "TYPESAFE_API_KEY": "sk-your-key-here"
      }
    }
  }
}
```

重開 Claude Code，用 `/mcp` 確認 `ai-to-agent-jev-mcp` 已連上。

### 環境變數

| 變數 | 必填 | 預設 |
|---|---|---|
| `TYPESAFE_API_KEY` | ✅ | — |
| `TYPESAFE_BASE_URL` | | `https://api.typesafe.ai` |
| `TYPESAFE_DEFAULT_MODEL` | | `jev-latest` |
| `TYPESAFE_TIMEOUT` | | `30`（秒） |

---

## Claude Code 中使用

### 在 Agent 程式裡呼叫 Jev

MCP 連上後，Claude Code 會自動看到四個工具。你可以在程式碼中直接呼叫：

```python
# 真偽判斷：單一 yes/no 問題
result = await jev_noul(
    state="空腹血糖 186 mg/dL",
    question="這個數值是否需要立即通知照護者？",
    criteria={
        "true": "明顯超出安全範圍，需立即處理",
        "false": "在可控範圍內，例行追蹤"
    }
)
# result = {"noul": 0.92, "confidence": 0.88}

# 分流選擇：固定選項中擇一
route = await jev_choice(
    state="患者 BMI 28，無共病，願意配合運動",
    question="該推薦哪種減重方案？",
    criteria={
        "輕運動+飲食調整": "BMI 在健康邊緣、無共病",
        "醫療介入": "BMI > 30 或有共病風險",
        "暫不介入": "患者未表達需求或條件不足"
    }
)
# route = {"choice": "輕運動+飲食調整", "confidence": 0.91, "probabilities": {...}}

# 評分判斷：沿評分階梯打分
score = await jev_score(
    state="短影音開場三秒未曾出現主人公，背景音樂偏低調",
    question="這支短影音的開場鉤子強度？",
    criteria=["平淡", "普通", "有吸引力", "非常抓人"]
)
# score = {"score": 1.5, "level": "普通", "confidence": 0.75}

# 批次決策（官方建議）：一次問多題
answers = await jev_ask(
    state="患者血糖資料：空腹 186、餐後 240、連續三天；症狀：疲倦、夜間頻尿",
    questions={
        "需通知照護者": {
            "type": "noul",
            "instructions": "這組數據是否需要立即通知？",
            "criteria": {"true": "明顯超出且持續", "false": "可控範圍"}
        },
        "處理路徑": {
            "type": "choice",
            "instructions": "應走哪條處理路徑？",
            "criteria": {"自動推播": "...", "人工跟進": "...", "就醫轉介": "..."}
        },
        "風險程度": {
            "type": "score",
            "instructions": "整體風險有多高？",
            "criteria": ["控制良好", "需留意", "控制不佳", "立即介入"]
        }
    }
)
# answers = {
#   "需通知照護者": {"noul": 0.92, "confidence": 0.88},
#   "處理路徑": {"choice": "就醫轉介", "confidence": 0.85, ...},
#   "風險程度": {"score": 3.2, "level": "立即介入", "confidence": 0.90}
# }
```

### 在 Claude Code 對話中用文字呼叫

你也可以在 Claude Code 的對話框直接說：

> 用 jev_ask 一次問完三題：(1) 這筆訂單是否需人工確認？(2) 優先度如何？(3) 備註屬於哪一類？

Claude 會看到 MCP 工具並自動組織參數、呼叫 Jev、解析結果。

### 信心值怎麼用

```python
ans = await jev_choice(...)

if ans["confidence"] < 0.6:
    # 信心不足，不要直接自動執行
    hand_off_to_human_or_llm()
else:
    # 信心足夠，直接依選擇分流
    execute(ans["choice"])
```

---

## 四個工具

| 工具 | 回傳 | 什麼時候用 |
|---|---|---|
| `jev_noul` | 0~1 機率 | 是非題：條件成不成立、要不要觸發動作 |
| `jev_choice` | 選中項 + 各項機率 + 信心 | 分流：路由到固定的幾個處理路徑 |
| `jev_score` | 加權分數 + 信心 | 程度題：緊急度、風險、品質、優先度 |
| `jev_ask` | 多題答案 | **決策點多時優先用這個** |

### 為什麼優先用 `jev_ask`

同樣的題目分開問跟一次問，**答案一樣**，但批次呼叫約**便宜 12 倍、快 10 倍**——因為 state 只送一次。Agent 流程裡只要有兩個以上的決策點，就該合併成一次 `jev_ask`。

---

## 三大事業的實際用例

### 1. 血糖管理 Agent

一次問完三題，程式再依數值分流：

```json
{
  "state": "空腹 186 mg/dL，餐後兩小時 240 mg/dL，連續三天。患者回報最近容易疲倦、夜間頻尿。",
  "questions": {
    "需通知照護者": {
      "type": "noul",
      "instructions": "這組數據是否需要立即通知照護者或衛教師？",
      "criteria": {
        "true": "數值明顯超出安全範圍且持續，或伴隨警示症狀",
        "false": "在可控範圍內，例行追蹤即可"
      }
    },
    "處理路徑": {
      "type": "choice",
      "instructions": "這個個案該走哪條處理路徑？",
      "criteria": {
        "自動衛教推播": "推送既有衛教內容即可",
        "衛教師跟進": "需要人工聯繫了解狀況",
        "建議就醫": "超出衛教範圍，應轉介醫療"
      }
    },
    "風險程度": {
      "type": "score",
      "instructions": "整體血糖控制風險有多高？",
      "criteria": ["控制良好", "需留意", "控制不佳", "需立即介入"]
    }
  }
}
```

**程式怎麼接**：
```python
if ans["需通知照護者"]["noul"] > 0.8:
    notify_caregiver()

if ans["處理路徑"]["confidence"] < 0.6:
    escalate_to_human()          # 信心不足，不要自動決定
else:
    route(ans["處理路徑"]["choice"])

if ans["風險程度"]["score"] >= 2.5:
    flag_for_review()
```

> ⚠️ 衛教定位提醒：Jev 的輸出是**分流用的訊號**，不是診斷。凡是「建議就醫」這條路徑，一律導向專業醫療，不要讓 Agent 直接給醫療建議。

---

### 2. 短影音生成 Agent

腳本草稿進來，先判斷風格與品質，再決定要不要進生成流程：

```json
{
  "state": "<腳本草稿全文>",
  "questions": {
    "風格模板": {
      "type": "choice",
      "instructions": "這支短影音該套用哪個風格模板？",
      "criteria": {
        "CGM衛教版": "專業醫療衛教口吻，重數據與實證",
        "AI導師版": "創業經營乾貨，重方法論與案例",
        "跨界融合版": "串接健康與商管，重觀點與洞察"
      }
    },
    "開場鉤子強度": {
      "type": "score",
      "instructions": "前三秒的鉤子抓不抓得住人？",
      "criteria": ["平淡", "普通", "有吸引力", "非常抓人"]
    },
    "有無醫療宣稱風險": {
      "type": "noul",
      "instructions": "腳本中是否出現可能觸法的療效宣稱？",
      "criteria": {
        "true": "有明示或暗示治療、療效、預防疾病的說法",
        "false": "僅描述知識、經驗或一般性健康概念"
      }
    }
  }
}
```

**程式怎麼接**：鉤子分數 < 2 就退回重寫、療效宣稱 > 0.5 直接擋下不生成、風格模板決定套哪組素材與字卡。

---

### 3. 寵物餐廳自動化 Agent

訂單進來，判斷要不要人工介入：

```json
{
  "state": {
    "訂位人數": 12,
    "時段": "週六 18:00",
    "備註": "兩隻狗對雞肉過敏，另有一隻大型犬需要無障礙走道",
    "是否包廂": true
  },
  "questions": {
    "需人工確認": {
      "type": "noul",
      "instructions": "這筆訂單是否需要人工致電確認？",
      "criteria": {
        "true": "有特殊餐飲需求、動線需求，或超出標準流程",
        "false": "標準訂位，系統自動確認即可"
      }
    },
    "處理優先度": {
      "type": "score",
      "instructions": "這筆訂單的處理優先度？",
      "criteria": ["照常排入", "當日留意", "需立即處理"]
    },
    "備註類型": {
      "type": "choice",
      "instructions": "備註主要屬於哪一類需求？",
      "criteria": {
        "飲食限制": "過敏、忌口、特殊餐食",
        "空間需求": "無障礙、大型犬、包廂配置",
        "混合需求": "同時涉及飲食與空間",
        "無特殊需求": "一般備註"
      }
    }
  }
}
```

**程式怎麼接**：`需人工確認 > 0.7` 就推到店長的待辦；`備註類型 = 飲食限制` 自動帶出過敏原檢查表；`處理優先度 >= 1.5` 當天早班先處理。

---

## 設計要點

**信心值是第二道關卡**。答案告訴你「是什麼」，信心告訴你「能不能直接照做」。低信心的決策交給 LLM 或人工，這是 Jev 最值錢的用法——比單純的 true/false 多一層安全網。

```python
if answer["confidence"] < THRESHOLD:
    hand_off_to_llm_or_human()
else:
    act_on(answer["choice"])
```

**把複雜判斷拆成原子問題**。與其問「這個個案該怎麼處理」，不如拆成三題各自判斷，權重留在你自己的程式裡——這樣門檻可以調、邏輯可以測、出錯可以追。

**state 用結構化資料**。訂單、紀錄、數據這類東西直接傳 JSON，比塞成一段文字準確。

---

## 錯誤處理

server 已內建：

- `429` / `529` / `5xx` → 指數退避自動重試最多 4 次（會聽 `Retry-After`）
- `401` → 回傳「API 金鑰無效」的中文說明
- `422` → 回傳「請求格式不合法」並附上 API 指出的問題欄位
- 所有錯誤都以 `{"error": "..."}` 回傳，不會噴 stack trace 給 Agent

參數驗證也在送出前就擋掉：選項少於 2 個 / 超過 255 個、評分階梯少於 2 階 / 超過 10 階、choice 與 score 缺 criteria、未知題型。

---

## 測試

```bash
python3 test_offline.py
```

用假的 API server 驗證請求格式與回傳解析，不需要金鑰、不連外網。目前 29 項全過。

---

## 版權與引用

AI Coach 益力康陳董 × CGM Coach 血糖教練｜2026 AI to Agent

Copyright © 2026 AI Coach 益力康陳董。All rights reserved.

本版未授予 MIT、Apache 或 Creative Commons 等開放授權。公開展示不等於授予任意商用、改作或再散布權；使用條件見 [LICENSE](LICENSE)。這是保留權利的專案，不宣稱為開源軟體。

建議引用：AI Coach 益力康陳董（2026）。《ai-to-agent-jev-mcp：TypeSafe Jev 標準 MCP server》（1.0.0 版）。