feat: publish package to npm

.github/workflows/publish-npm.yml

@@ -0,0 +1,72 @@
+name: Publish npm package
+
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+concurrency:
+  group: publish-npm-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    permissions:
+      contents: read
+      # npm exchanges this OIDC token for a short-lived publish credential; no npm token is stored.
+      id-token: write
+    runs-on: macos-latest
+    steps:
+      - name: Check out release source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+
+      # Node 24.18.1 bundles npm 11.16.0; trusted publishing needs npm 11.5.1 or newer.
+      - name: Set up Node.js
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24.18.1
+          registry-url: https://registry.npmjs.org
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+
+      - name: Resolve release version
+        id: release
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version="$(node -p 'require("./package.json").version')"
+          if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Could not resolve a stable package.json version"
+            exit 1
+          fi
+          if [[ "$RELEASE_TAG" != "v$version" ]]; then
+            echo "::error::Expected release tag v$version (package.json version), got $RELEASE_TAG"
+            exit 1
+          fi
+          if npm view "@cavi-ai/ableton-mcp@$version" version >/dev/null 2>&1; then
+            echo "::notice::@cavi-ai/ableton-mcp@$version is already published"
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "publish=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Test package
+        if: steps.release.outputs.publish == 'true'
+        run: |
+          brew install imagemagick ffmpeg
+          npm ci
+          npm test
+          npm run verify:package
+
+      # The trusted publisher for @cavi-ai/ableton-mcp on npmjs.com names this repository and the
+      # workflow filename publish-npm.yml; renaming this file stops publishing until it is updated.
+      - name: Publish
+        if: steps.release.outputs.publish == 'true'
+        run: npm publish --access public --provenance

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Publish `@cavi-ai/ableton-mcp` to npm from each GitHub release with trusted publishing and provenance.
+
 ## 0.4.0
 
 - Preserve per-operation production attempts and receipts across interruptions, add explicit recovery proposals, and expose runtime fingerprints with guarded CLI server restart.

README.md

@@ -10,44 +10,46 @@ Local-first Ableton Live control for MCP clients. It has three parts: a Remote S
 Requirements: macOS, Ableton Live 12 (tested with 12.4.6), Node.js 22.13 or newer, and `ffmpeg` for the audio analysis tools.
 
 ```bash
-git clone https://github.com/cavi-ai/ableton-mcp.git
-cd ableton-mcp
-npm ci
-npm run cli -- install
+npm install -g @cavi-ai/ableton-mcp
+ableton-mcp install
 ```
 
 In Live's preferences, select **CaviMcpBridge** as a Control Surface. Then check the connection:
 
 ```bash
-npm run cli -- doctor --json
+ableton-mcp doctor --json
 ```
 
+To run from a source checkout instead, clone the repository, run `npm ci`, and use `npm run cli --` in place of `ableton-mcp`.
+
 ## Quickstart
 
-Register the stdio server with your MCP client, using the absolute path of your checkout:
+Register the stdio server with your MCP client:
 
 ```json
 {
   "mcpServers": {
     "ableton": {
-      "command": "node",
-      "args": ["/path/to/ableton-mcp/apps/ableton-mcp/src/cli.mjs", "serve"]
+      "command": "ableton-mcp",
+      "args": ["serve"]
     }
   }
 }
 ```
 
+If your client does not inherit your shell's `PATH`, use the absolute path printed by `which ableton-mcp`.
+
 Or call tools from the shell:
 
 ```bash
-npm run cli -- status --json
-npm run cli -- call list_devices --args '{"trackId":"track-0"}' --json
+ableton-mcp status --json
+ableton-mcp call list_devices --args '{"trackId":"track-0"}' --json
 ```
 
 Find workflow guidance before choosing individual tools:
 
 ```bash
-npm run cli -- call get_producer_workflow --args '{"query":"silent part","limit":3}' --json
+ableton-mcp call get_producer_workflow --args '{"query":"silent part","limit":3}' --json
 ```
 
 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.

docs/ableton-mcp/source/pages/introduction/installation.md

@@ -11,6 +11,12 @@
 
 ## Install the server
 
+```bash
+npm install -g @cavi-ai/ableton-mcp
+```
+
+This installs the `ableton-mcp` command. To run from a source checkout instead, use `npm run cli --` in place of `ableton-mcp`:
+
 ```bash
 git clone https://github.com/cavi-ai/ableton-mcp.git
 cd ableton-mcp
@@ -20,27 +26,27 @@ npm ci
 ## Install the bridge
 
 ```bash
-npm run cli -- install
+ableton-mcp install
 ```
 
 This copies `CaviMcpBridge` into `~/Music/Ableton/User Library/Remote Scripts`. It copies nothing else. Then open Live's preferences, go to **Link, Tempo & MIDI**, and select **CaviMcpBridge** as a Control Surface.
 
-Pass `--destination <Remote Scripts path>` if your User Library is somewhere else. `npm run cli -- uninstall` removes only the installed `CaviMcpBridge` directory.
+Pass `--destination <Remote Scripts path>` if your User Library is somewhere else. `ableton-mcp uninstall` removes only the installed `CaviMcpBridge` directory.
 
 ### An older copy inside the application bundle
 
 An older copy of the script inside the application bundle can take precedence over the User Library copy. If `doctor` reports an outdated bridge after installing, check and update that copy:
 
 ```bash
-npm run cli -- install --destination "/Applications/Ableton Live 12 Suite.app/Contents/App-Resources/MIDI Remote Scripts"
+ableton-mcp install --destination "/Applications/Ableton Live 12 Suite.app/Contents/App-Resources/MIDI Remote Scripts"
 ```
 
 Then restart Live. This modifies the application bundle; the default install does not. A Live update can replace the copy, so run `doctor` again after updating Live.
 
 ## Check the connection
 
 ```bash
-npm run cli -- doctor --json
+ableton-mcp doctor --json
 ```
 
 `ok: true` means the bridge answered on the socket, reports version {{PRODUCT_VERSION}}, and advertises every capability the server needs. If it doesn't, see [Troubleshooting](../guides/troubleshooting.md).