audiobookshelf-mcp 0.1.4 → 0.3.0

package/README.md

@@ -4,20 +4,25 @@
 [![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)
-[![Sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
+[![container](https://img.shields.io/badge/ghcr.io-ni--c%2Faudiobookshelf--mcp-blue)](https://github.com/ni-c/audiobookshelf-mcp/pkgs/container/audiobookshelf-mcp)
+[![docs](https://img.shields.io/badge/docs-audiobookshelf--mcp.ni--c.de-informational)](https://audiobookshelf-mcp.ni-c.de)
+[![HTTP • via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-6f42c1)](https://mcp-hub.ni-c.de)
+[![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
 
-An [MCP](https://modelcontextprotocol.io) server for
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) 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.
+podcast server.
 
-44 tools: 29 read, 15 write.
+Lets MCP clients like Claude Code, Claude Desktop or Codex 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 and 15 write.
 
-📖 **Full documentation: <https://audiobookshelf-mcp.ni-c.de>**
+Forty-four tools is the ceiling, not the floor: `AUDIOBOOKSHELF_ALLOW_TOOLS=essential`
+registers a curated eight instead, and a model picks the right tool far more
+reliably from eight than from forty-four — see
+[choosing which tools load](#choosing-which-tools-load).
 
 <!-- <picture> is resolved against the colour scheme of the page showing it, so GitHub
      picks the variant that matches its own theme toggle. npm strips <picture> and
@@ -31,6 +36,21 @@ keep your listening progress, bookmarks, collections and playlists up to date.
 
 <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">
 
+## What makes it different
+
+**Every response is a projection, not the raw object.** An expanded library item
+carries every audio file, track and chapter with full ffprobe metadata. The media
+tools answer with a compact shape instead, and `detail="full"` is there for when
+the raw object really is what you want.
+
+**Twenty-nine of the forty-four tools only read.** `AUDIOBOOKSHELF_READ_ONLY=true`
+registers those and nothing else, so a write tool is absent from `tools/list`
+rather than refused when it is called.
+
+**The six tools that take something out ask a person first**, through MCP
+elicitation — a dialog the model cannot answer on its behalf, falling back to a
+single-use token bound to the exact targets where the client cannot show one.
+
 ## Requirements
 
 - Node.js 22 or newer
@@ -53,12 +73,39 @@ once, at creation.
 | `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   |
+| `AUDIOBOOKSHELF_ALLOW_TOOLS`  | no       | Comma-separated tool names, `list_*` prefixes, or `essential` for a curated preset      |
+| `AUDIOBOOKSHELF_DENY_TOOLS`   | no       | Same syntax; removed from whatever `AUDIOBOOKSHELF_ALLOW_TOOLS` left                    |
+| `ELICITATION`                 | no       | `false` replaces the approval dialog with the two-call token. **Not prefixed**          |
 
 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
+### Choosing which tools load
+
+`AUDIOBOOKSHELF_ALLOW_TOOLS` and `AUDIOBOOKSHELF_DENY_TOOLS` take comma-separated tool names;
+a trailing `*` matches a whole family. `essential` is a curated preset of
+eight: `list_libraries`, `search_library`, `list_library_items`, `get_library_item`, `get_item_chapters`, `list_items_in_progress`, `get_media_progress`, `set_media_progress`.
+
+```sh
+AUDIOBOOKSHELF_ALLOW_TOOLS=essential
+AUDIOBOOKSHELF_ALLOW_TOOLS=search_library,get_library_item,set_media_progress
+AUDIOBOOKSHELF_DENY_TOOLS=delete_*
+```
+
+An entry that matches no tool aborts startup and names it, so a typo cannot
+silently hide a tool — an absent tool is not something anyone traces back to an
+environment variable. A filtered tool is never registered, so it is absent from
+`tools/list` and unknown to `tools/call` alike, exactly like a write tool under
+`AUDIOBOOKSHELF_READ_ONLY`.
+
+If you run several of these servers at once, [mcp-hub](https://mcp-hub.ni-c.de)
+is the other answer — its `/hub` endpoint replaces every server's tools with six
+meta-tools.
+
+## Installation
+
+### Claude Code
 
 ```sh
 claude mcp add audiobookshelf \
@@ -67,7 +114,9 @@ claude mcp add audiobookshelf \
   -- npx -y audiobookshelf-mcp
 ```
 
-Claude Desktop (`claude_desktop_config.json`):
+### Claude Desktop
+
+`claude_desktop_config.json`:
 
 ```json
 {
@@ -84,7 +133,9 @@ Claude Desktop (`claude_desktop_config.json`):
 }
 ```
 
-Codex (`~/.codex/config.toml`):
+### Codex
+
+`~/.codex/config.toml`:
 
 ```toml
 [mcp_servers.audiobookshelf]
@@ -93,7 +144,9 @@ args = ["-y", "audiobookshelf-mcp"]
 env = { AUDIOBOOKSHELF_URL = "https://abs.example.com", AUDIOBOOKSHELF_API_KEY = "…" }
 ```
 
-Container (multi-arch, with SBOM and build provenance):
+### Docker
+
+Multi-arch, with SBOM and build provenance:
 
 ```sh
 docker run -i --rm \
@@ -107,8 +160,59 @@ 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).
 
+### Through mcp-hub
+
+A client that cannot spawn a local process — ChatGPT connectors, Claude on the web,
+Cursor, LibreChat — reaches audiobookshelf-mcp through [mcp-hub](https://mcp-hub.ni-c.de): one
+container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login
+behind a single password and long-lived tokens for the clients that cannot do OAuth. Its
+`/hub` endpoint puts every server behind six meta-tools, so one connector reaches all of
+them without N×tool schemas in the model's context, and it speaks both protocol revisions
+— a question this server asks travels through it to the person at the far end.
+
+Its `/config/mcp.json` uses Claude Code's format, so the entry is the one you already
+have:
+
+```json
+{
+  "mcpServers": {
+    "audiobookshelf": {
+      "command": "npx",
+      "args": ["-y", "audiobookshelf-mcp"],
+      "env": { "AUDIOBOOKSHELF_ALLOW_TOOLS": "essential" },
+      "denyTools": ["delete_*"]
+    }
+  }
+}
+```
+
+`allowTools` and `denyTools` there are the hub's **own** per-server filter, which is not
+the same thing as `*_ALLOW_TOOLS` in `env` — the difference, and the mistake it invites,
+are in the [client guide](https://audiobookshelf-mcp.ni-c.de/guide/clients#through-mcp-hub).
+
 ## Tools
 
+Every tool declares an `outputSchema` and answers with `structuredContent`
+alongside the text block, so a client can use the result without parsing prose.
+Seven tools that answered with a sentence — _"Collection col_1 deleted."_ — now
+answer with the fields as well.
+
+The tools that report library metadata carry `untrusted: true` and
+`source: "audiobookshelf"` as fields: book descriptions pulled from metadata
+providers, podcast feed summaries and episode titles are all written by someone
+else. The rest are without it — an id this server was given, the account it
+authenticates as, counters the instance keeps about itself.
+
+The documents are described as open objects with the top-level keys this server
+builds. `detail: "full"` hands the API record back whole, so the same tool
+answers with far more keys than it names — and the SDK validates each result
+against its schema before it goes out, which is exactly why a strict shape would
+be wrong here.
+
+`get_personalized_shelves` answers `{items: [...]}` rather than the bare array
+the API sends: a schema whose root is an array is served to a 2025-era client
+rewritten as `{result: …}`, so it would otherwise answer in two shapes.
+
 ### Reading
 
 | Tool                                  | What it does                                                                                        |
@@ -140,23 +244,45 @@ command line, are in the
 
 ### 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                                                     |
+| Tool                                                               | What it does                                                            |
+| ------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| `set_media_progress`                                               | Set position, mark finished or unfinished, hide from Continue Listening |
+| `delete_media_progress` 👤                                         | Delete a progress record — the listening history of that item           |
+| `create_bookmark` / `update_bookmark` / `delete_bookmark` 👤       | Named positions in a book                                               |
+| `create_collection` / `update_collection` / `delete_collection` 👤 | Collections                                                             |
+| `add_books_to_collection` / `remove_books_from_collection` 👤      | Collection membership                                                   |
+| `create_playlist` / `update_playlist` / `delete_playlist` 👤       | Playlists                                                               |
+| `add_items_to_playlist` / `remove_items_from_playlist` 👤          | Playlist membership                                                     |
+
+👤 asks a person through MCP elicitation · falls back to a two-call
+`confirm_token` where the client cannot show a dialog.
 
 ### 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.
+`detail: "full"` for the raw object.
+
+Three bounds, because one is not enough:
+
+- **A response ceiling of 5 MB.** `content-length` is checked before a byte is
+  read and a chunked body is counted while reading, so an oversized answer is
+  refused rather than parsed.
+- **A result ceiling of 100 000 bytes**, applied in `jsonResult` — so it covers
+  `detail: "full"` too. Whole entries are dropped, never characters: a truncated
+  document is not a smaller answer, it is an unparseable one. The result then
+  carries a `truncated` block naming what to call instead.
+- **A cap on embedded members.** A compact collection or playlist embeds the
+  first 25 of its books or entries and reports the real count; `get_collection`
+  and `get_playlist` return the whole membership for one of them.
+
+`list_library_items` pages properly, with `limit` and `page`. Seven listing tools
+have neither — `list_libraries`, `list_authors`, `list_tags`, `list_genres`,
+`list_collections`, `list_playlists` and `list_bookmarks` — because the
+Audiobookshelf routes behind them return everything in one answer and take no
+paging parameters. `library_id` narrows the two collection routes; the rest are
+bounded by the ceilings above.
 
 ### Filtering
 
@@ -171,20 +297,44 @@ filter_group="progress", filter_value="finished" | "in-progress" | "not-started"
 filter_group="issues"    (standalone, no value)
 ```
 
+## Not exposed, on purpose
+
+**No playback.** Pausing, seeking and playing are a session state machine that
+belongs in a real client. `set_media_progress` covers "mark this finished" and
+"jump me to chapter 12"; your phone does the playing.
+
+**No administration, even with an admin key.** There is no tool for user
+management, server settings, backups, cache purging, filesystem browsing, library
+or item deletion, metadata rewriting or file uploads. Those endpoints exist in
+Audiobookshelf; they are simply not wired up here, because the blast radius of a
+confused or manipulated model is bounded by the tool list.
+
 ## 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.
+- **A person is asked, not just told.** The eight tools that can take something
+  out — the three deletes, `delete_bookmark`, `remove_books_from_collection`,
+  `remove_items_from_playlist`, and `update_collection` / `update_playlist` when
+  they are asked to reorder, which replaces an order nobody can reconstruct —
+  raise a real dialog through MCP elicitation,
+  which the model cannot answer on its behalf. 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.
+
+  Where the client cannot show a dialog they fall back to a single-use token
+  bound to the exact targets and expiring after five minutes. That fallback
+  proves the call was made twice with the same arguments and nothing more, and
+  the text says so rather than implying somebody approved. `ELICITATION=false`
+  takes it deliberately; it never removes the guard. See
+  [Asking a person](https://audiobookshelf-mcp.ni-c.de/guide/approval).
+
 - **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.
+  are user-supplied text and are read by a model, so the prompts name ids and
+  counts only.
+- **A 200 that is not JSON is an error.** Returning the body as a string made an
+  SSO portal or a captive proxy in front of the instance look like an empty
+  library rather than like a failure.
 - **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.
@@ -206,11 +356,16 @@ One caveat that comes from Audiobookshelf itself: removing the _last_ entry from
 playlist deletes the playlist. `remove_items_from_playlist` says so in its result
 when it happens.
 
+## Documentation
+
+The full guide, tool reference and security notes live at
+**[audiobookshelf-mcp.ni-c.de](https://audiobookshelf-mcp.ni-c.de)** (source in [`docs/`](docs/)).
+
 ## Development
 
 ```sh
 npm install
-npm run lint          # eslint + prettier --check
+npm run lint          # oxlint + prettier --check
 npm run build         # tsc
 npm test              # vitest
 npm run test:coverage # with thresholds
@@ -261,4 +416,4 @@ rather than a public issue; the policy is in [SECURITY.md](SECURITY.md).
 
 ## License
 
-MIT
+[MIT](LICENSE) © Willi Thiel

package/dist/api.d.ts

@@ -4,6 +4,36 @@ export declare class AudiobookshelfApiError extends Error {
     readonly body: string;
     constructor(status: number, body: string, method: string, path: string);
 }
+/** Thrown when a response is larger than this server is willing to read. */
+export declare class ResponseTooLargeError extends Error {
+    constructor(path: string, limit: number);
+}
+/**
+ * Thrown when a 200 carries something other than JSON.
+ *
+ * Returning the body instead would send an HTML login page into `listFrom`,
+ * which finds neither an array nor an envelope and answers `[]` — so
+ * `list_libraries` reports "you have no libraries" where the truth is that an
+ * SSO portal or a misconfigured reverse proxy answered instead of the API. A
+ * swallowed error replaced by a plausible wrong answer is worse than an error.
+ */
+export declare class UnexpectedContentTypeError extends Error {
+    constructor(path: string, contentType: string);
+}
+export interface RequestOptions {
+    /**
+     * Accept a body that is not JSON.
+     *
+     * Only for the five routes that are known to answer `200 text/plain "OK"`
+     * rather than a document — verified against 2.29.0:
+     * `DELETE /api/collections/{id}`, `DELETE /api/playlists/{id}`,
+     * `PATCH /api/me/progress/{id}`, `DELETE /api/me/progress/{id}` and
+     * `DELETE /api/me/item/{id}/bookmark/{time}`. Every one of them is a mutation
+     * whose caller ignores the value, so the honest thing is to say so at the
+     * call site rather than to weaken the check for everything.
+     */
+    text?: boolean;
+}
 /** Minimal client for the Audiobookshelf REST API. */
 export declare class AudiobookshelfApi {
     private readonly config;
@@ -15,11 +45,11 @@ export declare class AudiobookshelfApi {
      */
     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>;
+    request(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<unknown>;
+    get(path: string, options?: RequestOptions): Promise<unknown>;
+    post(path: string, body?: unknown, options?: RequestOptions): Promise<unknown>;
+    patch(path: string, body?: unknown, options?: RequestOptions): Promise<unknown>;
+    delete(path: string, options?: RequestOptions): Promise<unknown>;
 }
 /**
  * Guards an id that ends up in a URL path. Path traversal here would let a

package/dist/api.js

@@ -1,6 +1,17 @@
 import { Agent, fetch as undiciFetch, } from 'undici';
 import { missingConfigKeys, missingConfigMessage, } from './config.js';
 const REQUEST_TIMEOUT_MS = 15_000;
+/**
+ * Ceiling on a single upstream response.
+ *
+ * Not a theoretical number. `/api/collections` has no pagination at all, and a
+ * collection carries every one of its books expanded — a shared server with
+ * forty collections of three hundred books answers in double-digit megabytes,
+ * and `response.text()` followed by `JSON.parse` holds roughly three copies of
+ * that at once. The documented 95 kB of `/api/me/listening-stats` is the
+ * harmless end of the same range.
+ */
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
 export class AudiobookshelfApiError extends Error {
     status;
     body;
@@ -11,6 +22,74 @@ export class AudiobookshelfApiError extends Error {
         this.name = 'AudiobookshelfApiError';
     }
 }
+/** Thrown when a response is larger than this server is willing to read. */
+export class ResponseTooLargeError extends Error {
+    constructor(path, limit) {
+        super(`the Audiobookshelf response for ${path} exceeds the ` +
+            `${Math.round(limit / 1024 / 1024)} MB ceiling and was not read. ` +
+            'Narrow the request — most listing tools take limit and page, and ' +
+            'library_id restricts a server-wide listing to one library.');
+        this.name = 'ResponseTooLargeError';
+    }
+}
+/**
+ * Thrown when a 200 carries something other than JSON.
+ *
+ * Returning the body instead would send an HTML login page into `listFrom`,
+ * which finds neither an array nor an envelope and answers `[]` — so
+ * `list_libraries` reports "you have no libraries" where the truth is that an
+ * SSO portal or a misconfigured reverse proxy answered instead of the API. A
+ * swallowed error replaced by a plausible wrong answer is worse than an error.
+ */
+export class UnexpectedContentTypeError extends Error {
+    constructor(path, contentType) {
+        super(`Audiobookshelf answered ${path} with "${contentType || 'no content type'}" ` +
+            'instead of JSON. A 200 that is not JSON usually means something in ' +
+            'front of the instance answered instead of the API — an SSO portal, a ' +
+            'captive proxy or a login page. Check AUDIOBOOKSHELF_URL.');
+        this.name = 'UnexpectedContentTypeError';
+    }
+}
+/**
+ * Reads a response body with a hard byte ceiling.
+ *
+ * Both halves matter: `content-length` catches an oversized answer before a
+ * single byte is read, and the streaming count catches a chunked response,
+ * which declares no length at all.
+ */
+async function readCapped(response, maxBytes, allowTruncation) {
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes && !allowTruncation) {
+        // Nothing has been read yet, so the body can simply be discarded.
+        await response.body?.cancel();
+        return { text: '', truncated: true };
+    }
+    const body = response.body;
+    if (!body)
+        return { text: '', truncated: false };
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value === undefined)
+            continue;
+        if (total + value.byteLength > maxBytes) {
+            // `maxBytes - total` is exactly the remaining budget, and the `>` above
+            // makes an exactly-maxBytes response legal rather than truncated.
+            chunks.push(value.subarray(0, maxBytes - total));
+            truncated = true;
+            await reader.cancel();
+            break;
+        }
+        chunks.push(value);
+        total += value.byteLength;
+    }
+    return { text: Buffer.concat(chunks).toString('utf8'), truncated };
+}
 /** Minimal client for the Audiobookshelf REST API. */
 export class AudiobookshelfApi {
     config;
@@ -30,7 +109,7 @@ export class AudiobookshelfApi {
             });
         }
     }
-    async request(method, path, body) {
+    async request(method, path, body, options = {}) {
         // 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);
@@ -62,32 +141,47 @@ export class AudiobookshelfApi {
                 dispatcher: this.insecureDispatcher,
             })
             : await fetch(url, init);
-        const text = await response.text();
+        // An error body is only ever quoted back after `sanitizeErrorBody` cuts it
+        // to 2 000 characters, so truncating it costs nothing and keeps the status
+        // code — which is the diagnostic — instead of replacing it with a size
+        // complaint. A successful body cannot be truncated: half a JSON document is
+        // not a smaller answer.
+        const { text, truncated } = await readCapped(response, MAX_RESPONSE_BYTES, !response.ok);
         if (!response.ok) {
             throw new AudiobookshelfApiError(response.status, text, method, path);
         }
+        if (truncated) {
+            throw new ResponseTooLargeError(path, MAX_RESPONSE_BYTES);
+        }
+        // A body-less success. Several routes answer 200 or 204 with nothing at
+        // all, and "nothing" has no content type to check.
+        if (text.length === 0)
+            return undefined;
+        // A route that is known to answer text. Its caller ignores the value.
+        if (options.text)
+            return text;
         const contentType = response.headers.get('content-type') ?? '';
-        if (contentType.includes('application/json')) {
-            try {
-                return JSON.parse(text);
-            }
-            catch {
-                return text;
-            }
+        if (!contentType.includes('application/json')) {
+            throw new UnexpectedContentTypeError(path, contentType);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new UnexpectedContentTypeError(path, `${contentType} (unparseable)`);
         }
-        return text;
     }
-    get(path) {
-        return this.request('GET', path);
+    get(path, options) {
+        return this.request('GET', path, undefined, options);
     }
-    post(path, body) {
-        return this.request('POST', path, body);
+    post(path, body, options) {
+        return this.request('POST', path, body, options);
     }
-    patch(path, body) {
-        return this.request('PATCH', path, body);
+    patch(path, body, options) {
+        return this.request('PATCH', path, body, options);
     }
-    delete(path) {
-        return this.request('DELETE', path);
+    delete(path, options) {
+        return this.request('DELETE', path, undefined, options);
     }
 }
 /**

package/dist/api.js.map

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

package/dist/config.d.ts

@@ -8,11 +8,41 @@ export interface Config {
     apiKey: string | undefined;
     insecureTls: boolean;
     readOnly: boolean;
+    /**
+     * Whether a client that *can* show a dialog is asked before a guarded tool
+     * acts. `ELICITATION=false` turns the dialog off — the guard stays and falls
+     * back to the two-call token, so there is no setting in which a guarded call
+     * goes unannounced.
+     */
+    elicitation: boolean;
+    /**
+     * Raw value of `AUDIOBOOKSHELF_ALLOW_TOOLS` — comma-separated tool names, `list_*`
+     * prefixes, or `essential`. Kept unparsed on purpose: this file is a mirror of
+     * the environment, and the names can only be checked against the tool
+     * catalogue, which `buildToolFilter` does.
+     */
+    allowTools: string | undefined;
+    /** Raw value of `AUDIOBOOKSHELF_DENY_TOOLS`, same shape, subtracted from the above. */
+    denyTools: string | undefined;
 }
 /** 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 `ELICITATION` — deliberately unprefixed, and deliberately fatal on
+ * anything it does not recognise.
+ *
+ * Unprefixed: environment variables are process-wide, so this is one switch for
+ * every server in the same environment. That is also its risk, which is why a
+ * server started with it off says so on its startup line.
+ *
+ * Fatal: this is the first variable of the family that defaults to *on*. The
+ * others fail open on a typo, which is the safe direction for them. Here a typo
+ * would leave the dialog running while the operator believes it is off — and an
+ * operator who believes that has no way to find out.
+ */
+export declare function parseElicitation(raw: string | undefined): boolean;
 /**
  * Reads the configuration from environment variables.
  *