Shaderc Vkrunner Mcp

= `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 safel

... [View full README on GitHub]