Metal Shader MCP - Claude 的着色器开发游乐场

[![文档 & 守护](https://github.com/erichowens/metal-shader-m-金属着色器开发的完整系统，其中 Claude 可以实时编写、修改和视觉迭代着色器。

项目概述

新功能：导出帧时可选的 Core ML 后处理。参见下文的配置部分。

注意：旧的文件桥接（向 Resources/communication 写入命令）正在被严格的 MCP 客户端取代。参见下文的弃用通知。 Metal Shader MCP 是一个 macOS SwiftUI + Metal 的游乐场，具有规范的工作流程，用于着色器迭代、视觉证据和持续集成。计划有一个 MCP 层，让 AI 助手与应用程序交互（编译、预览、快照），但目前的主要入口点是你可以本地编译和运行的 macOS 应用程序。

当前状态（截至 2025-10-02）

• macOS 应用程序（SwiftUI + Metal）在本地和持续集成中构建并运行。
• 使用简单的渲染器进行实时着色器编辑，并带有截图/导出助手。
• 会话浏览器（历史记录标签）捕获每个会话的快照（代码 + 图像 + 元数据）。
• 持续集成强制执行：构建、测试、视觉证据捕获、WARP 工作流合规性、UI 烟雾测试（标签选择/状态）、文档检查。
• 分支保护及合并策略：所有持续集成检查必须通过才能合并到主分支。直接推送到主分支将被拒绝。更改必须通过带有绿色检查的 PR 进行。覆盖需要明确的用户决策，并且不鼓励这样做。
• 单次飞行 PR 策略：一次只有一个活动的核心 PR（非草稿）；其他 PR 保持草稿状态，直到活动的 PR 合并。

发展路线图

• 将 MCP 服务器集成到驱动 macOS 应用程序（编译/预览/快照）的工具中。
• 多分辨率基线的视觉回归测试。
• 带有名称、描述和持久元数据的着色器库（参见 WARP/元数据规则）。
• 导出管道（PNG/视频）带有参数扫描和性能分析。
• Xcode 项目或 Swift 包目标，以便在持续集成中自动发现文件。

快速开始（macOS 应用程序）

• 需求：安装了最新稳定版 Xcode 的 macOS 和支持 Metal 的设备。
• 在本地构建和运行：

swiftc -o MetalShaderStudio \
  ShaderPlayground.swift AppShellView.swift HistoryTabView.swift SessionRecorder.swift \
  Sources/MetalShaderCore/MCPClient.swift \
  -framework SwiftUI -framework MetalKit -framework AppKit -framework UniformTypeIdentifiers \
  -parse-as-library

./MetalShaderStudio --tab history

特性

• 实时编译：实时编译 Metal 着色器并报告错误
• 热重载：文件更改时自动重新编译
• 性能分析：测量 FPS、GPU/CPU 时间和内存使用情况
• 预览引擎：实时着色器预览，带有 WebSocket 更新
• 着色器模板：内置的着色器示例和效果
• MCP 集成：与 AI 助手无缝集成

安装

• macOS 应用程序（当前）：参见上面的快速开始。
• MCP 服务器（计划）：现有的 npm 脚本是未来 MCP 服务器的占位符。它们不是今天运行 macOS 应用程序所必需的。

# 计划（MCP 服务器），今天不需要 macOS 应用程序
npm install
npm run build

无头渲染器（用于数据集和持续集成）

无需启动应用即可将着色器渲染为 PNG：

swift run ShaderRenderCLI --shader-file shaders/plasma_fractal.metal --out data/sample.png --width 256 --height 256 --time 0.0

Core ML 后处理（可选）

• 在 Resources/communication/coreml_config.json 中配置（提供模板）。
• 在 Resources/models/YourModel.mlmodelc 或 .mlmodel 提供模型。
• 当存在且有效时，导出将通过模型后再保存。

配置字段：

• modelPath：模型路径（例如，Resources/models/StyleTransfer.mlmodelc）
• inputName：图像输入特征名称（例如，image）
• outputName：输出图像特征名称（例如，stylizedImage）
• width，height：模型输入尺寸

注意：UI 保持不变；这仅影响导出的帧和会话快照。

使用方法

启动 MCP 服务器

npm start

开发模式

npm run dev

可用的 MCP 工具

1. compile_shader：编译 Metal 着色器代码

   • 支持 AIR、metallib 和 SPIRV 目标
   • 优化选项
   • 错误和警告报告

2. preview_shader：生成预览图像

   • 实时渲染
   • 自定义分辨率
   • 触摸交互支持

3. update_uniforms：更新着色器参数

   • 时间、触摸位置、分辨率
   • 自定义统一值

4. profile_performance：性能指标

   • FPS 测量
   • GPU/CPU 时间跟踪
   • 内存使用监控

5. hot_reload：文件监视

   • 自动重新编译
   • WebSocket 通知
   • 开发仪表板

6. validate_shader：语法验证

   • 错误检测
   • 性能建议
   • 代码分析

着色器开发

示例：万花筒效果

#include <metal_stdlib>
using namespace metal;

fragment float4 kaleidoscopeFragment(
    VertexOut in [[stage_in]],
    texture2d<float> texture [[texture(0)]],
    constant Uniforms& uniforms [[buffer(0)]]
) {
    // 万花筒变换
    float2 uv = kaleidoscope(in.texCoord, 6, uniforms.time);
    
    // 生成 RGBY 颜色块
    float4 color = generateColorBlock(uv, uniforms.blockSize);
    
    return color;
}

性能需求

• 目标：现代设备上 60fps
• 内存：高效内存使用
• 编译：<500ms

着色器元数据约定

着色器应包括一个 docstring，在顶部声明名称和描述。此内容由 ShaderMetadata.from(code:path:) 解析，并将驱动库搜索、缩略图和元数据视图。

示例：

/**
 * 万花筒方块
 * 带动画控制的几何颜色块。
 */
#include <metal_stdlib>
using namespace metal;
fragment float4 fragmentShader() { return float4(0,0,0,1); }

• 第一行非空 docstring → name
• 下面的非空行（直到空白行）→ description
• 当可用时，源路径会被记录以供溯源

库标签和缩略图

• 库条目从着色器 docstring 衍生其标题/描述。
• 缩略图可以从会话快照中获取，也可以通过无头渲染器生成以保持一致性。
• 随着库 UX 的扩展，预计可以通过标签进行搜索/过滤，并快速比较叠加。

文件桥通信契约（过渡期）

在严格 MCP 客户端被集成之前，应用程序使用位于 Resources/communication/ 的简单文件桥：

• commands.json（输入，本地工作流中可选）：排队的操作（例如，set_shader, export_frame）
• status.json（输出）：最后操作的状态和诊断信息
• current_shader_meta.json：活动着色器的解析名称/描述/路径
• library_index.json：索引库元数据
• uniforms.json：当前统一值
• compilation_errors.json：最后编译诊断

键和确切形状将在 MCP 传输替换桥梁时稳定化，但这些文件是当前本地工具集成的事实来源。

架构

metal-shader-mcp/
├── src/
│   ├── index.ts         # MCP 服务器
│   ├── compiler.ts      # Metal 编译
│   ├── preview.ts       # 预览引擎
│   ├── hotReload.ts     # 文件监视
│   ├── profiler.ts      # 性能分析
│   └── parameters.ts    # 统一管理
├── shaders/
│   └── kaleidoscope.metal  # 示例着色器
└── dist/                # 编译输出

热重载仪表板

访问开发仪表板：

http://localhost:3000/dashboard

特性：

• 实时编译状态
• 错误和警告显示
• 性能指标
• 文件监视状态

着色器示例

包含的万花筒着色器演示：

• 实时几何变换
• Perlin 噪声生成
• 颜色块效果
• 交互式动画
• 性能优化技术

性能优化

分析器测量：

• 平均帧时间
• 每秒帧数
• GPU 处理时间
• CPU 开销
• 内存使用
• 功耗估计

开发

重要提示：无论启动目录如何，路径都保持一致

此项目先前使用当前工作目录解析资源路径，导致从不同文件夹启动 MCP 时行为不匹配（例如，动画工作但库/历史记录不工作，反之亦然）。现在路径相对于项目根目录解析，如下检测：

1. 如果设置了 METAL_SHADER_MCP_ROOT，则使用该目录（期望有一个 Resources 子文件夹）
2. 否则，我们从 MCP 源位置向上遍历，直到找到一个 Resources 目录
3. 回退：process.cwd()（只有在上述方法失败时）

如果需要覆盖，请在启动前设置环境变量：

• macOS/zsh export METAL_SHADER_MCP_ROOT="/Users/erichowens/coding/metal-shader-mcp"

这确保 MCP 和应用程序无论在哪里运行 CLI，都能读写相同的 Resources/communication 和 Resources/screenshots 文件夹。

服务密钥/秘密

此存储库不需要外部服务密钥来运行核心 ShaderPlayground + MCP 流程。如果你添加需要秘密的集成，请按以下顺序存储它们：

• 本地开发：.env.local（已 gitignore）
• 同一台机器上的共享开发：.env（已 gitignore）
• 持续集成：在 CI 提供商的加密秘密存储中配置秘密
• 生产：使用你的部署平台的秘密管理器（例如，GitHub Actions Secrets，1Password，AWS/GCP 秘密管理器）

永远不要将秘密提交到仓库。在代码中使用环境变量（如 process.env.MY_KEY），并在本文档中记录任何所需变量。

事后行动要求

每次重要的开发动作都必须完成以下步骤：

1. 更新 BUGS.md - 记录发现的问题
2. 更新 CHANGELOG.md - 记录已完成的内容
3. 捕获视觉证据 - 对于 UI/着色器更改的截图
4. 运行测试 - 确保没有引入回归
5. Git 操作 - 使用描述性消息提交

详见 WARP.md 中的详细工作流程文档。

视觉测试

此项目包含一个带有着色器固定装置和黄金图像的视觉回归框架。

# 捕获当前状态的截图（可选手动证据）
./scripts/screenshot_app.sh "feature_description"

# 运行视觉测试
swift test --filter VisualRegressionTests

# 如果有意更改视觉效果，重新生成黄金图像
make regen-goldens

• 失败时，工件保存在 Resources/screenshots/tests/（例如，actual_*.png，diff_*.png 和一个总结 JSON）。
• 黄金图像位于 Tests/MetalShaderTests/Fixtures/ 并通过 SPM 资源捆绑。

文档文件

• WARP.md - 代理工作流程要求
• CLAUDE.md - 创意愿景和 AI 交互模式
• VISUAL_TESTING.md - 视觉测试框架
• BUGS.md - 当前问题和解决方案
• CHANGELOG.md - 项目演变历史

弃用通知（文件桥）

• 文件桥（commands.json 汇报）是过渡性的，一旦严格的 MCP 客户端（MCPLiveClient）通过 MCPBridge 集成到 Swift 应用程序中，它将被移除。
• 目标：用适当的 MCP 传输（stdio/websocket）替换桥梁，移除汇报，增加健壮的错误处理。
• 时间表：一旦 PR #29 合并，我们将继续推进 PR #32 来完成此迁移。

贡献

欢迎贡献！请遵循 WARP.md 中的工作流程要求：

1. 从主分支创建功能分支
2. 实现更改并附带视觉证据
3. 更新相关文档
4. 运行视觉回归测试
5. 提交带有截图的拉取请求

许可证

MIT