Shaderc Vkrunner Mcp
一个玩具MCP，让AI代理通过Mesa、VkRunner、shaderc和Docker实现软件模拟的Vulkan
= shaderc-vkrunner-mcp
:toc:
一个面向AI代理的玩具级模型上下文协议(MCP)服务器，用于安全地编写、运行和可视化GPU着色器。
image::shaderc-vkrunner-mcp.jpg[align="center", width="90%"]
== 概述
shaderc-vkrunner-mcp为AI代理提供了一个安全沙箱，使其能够使用Vulkan开发、编译、优化和运行GPU着色器。该设计完全在本地运行，兼容支持模型上下文协议的自托管LLM和AI工具。
核心特性:
- 完全本地执行 - 无需额外API依赖
- 支持着色器编译、优化和可视化
- 基于Docker实现简易部署和隔离
- 已通过VS Code Copilot的Agent MCP测试
- AI生成着色器代码的安全执行环境 - 在基本隔离的容器中以CPU运行，避免物理GPU崩溃或设备丢失风险
== 系统要求
除自选的MCP兼容AI代理外，使用shaderc-vkrunner-mcp仅需Docker环境。该应用已打包为包含所有必要依赖的Docker镜像。
== 快速入门
=== 安装
虽然GitHub容器注册表提供预构建镜像，但从源码构建也很简便：
[source,bash]
git clone https://github.com/mehmetoguzderin/shaderc-vkrunner-mcp
cd shaderc-vkrunner-mcp
docker build -t shaderc-vkrunner-mcp -f Dockerfile .
=== 连接MCP客户端
==== VS Code Copilot
在VS Code的mcp.json中添加：
[source,json]
"shaderc-vkrunner-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v", "${workspaceFolder}:/work",
"shaderc-vkrunner-mcp",
"--work-dir",
"/work"
]
}
随后可在Copilot Chat的Agent模式下通过#compile_run_shaders标签调用。
==== 配合MCP检查器使用
调试和测试时可使用MCP检查器：
[source,bash]
npx @modelcontextprotocol/inspector docker run -i --rm shaderc-vkrunner-mcp
== 架构设计
shaderc-vkrunner-mcp遵循以下核心设计原则：
- CPU模拟保障安全：使用Mesa的软件Vulkan实现，在CPU上运行着色器，规避GPU崩溃、准虚拟化问题和设备丢失等常见GPU编程障碍
- 跨平台兼容性：采用Vulkan而非CUDA/OpenCL实现更广泛的硬件支持，同时保持全软件运行
- 精简而实用：支持测试原子操作、子组、协作矩阵和光线追踪等高级功能，无需物理GPU硬件
- 类型安全实现：基于Rust强类型系统构建
- 一体化设计：提供着色器开发、优化和可视化的统一接口
== 高级功能
shaderc-vkrunner-mcp支持AI代理探索各类Vulkan特性，均以CPU安全运行，包括：
- 子组操作：实现高效并行处理
- 原子操作：保障线程安全的内存操作
== 开发指南
=== 开发环境
克隆仓库后，可使用Devcontainer获得高效开发体验。该环境包含Vulkan工具链、虚拟帧缓冲截图等全套开发工具，本项目主要在此环境中开发。即使非开发用途也推荐尝试此环境。
=== Git依赖管理
项目通过git subtree集成VkRunner，具体命令：
[source,bash]
git subtree add --prefix vkrunner https://gitlab.freedesktop.org/mesa/vkrunner main --squash
此方案确保始终使用正确版本的VkRunner，无需外部依赖。
=== 运行Clippy
[source,bash]
cargo clippy --
-W clippy::pedantic
-W clippy::nursery
-A clippy::missing-errors-doc
-A clippy::wildcard-imports
-A clippy::unused-self
-A clippy::unnecessary-wraps
-A clippy::needless-pass-by-value
== 贡献指南
欢迎贡献！如有改进或错误修复，请提交PR。遇到问题或功能请求，请创建issue。
亟需贡献的领域包括：
- 完善文档、示例和测试
- 增强着色器调试能力
- 支持更多Vulkan特性
- 性能优化
- 改进可视化工具
== 许可证
本项目采用知识共享CC0 1.0通用许可协议，详见link:LICENSE[LICENSE]文件。
注意依赖项可能采用不同许可证，请查阅各仓库目录获取许可信息。
== 致谢