@hoyongjin/gitbook-mcp 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+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).
+
+## [1.0.0] - 2026-06-23
+
+First public release: an MCP server for GitBook exposing **7 read tools** and a
+**4-tool change-request write workflow** plus a page resource, over **stdio** or
+**Streamable HTTP**. Built on `@gitbook/api` 0.183 and `@modelcontextprotocol/sdk`
+1.29; 103 unit/protocol tests, and verified end-to-end against the built artifact.
+
+### Added
+
+- **Read tools:** `gitbook_whoami`, `gitbook_list_orgs`, `gitbook_list_spaces`,
+  `gitbook_get_space`, `gitbook_list_pages`, `gitbook_get_page` (markdown or
+  structured document), `gitbook_search` (org- or space-scoped — exactly one).
+- **Change-request write tools:** `gitbook_create_change_request`,
+  `gitbook_import_content` (web-URL import; http(s)-only, embedded-credential
+  guard), `gitbook_comment_change_request`, and `gitbook_merge_change_request`
+  (destructive — a `result:"conflicts"` outcome is surfaced as an error because it
+  does not publish). Write tools are **not registered** in read-only mode, so they
+  never appear in `tools/list`.
+- **Resource:** GitBook pages at `gitbook://{spaceId}/{pageId}` (markdown), with the
+  same error-classification + token-redaction guarantees as the tools.
+- **Transports:** stdio (default, local) and Streamable HTTP — per-session
+  server/transport; constant-time bearer auth; DNS-rebinding protection with a
+  configurable public-host allow-list (`GITBOOK_HTTP_ALLOWED_HOSTS` /
+  `GITBOOK_HTTP_ALLOWED_ORIGINS`); loopback-bound by default and fail-closed on a
+  non-loopback bind without an auth token; a bounded session store (cap + idle and
+  absolute-lifetime reapers); per-IP rate limiting; `/healthz` `/livez` `/readyz`
+  probes; and a bearer-gated Prometheus `/metrics`.
+- **Resilience:** per-request timeouts, bounded retries with full-jitter backoff,
+  `Retry-After` / `X-RateLimit-Reset` honored on 429 **and** 5xx, an outbound
+  concurrency limiter, and **idempotency-aware retries** (5xx/timeout retries are
+  suppressed for non-idempotent writes to avoid duplicate change requests, comments,
+  or import runs).
+- **Security:** token read from the environment only (never `argv`); secret
+  redaction across logs, error messages, and tool/resource results; read-only mode;
+  and a token-length floor that keeps every accepted token redactable.
+- **Observability:** in-process Prometheus metrics (tool calls/errors, fetch
+  retries, rate-limit hits, active sessions, resource reads); request-correlation
+  ids stamped on every log line via AsyncLocalStorage; info-level audit logs for
+  write/destructive tools. Logs are JSON to **stderr only** (stdout is the protocol).
+- **Packaging / CI:** npm provenance (`--provenance` + `id-token`) with a resolvable
+  `repository`; a `files` allowlist with no shipped source maps; a release-tag ==
+  `package.json` version guard before publish; Node 20/22 CI
+  (typecheck → lint → format → build → coverage gate → `npm audit`); Dependabot;
+  CodeQL; and a Dockerfile for the HTTP transport.
+
+> Published as `@hoyongjin/gitbook-mcp` from `github.com/HoYongJin/gitbook-mcp`.
+> 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.
+
+[1.0.0]: https://github.com/HoYongJin/gitbook-mcp/releases/tag/v1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,231 @@
+# gitbook-mcp
+
+A **[Model Context Protocol](https://modelcontextprotocol.io) server for GitBook.**
+It lets an MCP host (Claude Code, Claude Desktop, Cursor, …) **read** your GitBook
+content and drive a **change-request write workflow**, over **stdio** or
+**streamable HTTP**.
+
+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).
+- **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
+> 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
+> `github.com/HoYongJin/gitbook-mcp`, ensure your npm account owns the `@hoyongjin`
+> scope, then create a GitHub release (CI publishes to npm with provenance).
+
+---
+
+## ⚠️ What GitBook's API can and cannot write
+
+GitBook's public API has **no direct "edit this page body" endpoint**
+(`createPage`/`updatePage` exist only as the GitBook Assistant's _internal_ tool
+names, not as REST methods). Content authoring goes through:
+
+1. **Change requests** — open a draft (`gitbook_create_change_request`), review, then `gitbook_merge_change_request` to publish.
+2. **Content import** — `gitbook_import_content` imports a **web page URL** into a space/change-request/page, AI-enhanced by default. This is the supported "write content" primitive. Imports are asynchronous, and GitBook exposes no status-poll endpoint.
+3. **Git Sync** — for fine-grained, paragraph-level authoring, connect the space to a Git repo and edit markdown there. _(Out of scope for this server; it is the right path if you need precise prose edits.)_
+
+So this server is **read-rich** with a **coarse, review-gated write** path. It
+cannot rewrite a specific paragraph via the API.
+
+---
+
+## Install
+
+```bash
+# From source (local use):
+cd gitbook-mcp && npm install && npm run build
+# → run with:  node dist/index.js   (or `npm start`)
+
+# Or, once published:
+npx @hoyongjin/gitbook-mcp
+```
+
+> The package is **scoped** to `@hoyongjin/gitbook-mcp` (the unscoped `gitbook-mcp`
+> on npm belongs to a different project). Make sure your npm account owns the
+> `@hoyongjin` scope before publishing.
+
+Create a token at **GitBook → Settings → Developer → Personal access tokens**.
+
+## Configure in your MCP client
+
+### Claude Code
+
+```bash
+# Local build:
+claude mcp add gitbook \
+  --env GITBOOK_TOKEN=gb_api_xxx \
+  -- node /absolute/path/to/gitbook-mcp/dist/index.js
+```
+
+### `.mcp.json` / Claude Desktop config
+
+```json
+{
+  "mcpServers": {
+    "gitbook": {
+      "command": "node",
+      "args": ["/absolute/path/to/gitbook-mcp/dist/index.js"],
+      "env": { "GITBOOK_TOKEN": "gb_api_xxx" }
+    }
+  }
+}
+```
+
+(After publishing, replace `command`/`args` with
+`"command": "npx", "args": ["@hoyongjin/gitbook-mcp"]`.)
+
+Run read-only (recommended unless you need writes) by adding `"--read-only"` to
+`args`, or `"GITBOOK_READONLY": "true"` to `env`.
+
+## Configuration
+
+All configuration is via environment variables (see [`.env.example`](./.env.example)).
+The token is **never** taken from a CLI argument.
+
+| Variable                               | Default                   | Description                                                                                                                            |
+| -------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `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_TRANSPORT`                    | `stdio`                   | `stdio` or `http`.                                                                                                                     |
+| `GITBOOK_HTTP_HOST`                    | `127.0.0.1`               | HTTP bind host.                                                                                                                        |
+| `GITBOOK_HTTP_PORT`                    | `3000`                    | HTTP port.                                                                                                                             |
+| `GITBOOK_HTTP_AUTH_TOKEN`              | —                         | Bearer token required on the HTTP transport.                                                                                           |
+| `GITBOOK_HTTP_MAX_SESSIONS`            | `256`                     | Concurrent-session cap; new initializes past it get 503 (1–100000).                                                                    |
+| `GITBOOK_HTTP_SESSION_TTL_MS`          | `300000`                  | Idle-session reaper TTL (1 000–86 400 000).                                                                                            |
+| `GITBOOK_HTTP_SESSION_MAX_LIFETIME_MS` | `3600000`                 | Absolute session lifetime; reaped regardless of activity.                                                                              |
+| `GITBOOK_HTTP_TRUST_PROXY`             | `false`                   | Trust `X-Forwarded-*` (enable only behind a trusted reverse proxy).                                                                    |
+| `GITBOOK_HTTP_ALLOWED_HOSTS`           | —                         | Comma-separated hosts appended to the DNS-rebinding allow-list. **Required for proxied/non-loopback access** (e.g. `mcp.example.com`). |
+| `GITBOOK_HTTP_ALLOWED_ORIGINS`         | —                         | Comma-separated origins appended to the allow-list (e.g. `https://mcp.example.com`).                                                   |
+| `GITBOOK_HTTP_RATE_LIMIT_WINDOW_MS`    | `60000`                   | Rate-limit window per client IP.                                                                                                       |
+| `GITBOOK_HTTP_RATE_LIMIT_MAX`          | `120`                     | Max `/mcp` requests per window per IP; `0` disables.                                                                                   |
+| `GITBOOK_LOG_LEVEL`                    | `info`                    | `debug`/`info`/`warn`/`error` (logs → stderr).                                                                                         |
+| `GITBOOK_TIMEOUT_MS`                   | `30000`                   | Per-request timeout (1 000–120 000).                                                                                                   |
+| `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>`.
+
+## 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`.
+
+## Resources
+
+Pages are exposed as resources at `gitbook://{spaceId}/{pageId}` (rendered as
+markdown). Enumeration is intentionally not provided — discover page ids via
+`gitbook_list_pages` / `gitbook_search`, then read by URI.
+
+## Transports
+
+- **stdio** (default): one server per process; the token stays in-process. Best
+  for local IDE/CLI integrations.
+- **streamable HTTP** (`--http`): one MCP session per `mcp-session-id`. Binds to
+  `127.0.0.1`, enables DNS-rebinding protection (Host/Origin allow-lists), and —
+  when `GITBOOK_HTTP_AUTH_TOKEN` is set — requires a constant-time-compared bearer
+  token on every request. Binding to a non-loopback host **without** an auth token
+  is refused (fail-closed). Sessions are capped and idle-reaped; the `/mcp`
+  endpoint is per-IP rate-limited. Operational endpoints: `GET /healthz` `/livez`
+  `/readyz` (unauthenticated probes) and `GET /metrics` (Prometheus; bearer-gated
+  when an auth token is set). Behind a TLS-terminating reverse proxy, set
+  `GITBOOK_HTTP_TRUST_PROXY=true` **and** `GITBOOK_HTTP_ALLOWED_HOSTS=<your-public-host>`
+  — DNS-rebinding protection matches the exact `Host` header, so a proxied or
+  non-loopback deployment (including the Docker image, which binds `0.0.0.0`) must
+  add its public host(s) or every request is rejected with 403 `Invalid Host`. A
+  [`Dockerfile`](./Dockerfile) is provided. See [`SECURITY.md`](./SECURITY.md).
+
+```bash
+GITBOOK_TOKEN=… GITBOOK_HTTP_AUTH_TOKEN=… gitbook-mcp --http --port 3000
+# → POST/GET/DELETE http://127.0.0.1:3000/mcp   ·   GET /healthz   ·   GET /metrics
+```
+
+## Development
+
+```bash
+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 run test:coverage  # + v8 coverage with an 80% gate
+npm run build       # tsc → dist/ (+ chmod the bin)
+```
+
+CI (`.github/workflows/ci.yml`) runs `npm audit` → typecheck → lint → format:check
+→ build → coverage on Node 20 & 22, then asserts a clean `git diff`. CodeQL and
+Dependabot run separately.
+
+## Architecture
+
+```
+src/
+  index.ts            launcher: load config → pick transport → graceful shutdown
+  config.ts           zod-validated env + CLI overrides (frozen Config)
+  logger.ts           structured stderr logging + secret redaction + correlation
+  request-context.ts  AsyncLocalStorage requestId/tool (log correlation)
+  metrics.ts          in-process Prometheus registry (served at /metrics)
+  limiter.ts          async concurrency semaphore (outbound rate control)
+  server.ts           createServer(): McpServer factory (tools + resources)
+  resources.ts        gitbook://{spaceId}/{pageId}
+  version.ts          stable SERVER_NAME + runtime SERVER_VERSION (from package.json)
+  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)
+    errors.ts         HTTP/transport error classification → safe messages
+  tools/
+    read.ts write.ts  one registrar each; index.ts gates writes by read-only mode
+    shared.ts         ToolContext + result/guard helpers + annotation presets
+  transports/
+    stdio.ts http.ts  the two transports (http: sessions, rate limit, health, metrics)
+```
+
+For agent-facing contributor conventions and the dependency gotchas below, see
+[`CLAUDE.md`](./CLAUDE.md).
+
+### Notes / gotchas (pinned to @gitbook/api 0.183.0)
+
+- **tsconfig uses `moduleResolution: "Bundler"`**, not `NodeNext`. `@gitbook/api`
+  0.183 ships a `.d.ts` that re-exports with extensionless relative specifiers
+  (`export * from './client'`); under NodeNext those don't resolve and the entire
+  client surface (and the `GitBookAPI` namespace members) silently disappears.
+  Bundler resolution accepts them, giving full typing with no facade. Internal
+  imports use explicit `.js` extensions so the emitted ESM runs on Node.
+- **Import runs live under the singular `client.org` namespace**, not the plural
+  `client.orgs` (which holds list/search). They are different runtime objects.
+- **`gitbook_get_page` markdown vs document**: `format=markdown` returns rendered
+  markdown; `format=document` returns GitBook's structured Document JSON.
+- Node ≥ 20 (global `fetch`, `AbortSignal.any`).
+
+## License
+
+[MIT](./LICENSE)

