跳至主要内容

FactVerse MCP — AI Agent 適用的受控工業工具

透過 Model Context Protocol (MCP)，讓 AI 客戶端連接受控的 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潔淨室、公用工程、設施環境和 SMT 運營上下文

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

快速接入​

下面以 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)

工具參考流程​

本指南不維護完整的手寫工具目錄。FactVerse MCP 工具會隨產品模組和客戶環境持續演進，穩定的使用流程是：

步驟使用
選擇客戶工作流程MCP 能力指南
規劃 endpoint 和 scopeMCP Scope 矩陣
列出該 key 可見工具客戶端執行時 MCP 工具發現
查看目前工具名和參數MCP 工具參考
診斷存取、來源資料、計算或寫入失敗MCP 錯誤與稽核

準確的工具名稱、說明、scope 和參數以生成參考為準。客戶環境中的最終可用性，以執行時工具發現為準。

能力選擇​

需求從這裡開始經複核後增加
讀取資產、文件或來源資料上下文/mcp/base/ + base.read用於領域訊號的模組 endpoint。
執行模擬、預測、最佳化或空間分析/mcp/base/ + base.compute.run對假設和輸出進行工程複核。
起草工單或巡檢任務/mcp/base/ + base.action.write人工審批和稽核記錄。
複核預測性維護輸出/mcp/pdm/ + pdm.read用於資產記錄和已複核動作草稿的 /mcp/base/。
複核模組化營運域已啟用的模組 endpoint用於共享文件和資產上下文的 /mcp/base/。

認證與授權（依 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.readbase面向資產、知識、文件、連接器、資料品質和待辦的通用讀
base.compute.runbase面向模擬、優化、預測、分析和空間工作流的通用計算
base.action.writebase已複核動作草稿和受控記錄建立，預設不授予
trafficops.readtrafficops面向流量、檢查點、車道、排班和激增複核的 TrafficOps 模組上下文
pdm.readpdm面向設備健康、異常和維護規劃的預測性維護模組上下文
telcoops.readtelcoops面向網路健康、事件和容量規劃的 TelcoOps 模組上下文
semiops.readsemiops半導體、潔淨室、公用工程、設施環境和 SMT 運營上下文

模組互相隔離：一個 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 的工具呼叫。