MCP 开发计划

AoifeLab Web 将渲染知识体系、特性库与 Shader 资产通过 Model Context Protocol 暴露给 Agent 平台，使 AI 能读取结构化数据并指导各引擎内的效果实现。
本文档为 MCP 子系统的完整开发计划，与 渲染验证与引擎落地技术选型 配套。

1. 总体目标

1.1 要解决的问题

当前网站已沉淀渲染知识框架、特性库与 HLSL 参考实现，但这些资产仅供人类浏览。Agent 无法：

• 按语义检索「透射」特性的输入、通道、参数契约
• 理解该特性在材质研发管线中的上下游位置
• 将语言无关的 Spec 翻译为 UE / Unity 等引擎的具体实现步骤

MCP 子系统的目标是打通 网站资产 → Agent 可读协议 → 引擎落地 的自动化链路。

1.2 成功标准

1.3 总体架构

┌─────────────────────────────────────────────────────────────┐
│  网站数据层（唯一真相源）                                      │
│  framework-data · knowledge-data · mcp-feature-specs        │
│  repo-feature-shaders · repo-feature-categories             │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│  MCP Server（/api/mcp · Streamable HTTP）                     │
│  Resources · Tools · Prompts                                │
└──────────────────────────┬──────────────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   MCP Registry      Cursor / Claude    自建 Agent 平台
          │                │                │
          └────────────────┼────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  引擎翻译层（Engine Adapter）                                 │
│  UE（首验）→ Unity → Godot …                                 │
└──────────────────────────┬──────────────────────────────────┘
                           ▼
                    引擎内验证（RenderDoc MCP）

2. 核心设计原则

3. 数据层设计

3.1 特性规格层（Canonical Spec）

文件： lib/mcp-feature-specs.ts
页面： /tools/mcp/feature-spec
状态： ✅ 初版已完成（Transmission 完整 Spec，其余 draft）

每个特性存一份与语言无关的定义，是 MCP 往各引擎翻译时的契约：

{
  "id": "Transmission",
  "inputs": ["BaseColor", "Normal", "ViewDir", "UV"],
  "channels": {
    "iChannel0": { "role": "environment", "type": "cube|2d" },
    "iChannel1": { "role": "thickness", "channel": "R" },
    "iChannel2": { "role": "absorption", "channel": "RGB" }
  },
  "parameters": {
    "IOR": { "default": 1.45, "range": [1.0, 2.5] },
    "TransmissionWeight": { "default": 1.0, "range": [0, 1] }
  },
  "algorithm": "refract_sample + beer_lambert + schlick_fresnel",
  "validated": true
}

字段说明：

规划扩展： 将单一 validated 拆为 algorithmValidated（WebGL 函数验证）与 lookdevValidated（WebGPU 画面验证），与技术选型文档 §4.3 对齐。

3.2 Shader 资产分层

同一 Spec 维护多语言载体：

Canonical Spec（契约）
    ├── glsl   → WebGL 网站预览（渲染特性库，待建）
    ├── wgsl   → WebGPU 网站预览（实验台，待建）
    └── hlsl   → UE MCP 导出（repo-feature-shaders.ts，进行中）

文件映射：

3.3 框架上下文层

文件： lib/framework-data.ts
用途： MCP Tool get_framework_context 返回特性在数据流中的 role、inputs、outputs 上下游节点。

示例：Transmission 属于 rendering-feature 节点，上游为 shading-model-step，下游为 feature-dependency。

3.4 知识体系层

文件： lib/knowledge-data.ts
用途： MCP Resource 暴露五大知识体系的节点详情，供 Agent 理解渲染与性能背景。

4. 站点入口（已完成）

相关实施记录：

• 2026-07-16-工具MCP子页面计划.md
• 2026-07-16-MCP特性规则设计子页面计划.md

5. MCP Server 设计

5.1 技术选型

5.2 目录规划

Git/
├── app/api/mcp/route.ts          # HTTP 入口（GET / POST / DELETE / OPTIONS）
├── lib/mcp/
│   ├── server.ts                 # McpServer 实例与能力注册
│   ├── tools.ts                  # Tool 定义与 handler
│   ├── resources.ts              # Resource 定义与 handler
│   └── prompts.ts                # Prompt 模板
└── lib/mcp-feature-specs.ts      # 已有：Spec 数据层

5.3 Resources（只读知识）

Agent 通过 URI 读取静态内容，适合上下文自动注入。

5.4 Tools（可调用动作）

