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 中查询生产数据​

公开部署要求​