From 983a3036ef74597e7ac51fd9887637746c1f8d36 Mon Sep 17 00:00:00 2001 From: Sasan Sotoodehfar Date: Sat, 31 Oct 2026 16:43:46 -0400 Subject: [PATCH] docs: install from npm in README and quickstart --- README.md | 7 +++++-- .../source/pages/introduction/quickstart.md | 16 ++++++++-------- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 593a6539..957da5e4 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ # ableton-mcp +[![npm](https://img.shields.io/npm/v/@cavi-ai/ableton-mcp)](https://www.npmjs.com/package/@cavi-ai/ableton-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![M8ven Score](https://m8ven.ai/badge/mcp/cavi-ai/ableton-mcp)](https://m8ven.ai/mcp/cavi-ai/ableton-mcp) @@ -20,6 +21,8 @@ In Live's preferences, select **CaviMcpBridge** as a Control Surface. Then check ableton-mcp doctor --json ``` +To update, run the same `npm install -g` command, then `ableton-mcp install`, and restart Live so the bridge matches the server. + To run from a source checkout instead, clone the repository, run `npm ci`, and use `npm run cli --` in place of `ableton-mcp`. ## Quickstart @@ -54,7 +57,7 @@ ableton-mcp call get_producer_workflow --args '{"query":"silent part","limit":3} Search returns keyword candidates with their required arguments. Retrieve a chosen reference by its exact `workflow` name and named string `arguments`. Searching and reading guidance do not execute Live operations. -To try client wiring without Live, run `ABLETON_MCP_FIXTURE=1 npm start`. +To try client wiring without Live, run `ABLETON_MCP_FIXTURE=1 ableton-mcp serve`. For a smaller initial tool catalog, set `ABLETON_MCP_TOOL_PROFILE=core` in the MCP server's environment. It advertises 63 common tools instead of the full catalog. Use the default `all` profile when an agent needs the complete MIDI, audio, rack, or snapshot toolset; restart the server after changing profiles. The CLI's direct `call` command remains independent of the discovery profile. @@ -118,7 +121,7 @@ It publishes 328 tools, 9 concrete resources, 13 resource templates and 89 promp | `ABLETON_MCP_SPLICE_ROOTS` | Existing macOS `~/Splice/Sounds` and `~/Library/Splice/Plug-in/samples` directories; otherwise `[]` | Override with a JSON array of absolute local Splice folders. Set `[]` to disable discovery. Local cache files are not proof of a download license; cloud search and sync are not supported. | | `ABLETON_MCP_CONFIRMATION_DIR` | `~/.cavi/ableton-mcp/confirmations` | Confirmation tokens for CLI `call`. | | `ABLETON_MCP_SNAPSHOT_DIR` | `~/.cavi/ableton-mcp/snapshots` | Saved track, device-chain, group-system, and MIDI-feel snapshots in separate subdirectories. | -| `ABLETON_MCP_FIXTURE` | unset | `1` makes `npm start` serve fixture data without Live. | +| `ABLETON_MCP_FIXTURE` | unset | `1` makes `ableton-mcp serve` serve fixture data without Live. | | `ABLETON_MCP_TOOL_PROFILE` | `all` | `core`: 63 common tools; `producer`: 12 specialist/session tools; `directory`: named native tools without coordinators; `all`: every tool. Compact profiles retain full runtime result validation. | ## Security diff --git a/docs/ableton-mcp/source/pages/introduction/quickstart.md b/docs/ableton-mcp/source/pages/introduction/quickstart.md index 2839cda1..5557124d 100644 --- a/docs/ableton-mcp/source/pages/introduction/quickstart.md +++ b/docs/ableton-mcp/source/pages/introduction/quickstart.md @@ -2,14 +2,14 @@ ## Register the server with an MCP client -Point the client at `cli.mjs serve` in your checkout. Use an absolute path: +After [installing](installation.md), point the client at `ableton-mcp serve`: ```json { "mcpServers": { "ableton": { - "command": "node", - "args": ["/path/to/ableton-mcp/apps/ableton-mcp/src/cli.mjs", "serve"] + "command": "ableton-mcp", + "args": ["serve"] } } } @@ -22,9 +22,9 @@ The server speaks MCP over stdio. It publishes tools, resources and prompts. The CLI calls the same service: ```bash -npm run cli -- status --json -npm run cli -- resource ableton://set/tracks --json -npm run cli -- call list_devices --args '{"trackId":"track-0"}' --json +ableton-mcp status --json +ableton-mcp resource ableton://set/tracks --json +ableton-mcp call list_devices --args '{"trackId":"track-0"}' --json ``` ## Make a change @@ -35,13 +35,13 @@ Every Live mutation is planned first, then executed. 2. Call the tool with `expectedStateVersion`. The result is a dry-run plan with a `confirmation`. ```bash -npm run cli -- call set_tempo --args '{"expectedStateVersion":12,"tempo":124}' --json +ableton-mcp call set_tempo --args '{"expectedStateVersion":12,"tempo":124}' --json ``` 3. Execute the reviewed plan with its single-use token and plan hash: ```bash -npm run cli -- call set_tempo --args '{"expectedStateVersion":12,"tempo":124,"dryRun":false,"confirmationToken":"","planHash":""}' --json +ableton-mcp call set_tempo --args '{"expectedStateVersion":12,"tempo":124,"dryRun":false,"confirmationToken":"","planHash":""}' --json ``` If the Set changed after the plan was made, execution is refused. [Guarded mutations](../guides/guarded-mutations.md) covers the full contract.