calibreweb-mcp 0.2.0 → 0.3.1

package/README.md

@@ -1,13 +1,19 @@
 # calibreweb-mcp
 
+<!-- badges: start -->
+
 [![CI](https://img.shields.io/github/actions/workflow/status/ni-c/calibreweb-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/calibreweb-mcp/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ni-c/calibreweb-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/ni-c/calibreweb-mcp)
+<a href="https://socket.dev/npm/package/calibreweb-mcp"><img src="https://socket.dev/api/badge/npm/package/calibreweb-mcp" alt="Socket supply-chain report" height="20"></a>
+[![Glama score](https://glama.ai/mcp/servers/ni-c/calibreweb-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/calibreweb-mcp)
+<br>
 [![npm version](https://img.shields.io/npm/v/calibreweb-mcp)](https://www.npmjs.com/package/calibreweb-mcp)
-[![npm downloads](https://img.shields.io/npm/dm/calibreweb-mcp)](https://www.npmjs.com/package/calibreweb-mcp)
-[![node](https://img.shields.io/node/v/calibreweb-mcp)](https://nodejs.org)
-[![license](https://img.shields.io/npm/l/calibreweb-mcp)](LICENSE)
-[![container](https://img.shields.io/badge/ghcr.io-ni--c%2Fcalibreweb--mcp-blue)](https://github.com/ni-c/calibreweb-mcp/pkgs/container/calibreweb-mcp)
-[![docs](https://img.shields.io/badge/docs-calibreweb--mcp.ni--c.de-informational)](https://calibreweb-mcp.ni-c.de)
+[![container image](https://img.shields.io/badge/ghcr.io-ni--c%2Fcalibreweb--mcp-4f46e5?logo=docker&logoColor=white)](https://github.com/ni-c/calibreweb-mcp/pkgs/container/calibreweb-mcp)
+[![HTTP via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-4f46e5?logo=modelcontextprotocol&logoColor=white)](https://mcp-hub.ni-c.de)
+<br>
+[![docs](https://img.shields.io/badge/docs-calibreweb--mcp.ni--c.de-4f46e5?logo=readthedocs&logoColor=white)](https://calibreweb-mcp.ni-c.de)
 [![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
+<!-- badges: end -->
 
 A read-only [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
 [Calibre-Web](https://github.com/janeczku/calibre-web) (and
@@ -42,6 +48,18 @@ HTTP Basic auth in, structured book data out.
 
 ![Demo: listing the tools, searching the library and reading the stats through the MCP Inspector CLI](https://calibreweb-mcp.ni-c.de/demo.gif)
 
+## What makes it different
+
+**The API Calibre-Web never had.** Calibre-Web exposes no REST API — its only
+stable machine interface is the OPDS Atom feed built for e-reader apps. These
+tools parse that feed into structured book data with numeric ids, per-format
+download URLs and bounded summaries.
+
+**Read-only by construction.** All six tools are GETs. Redirects are refused so
+Basic credentials never travel, XML carrying a DOCTYPE is rejected outright,
+hrefs are locked to the configured origin, and metadata is marked as the
+untrusted data it is.
+
 ## Requirements
 
 - Node.js 22 or newer
@@ -66,6 +84,29 @@ HTTP Basic auth in, structured book data out.
 ¹ Leave **both** unset for an instance that allows anonymous browsing; setting
 only one of them is a configuration error.
 
+### Choosing which tools load
+
+`CALIBRE_WEB_ALLOW_TOOLS` and `CALIBRE_WEB_DENY_TOOLS` take comma-separated tool names;
+a trailing `*` matches a whole family. `essential` is a curated preset of
+five: `search_books`, `list_books`, `list_shelves`, `get_shelf_books`, `get_stats`.
+
+```sh
+CALIBRE_WEB_ALLOW_TOOLS=essential
+CALIBRE_WEB_ALLOW_TOOLS=search_books,list_shelves
+CALIBRE_WEB_DENY_TOOLS=get_cover
+```
+
+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.
+
+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
@@ -103,6 +144,46 @@ args = ["calibreweb-mcp"]
 env = { CALIBRE_WEB_URL = "https://books.example.com", CALIBRE_WEB_USERNAME = "reader", CALIBRE_WEB_PASSWORD = "..." }
 ```
 
+### Docker
+
+```sh
+docker run -i --rm \
+  -e CALIBRE_WEB_URL=https://books.example.com \
+  -e CALIBRE_WEB_USERNAME=reader \
+  -e CALIBRE_WEB_PASSWORD=... \
+  ghcr.io/ni-c/calibreweb-mcp
+```
+
+### Through mcp-hub
+
+A client that cannot spawn a local process — ChatGPT connectors, Claude on the web,
+Cursor, LibreChat — reaches calibreweb-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": {
+    "calibreweb": {
+      "command": "npx",
+      "args": ["-y", "calibreweb-mcp"],
+      "env": { "CALIBRE_WEB_ALLOW_TOOLS": "essential" },
+      "denyTools": ["get_cover"]
+    }
+  }
+}
+```
+
+`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://calibreweb-mcp.ni-c.de/guide/clients#through-mcp-hub).
+
 ## Tools
 
 All tools are read-only (`readOnlyHint: true`).
@@ -120,6 +201,34 @@ Book entries include authors, tags, series (with index), rating, a bounded
 summary, a cover URL and per-format download URLs — ready-made links a human can
 open, since the model itself has no reason to download an EPUB.
 
+### Structured output
+
+Every tool declares an `outputSchema` and answers with `structuredContent`
+alongside the text block, so a client can use the result without parsing prose:
+
+```jsonc
+{
+  "untrusted": true,
+  "source": "calibre-web",
+  "totalFound": 2,
+  "truncated": false,
+  "books": [{ "id": 7, "title": "Dune", "authors": ["Frank Herbert"] }],
+  "notes": ["Book titles, authors, tags, series and summaries come from …"],
+}
+```
+
+The `untrusted` marker is a field and not only a line in `notes`, because a
+client that reads the structured half would otherwise have to find the warning
+in a list of sentences. The two tools without it are `get_stats`, which is four
+counters this server has checked are numbers, and `get_cover`, which reports an
+id, a media type from a four-entry allowlist and a byte count — the image itself
+stays in the content block where a client renders it.
+
+An over-budget result drops book summaries as before. Where that is still not
+enough it is now an **error** rather than JSON cut at the ceiling: unparseable
+text was tolerable in a text block and is not something `structuredContent` can
+carry, and the two channels have to hold the same value.
+
 ### Pagination
 
 Feeds are paginated by the instance's _books per page_ setting (default 60); the
@@ -127,7 +236,7 @@ page size is not client-controllable. Every listing returns
 `pagination.nextOffset` when more pages exist — pass it as `offset` in the next
 call. The `discover` view is a random selection and not paginated.
 
-### Deliberately out of scope
+## Not exposed, on purpose
 
 - **No writes.** The OPDS feed has none, and this server would not add any.
 - **No file downloads.** Tools return download URLs, not ebook payloads.
@@ -151,15 +260,10 @@ call. The `discover` view is a random selection and not paginated.
 - The password is scrubbed from the process environment at startup, and URLs
   are credential-redacted before they appear in any log or result.
 
-## Container
+## Documentation
 
-```sh
-docker run -i --rm \
-  -e CALIBRE_WEB_URL=https://books.example.com \
-  -e CALIBRE_WEB_USERNAME=reader \
-  -e CALIBRE_WEB_PASSWORD=... \
-  ghcr.io/ni-c/calibreweb-mcp
-```
+The full guide, tool reference and security notes live at
+**[calibreweb-mcp.ni-c.de](https://calibreweb-mcp.ni-c.de)** (source in [`docs/`](docs/)).
 
 ## Development
 
@@ -178,27 +282,13 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 2. `npm run lint && npm run test:coverage && npm run build`
 3. Tag the release: `git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z`
 
-## License
-
-[MIT](LICENSE)
+## Contributing
 
-### Choosing which tools load
+Issues, discussions and pull requests are welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md). For vulnerabilities please use
+[private reporting](https://github.com/ni-c/calibreweb-mcp/security/advisories/new)
+rather than a public issue; the policy is in [SECURITY.md](SECURITY.md).
 
-`CALIBRE_WEB_ALLOW_TOOLS` and `CALIBRE_WEB_DENY_TOOLS` take comma-separated tool names;
-a trailing `*` matches a whole family. `essential` is a curated preset of
-five: `search_books`, `list_books`, `list_shelves`, `get_shelf_books`, `get_stats`.
-
-```sh
-CALIBRE_WEB_ALLOW_TOOLS=essential
-CALIBRE_WEB_ALLOW_TOOLS=search_books,list_shelves
-CALIBRE_WEB_DENY_TOOLS=get_cover
-```
-
-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.
+## License
 
-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.
+[MIT](LICENSE) © Willi Thiel

package/dist/api.d.ts

@@ -2,7 +2,11 @@ import { type Config } from './config.js';
 export declare class CalibreWebApiError extends Error {
     readonly status: number;
     readonly body: string;
-    constructor(status: number, body: string, method: string, path: string);
+    /** Set when this answer was repeated from memory rather than requested. */
+    readonly note?: string | undefined;
+    constructor(status: number, body: string, method: string, path: string, 
+    /** Set when this answer was repeated from memory rather than requested. */
+    note?: string | undefined);
 }
 /** Minimal client for the Calibre-Web OPDS endpoints, using HTTP Basic auth. */
 export declare class CalibreWebApi {
@@ -16,10 +20,27 @@ export declare class CalibreWebApi {
      * disabling it process-wide via NODE_TLS_REJECT_UNAUTHORIZED.
      */
     private readonly insecureDispatcher?;
+    /**
+     * The last refused login, until {@link AUTH_REFUSAL_MEMORY_MS} has passed.
+     *
+     * Per process, which is the honest scope: a restart forgets it, and so does
+     * a second server instance.
+     */
+    private authRefusal;
     constructor(config: Config);
     /** Base URL for absolutizing feed hrefs; empty string when unconfigured. */
     get url(): string;
     private send;
+    /**
+     * Decides on the status before a byte of the body is read.
+     *
+     * The other order — read under the success ceiling, then look at `ok` — made
+     * a 401 behind a reverse proxy that answers with a login page report itself
+     * as "returned a response larger than 1048576 bytes and was refused": the
+     * size instead of the status, no hint about the credentials, and none of the
+     * handling that keys on 401 ever running.
+     */
+    private expectOk;
     /** Fetches an OPDS feed and returns the parsed XML document. */
     getFeed(path: string, params?: Record<string, string | number | undefined>): Promise<unknown>;
     /** Fetches a JSON endpoint (`/opds/stats`). */

package/dist/api.js

@@ -17,13 +17,44 @@ const MAX_FEED_BYTES = 8 * 1024 * 1024;
  * an oversized scan is better retrieved out-of-band via the book's coverUrl.
  */
 const MAX_COVER_BYTES = 1 * 1024 * 1024;
+/**
+ * Ceiling on the JSON of `/opds/stats`, which is four counters.
+ *
+ * The feed ceiling was doing this job, and eight megabytes for four numbers is
+ * not a ceiling — it is the absence of one at the scale that matters.
+ */
+const MAX_STATS_BYTES = 64 * 1024;
+/**
+ * Ceiling on an error body, which is read to be quoted and nothing else.
+ *
+ * Separate from the success ceilings on purpose: this reader cuts instead of
+ * refusing, so a reverse proxy answering a 401 with a two-megabyte login page
+ * still surfaces as a 401 with a hint about the credentials.
+ */
+const MAX_ERROR_BODY_BYTES = 64 * 1024;
+/**
+ * How long a refused login is remembered, in milliseconds.
+ *
+ * Calibre-Web's `verify_password` writes `OPDS Login failed for user "%s"
+ * IP-address: %s` at warning level for every refusal — the line fail2ban
+ * filters on — and the rate limiter that would otherwise cap the attempts is
+ * commented out in that function, with no limiter on the OPDS routes at all.
+ * Every tool here is annotated read-only, idempotent and cheap, which is
+ * exactly what a model retries after "check your credentials". One wrong
+ * password should not become a banned address.
+ */
+const AUTH_REFUSAL_MEMORY_MS = 10_000;
 export class CalibreWebApiError extends Error {
     status;
     body;
-    constructor(status, body, method, path) {
+    note;
+    constructor(status, body, method, path, 
+    /** Set when this answer was repeated from memory rather than requested. */
+    note) {
         super(`Calibre-Web ${method} ${path} failed with HTTP ${status}`);
         this.status = status;
         this.body = body;
+        this.note = note;
         this.name = 'CalibreWebApiError';
     }
 }
@@ -67,6 +98,13 @@ export class CalibreWebApi {
      * disabling it process-wide via NODE_TLS_REJECT_UNAUTHORIZED.
      */
     insecureDispatcher;
+    /**
+     * The last refused login, until {@link AUTH_REFUSAL_MEMORY_MS} has passed.
+     *
+     * Per process, which is the honest scope: a restart forgets it, and so does
+     * a second server instance.
+     */
+    authRefusal;
     constructor(config) {
         this.config = config;
         this.baseUrl = config.url ?? '';
@@ -90,6 +128,17 @@ export class CalibreWebApi {
         if (missing.length > 0) {
             throw new Error(missingConfigMessage(missing));
         }
+        const refusal = this.authRefusal;
+        if (refusal !== undefined) {
+            if (Date.now() - refusal.at < AUTH_REFUSAL_MEMORY_MS) {
+                throw new CalibreWebApiError(refusal.status, refusal.body, 'GET', path, 'Repeated from memory: this login was refused less than ' +
+                    `${AUTH_REFUSAL_MEMORY_MS / 1000} seconds ago and was not tried again — ` +
+                    'Calibre-Web logs every refused OPDS login and does not rate-limit ' +
+                    'them, so a retry loop is what gets an address banned. Next attempt ' +
+                    `possible at ${new Date(refusal.at + AUTH_REFUSAL_MEMORY_MS).toISOString()}.`);
+            }
+            this.authRefusal = undefined;
+        }
         const headers = { Accept: accept };
         if (this.authHeader !== undefined) {
             headers.Authorization = this.authHeader;
@@ -128,14 +177,30 @@ export class CalibreWebApi {
             response,
         };
     }
+    /**
+     * Decides on the status before a byte of the body is read.
+     *
+     * The other order — read under the success ceiling, then look at `ok` — made
+     * a 401 behind a reverse proxy that answers with a login page report itself
+     * as "returned a response larger than 1048576 bytes and was refused": the
+     * size instead of the status, no hint about the credentials, and none of the
+     * handling that keys on 401 ever running.
+     */
+    async expectOk(path, result) {
+        if (result.ok)
+            return;
+        const body = await readErrorBody(result.response);
+        if (result.status === 401) {
+            this.authRefusal = { status: 401, body, at: Date.now() };
+        }
+        throw new CalibreWebApiError(result.status, body, 'GET', path);
+    }
     /** Fetches an OPDS feed and returns the parsed XML document. */
     async getFeed(path, params) {
-        const { ok, status, response } = await this.send(path, 'application/atom+xml', params);
-        const bytes = await readBoundedBody(response, path, MAX_FEED_BYTES);
+        const result = await this.send(path, 'application/atom+xml', params);
+        await this.expectOk(path, result);
+        const bytes = await readBoundedBody(result.response, path, MAX_FEED_BYTES);
         const text = bytes.toString('utf8');
-        if (!ok) {
-            throw new CalibreWebApiError(status, text, 'GET', path);
-        }
         const trimmed = text.trimStart();
         if (/^(<!doctype\s+html|<html[\s>])/i.test(trimmed)) {
             throw new Error(`Calibre-Web GET ${path} returned an HTML page instead of an Atom feed — ` +
@@ -152,12 +217,10 @@ export class CalibreWebApi {
     }
     /** Fetches a JSON endpoint (`/opds/stats`). */
     async getJson(path) {
-        const { ok, status, response } = await this.send(path, 'application/json');
-        const bytes = await readBoundedBody(response, path, MAX_FEED_BYTES);
+        const result = await this.send(path, 'application/json');
+        await this.expectOk(path, result);
+        const bytes = await readBoundedBody(result.response, path, MAX_STATS_BYTES);
         const text = bytes.toString('utf8');
-        if (!ok) {
-            throw new CalibreWebApiError(status, text, 'GET', path);
-        }
         try {
             return JSON.parse(text);
         }
@@ -167,12 +230,10 @@ export class CalibreWebApi {
     }
     /** Fetches a binary body (cover images), bounded by {@link MAX_COVER_BYTES}. */
     async getBinary(path) {
-        const { ok, status, headers, response } = await this.send(path, 'image/*');
-        const data = await readBoundedBody(response, path, MAX_COVER_BYTES);
-        if (!ok) {
-            throw new CalibreWebApiError(status, data.toString('utf8'), 'GET', path);
-        }
-        return { data, contentType: headers.get('content-type') ?? '' };
+        const result = await this.send(path, 'image/*');
+        await this.expectOk(path, result);
+        const data = await readBoundedBody(result.response, path, MAX_COVER_BYTES);
+        return { data, contentType: result.headers.get('content-type') ?? '' };
     }
     isConfiguredOrigin(url) {
         try {
@@ -183,6 +244,47 @@ export class CalibreWebApi {
         }
     }
 }
+/**
+ * Reads at most {@link MAX_ERROR_BODY_BYTES} of an error body, and never
+ * throws.
+ *
+ * An error body exists to be quoted in the error message. Refusing to read it
+ * because it is large would replace a status the caller can act on with a size
+ * nobody can, which is the failure this function was written to end.
+ */
+async function readErrorBody(response) {
+    try {
+        const body = response.body;
+        if (!hasStreamingBody(body)) {
+            const buffer = Buffer.from(await response.arrayBuffer());
+            return buffer.subarray(0, MAX_ERROR_BODY_BYTES).toString('utf8');
+        }
+        const reader = body.getReader();
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value === undefined)
+                continue;
+            chunks.push(value);
+            total += value.byteLength;
+            if (total >= MAX_ERROR_BODY_BYTES) {
+                await reader.cancel();
+                break;
+            }
+        }
+        return Buffer.concat(chunks)
+            .subarray(0, MAX_ERROR_BODY_BYTES)
+            .toString('utf8');
+    }
+    catch {
+        // A body that cannot be read is not an error worth replacing the status
+        // with; the status is the answer.
+        return '';
+    }
+}
 function hasStreamingBody(body) {
     return (typeof body === 'object' &&
         body !== null &&

package/dist/config.js

@@ -1,4 +1,4 @@
-import { internalHostKind } from './hosts.js';
+import { internalHostKind } from 'mcp-internal-hosts';
 import { redactUrlCredentials } from './redact.js';
 /** Shown when the configuration is incomplete — at startup and on every API call. */
 export function missingConfigMessage(missing) {
@@ -67,15 +67,18 @@ export function loadConfig(env = process.env) {
         parsed = new URL(url);
     }
     catch {
-        // Redacted, and deliberately so: the userinfo check below only runs once the
-        // URL parses, so a value that does not parse at all but still carries
-        // credentials — "https://admin:s3cret@host:99999", an out-of-range port —
-        // would otherwise print the password into the MCP client's log file.
-        console.error(`calibreweb-mcp: CALIBRE_WEB_URL is not a valid URL: ${redactUrlCredentials(url)}`);
+        // The value that does not parse at all is the one most likely to be the
+        // secret: a password pasted one line too high fails `new URL()`, and
+        // redacting userinfo does nothing for a bare one. Quote it only when it
+        // looks like a URL at all, and describe the rest by length.
+        console.error(`calibreweb-mcp: CALIBRE_WEB_URL is not a valid URL: ${describeValue(url)}`);
         process.exit(1);
     }
     if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-        console.error(`calibreweb-mcp: CALIBRE_WEB_URL must use http:// or https:// (got ${parsed.protocol})`);
+        // Not `(got ${parsed.protocol})`: a 56-character hexadecimal key with a
+        // colon after it is a valid URL whose scheme is the key, and that branch
+        // would print it in full.
+        console.error('calibreweb-mcp: CALIBRE_WEB_URL must use http:// or https://');
         process.exit(1);
     }
     // Credentials embedded in the URL would end up in logs and error messages.
@@ -88,8 +91,17 @@ export function loadConfig(env = process.env) {
         console.error('calibreweb-mcp: WARNING: CALIBRE_WEB_URL uses plain http to a non-local ' +
             'host — the password will be sent unencrypted. Use https:// instead.');
     }
+    if (parsed.search !== '' || parsed.hash !== '') {
+        console.error('calibreweb-mcp: CALIBRE_WEB_URL carried a query string or fragment; ' +
+            'both were dropped — only the origin and path are used.');
+    }
     return {
-        url: url.replace(/\/+$/, ''),
+        // The parsed origin and path, not the environment string: a stray space,
+        // query or fragment in that string was glued in front of every request
+        // path. And the trailing slashes come off with an index walk rather than
+        // `replace(/\/+$/, '')`, which is tried from every position of the run and
+        // took 1.6 seconds on 80 000 of them.
+        url: parsed.origin + trimTrailingSlashes(parsed.pathname),
         username,
         password,
         insecureTls,
@@ -97,6 +109,28 @@ export function loadConfig(env = process.env) {
         denyTools,
     };
 }
+/**
+ * Quotes a configuration value only when it has the shape of a URL.
+ *
+ * `redactUrlCredentials` takes the userinfo out of something that *is* a URL;
+ * it cannot help with a value that is a password, an API token or a path. Those
+ * are described by length instead, which is all a person debugging their
+ * configuration needs.
+ */
+function describeValue(value) {
+    if (!value.includes('://')) {
+        return `a ${value.length}-character value that does not look like a URL`;
+    }
+    const redacted = redactUrlCredentials(value);
+    return redacted.length > 120 ? `${redacted.slice(0, 120)}...` : redacted;
+}
+/** Trailing `/` removed with one walk and one slice. */
+function trimTrailingSlashes(path) {
+    let end = path.length;
+    while (end > 0 && path.charCodeAt(end - 1) === 47)
+        end -= 1;
+    return path.slice(0, end);
+}
 function isLoopbackHost(hostname) {
     // The shared classifier, so every spelling of a loopback address is
     // recognised — including http://[::ffff:127.0.0.1] and 'localhost.' with its

package/dist/index.js

@@ -1,16 +1,19 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { loadConfig } from './config.js';
 import { createServer } from './server.js';
-import { ToolFilterError } from './tool-filter.js';
+import { ToolFilterError } from 'mcp-tool-allowlist';
 async function main() {
     const config = loadConfig();
     if (config.insecureTls) {
         console.error('calibreweb-mcp: CALIBRE_WEB_INSECURE_TLS=true — TLS certificate validation is disabled for the Calibre-Web connection');
     }
-    let server;
+    // Built before anything is served, so a rejected tool filter still ends
+    // the process rather than surfacing as a failed handshake once a client
+    // has already connected.
+    let pending;
     try {
-        server = createServer(config);
+        pending = createServer(config);
     }
     catch (error) {
         // A bad tool list is operator feedback, not a crash: print the
@@ -22,11 +25,28 @@ async function main() {
         throw error;
     }
     // stdout belongs to the protocol; everything human-readable goes to stderr.
-    await server.connect(new StdioServerTransport());
+    // `serveStdio` owns the era decision for the connection: the opening
+    // exchange selects 2025-11-25 or 2026-07-28 and pins one instance from
+    // this factory for its lifetime. A hand-wired `StdioServerTransport`
+    // serves only the 2025 era, which is why a negotiating client’s
+    // `server/discover` probe was answered with "Method not found".
+    //
+    // The instance built above serves the first connection; a second call — a
+    // modern probe followed by the real connection — builds a fresh one, which
+    // is safe because `createServer` only registers tools.
+    serveStdio(() => {
+        const server = pending ?? createServer(config);
+        pending = undefined;
+        return server;
+    });
     console.error(config.url
         ? `calibreweb-mcp: connected, targeting ${config.url}`
         : 'calibreweb-mcp: connected without configuration — tools are listed but every call will fail');
 }
+// In a container node runs as PID 1 with no default signal disposition, so
+// without this handler `docker stop` waits out the grace period and SIGKILLs.
+process.on('SIGTERM', () => process.exit(0));
+process.on('SIGINT', () => process.exit(0));
 main().catch((error) => {
     console.error('calibreweb-mcp: fatal error:', error);
     process.exit(1);

package/dist/redact.js

@@ -5,8 +5,17 @@
  * that is already percent- or XML-encoded is handed back byte-identical when it
  * holds no credentials, and a value that is *not* a valid URL — the case
  * `loadConfig` reports on — still gets redacted.
+ *
+ * The class excludes `/?#` but deliberately not `@`, because userinfo ends at
+ * the *last* `@` before the path, not the first. A password may legitimately
+ * contain one and nothing percent-encodes it on the way in — the audience for
+ * this function are the people who paste `https://user:pass@host` into a config
+ * file. Stopping at the first `@` published the tail of such a password:
+ * `https://alice:p@ssw0rd@host` came back as `https://***@ssw0rd@host`. Not
+ * crossing `/` is what keeps `https://host/users/@alice` untouched, since no
+ * `@` is reachable from the scheme without passing the path.
  */
-const URL_USERINFO = /^([a-z][a-z0-9+.-]*:\/\/)[^/?#@]*@/i;
+const URL_USERINFO = /^([a-z][a-z0-9+.-]*:\/\/)[^/?#]*@/i;
 /**
  * Removes credentials from a URL before it reaches the model or a log.
  *

package/dist/result.d.ts

@@ -1,14 +1,36 @@
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult } from '@modelcontextprotocol/server';
 export declare function textResult(text: string): CallToolResult;
 /**
- * Serializes a result, stripping book summaries if the payload is still
- * pathologically large after the per-tool truncation.
+ * An answer in both channels at once, with book summaries stripped if the
+ * payload is still pathologically large after the per-tool truncation.
  *
  * A Calibre library can hold book descriptions of arbitrary length, and the
  * OPDS search endpoint returns every match in one feed. Everything downstream
  * of this function assumes the budget held; this is what guarantees it.
+ *
+ * `structuredContent` is the machine-readable half and the reason every tool
+ * here declares an `outputSchema`; the text block stays because the SDK does
+ * NOT synthesize one for an object-shaped value, and a client that reads only
+ * `content` would otherwise get an empty answer. Both carry the same object —
+ * which is why the over-budget path rebuilds the *value* rather than editing
+ * its serialization.
  */
-export declare function jsonResult(data: unknown): CallToolResult;
+export declare function jsonResult(data: Record<string, unknown>): CallToolResult;
+/**
+ * {@link jsonResult}, with the untrusted-content marker on the object.
+ *
+ * The note has always gone out in `notes`, which is in the text block and in
+ * the structured half alike. The two fields are what a client reading only
+ * `structuredContent` can *check* rather than have to find in a list of
+ * sentences — and they are stripped from the payload before they are set, so
+ * the guard cannot be switched off by the content it guards against.
+ */
+export declare function untrustedResult(data: Record<string, unknown>): CallToolResult;
+/** Raised by {@link jsonResult}; `run` turns it into an error result. */
+export declare class ResultTooLargeError extends Error {
+}
+/** A value in both channels, with no budget applied. */
+export declare function structuredResult(data: Record<string, unknown>, rendered?: string): CallToolResult;
 export declare function errorResult(text: string): CallToolResult;
 /** Thrown by tools for problems detected before any request goes out. */
 export declare class ToolInputError extends Error {