@hoyongjin/gitbook-mcp 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-06-23
+
+Full GitBook API coverage: the server now exposes **all 345 practical operations**
+(346 of 355 namespaced ops; 8 streaming/trivial carve-outs and 1 root system-info op
+are intentionally not exposed), organized into **config-gated toolsets**.
+
+> **Compatibility:** the original **11 tools keep their exact names and behavior** and
+> are **enabled by default** (in the `core` + `change-requests` toolsets), including
+> `gitbook_merge_change_request`. Upgrading changes the _default_ `tools/list` surface
+> (now ~89 tools: the 11 + the change-request review/merge loop + content reads) and the
+> test/conformance contract, hence the major bump.
+
+### Added
+
+- **Toolsets:** `GITBOOK_TOOLSETS` (CSV of toolset keys, or `all`; unset → `core,change-requests`;
+  unknown key fails closed). Toolsets: `core`, `change-requests`, `collections`, `sites`,
+  `site-ai`, `site-insights`, `integrations`, `data`, `git`, `public`, `org-admin`. Plus
+  `--toolsets` CLI flag.
+- **Destructive opt-in:** `GITBOOK_ALLOW_DESTRUCTIVE` (+ `--allow-destructive`). NEW delete/
+  unpublish/admin operations register only with this opt-in **and** `!readOnly`; the legacy
+  `merge` tool is exempt (back-compat).
+- **Generated tool manifest** (`scripts/generate-manifest.mjs` → `src/tools/manifest.ts`):
+  the single source of truth for the tool surface (counts, namespace, verb, tags, toolset,
+  kind, return shape, path/body params). Re-run with `npm run generate:manifest`; a CI step
+  fails on drift, and a contract test asserts every operation exists on `@gitbook/api`.
+- **Generic invoker + factory:** `GitBookClient.call`/`callList` and a manifest-driven handler
+  factory register every non-bespoke operation uniformly.
+- Generalized URL safety (`isSafeFetchUrl`) now covers git import/export and context-connection
+  URLs (http(s)-only, no embedded credentials), not just `import_content`.
+
+### Changed
+
+- The DNS-rebinding, redaction, resilient-fetch, metrics, audit-log, and read-only guarantees
+  are unchanged and apply to every new tool. `@gitbook/api` is pinned to an exact version
+  (churn guard for the `0.0.1-beta` API).
+
+## [1.0.1] - 2026-06-23
+
+Re-released through CI with **OIDC trusted publishing** (no long-lived token) and a
+signed **provenance** attestation — 1.0.0 was bootstrapped with a local publish and
+is unsigned. **No functional changes**; the code is identical to 1.0.0.
+
 ## [1.0.0] - 2026-06-23
 
 First public release: an MCP server for GitBook exposing **7 read tools** and a
@@ -53,4 +95,6 @@ First public release: an MCP server for GitBook exposing **7 read tools** and a
 > The CI publish job runs on a GitHub Release and requires the `@hoyongjin` scope to
 > be owned by the publishing npm account and an `NPM_TOKEN` secret in the repo.
 
+[2.0.0]: https://github.com/HoYongJin/gitbook-mcp/releases/tag/v2.0.0
+[1.0.1]: https://github.com/HoYongJin/gitbook-mcp/releases/tag/v1.0.1
 [1.0.0]: https://github.com/HoYongJin/gitbook-mcp/releases/tag/v1.0.0

package/README.md

