Content
= `shaderc-vkrunner-mcp`
:toc:
A toy Model Context Protocol (MCP) server for AI agents to safely code, run, and visualize GPU shaders.
image::shaderc-vkrunner-mcp.jpg[align="center", width="90%"]
== Overview
`shaderc-vkrunner-mcp` provides a secure sandbox for AI agents to develop, compile, optimize, and run GPU shaders using Vulkan. It's designed to work entirely locally, making it compatible with self-hosted LLMs and AI tools that support the Model Context Protocol.
*Key Features:*
* Completely local execution - no additional API dependencies
* Support for shader compilation, optimization, and visualization
* Docker-based for easy deployment and isolation
* Tested with VS Code Copilot's Agent MCP
* Safe execution environment for AI-generated shader code - runs on CPU in a mostly isolated container without risking physical GPU crashes or lost devices
== Requirements
The only requirement to use `shaderc-vkrunner-mcp` is *Docker*, besides the MCP-capable AI Agent of your choice. The MCP server application is packaged as a Docker image with all necessary dependencies included.
== Quick Start
=== Installation
Although there are pre-built images in the GitHub Container Registry, it is easy to build the image from source:
[source,bash]
----
git clone https://github.com/mehmetoguzderin/shaderc-vkrunner-mcp
cd shaderc-vkrunner-mcp
docker build -t shaderc-vkrunner-mcp -f Dockerfile .
----
=== Connecting to MCP Clients
==== VS Code Copilot
Add this to your 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"
]
}
----
Then you can reference it in your Copilot Chat using `#compile_run_shaders` tag in Agent mode.
==== Using with MCP Inspector
For debugging and testing, you can use the MCP Inspector:
[source,bash]
----
npx @modelcontextprotocol/inspector docker run -i --rm shaderc-vkrunner-mcp
----
== Architecture and Design
`shaderc-vkrunner-mcp` is built with several key design principles:
1. *Safety through CPU emulation*: Uses Mesa's software Vulkan implementation to run shaders on CPU, eliminating risks of GPU crashes, paravirtualization issues, or lost devices that typically create barriers for GPU programming
2. *Cross-platform compatibility*: Uses Vulkan instead of CUDA/OpenCL for broader hardware support while running entirely in software
3. *Minimal but helpful*: Enables testing advanced features like atomics, subgroups, cooperative matrices, and raytracing without physical GPU hardware
4. *Type-safe implementation*: Leverages Rust's strong typing system
5. *Monolithic design*: Provides a unified interface for shader development, optimization, and visualization
== Advanced Features
`shaderc-vkrunner-mcp` supports a wide range of Vulkan features that can be explored by AI agents, all running safely on CPU, including:
* *Subgroup operations*: For efficient parallel processing
* *Atomic operations*: For thread-safe memory operations
== Development
=== Development Environment
After cloning, it is also possible to use Devcontainer for a productive development experience. This environment includes everything needed to iterate on codebase with utilities for Vulkan, screenshotting virtual framebuffer, etc. and development of this repo was bascally done there. Even for non-development purposes, it is recommended to try the development environment.
=== Git Dependencies
The project adds VkRunner as a git subtree. This was done using:
[source,bash]
----
git subtree add --prefix vkrunner https://gitlab.freedesktop.org/mesa/vkrunner main --squash
----
This approach ensures that VkRunner is always available with the correct version, without requiring external dependencies.
=== Running 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
----
== Contributing
Contributions are welcome! If you have improvements or bug fixes, please submit a pull request. If you encounter issues or have feature requests, please open an issue.
Some areas that could benefit from contributions:
* Improved documentation, examples, and testing
* Enhanced shader debugging capabilities
* Support for more Vulkan features
* Performance optimizations
* Better visualization tools
== License
This project is licensed under the Creative Commons CC0 1.0 Universal license. See the link:LICENSE[LICENSE] file for details.
Note that dependencies may have different licenses. Please check the respective repositories and directories for their licensing information.
== Acknowledgments
* link:https://modelcontextprotocol.io/[Model Context Protocol] for the MCP specification
* link:https://github.com/google/shaderc[Shaderc] for shader compilation
* link:https://gitlab.freedesktop.org/mesa/vkrunner[VkRunner] for shader execution (included as git subtree)
* link:https://www.mesa3d.org/[Mesa] for the software Vulkan implementation that enables GPU-less operation