package/dist/config.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Centralized, validated configuration. Read `process.env` (and a few CLI
+ * flags) EXACTLY ONCE, here, into a frozen typed object. Nothing else in the
+ * codebase should touch `process.env`.
+ *
+ * Security: the GitBook token is accepted ONLY via the environment, never a
+ * CLI argument — process arguments leak through `ps`, `/proc`, and shell
+ * history. (GitHub's and Notion's official MCP servers do the same.)
+ */
+export type Transport = "stdio" | "http";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface Config {
+    readonly token: string;
+    readonly endpoint: string;
+    readonly userAgent: string;
+    readonly readOnly: boolean;
+    readonly transport: Transport;
+    readonly http: {
+        readonly host: string;
+        readonly port: number;
+        /** Optional bearer token required on the HTTP transport (undefined = none). */
+        readonly authToken: string | undefined;
+        /** Hard cap on concurrent MCP sessions; new initializes past it are rejected (503). */
+        readonly maxSessions: number;
+        /** Idle session time-to-live in ms; sessions idle longer are reaped. */
+        readonly sessionIdleTtlMs: number;
+        /** Absolute session lifetime in ms; sessions older than this are reaped regardless of activity. */
+        readonly sessionMaxLifetimeMs: number;
+        /** Trust X-Forwarded-* (set true only behind a trusted reverse proxy). */
+        readonly trustProxy: boolean;
+        /**
+         * Extra entries appended to the DNS-rebinding Host allow-list, matched against
+         * the full incoming `Host` header (e.g. "mcp.example.com" or "mcp.example.com:8080").
+         * REQUIRED for proxied/non-loopback access: the derived list only covers the
+         * bind host + loopback, so a public hostname must be added here or every
+         * request is rejected with 403 "Invalid Host header".
+         */
+        readonly allowedHosts: readonly string[];
+        /** Extra entries appended to the DNS-rebinding Origin allow-list (e.g. "https://mcp.example.com"). */
+        readonly allowedOrigins: readonly string[];
+        readonly rateLimit: {
+            readonly windowMs: number;
+            /** Max requests per window per client IP; 0 disables rate limiting. */
+            readonly max: number;
+        };
+    };
+    readonly logLevel: LogLevel;
+    readonly request: {
+        readonly timeoutMs: number;
+        readonly maxRetries: number;
+        /** Max concurrent outbound GitBook requests per instance (bounds initiation→headers, not body transfer). */
+        readonly maxConcurrency: number;
+    };
+}
+export declare class ConfigError extends Error {
+    readonly name = "ConfigError";
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv, argv?: readonly string[]): Config;