@@ -8,14 +8,15 @@ content and drive a **change-request write workflow**, over **stdio** or
 Built on the official [`@gitbook/api`](https://www.npmjs.com/package/@gitbook/api)
 client and [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) 1.x.
 
-- **11 tools** — 7 read + 4 change-request write (write tools are hidden in read-only mode).
+- **Full API coverage** — ~345 tools across 11 config-gated **toolsets** (default: `core` + `change-requests`; write/destructive tools gated by read-only mode + an opt-in).
 - **Resources** — pages addressable as `gitbook://{spaceId}/{pageId}`.
 - **Two transports** — stdio (local) and streamable HTTP (multi-session, bearer-gated).
 - **Resilient** — request timeouts, bounded retries with full-jitter backoff, rate-limit aware.
 - **Safe** — read-only mode, env-only token, secret redaction, localhost-bound HTTP.
 
-> **Status:** the read path and the change-request write workflow are complete and
-> tested (103 unit/protocol tests). The **stdio** transport is ready for local
+> **Status:** full GitBook API coverage (~345 tools across 11 toolsets), with the
+> original 11 tools enabled by default. Tested with unit, MCP-protocol, and
+> manifest-contract tests. The **stdio** transport is ready for local
 > IDE/CLI use; the **HTTP** transport is hardened for hosted use — bearer auth,
 > DNS-rebinding protection, a session cap + idle reaper, per-IP rate limiting,
 > health/readiness probes, and Prometheus metrics. To publish: push to
@@ -96,7 +97,9 @@ The token is **never** taken from a CLI argument.
 | -------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | `GITBOOK_TOKEN`                        | —                         | **Required.** Personal access token (account-wide privileges).                                                                         |
 | `GITBOOK_ENDPOINT`                     | `https://api.gitbook.com` | API base URL.                                                                                                                          |
-| `GITBOOK_READONLY`                     | `false`                   | Hide all write tools when true.                                                                                                        |
+| `GITBOOK_READONLY`                     | `false`                   | Hide all write/destructive tools when true.                                                                                            |
+| `GITBOOK_TOOLSETS`                     | `core,change-requests`    | Comma-separated toolsets to enable, or `all`. Unset/empty → the default two. Unknown key fails closed. See [Toolsets](#tools).         |
+| `GITBOOK_ALLOW_DESTRUCTIVE`            | `false`                   | Opt-in to register NEW destructive ops (deletes, unpublish, admin removals). The legacy `merge` tool is exempt.                        |
 | `GITBOOK_TRANSPORT`                    | `stdio`                   | `stdio` or `http`.                                                                                                                     |
 | `GITBOOK_HTTP_HOST`                    | `127.0.0.1`               | HTTP bind host.                                                                                                                        |
 | `GITBOOK_HTTP_PORT`                    | `3000`                    | HTTP port.                                                                                                                             |
@@ -114,30 +117,46 @@ The token is **never** taken from a CLI argument.
 | `GITBOOK_MAX_RETRIES`                  | `5`                       | Max retries on 429/5xx/transport errors (0–10).                                                                                        |
 | `GITBOOK_MAX_CONCURRENCY`              | `8`                       | Max concurrent outbound GitBook HTTP requests per instance (1–256).                                                                    |
 
-CLI flags: `--stdio` / `--http` (transport), `--read-only`, `--port <n>`.
+CLI flags: `--stdio` / `--http` (transport), `--read-only`, `--toolsets <csv|all>`,
+`--allow-destructive`, `--port <n>`.
 
 ## Tools
 
-| Tool                             | R/W                     | Purpose                                                      |
-| -------------------------------- | ----------------------- | ------------------------------------------------------------ |
-| `gitbook_whoami`                 | read                    | Authenticated user.                                          |
-| `gitbook_list_orgs`              | read                    | Organizations you can access.                                |
-| `gitbook_list_spaces`            | read                    | Spaces in an org.                                            |
-| `gitbook_get_space`              | read                    | One space by id.                                             |
-| `gitbook_list_pages`             | read                    | Page tree of a space (not paginated).                        |
-| `gitbook_get_page`               | read                    | A page as **markdown** (default) or structured **document**. |
-| `gitbook_search`                 | read                    | Full-text search (org- or space-scoped; exactly one).        |
-| `gitbook_create_change_request`  | write                   | Open a draft change request.                                 |
-| `gitbook_import_content`         | write                   | Import a URL into a space/change-request (AI-enhanced).      |
-| `gitbook_comment_change_request` | write                   | Post a markdown comment on a change request.                 |
-| `gitbook_merge_change_request`   | **write · destructive** | Publish a change request into the live space.                |
-
-Tools that paginate (`list_orgs`, `list_spaces`, `search`) accept `limit` + a
-`cursor`, and return `nextCursor` when more results exist — pass it back to fetch
-the next page.
-
-Typical write flow: `create_change_request` → `import_content` (target that CR) →
-review in GitBook → `merge_change_request`.
+The server covers the **full GitBook API** — ~345 tools — organized into **toolsets**
+you enable with `GITBOOK_TOOLSETS`. By default only **`core` + `change-requests`** are
+on (~89 tools), which keeps `tools/list` small and the model's tool selection sharp.
+Set `GITBOOK_TOOLSETS=all` for everything, or list the ones you need
+(e.g. `GITBOOK_TOOLSETS=core,change-requests,sites`).
+
+Every tool is one API endpoint with its own input schema; read tools are always
+available, write tools need `!readOnly`, and NEW destructive tools (deletes, unpublish,
+admin removals) additionally need `GITBOOK_ALLOW_DESTRUCTIVE=true`.
+
+| Toolset           | Default | Scope                                                                     |
+| ----------------- | :-----: | ------------------------------------------------------------------------- |
+| `core`            |   ✅    | Identity, orgs/spaces/pages reads, search, content + `import_content`.    |
+| `change-requests` |   ✅    | Full CR loop: create, list/diff, reviews, reviewers, comments, **merge**. |
+| `collections`     |         | Collections + collection permissions.                                     |
+| `sites`           |         | Sites, structure, customization, redirects, share links, permissions.     |
+| `site-ai`         |         | Ask AI, agent settings, questions, glossary-adjacent AI.                  |
+| `site-insights`   |         | Analytics/insights, context connections, channels, site MCP servers.      |
+| `integrations`    |         | Integration install/configure/token + space integrations.                 |
+| `data`            |         | OpenAPI specs, translations, glossary, custom fonts, storage.             |
+| `git`             |         | Git Sync: import/export, provider installations, repo/branch listing.     |
+| `public`          |         | URL→content resolution, subdomains, custom hostnames.                     |
+| `org-admin`       |         | **Org members, teams, invites, SSO, permissions** (highest privilege).    |
+
+The **11 original tools keep their exact names** and live in `core` / `change-requests`,
+so existing setups are unchanged. Per-tool parameters are delivered live via each tool's
+MCP description + input schema.
+
+**Excluded carve-outs:** 5 streaming (SSE) AI endpoints, 2 ephemeral PDF-URL generators,
+and a few trivial auth/heartbeat ops are not exposed as tools (the non-streaming AI
+equivalents are).
+
+List tools (`*_list_*`, `search`) accept a `body` with `limit`/`page` and return
+`nextCursor` when more results exist. Typical write flow:
+`create_change_request` → `import_content` (target that CR) → review/diff → `merge_change_request`.
 
 ## Resources
 
@@ -175,7 +194,8 @@ npm install
 npm run typecheck   # tsc on src + test
 npm run lint        # eslint
 npm run format      # prettier --write   (format:check verifies)
-npm test            # vitest — 103 tests across 12 files
+npm test            # vitest — unit + protocol + manifest-contract tests
+npm run generate:manifest  # regenerate src/tools/manifest.ts from @gitbook/api (CI checks drift)
 npm run test:coverage  # + v8 coverage with an 80% gate
 npm run build       # tsc → dist/ (+ chmod the bin)
 ```
@@ -200,10 +220,14 @@ src/
   gitbook/
     client.ts         typed wrapper over @gitbook/api (cursor pagination → {items,nextCursor})
     resilient-fetch.ts timeouts + retry/backoff + concurrency cap; injected as the client's fetch
-    import-url.ts     SSRF guard for import sourceUrl (http(s) only, no credentials)
+    import-url.ts     URL guard for server-side-fetch ops (http(s) only, no credentials)
     errors.ts         HTTP/transport error classification → safe messages
   tools/
-    read.ts write.ts  one registrar each; index.ts gates writes by read-only mode
+    manifest.ts       GENERATED tool surface (one row per API op; source of truth)
+    toolsets.ts       toolset keys + defaults
+    index.ts          manifest-driven registration under toolset/read-only/destructive gates
+    factory.ts        generic handler factory (every non-bespoke op)
+    bespoke.ts        the 11 grandfathered tools (hand-written handlers)
     shared.ts         ToolContext + result/guard helpers + annotation presets
   transports/
     stdio.ts http.ts  the two transports (http: sessions, rate limit, health, metrics)

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import { type ToolsetKey } from "./tools/toolsets.js";
 /**
  * Centralized, validated configuration. Read `process.env` (and a few CLI
  * flags) EXACTLY ONCE, here, into a frozen typed object. Nothing else in the
@@ -14,6 +15,14 @@ export interface Config {
     readonly endpoint: string;
     readonly userAgent: string;
     readonly readOnly: boolean;
+    /** Enabled toolsets (gating groups). Tools outside these are not registered. */
+    readonly enabledToolsets: ReadonlySet<ToolsetKey>;
+    /**
+     * Allow NEW destructive operations (deletes, unpublish, admin removals) to
+     * register. Off by default; the four legacy write tools (incl. merge) are
+     * exempt and remain available under `!readOnly` alone for back-compat.
+     */
+    readonly allowDestructive: boolean;
     readonly transport: Transport;
     readonly http: {
         readonly host: string;

package/dist/config.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { TOOLSET_KEYS, DEFAULT_TOOLSETS } from "./tools/toolsets.js";
 export class ConfigError extends Error {
     name = "ConfigError";
 }
@@ -27,6 +28,10 @@ const EnvSchema = z.object({
     GITBOOK_ENDPOINT: z.string().url().default("https://api.gitbook.com"),
     GITBOOK_USER_AGENT: z.string().min(1).optional(),
     GITBOOK_READONLY: boolish.default(false),
+    // CSV of toolset keys to enable, or "all". Empty/unset → DEFAULT_TOOLSETS.
+    // Validated against TOOLSET_KEYS in resolveToolsets (unknown key → ConfigError).
+    GITBOOK_TOOLSETS: z.string().optional(),
+    GITBOOK_ALLOW_DESTRUCTIVE: boolish.default(false),
     GITBOOK_TRANSPORT: z.enum(["stdio", "http"]).default("stdio"),
     GITBOOK_HTTP_HOST: z.string().min(1).default("127.0.0.1"),
     GITBOOK_HTTP_PORT: z.coerce.number().int().min(1).max(65535).default(3000),
@@ -49,7 +54,26 @@ const EnvSchema = z.object({
     GITBOOK_MAX_RETRIES: z.coerce.number().int().min(0).max(10).default(5),
     GITBOOK_MAX_CONCURRENCY: z.coerce.number().int().min(1).max(256).default(8),
 });
-/** CLI flags that override env (transport selection + read-only safety). */
+/**
+ * Resolve the enabled toolset set from env + CLI. Empty/unset → DEFAULT_TOOLSETS
+ * (back-compat); `all` → every key; any unknown key fails closed with a
+ * ConfigError (a typo must never silently widen or empty the surface).
+ */
+function resolveToolsets(raw, cli) {
+    const tokens = [...csv(raw), ...csv(cli)];
+    if (tokens.length === 0)
+        return new Set(DEFAULT_TOOLSETS);
+    if (tokens.includes("all"))
+        return new Set(TOOLSET_KEYS);
+    const known = new Set(TOOLSET_KEYS);
+    const bad = tokens.filter((t) => !known.has(t));
+    if (bad.length > 0) {
+        throw new ConfigError(`Unknown GITBOOK_TOOLSETS value(s): ${bad.join(", ")}. ` +
+            `Valid: ${TOOLSET_KEYS.join(", ")}, all.`);
+    }
+    return new Set(tokens);
+}
+/** CLI flags that override env (transport selection + read-only safety + toolsets). */
 function parseArgvOverrides(argv) {
     const out = {};
     for (let i = 0; i < argv.length; i++) {
@@ -60,6 +84,16 @@ function parseArgvOverrides(argv) {
             out.transport = "stdio";
         else if (a === "--read-only" || a === "--readonly")
             out.readOnly = true;
+        else if (a === "--allow-destructive")
+            out.allowDestructive = true;
+        else if (a === "--toolsets") {
+            const next = argv[i + 1];
+            if (!next || next.startsWith("--")) {
+                throw new ConfigError("--toolsets requires a comma-separated value (or 'all')");
+            }
+            out.toolsets = next;
+            i++;
+        }
         else if (a === "--port") {
             const next = argv[i + 1];
             const n = next ? Number(next) : NaN;
@@ -89,6 +123,8 @@ export function loadConfig(env = process.env, argv = process.argv.slice(2)) {
         endpoint: e.GITBOOK_ENDPOINT,
         userAgent: e.GITBOOK_USER_AGENT ?? `gitbook-mcp`,
         readOnly: overrides.readOnly ?? e.GITBOOK_READONLY,
+        enabledToolsets: resolveToolsets(e.GITBOOK_TOOLSETS, overrides.toolsets),
+        allowDestructive: overrides.allowDestructive ?? e.GITBOOK_ALLOW_DESTRUCTIVE,
         transport: overrides.transport ?? e.GITBOOK_TRANSPORT,
         http: Object.freeze({
             host: e.GITBOOK_HTTP_HOST,

package/dist/gitbook/client.d.ts

@@ -2,6 +2,7 @@ import { GitBookAPI } from "@gitbook/api";
 import type { ChangeRequest, Comment, ContentImportRun, Organization, RevisionPage, SearchPageResult, SearchSpaceResult, Space, User } from "@gitbook/api";
 import type { Config } from "../config.js";
 import type { Logger } from "../logger.js";
+import type { ApiNamespace } from "../tools/manifest.js";
 /** A single page of a cursor-paginated GitBook list. */
 export interface Page<T> {
     readonly items: T[];
@@ -53,4 +54,18 @@ export declare class GitBookClient {
         revision: string;
         result: "merge" | "conflicts";
     }>;
+    /**
+     * Generic pass-through for the operations not worth a bespoke method. Calls
+     * `api[ns][method](...args)` and unwraps `HttpResponse.data`. Every call still
+     * flows through the injected resilient-fetch (retries/timeout/concurrency,
+     * idempotency-aware) because that lives on the api's serviceBinding — nothing
+     * here bypasses it. The `(ns, method)` pair is manifest-validated and covered
+     * by a contract test, so the not-a-function guard is purely defensive.
+     */
+    call<T = unknown>(ns: ApiNamespace, method: string, args: readonly unknown[]): Promise<T>;
+    /**
+     * Like `call`, but normalizes a cursor-paginated `{ items, next.page }` list
+     * response to `Page<T>`. Only for ops the manifest marks `returnShape:"items"`.
+     */
+    callList<T = unknown>(ns: ApiNamespace, method: string, args: readonly unknown[]): Promise<Page<T>>;
 }

package/dist/gitbook/client.js

@@ -1,5 +1,6 @@
 import { GitBookAPI } from "@gitbook/api";
 import { SERVER_VERSION } from "../version.js";
+import { ToolInputError } from "../tools/shared.js";
 import { createResilientFetch } from "./resilient-fetch.js";
 import { assertSafeImportUrl } from "./import-url.js";
 /**
@@ -106,4 +107,32 @@ export class GitBookClient {
     async mergeChangeRequest(spaceId, changeRequestId) {
         return (await this.api.spaces.mergeChangeRequest(spaceId, changeRequestId)).data;
     }
+    // ── generic invoker (manifest-driven tools) ─────────────────────────────────
+    /**
+     * Generic pass-through for the operations not worth a bespoke method. Calls
+     * `api[ns][method](...args)` and unwraps `HttpResponse.data`. Every call still
+     * flows through the injected resilient-fetch (retries/timeout/concurrency,
+     * idempotency-aware) because that lives on the api's serviceBinding — nothing
+     * here bypasses it. The `(ns, method)` pair is manifest-validated and covered
+     * by a contract test, so the not-a-function guard is purely defensive.
+     */
+    async call(ns, method, args) {
+        const namespace = this.api[ns];
+        const fn = namespace?.[method];
+        if (typeof fn !== "function") {
+            throw new ToolInputError(`Unknown GitBook operation ${ns}.${method}`);
+        }
+        // The client's methods are arrow-function properties (no `this` binding to
+        // preserve), so a spread call is equivalent to apply and accepts readonly args.
+        const res = (await fn(...args));
+        return res.data;
+    }
+    /**
+     * Like `call`, but normalizes a cursor-paginated `{ items, next.page }` list
+     * response to `Page<T>`. Only for ops the manifest marks `returnShape:"items"`.
+     */
+    async callList(ns, method, args) {
+        const data = await this.call(ns, method, args);
+        return { items: data.items, nextCursor: data.next?.page };
+    }
 }

package/dist/gitbook/import-url.d.ts

@@ -1,23 +1,30 @@
 /**
- * Scheme + credential validation for the `gitbook_import_content` source URL.
- * We require http(s) and forbid embedded credentials (`user:pass@`): the former
+ * Scheme + credential validation for any URL we hand to GitBook to fetch
+ * server-side: the `gitbook_import_content` source URL, and (when those toolsets
+ * ship) git import/export URLs and site context-connection website URLs. We
+ * require http(s) and forbid embedded credentials (`user:pass@`): the former
  * blocks non-web schemes (file:, gopher:, …); the latter stops a third-party
  * credential the user pasted into the URL from being echoed back (GitBook
- * returns the source URL in the import run, which the tool surfaces to the model).
+ * returns the source URL in its response, which the tool surfaces to the model).
  *
  * NOTE — this is NOT a full SSRF guard. This process never resolves or fetches
  * the URL; GitBook does, server-side. So protection against internal / loopback
  * / cloud-metadata targets (127.0.0.1, 169.254.169.254, etc.) is GitBook's
  * responsibility, not something a host/IP denylist here could enforce.
  *
- * `isSafeImportUrl` is used as a zod refinement at the tool boundary (so a bad
- * value becomes a clean validation error), and `assertSafeImportUrl` is used in
- * the client as defense-in-depth and to normalize the URL.
+ * `isSafeFetchUrl` is the zod-refinement form (a bad value becomes a clean
+ * validation error); `assertSafeFetchUrl` is the throwing/normalizing form used
+ * in the client as defense-in-depth. `isSafeImportUrl` / `assertSafeImportUrl`
+ * are the import_content-specific aliases kept for back-compat.
  */
 export declare class ImportUrlError extends Error {
     readonly name = "ImportUrlError";
 }
-/** Predicate form for zod `.refine`. Returns false for any unsafe/invalid URL. */
-export declare function isSafeImportUrl(raw: string): boolean;
-/** Throwing/normalizing form for the client. Returns the normalized URL string. */
+/** Predicate form for zod `.refine`. http(s) only, no embedded credentials. */
+export declare function isSafeFetchUrl(raw: string): boolean;
+/** Throwing/normalizing form. `label` names the offending field in errors. */
+export declare function assertSafeFetchUrl(raw: string, label?: string): string;
+/** Back-compat alias used as the `import_content` source-URL zod refinement. */
+export declare const isSafeImportUrl: typeof isSafeFetchUrl;
+/** Back-compat throwing form for `import_content` (labels errors "sourceUrl"). */
 export declare function assertSafeImportUrl(raw: string): string;

package/dist/gitbook/import-url.js

@@ -1,24 +1,27 @@
 /**
- * Scheme + credential validation for the `gitbook_import_content` source URL.
- * We require http(s) and forbid embedded credentials (`user:pass@`): the former
+ * Scheme + credential validation for any URL we hand to GitBook to fetch
+ * server-side: the `gitbook_import_content` source URL, and (when those toolsets
+ * ship) git import/export URLs and site context-connection website URLs. We
+ * require http(s) and forbid embedded credentials (`user:pass@`): the former
  * blocks non-web schemes (file:, gopher:, …); the latter stops a third-party
  * credential the user pasted into the URL from being echoed back (GitBook
- * returns the source URL in the import run, which the tool surfaces to the model).
+ * returns the source URL in its response, which the tool surfaces to the model).
  *
  * NOTE — this is NOT a full SSRF guard. This process never resolves or fetches
  * the URL; GitBook does, server-side. So protection against internal / loopback
  * / cloud-metadata targets (127.0.0.1, 169.254.169.254, etc.) is GitBook's
  * responsibility, not something a host/IP denylist here could enforce.
  *
- * `isSafeImportUrl` is used as a zod refinement at the tool boundary (so a bad
- * value becomes a clean validation error), and `assertSafeImportUrl` is used in
- * the client as defense-in-depth and to normalize the URL.
+ * `isSafeFetchUrl` is the zod-refinement form (a bad value becomes a clean
+ * validation error); `assertSafeFetchUrl` is the throwing/normalizing form used
+ * in the client as defense-in-depth. `isSafeImportUrl` / `assertSafeImportUrl`
+ * are the import_content-specific aliases kept for back-compat.
  */
 export class ImportUrlError extends Error {
     name = "ImportUrlError";
 }
-/** Predicate form for zod `.refine`. Returns false for any unsafe/invalid URL. */
-export function isSafeImportUrl(raw) {
+/** Predicate form for zod `.refine`. http(s) only, no embedded credentials. */
+export function isSafeFetchUrl(raw) {
     let url;
     try {
         url = new URL(raw);
@@ -32,20 +35,26 @@ export function isSafeImportUrl(raw) {
         return false;
     return true;
 }
-/** Throwing/normalizing form for the client. Returns the normalized URL string. */
-export function assertSafeImportUrl(raw) {
+/** Throwing/normalizing form. `label` names the offending field in errors. */
+export function assertSafeFetchUrl(raw, label = "url") {
     let url;
     try {
         url = new URL(raw);
     }
     catch {
-        throw new ImportUrlError("sourceUrl is not a valid URL.");
+        throw new ImportUrlError(`${label} is not a valid URL.`);
     }
     if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new ImportUrlError(`sourceUrl must use http(s); got scheme "${url.protocol.replace(":", "")}".`);
+        throw new ImportUrlError(`${label} must use http(s); got scheme "${url.protocol.replace(":", "")}".`);
     }
     if (url.username !== "" || url.password !== "") {
-        throw new ImportUrlError("sourceUrl must not contain embedded credentials (user:pass@).");
+        throw new ImportUrlError(`${label} must not contain embedded credentials (user:pass@).`);
     }
     return url.toString();
 }
+/** Back-compat alias used as the `import_content` source-URL zod refinement. */
+export const isSafeImportUrl = isSafeFetchUrl;
+/** Back-compat throwing form for `import_content` (labels errors "sourceUrl"). */
+export function assertSafeImportUrl(raw) {
+    return assertSafeFetchUrl(raw, "sourceUrl");
+}

package/dist/tools/bespoke.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolContext } from "./shared.js";
+/**
+ * The 11 original, hand-written tools. They keep their grandfathered names and
+ * bespoke logic (search's orgId-XOR-spaceId guard, import's SSRF refinement,
+ * merge's conflict→isError handling) that the generic factory cannot express.
+ * Each entry registers exactly one tool; the manifest (rows flagged `bespoke`)
+ * drives WHEN they register, under the same toolset/readOnly/destructive gates
+ * as every other tool. Keyed by tool name; `gitbook_search` maps two API ops
+ * (org + space search) to a single tool, so it appears once here.
+ */
+export declare const BESPOKE_TOOLS: Record<string, (server: McpServer, ctx: ToolContext) => void>;

package/dist/tools/bespoke.js

@@ -0,0 +1,166 @@
+import { z } from "zod";
+import { jsonResult, errorResult, guard, READ_ANNOTATIONS, WRITE_ANNOTATIONS, DESTRUCTIVE_ANNOTATIONS, ToolInputError, } from "./shared.js";
+import { isSafeImportUrl } from "../gitbook/import-url.js";
+/** Audit write/destructive tools at info level (invoke + ok lines). */
+const AUDIT = { audit: true };
+const limit = z
+    .number()
+    .int()
+    .min(1)
+    .max(1000)
+    .optional()
+    .describe("Max results to return (server caps apply).");
+const cursor = z
+    .string()
+    .optional()
+    .describe("Pagination cursor from a previous call's nextCursor.");
+/**
+ * The 11 original, hand-written tools. They keep their grandfathered names and
+ * bespoke logic (search's orgId-XOR-spaceId guard, import's SSRF refinement,
+ * merge's conflict→isError handling) that the generic factory cannot express.
+ * Each entry registers exactly one tool; the manifest (rows flagged `bespoke`)
+ * drives WHEN they register, under the same toolset/readOnly/destructive gates
+ * as every other tool. Keyed by tool name; `gitbook_search` maps two API ops
+ * (org + space search) to a single tool, so it appears once here.
+ */
+export const BESPOKE_TOOLS = {
+    gitbook_whoami: (server, ctx) => server.registerTool("gitbook_whoami", {
+        title: "Get authenticated user",
+        description: "Return the GitBook user the configured token authenticates as (id, name, email).",
+        inputSchema: {},
+        annotations: READ_ANNOTATIONS,
+    }, guard(ctx, "gitbook_whoami", async () => jsonResult(await ctx.gitbook.getAuthenticatedUser()))),
+    gitbook_list_orgs: (server, ctx) => server.registerTool("gitbook_list_orgs", {
+        title: "List organizations",
+        description: "List organizations the authenticated user can access. Use the returned id as orgId for other tools.",
+        inputSchema: { limit, cursor },
+        annotations: READ_ANNOTATIONS,
+    }, guard(ctx, "gitbook_list_orgs", async ({ limit, cursor }) => jsonResult(await ctx.gitbook.listOrganizations({ limit, cursor })))),
+    gitbook_list_spaces: (server, ctx) => server.registerTool("gitbook_list_spaces", {
+        title: "List spaces in an organization",
+        description: "List the spaces inside an organization. Get orgId from gitbook_list_orgs.",
+        inputSchema: { orgId: z.string().describe("Organization id."), limit, cursor },
+        annotations: READ_ANNOTATIONS,
+    }, guard(ctx, "gitbook_list_spaces", async ({ orgId, limit, cursor }) => jsonResult(await ctx.gitbook.listSpaces(orgId, { limit, cursor })))),
+    gitbook_get_space: (server, ctx) => server.registerTool("gitbook_get_space", {
+        title: "Get a space",
+        description: "Fetch a single space by id (title, visibility, urls, default revision).",
+        inputSchema: { spaceId: z.string().describe("Space id.") },
+        annotations: READ_ANNOTATIONS,
+    }, guard(ctx, "gitbook_get_space", async ({ spaceId }) => jsonResult(await ctx.gitbook.getSpace(spaceId)))),
+    gitbook_list_pages: (server, ctx) => server.registerTool("gitbook_list_pages", {
+        title: "List pages in a space",
+        description: "List the page tree of a space's current revision (page ids, titles, paths). Not paginated.",
+        inputSchema: { spaceId: z.string().describe("Space id.") },
+        annotations: READ_ANNOTATIONS,
+    }, guard(ctx, "gitbook_list_pages", async ({ spaceId }) => jsonResult({ pages: await ctx.gitbook.listPages(spaceId) }))),
+    gitbook_get_page: (server, ctx) => server.registerTool("gitbook_get_page", {
+        title: "Get a page's content",
+        description: "Read a page by id. format='markdown' (default) returns rendered markdown; format='document' returns GitBook's structured Document JSON.",
+        inputSchema: {
+            spaceId: z.string().describe("Space id."),
+            pageId: z.string().describe("Page id (from gitbook_list_pages)."),
+            format: z
+                .enum(["markdown", "document"])
+                .optional()
+                .describe("Output format (default markdown)."),
+        },
+        annotations: READ_ANNOTATIONS,
+    }, guard(ctx, "gitbook_get_page", async ({ spaceId, pageId, format }) => jsonResult(await ctx.gitbook.getPage(spaceId, pageId, format ?? "markdown")))),
+    gitbook_search: (server, ctx) => server.registerTool("gitbook_search", {
+        title: "Search content",
+        description: "Full-text search. Provide orgId to search an organization, or spaceId to search a single space (exactly one is required).",
+        inputSchema: {
+            query: z.string().min(1).max(512).describe("Search query."),
+            orgId: z.string().optional().describe("Organization id (search org-wide)."),
+            spaceId: z.string().optional().describe("Space id (search one space)."),
+            limit,
+            cursor,
+        },
+        annotations: READ_ANNOTATIONS,
+    }, guard(ctx, "gitbook_search", async ({ query, orgId, spaceId, limit, cursor }) => {
+        if (!orgId && !spaceId) {
+            return errorResult(new ToolInputError("Provide either orgId or spaceId."), ctx.config.token);
+        }
+        if (orgId && spaceId) {
+            return errorResult(new ToolInputError("Provide only one of orgId or spaceId, not both."), ctx.config.token);
+        }
+        const page = spaceId
+            ? await ctx.gitbook.searchSpace(spaceId, query, { limit, cursor })
+            : await ctx.gitbook.searchOrganization(orgId, query, { limit, cursor });
+        return jsonResult(page);
+    })),
+    gitbook_create_change_request: (server, ctx) => server.registerTool("gitbook_create_change_request", {
+        title: "Open a change request",
+        description: "Create a change request (draft branch) on a space. Returns its id to target with gitbook_import_content / gitbook_comment_change_request, then gitbook_merge_change_request to publish.",
+        inputSchema: {
+            spaceId: z.string().describe("Space id."),
+            subject: z.string().optional().describe("Title/subject of the change request."),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, guard(ctx, "gitbook_create_change_request", async ({ spaceId, subject }) => jsonResult(await ctx.gitbook.createChangeRequest(spaceId, subject)), AUDIT)),
+    gitbook_import_content: (server, ctx) => server.registerTool("gitbook_import_content", {
+        title: "Import content into a change request",
+        description: "GitBook's content-write primitive: import a public web page (sourceUrl) into a space — scoped to a change request (and optionally a page), AI-enhanced by default. There is NO direct 'set page body' API; this is the supported write path. The import is asynchronous (returns a run id + status); review in GitBook, then gitbook_merge_change_request to publish.",
+        inputSchema: {
+            orgId: z.string().describe("Organization id that owns the space."),
+            spaceId: z.string().describe("Target space id."),
+            sourceUrl: z
+                .string()
+                .url()
+                .refine(isSafeImportUrl, {
+                message: "sourceUrl must be an http(s) URL with no embedded credentials.",
+            })
+                .describe("Public http(s) URL of the page to import as content (no credentials)."),
+            changeRequestId: z
+                .string()
+                .optional()
+                .describe("Target change request id (recommended — keeps the import off the live branch)."),
+            pageId: z.string().optional().describe("Target page id to import into (optional)."),
+            enhance: z
+                .boolean()
+                .optional()
+                .describe("AI-enhance the imported content (default true)."),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, guard(ctx, "gitbook_import_content", async (args) => jsonResult(await ctx.gitbook.importContent(args)), AUDIT)),
+    gitbook_comment_change_request: (server, ctx) => server.registerTool("gitbook_comment_change_request", {
+        title: "Comment on a change request",
+        description: "Post a markdown comment on a change request (review feedback / notes).",
+        inputSchema: {
+            spaceId: z.string().describe("Space id."),
+            changeRequestId: z.string().describe("Change request id."),
+            body: z.string().min(1).describe("Comment text (markdown)."),
+            page: z.string().optional().describe("Page id to attach the comment to (optional)."),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, guard(ctx, "gitbook_comment_change_request", async ({ spaceId, changeRequestId, body, page }) => jsonResult(await ctx.gitbook.commentOnChangeRequest(spaceId, changeRequestId, body, page)), AUDIT)),
+    gitbook_merge_change_request: (server, ctx) => server.registerTool("gitbook_merge_change_request", {
+        title: "Merge (publish) a change request",
+        description: "Publish a change request into the live space. THIS IS DESTRUCTIVE — it changes the live published docs. Only call after the change request has been reviewed.",
+        inputSchema: {
+            spaceId: z.string().describe("Space id."),
+            changeRequestId: z.string().describe("Change request id to merge."),
+        },
+        annotations: DESTRUCTIVE_ANNOTATIONS,
+    }, guard(ctx, "gitbook_merge_change_request", async ({ spaceId, changeRequestId }) => {
+        const merge = await ctx.gitbook.mergeChangeRequest(spaceId, changeRequestId);
+        // GitBook returns HTTP 200 with result:"conflicts" when it could NOT merge
+        // — the change request is NOT published. Flag it as an error so the model
+        // never mistakes this no-op for a successful publish of the live docs.
+        if (merge.result === "conflicts") {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Merge did NOT publish: the change request has conflicts and remains open. " +
+                            `Resolve them in GitBook, then retry.\n${JSON.stringify(merge, null, 2)}`,
+                    },
+                ],
+                structuredContent: merge,
+                isError: true,
+            };
+        }
+        return jsonResult(merge);
+    }, AUDIT)),
+};