maxmsp

Max/MSP via maxmsp-mcp

You drive a running Max patch through the maxmsp-mcp tools. Objects you create appear live on the canvas in max/mcp_host.maxpat, which the user keeps open.

The one rule

Call max_init before any other tool. Every other tool refuses until you do. max_init returns the orientation guide — wire model, naming contract, object cheat sheet, cookbook, and the layout and style rules. That guide is the authoritative source on conventions; this file only tells you when to reach for the MCP and how to stay out of trouble.

Prerequisites the user must satisfy

• The host patch is open. max/mcp_host.maxpat must be open in Max, and the max/ folder on the Max search path (Options > File Preferences) so [v8 dump.js] resolves. If nothing appears in Max, this is almost always why.
• Object reference (optional but recommended). max_doc needs a local database built once from Max's own .maxref.xml files: python tools/build_maxref_db.py /Applications/Max.app -o maxmsp_mcp/objects.json. Without it, max_doc reports that no database is loaded; every other tool still works.

Working rules

• To build a patch from scratch, prefer max_build_patch. Pass the whole graph — objects (each with an id, a type = the Max class such as cycle~, optional args, optional one-line comment) and connections (by id). The server lays it out with no overlaps, wires it, verifies by reading back, and reissues any missing connection itself. You supply no coordinates. Use the unitary tools below only to EDIT a patch that already exists.
• Address objects by their scripting name (obj_0, obj_1, ...), returned by every create call. Wire, disconnect and delete by that name. Track the names you create; do not invent them.
• When unsure of an object's signature — inlet/outlet order, argument types, attribute names — call max_doc <object> instead of guessing. In particular, before connecting to an inlet other than 0, confirm the object has that inlet ([*~] and [dac~] have only inlets 0 and 1).
• Build incrementally, then verify: after wiring a non-trivial patch, call max_dump_patch (or max_verify) to confirm every connection took, and reissue any that are missing. A failed connect only logs to the Max Console; it does not come back as an error, so reading back is how you catch it.
• Before extending an existing patch, read it back first with max_dump_patch so you build on what is really there, including objects the user added by hand.
• Lay out per the guide, not by habit: build clear of the machinery (to the right of, and below, the chat panel and [thispatcher]), keep the signal flow vertical, and never overlap boxes. Follow the exact spacing in the guide returned by max_init.
• Do not propose mxj-based solutions, and do not write malicious or unsafe-loud audio (see below).