Skip to main content
Glama
PSW5

vcvpatch

by PSW5
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

vcvpatch

Read, write, inspect and validate VCV Rack 2 .vcv patch files. Python library, command-line tool, and an MCP server so Claude Desktop (or any MCP client) can create and edit patches on disk.

Why

Rack 2 does not save patches as plain JSON. A .vcv file is a Zstandard-compressed tar archive containing patch.json plus a modules/<id>/ folder for module assets (impulse responses, samples, ...). Tools that treat .vcv as JSON cannot read Rack 2 files and produce files Rack 2 cannot open. vcvpatch handles the real format, round-trips every field losslessly, and keeps the assets.

vcvpatch works on files. It does not talk to a running Rack. For live control of a running patch, see Neural-Harmonics/vcv-rack-plugin.

Related MCP server: Cardinal MCP Server

Install

Requires Python 3.11+ and uv.

# as a tool
uv tool install git+https://github.com/PSW5/vcvpatch

# or for development
git clone https://github.com/PSW5/vcvpatch
cd vcvpatch
uv sync --group dev
uv run pytest -q

CLI

vcvpatch unpack my_patch.vcv                 # -> my_patch/patch.json + my_patch/modules/
vcvpatch pack my_patch -o my_patch_v2.vcv    # directory or a bare patch.json
vcvpatch info my_patch.vcv                   # module/cable summary (--json, --markdown)
vcvpatch validate my_patch.vcv               # exit 1 on errors (missing plugins, bad cables, ...)
vcvpatch library oscillator --tags Polyphonic  # search installed modules
vcvpatch catalog ~/my_patches                # INDEX.md + catalog/ for a folder of patches (see below)
vcvpatch mcp                                 # run the MCP server over stdio

validate, info and library look at the plugins installed in your Rack user directory (~/Library/Application Support/Rack2 on macOS, %LOCALAPPDATA%\Rack2 on Windows, ~/.local/share/Rack2 on Linux). Override with RACK_USER_DIR.

Python API

from vcvpatch import Library, Patch, read_vcv, validate, write_vcv

patch = read_vcv("drone.vcv")            # Patch(raw=<patch.json dict>, assets={...})
lib = Library.scan()                     # installed plugins, Core included

vco = patch.add_module("Fundamental", "VCO", version=lib.plugin_version("Fundamental"))
vcf = patch.add_module("Fundamental", "VCF", version=lib.plugin_version("Fundamental"))
patch.add_cable(vco["id"], 2, vcf["id"], 0)   # VCO SAW out -> VCF in
patch.set_param(vcf["id"], 0, 0.6)

for issue in validate(patch, lib):
    print(issue)
write_vcv(patch, "drone_v2.vcv")         # refuses to overwrite unless overwrite=True

Patch.raw is the untouched patch.json dict. Unknown keys are preserved, so read_vcv -> write_vcv -> read_vcv yields identical content.

MCP server

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "vcvpatch": {
      "command": "uv",
      "args": ["--directory", "/path/to/vcvpatch", "run", "vcvpatch", "mcp"]
    }
  }
}

If installed with uv tool install, use "command": "vcvpatch", "args": ["mcp"] instead.

Tool

What it does

vcv_library_search

Find exact plugin / model slugs among installed modules (query, tags)

vcv_create

Write a new .vcv from a module list and cables; ids, plugin versions and positions are filled in

vcv_read

Return patch.json contents, asset list and a text summary

vcv_write

Write a full patch.json dict; validates first; keep_assets_from preserves assets of the original

vcv_validate

Structural checks plus "is this plugin/module installed?"

Suggested prompt flow: search the library -> create the patch -> open the file in Rack. Every tool returns {"ok": false, "error": "..."} instead of raising, so the client can recover.

Catalog a folder of patches

vcvpatch catalog <dir> turns a folder of .vcv files into something people and agents can browse:

<dir>/INDEX.md                    overview grouped by week (from names like ICMP_w5_ex_FM.vcv), with thumbnails
<dir>/catalog/catalog.json        one record per patch: week, topic, date, modules (with names), cables,
                                  embedded Notes text, plugins, bounding box, snapshot path, annotation
<dir>/catalog/patches/<stem>.md   one page per patch
<dir>/catalog/annotations.json    curated title / summary / tags / teaching_points; regeneration only adds
                                  missing entries (marked "inferred": true), it never overwrites yours