package/dist/config.js

@@ -0,0 +1,115 @@
+import { z } from "zod";
+export class ConfigError extends Error {
+    name = "ConfigError";
+}
+/** Coerce common truthy/falsy env strings to a boolean. */
+const boolish = z.union([z.boolean(), z.string()]).transform((v) => {
+    if (typeof v === "boolean")
+        return v;
+    return ["1", "true", "yes", "on"].includes(v.trim().toLowerCase());
+});
+/** Split a comma-separated env value into a trimmed, non-empty list. */
+const csv = (v) => v
+    ? v
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0)
+    : [];
+const EnvSchema = z.object({
+    GITBOOK_TOKEN: z
+        .string({ message: "GITBOOK_TOKEN is required" })
+        .trim()
+        // Floor matches redactSecret's >=6 guard (logger.ts) so EVERY accepted token
+        // is always redactable — there is no length window where the literal token
+        // would pass config yet be exempt from log/error scrubbing. Real GitBook
+        // tokens are far longer (gb_api_… + 40+ chars), so this rejects nothing real.
+        .min(6, "GITBOOK_TOKEN looks too short to be a valid GitBook token"),
+    GITBOOK_ENDPOINT: z.string().url().default("https://api.gitbook.com"),
+    GITBOOK_USER_AGENT: z.string().min(1).optional(),
+    GITBOOK_READONLY: 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),
+    GITBOOK_HTTP_AUTH_TOKEN: z.string().min(1).optional(),
+    GITBOOK_HTTP_MAX_SESSIONS: z.coerce.number().int().min(1).max(100000).default(256),
+    GITBOOK_HTTP_SESSION_TTL_MS: z.coerce.number().int().min(1000).max(86400000).default(300000),
+    GITBOOK_HTTP_SESSION_MAX_LIFETIME_MS: z.coerce
+        .number()
+        .int()
+        .min(1000)
+        .max(86400000)
+        .default(3600000),
+    GITBOOK_HTTP_TRUST_PROXY: boolish.default(false),
+    GITBOOK_HTTP_ALLOWED_HOSTS: z.string().optional(),
+    GITBOOK_HTTP_ALLOWED_ORIGINS: z.string().optional(),
+    GITBOOK_HTTP_RATE_LIMIT_WINDOW_MS: z.coerce.number().int().min(1000).max(3600000).default(60000),
+    GITBOOK_HTTP_RATE_LIMIT_MAX: z.coerce.number().int().min(0).max(1000000).default(120),
+    GITBOOK_LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+    GITBOOK_TIMEOUT_MS: z.coerce.number().int().min(1000).max(120000).default(30000),
+    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). */
+function parseArgvOverrides(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--http")
+            out.transport = "http";
+        else if (a === "--stdio")
+            out.transport = "stdio";
+        else if (a === "--read-only" || a === "--readonly")
+            out.readOnly = true;
+        else if (a === "--port") {
+            const next = argv[i + 1];
+            const n = next ? Number(next) : NaN;
+            if (Number.isInteger(n) && n >= 1 && n <= 65535) {
+                out.port = n;
+                i++;
+            }
+            else {
+                throw new ConfigError(`--port requires an integer 1-65535 (got "${next ?? ""}")`);
+            }
+        }
+    }
+    return out;
+}
+export function loadConfig(env = process.env, argv = process.argv.slice(2)) {
+    const parsed = EnvSchema.safeParse(env);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("\n");
+        throw new ConfigError(`Invalid configuration:\n${issues}`);
+    }
+    const e = parsed.data;
+    const overrides = parseArgvOverrides(argv);
+    return Object.freeze({
+        token: e.GITBOOK_TOKEN,
+        endpoint: e.GITBOOK_ENDPOINT,
+        userAgent: e.GITBOOK_USER_AGENT ?? `gitbook-mcp`,
+        readOnly: overrides.readOnly ?? e.GITBOOK_READONLY,
+        transport: overrides.transport ?? e.GITBOOK_TRANSPORT,
+        http: Object.freeze({
+            host: e.GITBOOK_HTTP_HOST,
+            port: overrides.port ?? e.GITBOOK_HTTP_PORT,
+            authToken: e.GITBOOK_HTTP_AUTH_TOKEN,
+            maxSessions: e.GITBOOK_HTTP_MAX_SESSIONS,
+            sessionIdleTtlMs: e.GITBOOK_HTTP_SESSION_TTL_MS,
+            sessionMaxLifetimeMs: e.GITBOOK_HTTP_SESSION_MAX_LIFETIME_MS,
+            trustProxy: e.GITBOOK_HTTP_TRUST_PROXY,
+            allowedHosts: Object.freeze(csv(e.GITBOOK_HTTP_ALLOWED_HOSTS)),
+            allowedOrigins: Object.freeze(csv(e.GITBOOK_HTTP_ALLOWED_ORIGINS)),
+            rateLimit: Object.freeze({
+                windowMs: e.GITBOOK_HTTP_RATE_LIMIT_WINDOW_MS,
+                max: e.GITBOOK_HTTP_RATE_LIMIT_MAX,
+            }),
+        }),
+        logLevel: e.GITBOOK_LOG_LEVEL,
+        request: Object.freeze({
+            timeoutMs: e.GITBOOK_TIMEOUT_MS,
+            maxRetries: e.GITBOOK_MAX_RETRIES,
+            maxConcurrency: e.GITBOOK_MAX_CONCURRENCY,
+        }),
+    });
+}

