FactVerse MCP — 任何 AI Agent 適用的物理 AI 工具

透過 Model Context Protocol (MCP) 讓任何 AI Agent 呼叫 FactVerse 的物理世界工具

什麼是 MCP？

Model Context Protocol 是一個開放標準，讓 AI 應用（如 Claude Desktop、Cursor、自建 Agent）能夠安全地呼叫外部工具和資料來源。

FactVerse 依 基盤 / 模組（base / module） 將平台工具拆成並列的治理切片，每個切片是獨立的端點，由 per-customer API key 解析出租戶 + scope 後鑑權：

切片	用途	範例工具
base（基盤）	通用讀 + 通用計算 + 跨域執行	設備狀態、知識查詢、模擬、優化、預測、建立工單
trafficops（模組）	人流/車流運營	車流預測、檢查點車道、巡檢排班、激增偵測
pdm（模組）	預測性維護	設備健康、預測性維護總覽/異常、濾芯智慧
telcoops（模組）	通訊網路運營	網路健康、事件解釋、容量預測
semiops（模組）	半導體 / 潔淨室 / Fab / SMT	潔淨室狀態、顆粒/壓差、HEPA 濾芯壽命、ISO 14644 合規、Fab PUE、SMT OEE

其他客戶專屬切片可在交付範圍內單獨啟用。

快速接入

下面以 base 切片（通用讀 + 通用計算）為例。換模組只需把 URL 裡的 base 換成 trafficops / pdm / telcoops / semiops，並用持有對應 scope 的 key。

Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "factverse-base": {
      "url": "https://your-factverse-server/mcp/base/",
      "headers": {
        "X-API-Key": "fvk_your_scoped_key"
      }
    }
  }
}

Cursor IDE

在 .cursor/mcp.json 中：

{
  "mcpServers": {
    "factverse-base": {
      "url": "https://your-factverse-server/mcp/base/",
      "headers": {
        "X-API-Key": "fvk_your_scoped_key"
      }
    }
  }
}

