Marionettev5
Read Markdown

Marionette documentation MCP#

A local, read-only stdio server for the website's generated documentation corpus and executable workshop recipes. It uses the official MCP TypeScript SDK's maintained v2 server and client packages, pinned in the website lockfile.

Install from this repository#

Use Node.js 24 or newer. Clone and review the website source, then install its locked dependencies and build the same corpus the website serves:

git clone https://github.com/marionettejs/website.git
cd website
npm ci
npm run build
node mcp/server.mjs

The final command waits for an MCP client on stdin; silence is expected. It is not an interactive shell. This repository does not publish an npm MCP package or operate a hosted MCP endpoint.

Configure a client that supports local stdio servers with the following command and argument. Replace both absolute paths with your installed Node 24+ binary and cloned repository location. The server works independently of client cwd.

{
  "mcpServers": {
    "marionette-docs": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/website/mcp/server.mjs"]
    }
  }
}

This is the common mcpServers configuration shape; use your client's equivalent stdio settings if its configuration differs. Do not launch through npm run in a client command: npm's normal script banner would mix with protocol stdout. For a terminal smoke check, run npm run build && node --test test/mcp.test.mjs.

After updating the checkout or importing a new documentation snapshot, run npm ci and npm run build again and restart the MCP connection. The server reads the generated corpus once at startup and rejects mismatched snapshot or publication provenance.

Retrieval workflow#

  1. Read marionette://catalog for the exact supported package version, provenance, document count, and example names.
  2. Call search_docs with a short query and your exact installed version. Search ranks word matches in titles and Markdown, favors titles and multiple matching terms, and ignores common function words. Results report the terms that matched; they need not contain every query word. This is lexical search, so try an API name if a prose query returns nothing.
  3. Pass a returned id to get_doc as path. Follow nextOffset until it is null to retrieve the complete contract. Search snippets are incomplete.
  4. Call get_example with a catalog example name. Concatenate its chunks, then parse the resulting JSON for code, CSS, related docs, and expected checks. Load that recipe in the workshop to run and inspect its behavior.

For this snapshot, a search call is:

{"query":"Region", "version":"5.0.0-beta.1", "limit":5}

version is required for every tool. Unsupported versions, including latest and next, return errors instead of silently choosing another release. Successful tool results contain snapshot version, revision, original content hash, publication edit hash, and generated corpus hash. Document results also include canonical links and the reading Markdown hash. Example results include the hash of the exact returned recipe JSON.

Search returns at most 10 results with 600-character snippets and supports result offsets. Document and example reads default to 8,000 characters and allow at most 12,000 per call. Their offsets count UTF-16 characters, not bytes. Use the returned nextOffset exactly. A requested limit never silently loses the rest of a document or example.

Boundaries and verification#

The three tools only look up identifiers in loaded maps. Tool arguments cannot select filesystem paths, URLs, imports, or commands. The process reads fixed repository files during startup, makes no network requests, writes no files, and never executes recipe code. The MCP server does not run or certify the example's expected checks. The website workshop and browser tests do that work.

The trust boundary is the local checkout and its installed dependencies: review them as you would any executable developer tool. This server does not accept untrusted external corpora or read an application's source code or credentials.

test/mcp.test.mjs uses the official SDK client against a subprocess to verify initialization, discovery, search pagination, full chunk reconstruction, recipe identity, explicit version rejection, invalid input and path rejection, unknown resources, and clean client/EOF shutdown. It is included in npm run check. The tests also reject stale provenance and modified Markdown before startup.

SDK reference: official TypeScript SDK and v2 documentation.