<dir>/catalog/snapshots/<stem>.png screenshots (see below)

Screenshots are taken by scripts/snapshot_rack_macos.py (macOS only). For every patch it writes a temporary copy whose zoom and gridOffset fit the whole patch into the Rack window, relaunches Rack with that file, waits for the log to report the modules, and captures the window:

uv run python scripts/snapshot_rack_macos.py ~/my_patches --size 1700x1050   # add --force to retake

It needs Screen Recording + Accessibility permission for your terminal, mutes the system volume while running, and restores Rack's window settings afterwards.

File format notes (Rack 2.5.x, observed)

  • .vcv = zstd(tar) with entries ./, ./patch.json, ./modules/, ./modules/<moduleId>/<asset>.

  • patch.json top level: version, path, zoom, gridOffset, modules, cables, masterModuleId.

  • module: id, plugin, model, version, params: [{id, value}], pos: [x_hp, row], optional leftModuleId, rightModuleId, data.

  • cable: id, outputModuleId, outputId, inputModuleId, inputId, color.

  • zoom is linear; gridOffset is the viewport's top-left corner in grid units (HP, rows).

  • ids are random 53-bit integers. Rack 1 files (plain JSON) are also readable.

Limitations

  • Offline tools cannot know a module's width or port count: auto-placement assumes 16 HP per module, and port indices are not range-checked. Pass pos explicitly for tight layouts.

  • Parameter values are raw knob values, not Hz or dB.

  • Windows paths follow the Rack manual but are untested.

繁體中文簡介

Rack 2 的 .vcv 不是純 JSON，而是 zstd 壓縮的 tar（內含 patch.json 與 modules/ 附檔）。 vcvpatch 提供 Python 函式庫、CLI 與 MCP server，讓你（或 Claude）可以正確解包、打包、 檢視、驗證與產生 Rack 2 patch，並保證 round-trip 無損。它只處理檔案，不連線正在執行的 Rack。

License

MIT

Available Tools

5 tools
vcv_createA

Create a new .vcv file from a list of modules and cables. Module ids, plugin versions and positions are filled in automatically. Cables reference modules by their index in the modules list.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
cablesNo
modulesYes
overwriteNo
rack_versionNo2.5.2

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It usefully reveals that module ids, plugin versions, and positions are auto-filled, and that cables reference modules by index. However, it does not disclose overwrite behavior, failure conditions, or other side effects beyond creating a file.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, with the core purpose front-loaded and each subsequent sentence adding a meaningful behavioral detail. There is no filler or repetition of schema information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description adequately covers the main creation behavior and the module/cable relationship, and an output schema exists so return values need not be elaborated. However, it omits overwrite semantics and the meaning of rack_version, which an agent needs to safely invoke the tool on an existing file.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Top-level schema description coverage is 0%, so the description must compensate. It adds meaning for modules and cables by explaining auto-fill behavior and index-based cable references. However, path, overwrite, and rack_version are left unexplained, leaving several parameters semantically ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Create a new .vcv file', which names a specific verb and resource, and clarifies the input is a list of modules and cables. This clearly distinguishes it from sibling tools like vcv_read, vcv_write, vcv_validate, and vcv_library_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for generating a .vcv patch file from structured module/cable data, but it does not explicitly state when to prefer it over vcv_write or mention prerequisites such as plugin availability. Usage context is present but exclusions and alternatives are not.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vcv_readA

Read a .vcv file: Rack version, modules, cables, asset list and a text summary.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden, and it does provide useful detail about what the tool exposes: Rack version, modules, cables, asset list, and a summary. 'Read' conveys a non-mutating operation, though the description could have clarified error behaviors or file-format expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-front-loaded sentence. It states the core action first and then lists the returned content without any filler or redundant restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with one parameter and an output schema present, the description provides enough context about what the tool does and what it returns. It could be slightly more complete with explicit mention of file-not-found or invalid-format behavior, but those are minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has a single 'path' parameter with no description coverage. The description indirectly clarifies that path should refer to a .vcv file, but it does not add explicit detail about path format, validation, or accepted file variations beyond the extension.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with a specific verb and resource: 'Read a .vcv file' and then lists exactly what is included: Rack version, modules, cables, asset list, and a text summary. This clearly distinguishes it from sibling tools like vcv_write, vcv_create, and vcv_validate, which imply different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for reading/inspecting an existing .vcv file, which is reasonable, but it does not explicitly state when to choose it over alternatives or when not to use it. No sibling tool is referenced as an alternative, so the guidance is only implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vcv_validateA

