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:

Feature	Shortcut	What it does
Bridge	`Alt+B` toggle	HTTP server on `localhost:7123` — exposes the live vvvv session to any external MCP client (VS Code + Kilo, Claude Desktop, etc.)
Chat	`Alt+C` toggle	Launches Open WebUI as a chat panel directly inside the vvvv editor, pre-connected to the bridge's MCP tools

Install

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

Bridge mode (`Alt+B`)

Starts an HTTP server inside vvvv at localhost:7123. 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):

Open WebUI → Workspace → Models
Edit the model you want to use
Under Tools, enable vvvv-mcp
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

Tool	Description
`search_nodes_live`	(bridge) Search the LIVE node registry of the running vvvv — exact pins, real types, only nodes actually placeable in the session.
`get_node_details_live`	(bridge) Exact pin names, real types, defaults, visibility for one node from the live registry.
`refresh_live_nodes`	(bridge) Rebuild the live node snapshot (e.g. after installing a pack).
`search_nodes`	Offline catalog search (two-phase: precise AND, then OR fallback).
`get_node_details`	Offline catalog details for a node by name (tolerant: variants, full names).
`list_categories`	All category namespaces, optionally filtered by prefix.
`list_packages`	All packages in the catalog.

Knowledge Base

Tool	Description
`list_knowledge`	List all knowledge documents with descriptions.
`read_knowledge`	Read the full content of a knowledge document by name.
`search_knowledge`	Full-text search across all knowledge documents with snippet results.
`search_practical`	Search help patches, forum solutions, and code snippets from the community knowledge index.
`get_index_stats`	Row counts for the SQLite search index (knowledge, nodes, practical).

Patch Read Tools

Tool	Description
`read_patch`	Parse a `.vl` file and return the structured graph (nodes, pins, links, IOBoxes, dependencies).
`explain_patch`	Natural-language explanation of a parsed patch.
`list_patch_dependencies`	List NuGet dependencies declared in a `.vl` file.

Patch Write Tools

Tool	Description
`build_patch`	The primary tool. Builds a whole connected subgraph in ONE call: resolves nodes (live registry first), adds NuGet deps, declares pins with correct visibility, auto-layouts by dataflow, wires all links (incl. pin-group auto-indexing and links into existing pins), saves, reloads in vvvv, reports compile errors.
`create_patch`	Create a new empty `.vl` patch. `mode: "file"` (from scratch) or `"editor"` (also opens in vvvv).
`add_node`	Add a single node — pins auto-declared from the live registry/catalog, dependency auto-added, optional verify.
`add_pad`	Add a value pad (IOBox) to a patch with an optional initial value.
`connect_pins`	Connect an output pin (or pad) to an input pin.
`remove_node`	Remove a node and all its connected links from a patch.
`remove_link`	Remove a specific connection from a patch.
`set_value`	Set the default value of a pad or pin.

Code Generation Tools

Tool	Description
`create_csharp_plugin`	Generate a C# `[ProcessNode]` or static operation from a description, with typed input/output pins.
`create_shader`	Generate a Stride SDSL shader — TextureFX (filter/mixer/source), ComputeFX, DrawFX, or ShaderFX.
`list_templates`	List all available vvvv project templates (VL, C#, SDSL).
`get_template`	Get the full content of a template file.

Live Editor Tools (requires `VL.MCP.HDE`)

Tool	Description
`check_bridge_connection`	Check if the vvvv bridge is reachable and return runtime state.
`get_running_documents`	List all `.vl` documents currently open in the vvvv editor.
`get_vvvv_errors`	Get current compilation errors and warnings.
`get_vvvv_state`	Runtime state: running/paused, frame count, uptime.
`get_vvvv_log`	Recent log entries from the vvvv console (captures ILogger + System.Console output).
`get_open_tabs`	Get open canvas tabs in the patch editor.
`open_document_in_vvvv`	Open a `.vl` file in the editor.
`close_document_in_vvvv`	Close a document (optionally saving first).
`save_document_in_vvvv`	Save a document or all documents.
`reload_file_in_vvvv`	Force vvvv to hot-reload a file from disk.
`undo_in_vvvv`	Undo the last action on the active canvas.
`redo_in_vvvv`	Redo the last undone action.

Resources

Knowledge (`vvvv://knowledge/`)

URI	Content
`vvvv://knowledge/quickref`	XML cheat sheet: NodeReference patterns, critical .vl rules, VL.CoreLib categories, Stride scene, topic index
`vvvv://knowledge/file-format`	Complete `.vl` XML format reference
`vvvv://knowledge/fundamentals`	Live compilation model, frame-based execution, node categories
`vvvv://knowledge/patching`	Dataflow patterns, regions, channels, event handling, anti-patterns
`vvvv://knowledge/custom-nodes`	`[ProcessNode]` lifecycle, `Update()`, change detection, assembly import
`vvvv://knowledge/shaders`	SDSL TextureFX/DrawFX/ComputeFX, streams system, mixins, GPU patterns
`vvvv://knowledge/dotnet`	.csproj setup, NuGet packages, vector type interop, async, threading
`vvvv://knowledge/channels`	IChannelHub, `[CanBePublished]`, reactive subscriptions, bang channels
`vvvv://knowledge/spreads`	`Spread<T>`, `SpreadBuilder`, mapping, filtering, performance rules
`vvvv://knowledge/node-libraries`	Creating node libraries: ImportAsIs/Namespace/Type, service registration
`vvvv://knowledge/troubleshooting`	Common errors: pin order, missing ImportAsIs, shader mistakes, runtime issues
`vvvv://knowledge/packages`	230 curated packages from Libraries.xml, organized by category
`vvvv://knowledge/gray-book/*`	Official Gray Book — language, extending, libraries, HDE, best-practice, getting-started

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+B / Alt+C (HDE menu)                               │
│                                                                 │
│  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.

Navigation Menu

Repository files navigation

vvvv-mcp

Install (end users)

Update

What it does

Help to Improve

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

Install

Bridge mode (`Alt+B`)

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

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

Build

Run locally (without installing as a global tool)

Test with MCP Inspector

Publish a new version of the MCP server

Publish VL.MCP.HDE (vvvv editor extension)

Repository Structure

Architecture

Roadmap

Node Catalog

Coverage

Extending the catalog

License

Third-party attributions

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 58 Commits
.github/workflows		.github/workflows
.kilo		.kilo
VL.MCP.HDE		VL.MCP.HDE
VVVVNodeAnalyzer		VVVVNodeAnalyzer
knowledge		knowledge
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
LICENSE.md		LICENSE.md
README.md		README.md
THIRD-PARTY-NOTICES.md		THIRD-PARTY-NOTICES.md

Folders and files

Latest commit

History

Repository files navigation

vvvv-mcp

Install (end users)

Update

What it does

Help to Improve

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

Install

Bridge mode (Alt+B)

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

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

Build

Run locally (without installing as a global tool)

Test with MCP Inspector

Publish a new version of the MCP server

Publish VL.MCP.HDE (vvvv editor extension)

Repository Structure

Architecture

Roadmap

Node Catalog

Coverage

Extending the catalog

License

Third-party attributions

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Bridge mode (`Alt+B`)

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

Live Editor Tools (requires `VL.MCP.HDE`)

Knowledge (`vvvv://knowledge/`)