Agent 主动调用，返回结构化结果。

5.5 Prompts（预置工作流）

5.6 API 路由实现要点

// 概念示意
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js"

export async function POST(req: Request) {
  const transport = new WebStandardStreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  })
  const server = createAoifeMcpServer()
  await server.connect(transport)
  return transport.handleRequest(req)
}

注意事项：

• 导出 GET、POST、DELETE、OPTIONS
• 配置 CORS 以支持浏览器类 Client
• 错误时返回标准 JSON-RPC 错误格式
• 生产环境可加 API Key 或 OAuth（P3）

6. Registry 发布与可发现性

6.1 发布流程

1. 部署 /api/mcp 至生产域名
2. 编写 server.json：

{
  "name": "com.aofielab/rendering-knowledge",
  "version": "1.0.0",
  "description": "渲染与性能一体化知识体系：特性 Spec、HLSL 参考、管线上下文与 UE 落地指导",
  "websiteUrl": "https://你的域名",
  "remotes": [{
    "type": "streamable-http",
    "url": "https://你的域名/api/mcp"
  }]
}

1. 用 mcp-publisher CLI 发布
2. 证明命名空间：com.aofielab（DNS TXT）或 io.github.账号（GitHub OAuth）

6.2 客户端配置示例

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "aofielab": {
      "url": "https://你的域名/api/mcp"
    }
  }
}

6.3 可发现性策略

• 在 /tools/mcp 接入方式区块补充 Registry 链接与配置片段
• server.json 描述含关键词：rendering, shader, HLSL, UE5, material feature
• Registry 是元数据目录；终端用户仍在各客户端手动或经由聚合器添加 MCP

7. 引擎翻译层

7.1 首验引擎：Unreal Engine

7.2 translate_to_engine 输出结构（规划）

{
  "engine": "UE5",
  "feature": "Transmission",
  "steps": [
    "创建 Custom HLSL 函数节点，粘贴 get_feature_hlsl 返回的代码",
    "在母材质中暴露 IOR、TransmissionWeight 参数，范围见 Spec",
    "绑定 iChannel0 为 Scene Texture / Cube，iChannel1 为厚度贴图 R"
  ],
  "parameters": { "...": "来自 Spec" },
  "validation": ["掠射角 Fresnel 增强", "厚区 Beer-Lambert 吸收", "薄区保留 BaseColor"]
}

7.3 首条落地链路

网站 Canonical Spec + HLSL（Transmission）
    → MCP get_feature_spec / get_feature_hlsl
    → Agent 生成 UE Custom HLSL 部署步骤
    → 写入 UE 工程 Content/Shaders/Features/
    → LookDev 场景目视确认
    → RenderDoc MCP 抓帧对比（验证闭环）

7.4 扩展引擎（P5）

8. 与网站验证闭环的关系

MCP 不替代网站内 GPU 验证，而是读取验证结果：

WebGL 特性库验证（algorithmValidated）
    ↓
Canonical Spec.validated = true
    ↓
MCP 优先推荐 + translate_to_engine
    ↓
UE 落地
    ↓
RenderDoc MCP 引擎内复核

9. 实施路线图

阶段总览

M0 — 站点入口 ✅ 已完成

• 工具导航子菜单 MCP
• /tools/mcp 介绍页
• /tools/mcp/feature-spec 特性规则设计
• lib/mcp-feature-specs.ts 数据层

M1 — MCP Server 骨架（当前重点）

完成标准： Cursor 中调用 get_feature_spec("Transmission") 返回完整 JSON。

M2 — 知识暴露扩展

完成标准： Agent 能一次性获取 Transmission 的 Spec + HLSL + 管线位置。

M3 — 引擎指导

完成标准： Agent 凭 MCP 输出可生成 UE Custom HLSL 落地文档。

M4 — Registry 发布

完成标准： Registry API 可搜索到 com.aofielab/rendering-knowledge。

M5 — UE Authoring（可选，高权限）

M6 — 跨引擎扩展

• Unity Shader Graph 适配
• Godot 适配
• 各引擎 translate_to_engine 分支

10. 代码与页面对照表

11. 风险与约束

12. 与其他子系统协作

13. 相关文档

• 2026-07-16-渲染验证与引擎落地技术选型.md
• 2026-07-16-工具MCP子页面计划.md
• 2026-07-16-MCP特性规则设计子页面计划.md
• 2026-07-16-渲染特性Shader资产计划.md

修订记录