Python 用戶端

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client(
        "https://your-factverse-server/mcp/base/",
        headers={"X-API-Key": "fvk_your_scoped_key"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # 列出目前 key 可見的工具
            tools = await session.list_tools()
            for tool in tools.tools:
                print(f"{tool.name}: {tool.description[:60]}...")

            # 呼叫工具：查詢設備狀態（base.read）
            result = await session.call_tool(
                "get_equipment_status",
                {"equipment_id": "EQ-001"}
            )
            print(result)

            # 執行模擬（base.compute.run）
            result = await session.call_tool(
                "run_simulation",
                {
                    "scene_type": "trafficops",
                    "scene_id": "rts-main-hall",
                    "simulation_time": 480
                }
            )
            print(result)

工具分類（依切片）

base — 通用讀 · scope `base.read`

工具名	說明
`get_equipment_status`	獲取設備即時狀態和感測器讀數
`query_knowledge`	查詢知識圖譜（設備/故障/關聯）
`search_documents`	文件搜尋
`get_equipment_documents`	設備關聯文件
`list_connectors`	資料連接器列表
`check_data_quality`	資料品質檢查
`get_pending_tasks`	獲取待處理審批任務（唯讀）

base — 通用計算（模擬/優化/預測/分析/空間） · scope `base.compute.run`

工具名	說明
`run_simulation`	執行 DES 模擬（交通/供熱/設備）
`run_doe`	執行實驗設計（識別關鍵因子）
`run_dag_simulation`	DAG 檢查站模擬 + Sankey 分析
`run_what_if_comparison`	A/B 方案 What-If 對比
`run_optimization`	NSGA-II 多目標優化
`optimize_layout`	設施空間布局優化
`get_optimization_recommendation`	預算約束下最優人員配置

base — 執行（寫） · scope `base.action.write`（預設不授予）

工具名	說明
`create_work_order`	從 AI 建議建立工單

pdm — 預測性維護 · scope `pdm.read`

工具名	說明
`get_equipment_health`	設備健康評分
`get_pdm_summary`	預測性維護總覽
`list_pdm_anomalies`	預測性維護異常列表

semiops — 半導體 / 潔淨室 / Fab / SMT · scope `semiops.read`

工具名	說明
`get_cleanroom_status`	潔淨室環境狀態
`get_particle_trend`	顆粒物趨勢
`get_pressure_gradient`	壓差梯度
`get_fab_pue`	工廠 PUE 值
`get_filter_life`	HEPA 濾芯壽命
`get_iso_compliance`	ISO 14644 合規狀態
`get_smt_oee`	SMT 產線 OEE
`get_utility_status`	公用工程(CDA/N2/水電)狀態
`analyze_env_correlation`	環境參數相關性分析
`monitor_particles`	顆粒物即時監控
`predict_env_trend`	環境趨勢預測
`simulate_smt_bottleneck`	SMT 產線瓶頸模擬
`forecast_fab_load`	Fab 負荷預測
`optimize_chiller_cop`	冷機 COP 優化

trafficops / telcoops 工具集見各自切片的 tools/list。

認證與授權（依 key 解析租戶 + scope）

每個 /mcp/<切片> 都是受治理的端點：請求用 per-customer API key 鑑權，由 key 在伺服器端解析出租戶和權限 scope——用戶端不傳 tenant，也不能用共享密鑰。

Header：X-API-Key: fvk_…（不是 Authorization: Bearer）
key 由管理員按租戶簽發（存雜湊，原文只顯示一次），不能自助生成。
沒有 key → 閘道回 403；無效/吊銷的 key → 401。

Scope（決定這個 key 能呼叫哪些工具）

scope	切片	覆蓋的工具
`base.read`	base	通用讀（設備狀態、知識查詢、文件、連接器、資料品質、待辦）
`base.compute.run`	base	通用計算（模擬、優化、預測、分析、空間——與租戶資料無關的計算）
`base.action.write`	base	執行類（建立工單等寫狀態工具，預設不授予）
`trafficops.read`	trafficops	TrafficOps 模組工具（車流預測、檢查點車道、巡檢排班等）
`pdm.read`	pdm	預測性維護模組工具（設備健康、預測性維護總覽/異常、濾芯智慧等）
`telcoops.read`	telcoops	TelcoOps 模組工具（網路健康、事件解釋、容量預測）
`semiops.read`	semiops	半導體/潔淨室工具（潔淨室、顆粒/壓差、HEPA 濾芯、ISO 14644、Fab PUE、公用工程、SMT OEE/缺陷分類）

模組互相隔離：一個 trafficops key 不能呼叫 pdm/telcoops/semiops 的工具，也不能呼叫 base 工具。需要跨切片就給同一個 key 授多個 scope。

key 缺少某工具所需的 scope 時，該 tools/call 會直接被拒（fail-closed），回傳 missing required scope '…'。同一個 key 可持有多個 scope。

使用場景

1. Claude 直接操控設施

使用者：「7號冷機最近運行怎麼樣？如果降頻到 42Hz 會怎樣？」

Claude 呼叫：
  → get_equipment_status(equipment_id="CHILLER-007")     # base.read
  → run_simulation(scene_type="fms", config_overrides={"frequency": 42})  # base.compute.run
  → 綜合分析並回答

2. 自建 Agent 自動化運維

# 每小時檢查設備健康（pdm.read），低分自動開工單（base.action.write）
health = await pdm_session.call_tool("get_equipment_health", {"equipment_name": "critical pump"})

for equipment in health.data["equipment"]:
    if equipment["health_score"] < 60:
        await base_session.call_tool("create_work_order", {
            "equipment_id": equipment["id"],
            "priority": "HIGH",
            "title": "檢查低健康評分設備",
            "description": f"AI 檢測到健康評分低於 60: {equipment['health_score']}"
        })

3. 在 Cursor 中查詢生產資料

在 Cursor IDE 接 semiops 切片後直接問：「潔淨室 CR-001 的顆粒物趨勢怎麼樣？」→ Cursor 透過 MCP 呼叫 get_particle_trend。

公開部署要求

FactVerse MCP 透過受控的 HTTPS 端點暴露，例如 /mcp/base/、/mcp/trafficops/、/mcp/pdm/、/mcp/telcoops/ 和 /mcp/semiops/。實際啟用哪些端點取決於客戶環境開通的模組。

生產客戶端應使用 HTTPS，在每次請求中送出 X-API-Key，並透過 MCP 在執行時發現可用工具。帶末尾斜線的 /mcp/<切片>/ 是標準端點形式。

客戶端不應傳遞租戶識別。平台會根據簽發的 key 解析租戶和 scope，並拒絕 key 不具備對應 scope 的工具呼叫。

什麼是 MCP？​

快速接入​

Claude Desktop​

Cursor IDE​

Python 用戶端​

工具分類（依切片）​

base — 通用讀 · scope base.read​

base — 通用計算（模擬/優化/預測/分析/空間） · scope base.compute.run​

base — 執行（寫） · scope base.action.write（預設不授予）​

pdm — 預測性維護 · scope pdm.read​

semiops — 半導體 / 潔淨室 / Fab / SMT · scope semiops.read​

認證與授權（依 key 解析租戶 + scope）​

Scope（決定這個 key 能呼叫哪些工具）​

使用場景​

1. Claude 直接操控設施​

2. 自建 Agent 自動化運維​

3. 在 Cursor 中查詢生產資料​

公開部署要求​