vvvv-mcp

A Model Context Protocol (MCP) server for vvvv gamma — giving AI agents deep knowledge of vvvv's node API, the ability to read, explain and write .vl patches, generate C# nodes and SDSL shaders, and optionally connect to a live running vvvv instance for real-time feedback.

Works without a vvvv installation for all knowledge, search, read, and generate tools. Live tools require the companion VL.MCP.HDE editor extension (see below).

Install (end users)

Requires .NET 8 SDK or later.

# Install globally
dotnet tool install -g vvvv-mcp

# Configure your MCP client (Claude Desktop, VS Code, Cursor, Kilo) automatically
vvvv-mcp --setup

--setup detects which MCP clients are installed, writes their config files, and prints the config snippet for anything it can't auto-detect. Run it again after updating.

Update

dotnet tool update -g vvvv-mcp
vvvv-mcp --setup   # re-run if paths changed

What it does

• Search 6,400+ vvvv nodes by name, category, or keyword across all core packages
• Read and explain .vl patch files — parse the dataflow graph and describe it in natural language
• Write .vl patches — add nodes, connect pins, set values, create new patches
• Generate C# custom nodes ([ProcessNode]) and SDSL shaders from a description
• Access the full vvvv knowledge base — the entire Gray Book, all of tebjan's agent skills, and a curated package reference, served as MCP resources
• Live vvvv bridge (via VL.MCP.HDE) — read compilation errors, running documents, log output, and perform editor operations directly inside a running vvvv instance

Help to Improve

• Anytime the MCP does a bad job/misunderstands vvvv, you can either dump the chat log (if non-sensitive) or ask the LLM to summarize what went wrong and how it would improve the MCP, then file it as an issue.
• When you create video-based tutorials, create a good transcript which we can add to the MCP's knowledge base.

VL.MCP.HDE — In-editor AI assistant (experimental preview)

Status: experimental preview — breaking changes expected. While the infrastructure itself is ok, the mcp still needs to improve a lot before this becomes truly useable. Don't expect any wonders (yet).

VL.MCP.HDE is a companion vvvv gamma editor extension that adds two features:

Install

# Install via vvvv's NuGet package manager, or add to startup args:
nuget install VL.MCP.HDE

Bridge mode (always on)

Runs an HTTP server inside vvvv at localhost:7123 as soon as the extension is loaded. External MCP clients connect to it directly. The bridge exposes:

• All 12 live-editor tools (documents, errors, log, open/save/reload, undo/redo)
• MCP/SSE endpoint (/mcp/sse) for legacy clients
• MCP Streamable HTTP endpoint (/mcp) for Open WebUI and 2025+ clients

Configure your external MCP client (once):

{
  "mcpServers": {
    "vvvv-bridge": {
      "command": "dotnet",
      "args": ["run", "--project", "path/to/VvvvMcp"]
    }
  }
}

Or point directly at the running bridge: http://localhost:7123/mcp

Chat mode (Alt+C) — powered by Open WebUI

Launches Open WebUI as an embedded browser panel inside vvvv. Open WebUI handles the full LLM chat interface; the vvvv MCP tools are automatically registered.

Requirements:

• uv must be installed: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
• An LLM endpoint — Ollama (local) or any OpenAI-compatible API

First start: uv downloads and installs Open WebUI (~500 MB, one-time). Subsequent starts are fast (~10 s). Chat history, settings, and uploaded documents are stored in %LOCALAPPDATA%\vvvv-mcp\openwebui-data\.

