@frixaco/ableton-docs

A read-only Model Context Protocol (MCP) server that indexes the complete English Ableton Live 12 manual, the Live Object Model reference, and selected support and tutorial pages.

It is a TypeScript side project built with the official MCP SDK 2.x. It supports protocol revision 2026-07-28, stdio, and authenticated local Streamable HTTP. It does not require Ableton Live and does not control it.

Quick start

Requires Node.js 24+ and npm.

npm install -g @frixaco/ableton-docs
ableton-docs sync-docs
ableton-docs status

The first sync downloads and indexes the source documents and two local search models. It can take several minutes. Search works offline after setup. Data is stored in ~/.ableton-mcp by default; set ABLETON_MCP_DATA or use --data-dir to change it.

Add the server to an MCP client after the sync:

{
  "mcpServers": {
    "ableton-docs": {
      "command": "npx",
      "args": ["-y", "@frixaco/[email protected]", "serve"]
    }
  }
}

On Windows, clients that need an explicit executable can use cmd with arguments ["/c", "npx", "-y", "@frixaco/[email protected]", "serve"].

The server needs no API key. It runs search models locally on the CPU and sends no queries to a model provider.

Tools

| Tool | Purpose | | ---------------------- | --------------------------------------------------- | | documentation_status | Check source coverage and index status. | | list_docs | List source pages. | | list_doc_sections | Browse a page by heading. | | search_docs | Find relevant passages. | | read_doc | Read a full page with pagination. | | read_doc_section | Read one section, its images, and related sections. | | list_doc_images | List image IDs, captions, and source URLs. | | read_doc_image | Return a screenshot or diagram as an MCP image. |

The normal workflow is: search a question, read the matching sections, and cite their publisher URLs. A search rank is a lead, not proof. Long reads return next_offset for pagination.

Resources are available at ableton://docs/catalog and ableton://docs/section/{section_id}. The server also provides the explain_live prompt.

How it works

sync-docs discovers and indexes every HTML chapter in the official Live 12 table of contents and every class linked from the Live Object Model index. It also indexes selected supplements, including Ableton's latency guide and EDMProd's independent beginner tutorial. It does not mirror the full help center, other manuals, or every language.

The searchable text comes from Ableton's HTML manual pages. The sync also downloads and validates the official PDF as a source artifact, but does not extract its text. It publishes the SQLite index only after the full replacement is ready, so failed syncs preserve the active index. Rebuilds reuse embeddings when the source text and model are unchanged. Use sync-docs --refresh to fetch fresh sources.

Search combines:

• SQLite FTS5 BM25 word matching with the Porter tokenizer;
• local BAAI/bge-small-en-v1.5 semantic embeddings;
• reciprocal rank fusion of lexical and semantic results;
• local Xenova/ms-marco-MiniLM-L-6-v2 cross-encoder reranking;
• overlapping text windows with heading context.

ONNX Runtime executes both models on the CPU. ABLETON_MCP_MODEL_DIR changes their cache location, and ABLETON_MCP_MODEL_THREADS sets 1–32 threads per model.

Source filters separate the manual, Live Object Model, Ableton help, and independent tutorials. Results retain page IDs, section IDs, source labels, and original URLs.

Images and safety

Section reads preserve each image's source order, caption, section, Unicode text offset, and nearby text. read_doc_image downloads an indexed image on first use, converts it to PNG, and returns an actual MCP image content block with citation metadata. Previously viewed images remain available offline. Search uses captions and source text; it does not use OCR or image embeddings.

Image reads accept only indexed HTTPS publishers. The downloader validates hosts after redirects and limits time, bytes, decoded pixels, and output dimensions. PNG, JPEG, WebP, and the first frame of GIF files are supported. Arbitrary URLs and filesystem paths are not accepted.

Optional HTTP transport binds only to 127.0.0.1:8766 and requires a random bearer token:

$env:ABLETON_MCP_HTTP_TOKEN = node -e 'console.log(require("node:crypto").randomBytes(32).toString("hex"))'
ableton-docs serve --transport streamable-http

Connect to http://127.0.0.1:8766/mcp with Authorization: Bearer <token>. Browser-origin requests are rejected. This is local shared-token authentication, not OAuth; do not expose it through a public proxy.

Development

npm ci
npm test
npm run check
npm run format:check
npm pack --dry-run

Tests use real stdio and HTTP MCP clients. They cover protocol negotiation, resources, structured output, parsing, hybrid retrieval, atomic index refresh, embedding reuse, image boundaries, authentication, and invalid input. Retrieval tests run the real local models.

The frozen benchmark contains 100 questions across beginner, intermediate, and professional levels. Recorded TypeScript runs matched the Python baseline: 65/100 evidence coverage with one search and 100/100 with authored follow-up searches in two runs. This measures evidence retrieval, not autonomous answer accuracy. See benchmark/README.md for the method and reports.

Sources and license

• Ableton Live 12 manual
• Live Object Model
• MCP TypeScript SDK

The MIT license covers this project's code. Downloaded documents, images, and model weights retain their publishers' ownership and licenses. They are not included in the npm package.