package/dist/gitbook/client.d.ts

@@ -0,0 +1,56 @@
+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";
+/** A single page of a cursor-paginated GitBook list. */
+export interface Page<T> {
+    readonly items: T[];
+    /** Opaque cursor for the next page; absent on the last page. */
+    readonly nextCursor: string | undefined;
+}
+export interface ListParams {
+    limit?: number;
+    cursor?: string;
+}
+export interface ImportContentParams {
+    orgId: string;
+    spaceId: string;
+    sourceUrl: string;
+    changeRequestId?: string;
+    pageId?: string;
+    enhance?: boolean;
+}
+export type PageFormat = "markdown" | "document";
+/**
+ * Thin, typed, resilient wrapper over @gitbook/api. Exposes only the domain
+ * operations the MCP tools need, normalizes cursor pagination, and centralizes
+ * the namespace gotchas (import runs live on the SINGULAR `org`; list/search on
+ * the PLURAL `orgs`). Inject a mock in tests.
+ */
+export declare class GitBookClient {
+    private readonly api;
+    constructor(config: Config, logger: Logger, 
+    /** Test seam: override the underlying client (e.g. a stub). */
+    api?: GitBookAPI);
+    getAuthenticatedUser(): Promise<User>;
+    listOrganizations(params?: ListParams): Promise<Page<Organization>>;
+    listSpaces(orgId: string, params?: ListParams): Promise<Page<Space>>;
+    getSpace(spaceId: string): Promise<Space>;
+    /** Page tree of the space's current revision. NOT paginated (no cursor). */
+    listPages(spaceId: string): Promise<RevisionPage[]>;
+    getPage(spaceId: string, pageId: string, format: PageFormat): Promise<RevisionPage>;
+    searchOrganization(orgId: string, query: string, params?: ListParams): Promise<Page<SearchSpaceResult>>;
+    searchSpace(spaceId: string, query: string, params?: ListParams): Promise<Page<SearchPageResult>>;
+    createChangeRequest(spaceId: string, subject?: string): Promise<ChangeRequest>;
+    /**
+     * GitBook's content-write primitive. Import runs are async and live on the
+     * SINGULAR `org` namespace. Returns the initial ContentImportRun (status
+     * pending/in-progress); GitBook exposes no poll endpoint.
+     */
+    importContent(params: ImportContentParams): Promise<ContentImportRun>;
+    commentOnChangeRequest(spaceId: string, changeRequestId: string, markdown: string, page?: string): Promise<Comment>;
+    mergeChangeRequest(spaceId: string, changeRequestId: string): Promise<{
+        revision: string;
+        result: "merge" | "conflicts";
+    }>;
+}