Activating the vvvv tools in chat: The vvvv MCP server (http://localhost:7123/mcp) is automatically registered in Open WebUI on first launch. To use it in a conversation:

• Click the Tool button in the chat input bar → toggle on vvvv-mcp

To activate tools by default for a model (so you don't need to click Tool every time):

1. Open WebUI → Workspace → Models
2. Edit the model you want to use
3. Under Tools, enable vvvv-mcp
4. Save — tools will now be active in every new chat with that model

Attribution: Chat mode is powered by Open WebUI (BSD-3-Clause). Open WebUI is an independent project and is not affiliated with this repository.

Tools

Node Catalog

Knowledge Base

Patch Read Tools

Patch Write Tools

Code Generation Tools

Live Editor Tools (requires VL.MCP.HDE)

Resources

Knowledge (vvvv://knowledge/)

Developer / contributor setup

Prerequisites

• .NET 8 SDK

Build

dotnet build src/VvvvMcp.sln

Run locally (without installing as a global tool)

dotnet run --project src/VvvvMcp -- --setup   # configure MCP clients to use this build

Test with MCP Inspector

npx @modelcontextprotocol/inspector -- dotnet src/VvvvMcp/bin/Debug/net8.0/VvvvMcp.dll

Publish a new version of the MCP server

# 1. Bump version in src/VvvvMcp/VvvvMcp.csproj
# 2. Commit, tag, push — GitHub Actions publishes to NuGet.org automatically
#    (or push the version bump on main without a tag; the workflow now watches the csproj path too)
git add -A && git commit -m "release 0.x.0"
git tag v0.x.0
git push origin main --tags

Publish VL.MCP.HDE (vvvv editor extension)

# 1. Bump version in VL.MCP.HDE/VL.MCP.HDE.nuspec
# 2. Commit, tag, push — GitHub Actions workflow publishes to NuGet.org
#    (or push the version bump on main without a tag; the workflow now watches the nuspec path too)
git add -A && git commit -m "VL.MCP.HDE 0.x.0"
git tag vl-0.x.0
git push origin main --tags

Repository Structure

vvvv-mcp/
│
├── src/                          # MCP server (.NET 8 dotnet tool)
│   ├── VvvvMcp.sln
│   ├── VvvvMcp/                  # Server entry point
│   │   ├── Program.cs
│   │   ├── Tools/                # search_nodes, read_patch, add_node, create_shader, ...
│   │   ├── Resources/            # vvvv://knowledge/* and vvvv://catalog/*
│   │   └── Prompts/              # explain_vl_patch, create_vl_patch, ...
│   ├── VvvvMcp.Core/             # Shared library
│   │   ├── Models/               # NodeModels, PatchModels, CatalogModels
│   │   └── Services/
│   │       ├── NodeCatalogService      # Node search & indexing
│   │       ├── KnowledgeService        # Knowledge document loading & search
│   │       ├── PatchReaderService      # .vl XML parser
│   │       ├── PatchWriterService      # .vl XML writer (add/connect/remove nodes)
│   │       ├── PatchExplainerService   # Natural language patch descriptions
│   │       ├── ShaderGeneratorService  # SDSL shader code generation
│   │       └── PluginGeneratorService  # C# ProcessNode code generation
│   └── VvvvMcp.Tests/            # Smoke tests
│
├── VL.MCP.HDE/                   # vvvv gamma editor extension (NuGet: VL.MCP.HDE)
│   ├── VL.MCP.HDE.vl             # HDE extension entry point (auto-loads in editor)
│   ├── VL.MCP.HDE.nuspec         # NuGet package spec
│   └── src/
│       ├── MCPBridgeServer.cs    # [ProcessNode]: HTTP server + MCP/SSE + chat host
│       ├── McpSseServer.cs       # MCP Streamable HTTP + legacy SSE endpoints
│       ├── McpChatHost.cs        # Open WebUI process manager (uv-based)
│       ├── BridgeState.cs        # vvvv runtime introspection via reflection
│       ├── LogCapture.cs         # ILoggerProvider + ConsoleTee for full log capture
│       └── VL.MCP.Bridge.csproj
│
├── VVVVNodeAnalyzer/             # Node catalog generator (no vvvv installation needed)
│
├── knowledge/                    # MCP knowledge base (677 KB, 24 files)
│   ├── The-Gray-Book/            # Git submodule: vvvv/The-Gray-Book
│   ├── tebjan-vvvv-skills/       # Git submodule: tebjan/vvvv-skills
│   └── ...
│
├── scripts/
│   ├── build-knowledge.ps1
│   ├── install-community-packs.ps1
│   └── update-catalog.ps1
│
└── .github/workflows/
    ├── publish.yml               # Publishes vvvv-mcp dotnet tool to NuGet.org
    └── publish-VL-package.yml    # Publishes VL.MCP.HDE to NuGet.org

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  External IDE (VS Code + Kilo / Claude Desktop / Cursor)        │
│       │  stdio MCP                                              │
│       ▼                                                         │
│  ┌──────────────────────────────────────┐                       │
│  │  vvvv-mcp  (dotnet tool, MCP server) │                       │
│  │  search, read, write, generate, ...  │                       │
│  └──────────────────────────────────────┘                       │
│       │  HTTP localhost:7123/api/*  (live tools only)           │
│       ▼                                                         │
│  ┌──────────────────────────────────────┐                       │
│  │  VL.MCP.HDE (inside vvvv.exe)        │                       │
│  │  MCPBridgeServer [ProcessNode]       │                       │
│  │  · /api/*   → REST for vvvv-mcp      │                       │
│  │  · /mcp     → Streamable HTTP MCP    │◄── Open WebUI         │
│  │  · /mcp/sse → legacy SSE MCP         │                       │
│  └──────────────────────────────────────┘                       │
│       ▲  Alt+C (HDE menu) · bridge always on                     │
│                                                                 │
│  vvvv.exe ────────────────────────────────────────────────────  │
│  running patches, compilation, editor state                     │
└─────────────────────────────────────────────────────────────────┘

Chat mode:
  vvvv (Alt+C) → McpChatHost → uv → Open WebUI (localhost:7125)
                                          │
                                          └─► /mcp (Streamable HTTP)
                                              → vvvv live tools

Roadmap

• Phase 1 ✅ Read-only tools — node search, patch reading, natural language explanations
• Phase 1.5 ✅ Knowledge base — full Gray Book, tebjan's skills, 677 KB of documentation
• Phase 1.6 ✅ Analyzer improvements — correct VL category resolution, getter/setter synthesis
• Phase 2 ✅ Write capabilities — create/edit .vl patches, generate C# plugins and SDSL shaders
• Phase 3 ✅ Live vvvv bridge — VL.MCP.HDE editor extension, console capture, hot-reload feedback
• Phase 3.5 ✅ In-editor AI chat — Open WebUI embedded via CEF, MCP Streamable HTTP transport
• Phase 4 🔜 Community ecosystem — analyze all Libraries.xml packages, index help patches, per-node usage lookup
• Phase 5 🔜 Continuous improvement — forum/changelog scraper, knowledge updater

Node Catalog

Coverage

The current catalog covers 38 packages with ~6,400 user-facing nodes across 374 categories.

Extending the catalog

./scripts/install-community-packs.ps1
dotnet run --project VVVVNodeAnalyzer/VVVVNodeAnalyzer.csproj -- batch packs-community VVVVNodeAnalyzer

License

Dual license — see LICENSE.md:

• Free for non-commercial use (hobbyists, students, educators, research, open-source) under the PolyForm Noncommercial 1.0.0 terms.
• Commercial use (any use by or on behalf of a business, paid client work, internal business tooling, commercial products/services) requires a paid license — individual / studio (seat-based) / enterprise via polar.sh (link at release).

Note: vvvv gamma itself is a separate product of the vvvv group with its own licensing — this tool does not replace or include it.

Third-party attributions

See THIRD-PARTY-NOTICES.md for the full list. In short:

• Open WebUI (BSD-3-Clause + branding terms) — used in Chat mode via VL.MCP.HDE; launched as a separate process via uv, not modified or redistributed.
• tebjan/vvvv-skills — knowledge base content (CC BY-SA 4.0); derived knowledge files remain CC BY-SA with attribution.
• vvvv/The-Gray-Book — official vvvv documentation by the vvvv group; condensed here with attribution.