跳到主要内容

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 的工具调用。