package/dist/gitbook/client.js

@@ -0,0 +1,109 @@
+import { GitBookAPI } from "@gitbook/api";
+import { SERVER_VERSION } from "../version.js";
+import { createResilientFetch } from "./resilient-fetch.js";
+import { assertSafeImportUrl } from "./import-url.js";
+/**
+ * Thin, typed, resilient wrapper over @gitbook/api. Exposes only the domain
+ * operations the MCP tools need, normalizes cursor pagination, and centralizes
+ * the namespace gotchas (import runs live on the SINGULAR `org`; list/search on
+ * the PLURAL `orgs`). Inject a mock in tests.
+ */
+export class GitBookClient {
+    api;
+    constructor(config, logger, 
+    /** Test seam: override the underlying client (e.g. a stub). */
+    api) {
+        this.api =
+            api ??
+                new GitBookAPI({
+                    authToken: config.token,
+                    endpoint: config.endpoint,
+                    userAgent: `${config.userAgent}/${SERVER_VERSION}`,
+                    // The 0.183 client wraps `serviceBinding.fetch`; injecting our
+                    // resilient fetch here gives retries+timeouts to every method.
+                    serviceBinding: {
+                        fetch: createResilientFetch({
+                            timeoutMs: config.request.timeoutMs,
+                            maxRetries: config.request.maxRetries,
+                            maxConcurrency: config.request.maxConcurrency,
+                            logger: logger.child({ component: "gitbook-fetch" }),
+                        }),
+                    },
+                });
+    }
+    // ── reads ──────────────────────────────────────────────────────────────────
+    async getAuthenticatedUser() {
+        return (await this.api.user.getAuthenticatedUser()).data;
+    }
+    async listOrganizations(params = {}) {
+        const res = await this.api.orgs.listOrganizationsForAuthenticatedUser({
+            limit: params.limit,
+            page: params.cursor,
+        });
+        return { items: res.data.items, nextCursor: res.data.next?.page };
+    }
+    async listSpaces(orgId, params = {}) {
+        const res = await this.api.orgs.listSpacesInOrganizationById(orgId, {
+            limit: params.limit,
+            page: params.cursor,
+        });
+        return { items: res.data.items, nextCursor: res.data.next?.page };
+    }
+    async getSpace(spaceId) {
+        return (await this.api.spaces.getSpaceById(spaceId)).data;
+    }
+    /** Page tree of the space's current revision. NOT paginated (no cursor). */
+    async listPages(spaceId) {
+        return (await this.api.spaces.listPages(spaceId)).data.pages;
+    }
+    async getPage(spaceId, pageId, format) {
+        return (await this.api.spaces.getPageById(spaceId, pageId, { format })).data;
+    }
+    async searchOrganization(orgId, query, params = {}) {
+        const res = await this.api.orgs.searchOrganizationContent(orgId, {
+            query,
+            limit: params.limit,
+            page: params.cursor,
+        });
+        return { items: res.data.items, nextCursor: res.data.next?.page };
+    }
+    async searchSpace(spaceId, query, params = {}) {
+        const res = await this.api.spaces.searchSpaceContent(spaceId, {
+            query,
+            limit: params.limit,
+            page: params.cursor,
+        });
+        return { items: res.data.items, nextCursor: res.data.next?.page };
+    }
+    // ── writes (change-request workflow) ────────────────────────────────────────
+    async createChangeRequest(spaceId, subject) {
+        return (await this.api.spaces.createChangeRequest(spaceId, subject ? { subject } : {})).data;
+    }
+    /**
+     * GitBook's content-write primitive. Import runs are async and live on the
+     * SINGULAR `org` namespace. Returns the initial ContentImportRun (status
+     * pending/in-progress); GitBook exposes no poll endpoint.
+     */
+    async importContent(params) {
+        return (await this.api.org.startImportRun(params.orgId, {
+            // Scheme/credential validation + normalize: http(s) only, reject embedded
+            // credentials. (Internal-target/SSRF protection is GitBook-side; it performs the fetch.)
+            source: { type: "website", url: assertSafeImportUrl(params.sourceUrl) },
+            target: {
+                space: params.spaceId,
+                changeRequest: params.changeRequestId,
+                page: params.pageId,
+            },
+            enhance: params.enhance ?? true,
+        })).data;
+    }
+    async commentOnChangeRequest(spaceId, changeRequestId, markdown, page) {
+        return (await this.api.spaces.postCommentInChangeRequest(spaceId, changeRequestId, {
+            body: { markdown },
+            ...(page ? { page } : {}),
+        })).data;
+    }
+    async mergeChangeRequest(spaceId, changeRequestId) {
+        return (await this.api.spaces.mergeChangeRequest(spaceId, changeRequestId)).data;
+    }
+}