Check a .vcv file for structural problems and missing plugins.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description conveys a non-mutating validation behavior and specifies what is checked, which is useful. However, with no annotations, it does not disclose side effects, success/failure behavior, or whether the file is modified in any way, so the agent must infer a lot from the word 'Check'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no wasted words. It immediately states the action and the target resource while remaining easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with an output schema, the description is mostly adequate because return values are presumably covered by that schema. It still lacks usage context relative to sibling tools and does not fully clarify behavioral side effects, leaving moderate gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it partially does by indicating the required 'path' parameter refers to a .vcv file. It does not specify path format, file accessibility, or constraints, but for a single simple parameter this is modestly helpful.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb, 'Check', identifies the exact resource (a .vcv file), and names two concrete validation concerns: structural problems and missing plugins. This clearly distinguishes it from sibling tools like vcv_read, vcv_write, vcv_create, and vcv_library_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to choose this tool over its siblings. No conditions, prerequisites, or exclusions are stated, leaving the agent to infer usage from the generic 'Check a .vcv file' phrasing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vcv_writeA

Write a full patch.json dict to a .vcv file. Validates first; refuses to overwrite unless overwrite=true. Pass keep_assets_from=<original .vcv> when saving an edited copy so module asset files are preserved.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
patchYes
overwriteNo
keep_assets_fromNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It discloses that validation happens first, that overwrites are refused unless overwrite=true, and that keep_assets_from preserves asset files. This is meaningful behavioral context beyond the bare schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, and the most important safeguards (validation, overwrite refusal) are front-loaded. The keep_assets_from usage note earns its place by providing crucial guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter write tool with no annotations, the description covers validation, overwrite policy, and asset preservation. It does not mention failure behavior or output format, but an output schema exists and the core calling contract is well specified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does: 'patch' is explained as a full patch.json dict, 'overwrite' is tied to refusal behavior, and 'keep_assets_from' is explained as preserving asset files. Only 'path' is left implicit, but that is fairly self-evident from the file-write context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action: writing a full patch.json dict to a .vcv file. This distinguishes it from sibling tools like vcv_read, vcv_validate, and vcv_library_search, and gives a clear sense of the resource involved.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance for a key case: using keep_assets_from when saving an edited copy. It also notes overwrite behavior. It does not explicitly contrast with vcv_create, but the write/validate framing implies the appropriate scenarios clearly enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv0.1.0
    • First observedvcv_create
    • First observedvcv_library_search
    • First observedvcv_read
    • First observedvcv_validate
    • First observedvcv_write
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: read, write, create, validate, and library search. Even where read and validate both touch .vcv files, one provides a summary while the other checks structural integrity, so there is no real ambiguity.

Naming Consistency4/5

All tools share the vcv_ prefix and use lowercase snake_case, which is consistent. The only minor deviation is vcv_library_search, which is object-verb rather than the verb-first pattern used by the other four tools.

Tool Count5/5

Five tools is well-scoped for a patch-file manipulation server. Each tool covers a necessary operation without redundancy or bloat.

Completeness5/5

The toolset covers the full patch lifecycle: create, read, write, validate, and search for library modules needed during creation. There are no obvious dead ends or missing core operations.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • re-patch

    Heretek-RE
    A
    license
    A
    quality
    C
    maintenance
    MCP server for on-disk patching of binary artifacts with SHA-256 manifest, byte-level patch application, and manifest-driven restore, ensuring auditability and reversibility.
    4
    MIT

  • vcv-rack-mcp

    sandraschi
    A
    license
    C
    quality
    B
    maintenance
    Enables LLMs to compose VCV Rack modular synth patches by generating plain JSON, with tools for patch creation, catalog search, and live OSC control.
    7
    3
    MIT

  • mcp-chatgpt-file-store

    tanongkiat
    F
    license
    A
    quality
    B
    maintenance
    Enables saving and managing files in a sandboxed local folder via MCP, with tools for listing, reading, writing, appending, searching, moving, and deleting files and directories.
    10
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/PSW5/vcvpatch'

If you have feedback or need assistance with the MCP directory API, please join our Discord server