audiobookshelf-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Willi Thiel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# audiobookshelf-mcp
+
+[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/audiobookshelf-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/audiobookshelf-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/audiobookshelf-mcp)](https://www.npmjs.com/package/audiobookshelf-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/audiobookshelf-mcp)](https://www.npmjs.com/package/audiobookshelf-mcp)
+[![node](https://img.shields.io/node/v/audiobookshelf-mcp)](https://nodejs.org)
+[![Container](https://img.shields.io/badge/ghcr.io-ni--c%2Faudiobookshelf--mcp-2496ED?logo=docker&logoColor=white)](https://github.com/ni-c/audiobookshelf-mcp/pkgs/container/audiobookshelf-mcp)
+[![license](https://img.shields.io/npm/l/audiobookshelf-mcp)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-audiobookshelf--mcp.ni--c.de-4f46e5)](https://audiobookshelf-mcp.ni-c.de)
+
+An [MCP](https://modelcontextprotocol.io) server for
+[Audiobookshelf](https://www.audiobookshelf.org/), the self-hosted audiobook and
+podcast server. It lets an AI assistant browse your libraries, answer questions
+about what you own and what you have listened to, and — unless you switch it off —
+keep your listening progress, bookmarks, collections and playlists up to date.
+
+44 tools: 29 read, 15 write.
+
+📖 **Full documentation: <https://audiobookshelf-mcp.ni-c.de>**
+
+<img src="https://audiobookshelf-mcp.ni-c.de/architecture.svg" alt="An MCP client talks to audiobookshelf-mcp over stdio; the server exposes 29 read and 15 write tools, compacts every response, and calls the Audiobookshelf REST API over HTTPS with a bearer API key" width="800">
+
+<img src="https://audiobookshelf-mcp.ni-c.de/demo.gif" alt="Terminal recording: the server reports 44 tools, lists library items as a compact projection, and answers the first delete_collection call with a single-use confirmation token instead of deleting anything" width="800">
+
+## Requirements
+
+- Node.js 22 or newer
+- Audiobookshelf **2.26.0 or newer** — earlier versions have no API keys
+- An Audiobookshelf API key
+
+## Getting an API key
+
+API keys are managed by an admin under **Settings → Users → API Keys**. A key acts
+on behalf of exactly one Audiobookshelf user and inherits that user's permissions,
+so a key issued for a normal account cannot see libraries that account cannot see,
+and cannot delete anything unless that account may delete. The key is shown only
+once, at creation.
+
+## Configuration
+
+| Variable                      | Required | Description                                                                             |
+| ----------------------------- | -------- | --------------------------------------------------------------------------------------- |
+| `AUDIOBOOKSHELF_URL`          | yes      | Base URL of the instance, e.g. `https://abs.example.com`. Must not contain credentials. |
+| `AUDIOBOOKSHELF_API_KEY`      | yes      | API key, sent as `Authorization: Bearer …`                                              |
+| `AUDIOBOOKSHELF_READ_ONLY`    | no       | `true` registers only the 29 read tools                                                 |
+| `AUDIOBOOKSHELF_INSECURE_TLS` | no       | `true` accepts self-signed certificates — scoped to this connection, not process-wide   |
+
+The server starts without configuration: it completes the MCP handshake and lists
+its tools, and every call then fails with the setup instructions. That is
+deliberate, so registries and sandbox inspectors can introspect it.
+
+## Install
+
+```sh
+claude mcp add audiobookshelf \
+  -e AUDIOBOOKSHELF_URL=https://abs.example.com \
+  -e AUDIOBOOKSHELF_API_KEY=… \
+  -- npx -y audiobookshelf-mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "audiobookshelf": {
+      "command": "npx",
+      "args": ["-y", "audiobookshelf-mcp"],
+      "env": {
+        "AUDIOBOOKSHELF_URL": "https://abs.example.com",
+        "AUDIOBOOKSHELF_API_KEY": "…"
+      }
+    }
+  }
+}
+```
+
+Codex (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.audiobookshelf]
+command = "npx"
+args = ["-y", "audiobookshelf-mcp"]
+env = { AUDIOBOOKSHELF_URL = "https://abs.example.com", AUDIOBOOKSHELF_API_KEY = "…" }
+```
+
+Container (multi-arch, with SBOM and build provenance):
+
+```sh
+docker run -i --rm \
+  -e AUDIOBOOKSHELF_URL=https://abs.example.com \
+  -e AUDIOBOOKSHELF_API_KEY=… \
+  ghcr.io/ni-c/audiobookshelf-mcp
+```
+
+`-i` is required — the protocol runs over stdin and stdout. There is no port to
+publish. More client recipes, including how to keep the key off the `docker run`
+command line, are in the
+[client guide](https://audiobookshelf-mcp.ni-c.de/guide/clients).
+
+## Tools
+
+### Reading
+
+| Tool                                  | What it does                                                                                        |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `list_libraries`                      | The accessible libraries with id, name and media type — the entry point                             |
+| `get_library`                         | One library with its folders and settings                                                           |
+| `get_library_stats`                   | Item, author and genre counts, total duration and size                                              |
+| `get_library_filter_data`             | The filterable values of a library: authors, genres, tags, series, narrators, languages, publishers |
+| `list_library_items`                  | Items of a library, paginated, sortable, filterable                                                 |
+| `search_library`                      | Full-text search across books, podcasts, series, authors, narrators and tags                        |
+| `get_personalized_shelves`            | The home screen shelves: Continue Listening, Recently Added, …                                      |
+| `list_series` / `get_series`          | Series with book count and total duration                                                           |
+| `list_authors` / `get_author`         | Authors, optionally with their items                                                                |
+| `list_tags` / `list_genres`           | All tags / genres used on the server                                                                |
+| `get_library_item`                    | One book or podcast with metadata, tags and your progress                                           |
+| `get_item_chapters`                   | The chapter list of a book, separate because it can be long                                         |
+| `get_podcast_episode`                 | One episode with publication date, duration and description                                         |
+| `list_recent_episodes`                | Newest episodes of a podcast library                                                                |
+| `get_me`                              | The user the API key acts for, with permissions and libraries                                       |
+| `list_items_in_progress`              | Started but unfinished items across all libraries                                                   |
+| `get_media_progress`                  | Position, percentage and finished state for one item                                                |
+| `get_listening_stats`                 | Total time, time per day and per weekday, most listened items                                       |
+| `get_year_stats`                      | The "year in review" figures for one calendar year                                                  |
+| `list_listening_sessions`             | Playback sessions with device, position and time listened                                           |
+| `list_bookmarks`                      | Bookmarks, all of them or those of one item                                                         |
+| `list_collections` / `get_collection` | Collections — shared, ordered groups of books                                                       |
+| `list_playlists` / `get_playlist`     | Playlists — private per user, books or episodes                                                     |
+| `get_server_status`                   | Version and initialization state of the server                                                      |
+
+### Writing
+
+| Tool                                                            | What it does                                                            |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `set_media_progress`                                            | Set position, mark finished or unfinished, hide from Continue Listening |
+| `delete_media_progress`                                         | Delete a progress record — needs a confirmation token                   |
+| `create_bookmark` / `update_bookmark` / `delete_bookmark`       | Named positions in a book                                               |
+| `create_collection` / `update_collection` / `delete_collection` | Collections; delete needs a confirmation token                          |
+| `add_books_to_collection` / `remove_books_from_collection`      | Collection membership                                                   |
+| `create_playlist` / `update_playlist` / `delete_playlist`       | Playlists; delete needs a confirmation token                            |
+| `add_items_to_playlist` / `remove_items_from_playlist`          | Playlist membership                                                     |
+
+### Response size
+
+Audiobookshelf returns very large objects — an expanded library item carries every
+audio file, track and chapter with full ffprobe metadata. Every tool that returns
+media therefore answers with a compact projection by default and accepts
+`detail: "full"` for the raw object. List tools are capped at 100 entries per call
+and say how to page on when more match.
+
+### Filtering
+
+`list_library_items` takes `filter_group` plus `filter_value` and builds the
+base64-encoded `filter` parameter the API expects. The valid values come from
+`get_library_filter_data`. A valued group without a value is rejected, because
+Audiobookshelf would silently answer with the _unfiltered_ library instead.
+
+```
+filter_group="authors",  filter_value="<author id>"
+filter_group="progress", filter_value="finished" | "in-progress" | "not-started" | "not-finished"
+filter_group="issues"    (standalone, no value)
+```
+
+## Safety
+
+- **Read-only mode.** `AUDIOBOOKSHELF_READ_ONLY=true` does not register the write
+  tools at all, rather than refusing them at call time.
+- **Confirmation tokens.** `delete_collection`, `delete_playlist` and
+  `delete_media_progress` answer the first call with a single-use token that is
+  bound to the target id and expires after five minutes; only a second call
+  carrying that token performs the deletion. A plain `confirm: true` flag could be
+  set by the model on the first try, or be talked into it by text coming out of
+  the library. Operations that are cheap to undo — removing an item from a
+  collection, deleting a bookmark — are marked destructive but do not require a
+  token.
+- **Confirmation prompts never quote API content.** Collection and playlist names
+  are user-supplied text and are read by a model, so the prompts name only ids.
+- **Untrusted content is marked.** Book descriptions come from metadata providers
+  and podcast summaries come from RSS feeds — third parties write them. Every
+  result carrying such content is labelled as data, not instructions.
+- **The API key is deleted from the environment** once the configuration has been
+  read, so it is not visible to child processes or in `/proc/<pid>/environ`.
+- **No redirects are followed** (`redirect: 'error'`), so the `Authorization`
+  header cannot be replayed against another host, and every request has a 15
+  second timeout.
+- **Ids are validated** before they enter a URL path.
+- **Upstream error bodies are sanitized**: HTML error pages are dropped, anything
+  else is truncated to 2000 characters.
+- **Progress updates send whitelisted fields only.** The Audiobookshelf endpoint
+  applies its payload to the progress record wholesale.
+- **What this server cannot do**, by design: no user management, no server
+  settings, no backups, no cache purging, no filesystem browsing, no library or
+  item deletion, no metadata rewriting, no file uploads.
+
+One caveat that comes from Audiobookshelf itself: removing the _last_ entry from a
+playlist deletes the playlist. `remove_items_from_playlist` says so in its result
+when it happens.
+
+## Development
+
+```sh
+npm install
+npm run lint          # eslint + prettier --check
+npm run build         # tsc
+npm test              # vitest
+npm run test:coverage # with thresholds
+npm run docs:tools    # regenerate docs/reference/tools.md from the registered tools
+```
+
+The table above is hand-curated; the complete
+[tool reference](https://audiobookshelf-mcp.ni-c.de/reference/tools) with every
+parameter is generated from the code, and CI fails if the committed copy is stale.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for a throwaway Audiobookshelf you can
+safely write to — the write tools change progress and bookmarks on the API key's
+own user, so don't develop against a library you care about.
+
+The tool definitions were derived from the Audiobookshelf server source
+(`server/routers/ApiRouter.js` and the controllers) rather than from
+[api.audiobookshelf.org](https://api.audiobookshelf.org/), which is out of date in
+several places — the filter data endpoint is `/filterdata` not `/filter`, progress
+updates are `PATCH /api/me/progress/:id` not `POST /api/me/progress`, and bookmarks
+live under `/api/me/item/:id/bookmark`.
+
+## Releasing
+
+Tag-driven, no manual publish step:
+
+1. Move the `[Unreleased]` entries into a new `## [x.y.z] - YYYY-MM-DD` section in
+   `CHANGELOG.md` and bump `package.json`.
+2. `npm run lint && npm run build && npm run test:coverage`.
+3. Commit, then a **signed annotated** tag: `git tag -s vx.y.z -m "vx.y.z"`.
+4. `git push origin main vx.y.z`.
+
+`release.yml` then runs the tests, publishes to npm with provenance via Trusted
+Publishing (no token secret involved), creates the GitHub release from the
+CHANGELOG section, and publishes to the
+[MCP registry](https://registry.modelcontextprotocol.io) as
+`io.github.ni-c/audiobookshelf-mcp`. `ci.yml` pushes the multi-arch image to GHCR
+on the same tag.
+
+If the registry step fails, fix it on `main` and dispatch the
+`Publish to MCP Registry` workflow — do **not** re-run the tag job, which would
+check out the old tree.
+
+## Contributing
+
+Issues, discussions and pull requests are welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md). For vulnerabilities please use
+[private reporting](https://github.com/ni-c/audiobookshelf-mcp/security/advisories/new)
+rather than a public issue; the policy is in [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,38 @@
+import { type Config } from './config.js';
+export declare class AudiobookshelfApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string, method: string, path: string);
+}
+/** Minimal client for the Audiobookshelf REST API. */
+export declare class AudiobookshelfApi {
+    private readonly config;
+    private readonly baseUrl;
+    /**
+     * Only set when AUDIOBOOKSHELF_INSECURE_TLS is enabled. Scopes the relaxed
+     * certificate validation to requests against the configured host instead of
+     * disabling it process-wide via NODE_TLS_REJECT_UNAUTHORIZED.
+     */
+    private readonly insecureDispatcher?;
+    constructor(config: Config);
+    request(method: string, path: string, body?: unknown): Promise<unknown>;
+    get(path: string): Promise<unknown>;
+    post(path: string, body?: unknown): Promise<unknown>;
+    patch(path: string, body?: unknown): Promise<unknown>;
+    delete(path: string): Promise<unknown>;
+}
+/**
+ * Guards an id that ends up in a URL path. Path traversal here would let a
+ * caller reach a different resource — or a different API entirely.
+ *
+ * Audiobookshelf ids are UUIDs on current servers and prefixed slugs
+ * (`li_…`, `lib_…`, `col_…`, `pl_…`, `aut_…`) on older ones; both fit.
+ */
+export declare function assertPathSegment(value: string, what: string): string;
+/**
+ * Builds a query string from defined values only.
+ *
+ * URLSearchParams does the percent-encoding, which matters for the `filter`
+ * parameter: its base64 payload can contain `+`, `/` and `=`.
+ */
+export declare function query(params: Record<string, string | number | boolean | undefined>): string;

package/dist/api.js

@@ -0,0 +1,122 @@
+import { Agent, fetch as undiciFetch, } from 'undici';
+import { missingConfigKeys, missingConfigMessage, } from './config.js';
+const REQUEST_TIMEOUT_MS = 15_000;
+export class AudiobookshelfApiError extends Error {
+    status;
+    body;
+    constructor(status, body, method, path) {
+        super(`Audiobookshelf API ${method} ${path} failed with HTTP ${status}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'AudiobookshelfApiError';
+    }
+}
+/** Minimal client for the Audiobookshelf REST API. */
+export class AudiobookshelfApi {
+    config;
+    baseUrl;
+    /**
+     * Only set when AUDIOBOOKSHELF_INSECURE_TLS is enabled. Scopes the relaxed
+     * certificate validation to requests against the configured host instead of
+     * disabling it process-wide via NODE_TLS_REJECT_UNAUTHORIZED.
+     */
+    insecureDispatcher;
+    constructor(config) {
+        this.config = config;
+        this.baseUrl = config.url ?? '';
+        if (config.insecureTls) {
+            this.insecureDispatcher = new Agent({
+                connect: { rejectUnauthorized: false },
+            });
+        }
+    }
+    async request(method, path, body) {
+        // The credentials are only required here, not at startup, so the server can
+        // still be started and introspected without them.
+        const missing = missingConfigKeys(this.config);
+        if (missing.length > 0) {
+            throw new Error(missingConfigMessage(missing));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.config.apiKey ?? ''}`,
+            Accept: 'application/json',
+        };
+        const init = {
+            method,
+            headers,
+            // Never follow a redirect: it would resend the Authorization header to
+            // whatever host the upstream points at.
+            redirect: 'error',
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        };
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(body);
+        }
+        const url = `${this.baseUrl}${path}`;
+        // The insecure dispatcher requires undici's own fetch; the default path uses
+        // the (stubbable) global fetch so tests can intercept it.
+        const response = this.insecureDispatcher
+            ? await undiciFetch(url, {
+                ...init,
+                dispatcher: this.insecureDispatcher,
+            })
+            : await fetch(url, init);
+        const text = await response.text();
+        if (!response.ok) {
+            throw new AudiobookshelfApiError(response.status, text, method, path);
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        if (contentType.includes('application/json')) {
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+        }
+        return text;
+    }
+    get(path) {
+        return this.request('GET', path);
+    }
+    post(path, body) {
+        return this.request('POST', path, body);
+    }
+    patch(path, body) {
+        return this.request('PATCH', path, body);
+    }
+    delete(path) {
+        return this.request('DELETE', path);
+    }
+}
+/**
+ * Guards an id that ends up in a URL path. Path traversal here would let a
+ * caller reach a different resource — or a different API entirely.
+ *
+ * Audiobookshelf ids are UUIDs on current servers and prefixed slugs
+ * (`li_…`, `lib_…`, `col_…`, `pl_…`, `aut_…`) on older ones; both fit.
+ */
+export function assertPathSegment(value, what) {
+    if (!/^[A-Za-z0-9._-]+$/.test(value) || value === '.' || value === '..') {
+        throw new Error(`invalid ${what}: only letters, digits, dot, underscore and hyphen are allowed`);
+    }
+    return value;
+}
+/**
+ * Builds a query string from defined values only.
+ *
+ * URLSearchParams does the percent-encoding, which matters for the `filter`
+ * parameter: its base64 payload can contain `+`, `/` and `=`.
+ */
+export function query(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        search.set(key, typeof value === 'boolean' ? (value ? '1' : '0') : String(value));
+    }
+    const encoded = search.toString();
+    return encoded ? `?${encoded}` : '';
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+export interface Config {
+    /**
+     * Base URL of the Audiobookshelf instance, e.g. `https://abs.example.com`.
+     * May be undefined together with the API key: the server still starts and
+     * lists its tools, every API call then fails with {@link missingConfigMessage}.
+     */
+    url: string | undefined;
+    apiKey: string | undefined;
+    insecureTls: boolean;
+    readOnly: boolean;
+}
+/** Shown when the configuration is incomplete — at startup and on every API call. */
+export declare function missingConfigMessage(missing: string[]): string;
+/** Names of the required environment variables that are unset in `config`. */
+export declare function missingConfigKeys(config: Config): string[];
+/**
+ * Reads the configuration from environment variables.
+ *
+ * Missing credentials are only a warning, not a fatal error: the server must be
+ * able to complete the MCP handshake and answer `tools/list` without them, so
+ * registries and sandbox inspectors can introspect it. A malformed URL still
+ * exits — that one could send the API key to the wrong host.
+ */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -0,0 +1,78 @@
+/** Shown when the configuration is incomplete — at startup and on every API call. */
+export function missingConfigMessage(missing) {
+    return (`missing required environment variable(s): ${missing.join(', ')}\n` +
+        'Required: AUDIOBOOKSHELF_URL (e.g. https://abs.example.com), AUDIOBOOKSHELF_API_KEY\n' +
+        'Create the API key in Audiobookshelf under Settings → Users → API Keys ' +
+        '(admin only, requires server 2.26.0 or newer).\n' +
+        'Optional: AUDIOBOOKSHELF_READ_ONLY=true to expose only read tools, ' +
+        'AUDIOBOOKSHELF_INSECURE_TLS=true to accept self-signed certificates');
+}
+/** Names of the required environment variables that are unset in `config`. */
+export function missingConfigKeys(config) {
+    return [
+        !config.url && 'AUDIOBOOKSHELF_URL',
+        !config.apiKey && 'AUDIOBOOKSHELF_API_KEY',
+    ].filter((v) => Boolean(v));
+}
+/**
+ * Reads the configuration from environment variables.
+ *
+ * Missing credentials are only a warning, not a fatal error: the server must be
+ * able to complete the MCP handshake and answer `tools/list` without them, so
+ * registries and sandbox inspectors can introspect it. A malformed URL still
+ * exits — that one could send the API key to the wrong host.
+ */
+export function loadConfig(env = process.env) {
+    const url = env.AUDIOBOOKSHELF_URL;
+    const apiKey = env.AUDIOBOOKSHELF_API_KEY;
+    const insecureTls = env.AUDIOBOOKSHELF_INSECURE_TLS === 'true';
+    const readOnly = env.AUDIOBOOKSHELF_READ_ONLY === 'true';
+    const missing = [
+        !url && 'AUDIOBOOKSHELF_URL',
+        !apiKey && 'AUDIOBOOKSHELF_API_KEY',
+    ].filter((v) => Boolean(v));
+    if (missing.length > 0) {
+        console.error(`audiobookshelf-mcp: ${missingConfigMessage(missing)}`);
+    }
+    if (!url) {
+        return { url: undefined, apiKey, insecureTls, readOnly };
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        console.error(`audiobookshelf-mcp: AUDIOBOOKSHELF_URL is not a valid URL: ${url}`);
+        process.exit(1);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        console.error(`audiobookshelf-mcp: AUDIOBOOKSHELF_URL must use http:// or https:// (got ${parsed.protocol})`);
+        process.exit(1);
+    }
+    // Credentials embedded in the URL would end up in logs and error messages.
+    if (parsed.username || parsed.password) {
+        console.error('audiobookshelf-mcp: AUDIOBOOKSHELF_URL must not contain credentials — use AUDIOBOOKSHELF_API_KEY');
+        process.exit(1);
+    }
+    if (parsed.protocol === 'http:' && !isLoopbackHost(parsed.hostname)) {
+        console.error('audiobookshelf-mcp: WARNING: AUDIOBOOKSHELF_URL uses plain http to a non-local host — ' +
+            'the API key will be sent unencrypted. Use https:// instead.');
+    }
+    const config = {
+        url: url.replace(/\/+$/, ''),
+        apiKey,
+        insecureTls,
+        readOnly,
+    };
+    // Don't keep the key in the environment for the process lifetime — it is
+    // visible to child processes and in /proc/<pid>/environ.
+    delete env.AUDIOBOOKSHELF_API_KEY;
+    return config;
+}
+function isLoopbackHost(hostname) {
+    return (hostname === 'localhost' ||
+        hostname.endsWith('.localhost') ||
+        hostname.startsWith('127.') ||
+        hostname === '::1');
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAYA,qFAAqF;AACrF,MAAM,UAAU,oBAAoB,CAAC,OAAiB;IACpD,OAAO,CACL,6CAA6C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACnE,uFAAuF;QACvF,yEAAyE;QACzE,kDAAkD;QAClD,qEAAqE;QACrE,qEAAqE,CACtE,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,OAAO;QACL,CAAC,MAAM,CAAC,GAAG,IAAI,oBAAoB;QACnC,CAAC,MAAM,CAAC,MAAM,IAAI,wBAAwB;KAC3C,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,GAAG,GAAG,GAAG,CAAC,kBAAkB,CAAC;IACnC,MAAM,MAAM,GAAG,GAAG,CAAC,sBAAsB,CAAC;IAC1C,MAAM,WAAW,GAAG,GAAG,CAAC,2BAA2B,KAAK,MAAM,CAAC;IAC/D,MAAM,QAAQ,GAAG,GAAG,CAAC,wBAAwB,KAAK,MAAM,CAAC;IAEzD,MAAM,OAAO,GAAG;QACd,CAAC,GAAG,IAAI,oBAAoB;QAC5B,CAAC,MAAM,IAAI,wBAAwB;KACpC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,KAAK,CAAC,uBAAuB,oBAAoB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;IAC3D,CAAC;IAED,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,KAAK,CACX,8DAA8D,GAAG,EAAE,CACpE,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAChE,OAAO,CAAC,KAAK,CACX,4EAA4E,MAAM,CAAC,QAAQ,GAAG,CAC/F,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,2EAA2E;IAC3E,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACvC,OAAO,CAAC,KAAK,CACX,kGAAkG,CACnG,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpE,OAAO,CAAC,KAAK,CACX,wFAAwF;YACtF,6DAA6D,CAChE,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAW;QACrB,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAC5B,MAAM;QACN,WAAW;QACX,QAAQ;KACT,CAAC;IAEF,yEAAyE;IACzE,yDAAyD;IACzD,OAAO,GAAG,CAAC,sBAAsB,CAAC;IAElC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,cAAc,CAAC,QAAgB;IACtC,OAAO,CACL,QAAQ,KAAK,WAAW;QACxB,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC;QAC/B,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;QAC3B,QAAQ,KAAK,KAAK,CACnB,CAAC;AACJ,CAAC"}

package/dist/confirm.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Issues short-lived confirmation tokens for irreversible operations.
+ *
+ * A plain boolean `confirm` parameter could be set by the model on the very
+ * first call — or be talked into it by instructions hidden in upstream content —
+ * whereas a random token that only ever appears in a *previous* tool result
+ * cannot be guessed. The token is bound to a resource key, so a confirmation for
+ * one target cannot be replayed for another.
+ */
+export declare class ConfirmationStore {
+    private readonly ttlMs;
+    private readonly pending;
+    constructor(ttlMs?: number);
+    /** Creates (or replaces) the pending token for `resource`. */
+    issue(resource: string): string;
+    /**
+     * Returns true and consumes the token when it matches the pending one for
+     * `resource` and has not expired. Tokens are single-use.
+     */
+    consume(resource: string, token: string | undefined): boolean;
+    /** Minutes the issued tokens stay valid, for use in messages. */
+    get ttlMinutes(): number;
+}
+/**
+ * Resource key for an operation on a *set* of targets. Without the fingerprint a
+ * confirmation for ["a.txt"] would also execute ["a.txt", "secrets.env"] — the
+ * model chooses the second list, and only the id would have been checked.
+ */
+export declare function setResourceKey(operation: string, targets: string[]): string;
+/**
+ * Builds the text returned by the first call of a destructive tool.
+ *
+ * Note what is NOT in here: no title, description or filename coming from the
+ * API. Those are attacker-controllable and this string is read by a model.
+ */
+export declare function confirmationPrompt(what: string, token: string, ttlMinutes: number): string;