@hoyongjin/gitbook-mcp 1.0.0

package/dist/metrics.js

@@ -0,0 +1,71 @@
+/**
+ * Minimal in-process metrics — no external dependency. A single process-global
+ * registry, scraped via `GET /metrics` on the HTTP transport in Prometheus text
+ * exposition format. Counters are monotonic; gauges can move both ways.
+ *
+ * Tool/fetch/transport code increments via the exported `metrics` singleton.
+ * Tests call `metrics.reset()` in a `beforeEach` to isolate. Label values are
+ * only ever fixed identifiers we control (tool names, error kinds, retry
+ * reasons), so they need no escaping; we still reject characters that would
+ * break the exposition format defensively.
+ */
+const NAME_RE = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;
+function sanitizeLabelValue(value) {
+    // Escape backslash, double-quote, and newline per the Prometheus text format.
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+function seriesKey(name, labels) {
+    if (!labels)
+        return name;
+    const keys = Object.keys(labels).sort();
+    if (keys.length === 0)
+        return name;
+    const inner = keys.map((k) => `${k}="${sanitizeLabelValue(labels[k] ?? "")}"`).join(",");
+    return `${name}{${inner}}`;
+}
+class Metrics {
+    series = new Map();
+    /** Increment a monotonic counter (default by 1). */
+    inc(name, labels, by = 1) {
+        if (!NAME_RE.test(name))
+            return;
+        const key = seriesKey(name, labels);
+        const existing = this.series.get(key);
+        if (existing)
+            existing.value += by;
+        else
+            this.series.set(key, { name, type: "counter", value: by });
+    }
+    /** Set a gauge to an absolute value. */
+    setGauge(name, value, labels) {
+        if (!NAME_RE.test(name))
+            return;
+        const key = seriesKey(name, labels);
+        const existing = this.series.get(key);
+        if (existing)
+            existing.value = value;
+        else
+            this.series.set(key, { name, type: "gauge", value });
+    }
+    /** Render the registry in Prometheus text exposition format. */
+    render() {
+        // Emit one HELP/TYPE per metric name (not per series), then the series.
+        const typesByName = new Map();
+        for (const s of this.series.values())
+            typesByName.set(s.name, s.type);
+        const lines = [];
+        for (const [name, type] of typesByName) {
+            lines.push(`# TYPE ${name} ${type}`);
+            for (const [key, s] of this.series) {
+                if (s.name === name)
+                    lines.push(`${key} ${s.value}`);
+            }
+        }
+        return lines.length ? `${lines.join("\n")}\n` : "";
+    }
+    /** Test seam: clear all series. */
+    reset() {
+        this.series.clear();
+    }
+}
+export const metrics = new Metrics();

package/dist/request-context.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Per-request correlation, threaded implicitly via AsyncLocalStorage so we do
+ * not have to plumb a request id through every function signature. The logger
+ * reads the active context and stamps `requestId` (and `tool`) onto every line,
+ * so a tool call and the GitBook fetch/retry lines it triggers share an id —
+ * the difference between debuggable and un-debuggable logs in production.
+ *
+ * The per-session HTTP logger separately binds `sessionId` via `logger.child`,
+ * so HTTP logs carry both session and request correlation.
+ */
+export interface RequestContext {
+    readonly requestId: string;
+    readonly tool?: string;
+}
+/** Run `fn` with the given request context active for all async work it spawns. */
+export declare function runWithRequestContext<T>(ctx: RequestContext, fn: () => T): T;
+/** The active request context, or undefined outside any request scope. */
+export declare function getRequestContext(): RequestContext | undefined;

package/dist/request-context.js

@@ -0,0 +1,10 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+/** Run `fn` with the given request context active for all async work it spawns. */
+export function runWithRequestContext(ctx, fn) {
+    return storage.run(ctx, fn);
+}
+/** The active request context, or undefined outside any request scope. */
+export function getRequestContext() {
+    return storage.getStore();
+}

package/dist/resources.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolContext } from "./tools/shared.js";
+/**
+ * Expose GitBook pages as MCP resources addressable by `gitbook://{spaceId}/{pageId}`,
+ * so clients can attach a specific page as context. Enumeration (`list`) is left
+ * undefined — listing every page across every space would be unbounded; pages are
+ * read by their known URI (e.g. surfaced from gitbook_list_pages / gitbook_search).
+ */
+export declare function registerResources(server: McpServer, ctx: ToolContext): void;

package/dist/resources.js

@@ -0,0 +1,56 @@
+import { randomUUID } from "node:crypto";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { redactSecret } from "./logger.js";
+import { describeError } from "./gitbook/errors.js";
+import { runWithRequestContext } from "./request-context.js";
+import { metrics } from "./metrics.js";
+/**
+ * Expose GitBook pages as MCP resources addressable by `gitbook://{spaceId}/{pageId}`,
+ * so clients can attach a specific page as context. Enumeration (`list`) is left
+ * undefined — listing every page across every space would be unbounded; pages are
+ * read by their known URI (e.g. surfaced from gitbook_list_pages / gitbook_search).
+ */
+export function registerResources(server, ctx) {
+    server.registerResource("gitbook-page", new ResourceTemplate("gitbook://{spaceId}/{pageId}", { list: undefined }), {
+        title: "GitBook page",
+        description: "A GitBook page rendered as markdown.",
+        mimeType: "text/markdown",
+    }, 
+    // Wrapped with the same discipline as guard() for tools: a request-correlation
+    // scope (so the fetch/retry log lines share an id), metrics, and — critically —
+    // error classification + token redaction. The SDK surfaces a thrown error's
+    // `.message` verbatim to the client, so we must never let a raw, unredacted
+    // error escape this path the way the tool path is protected by errorResult().
+    async (uri, variables) => runWithRequestContext({ requestId: randomUUID(), tool: "resource:gitbook-page" }, async () => {
+        metrics.inc("gitbook_resource_reads_total");
+        try {
+            const spaceId = String(variables.spaceId);
+            const pageId = String(variables.pageId);
+            const page = await ctx.gitbook.getPage(spaceId, pageId, "markdown");
+            // format=markdown surfaces a `markdown` string on the page payload; fall
+            // back to the structured JSON if it is absent.
+            const md = page.markdown;
+            if (typeof md === "string") {
+                return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: md }] };
+            }
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: "application/json",
+                        text: JSON.stringify(page, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            metrics.inc("gitbook_resource_errors_total");
+            ctx.logger.error("resource read failed", { error: describeError(err) });
+            // Re-throw a classified, token-redacted message (the SDK sends only
+            // `.message`/`.code`/`.data` to the client, never `.cause`) — same
+            // guarantee as errorResult() for tools. The raw `err` is kept as `cause`
+            // for server-side debugging; it never leaves the process.
+            throw new Error(redactSecret(describeError(err), ctx.config.token), { cause: err });
+        }
+    }));
+}

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Config } from "./config.js";
+import type { Logger } from "./logger.js";
+import { GitBookClient } from "./gitbook/client.js";
+export interface CreatedServer {
+    readonly server: McpServer;
+    readonly registeredTools: string[];
+}
+/**
+ * Build a fresh MCP server wired to a GitBook client. One instance per stdio
+ * process, or one per HTTP session. Pass a `gitbook` client to inject a mock
+ * in tests.
+ */
+export declare function createServer(config: Config, logger: Logger, gitbook?: GitBookClient): CreatedServer;

package/dist/server.js

@@ -0,0 +1,31 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { GitBookClient } from "./gitbook/client.js";
+import { registerTools } from "./tools/index.js";
+import { registerResources } from "./resources.js";
+import { SERVER_NAME, SERVER_VERSION } from "./version.js";
+const INSTRUCTIONS = [
+    "GitBook access. Read flow: gitbook_list_orgs → gitbook_list_spaces(orgId) →",
+    "gitbook_list_pages(spaceId) → gitbook_get_page(spaceId,pageId). Search with",
+    "gitbook_search (give orgId OR spaceId). Pages are also readable as resources",
+    "at gitbook://{spaceId}/{pageId}.",
+    "Write flow (when not read-only): gitbook_create_change_request →",
+    "gitbook_import_content (import a URL into that change request) → review in",
+    "GitBook → gitbook_merge_change_request to publish. There is no direct",
+    "page-body edit; content is written via change-request + import.",
+].join(" ");
+/**
+ * Build a fresh MCP server wired to a GitBook client. One instance per stdio
+ * process, or one per HTTP session. Pass a `gitbook` client to inject a mock
+ * in tests.
+ */
+export function createServer(config, logger, gitbook) {
+    const client = gitbook ?? new GitBookClient(config, logger);
+    const ctx = { gitbook: client, logger, config };
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION, title: "GitBook MCP" }, 
+    // tools/resources capabilities are auto-enabled by register*(); we don't
+    // advertise `logging` because diagnostics go to stderr, not MCP notifications.
+    { instructions: INSTRUCTIONS });
+    const registeredTools = registerTools(server, ctx);
+    registerResources(server, ctx);
+    return { server, registeredTools };
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolContext } from "./shared.js";
+export type { ToolContext } from "./shared.js";
+/**
+ * Register all tools. Read tools are always available; the change-request write
+ * tools are registered ONLY when not in read-only mode, so a read-only server
+ * never advertises them in tools/list. Returns the registered tool names.
+ */
+export declare function registerTools(server: McpServer, ctx: ToolContext): string[];

package/dist/tools/index.js

@@ -0,0 +1,17 @@
+import { registerReadTools } from "./read.js";
+import { registerWriteTools } from "./write.js";
+/**
+ * Register all tools. Read tools are always available; the change-request write
+ * tools are registered ONLY when not in read-only mode, so a read-only server
+ * never advertises them in tools/list. Returns the registered tool names.
+ */
+export function registerTools(server, ctx) {
+    const names = registerReadTools(server, ctx);
+    if (!ctx.config.readOnly) {
+        names.push(...registerWriteTools(server, ctx));
+    }
+    else {
+        ctx.logger.info("read-only mode: write tools not registered");
+    }
+    return names;
+}

package/dist/tools/read.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolContext } from "./shared.js";
+/** Register the read-only GitBook tools. Returns the registered tool names. */
+export declare function registerReadTools(server: McpServer, ctx: ToolContext): string[];

package/dist/tools/read.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { jsonResult, errorResult, guard, READ_ANNOTATIONS, ToolInputError, } from "./shared.js";
+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.");
+/** Register the read-only GitBook tools. Returns the registered tool names. */
+export function registerReadTools(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())));
+    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 }))));
+    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 }))));
+    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))));
+    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) })));
+    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"))));
+    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);
+    }));
+    return [
+        "gitbook_whoami",
+        "gitbook_list_orgs",
+        "gitbook_list_spaces",
+        "gitbook_get_space",
+        "gitbook_list_pages",
+        "gitbook_get_page",
+        "gitbook_search",
+    ];
+}

package/dist/tools/shared.d.ts

@@ -0,0 +1,48 @@
+import type { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { Config } from "../config.js";
+import { type Logger } from "../logger.js";
+import type { GitBookClient } from "../gitbook/client.js";
+/** Everything a tool handler needs, injected (so tests can mock the client). */
+export interface ToolContext {
+    readonly gitbook: GitBookClient;
+    readonly logger: Logger;
+    readonly config: Config;
+}
+/**
+ * A deliberate, model-facing input-validation error raised by a tool handler
+ * (e.g. mutually-exclusive arguments). classifyError() preserves its `.message`
+ * as a `validation` error — a plain `Error` would instead be flattened to the
+ * generic "unknown" message, swallowing the guidance the model needs to self-correct.
+ */
+export declare class ToolInputError extends Error {
+    readonly name = "ToolInputError";
+}
+/**
+ * Build a successful tool result. Always returns a text mirror (JSON) — every
+ * MCP client can read it — plus `structuredContent` for clients that consume it.
+ * structuredContent must be an object, so non-objects are wrapped.
+ */
+export declare function jsonResult(data: unknown): CallToolResult;
+/**
+ * Build an error tool result (isError:true) with a safe, classified message.
+ * Pass the token so any accidental interpolation of it (e.g. a credential-bearing
+ * URL) is scrubbed before reaching the model — the same invariant the logger holds.
+ */
+export declare function errorResult(err: unknown, secret?: string): CallToolResult;
+export interface GuardOptions {
+    /** Emit info-level invoke/ok audit lines (for write/destructive tools). */
+    audit?: boolean;
+}
+/**
+ * Wrap a tool handler with uniform error handling, metrics, and logging, inside
+ * a fresh request-correlation scope (a `requestId` is stamped on every log line
+ * the call produces — tool, client, and fetch/retry — so one invocation is
+ * traceable end to end). A thrown error becomes a clean `isError` result the
+ * model can read (never leaks the token). Write/destructive tools (`audit:true`)
+ * also emit info-level invoke/ok lines so there is an audit trail at the default
+ * log level.
+ */
+export declare function guard<Args>(ctx: ToolContext, toolName: string, fn: (args: Args) => Promise<CallToolResult>, opts?: GuardOptions): (args: Args) => Promise<CallToolResult>;
+export declare const READ_ANNOTATIONS: ToolAnnotations;
+export declare const WRITE_ANNOTATIONS: ToolAnnotations;
+export declare const DESTRUCTIVE_ANNOTATIONS: ToolAnnotations;

package/dist/tools/shared.js

@@ -0,0 +1,99 @@
+import { randomUUID } from "node:crypto";
+import { redactSecret } from "../logger.js";
+import { describeError } from "../gitbook/errors.js";
+import { runWithRequestContext } from "../request-context.js";
+import { metrics } from "../metrics.js";
+/**
+ * A deliberate, model-facing input-validation error raised by a tool handler
+ * (e.g. mutually-exclusive arguments). classifyError() preserves its `.message`
+ * as a `validation` error — a plain `Error` would instead be flattened to the
+ * generic "unknown" message, swallowing the guidance the model needs to self-correct.
+ */
+export class ToolInputError extends Error {
+    name = "ToolInputError";
+}
+/**
+ * Build a successful tool result. Always returns a text mirror (JSON) — every
+ * MCP client can read it — plus `structuredContent` for clients that consume it.
+ * structuredContent must be an object, so non-objects are wrapped.
+ */
+export function jsonResult(data) {
+    const structuredContent = data !== null && typeof data === "object" && !Array.isArray(data)
+        ? data
+        : { result: data };
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        structuredContent,
+    };
+}
+/**
+ * Build an error tool result (isError:true) with a safe, classified message.
+ * Pass the token so any accidental interpolation of it (e.g. a credential-bearing
+ * URL) is scrubbed before reaching the model — the same invariant the logger holds.
+ */
+export function errorResult(err, secret) {
+    return {
+        content: [{ type: "text", text: redactSecret(describeError(err), secret) }],
+        isError: true,
+    };
+}
+/**
+ * Wrap a tool handler with uniform error handling, metrics, and logging, inside
+ * a fresh request-correlation scope (a `requestId` is stamped on every log line
+ * the call produces — tool, client, and fetch/retry — so one invocation is
+ * traceable end to end). A thrown error becomes a clean `isError` result the
+ * model can read (never leaks the token). Write/destructive tools (`audit:true`)
+ * also emit info-level invoke/ok lines so there is an audit trail at the default
+ * log level.
+ */
+export function guard(ctx, toolName, fn, opts = {}) {
+    return (args) => runWithRequestContext({ requestId: randomUUID(), tool: toolName }, async () => {
+        const started = Date.now();
+        metrics.inc("gitbook_tool_calls_total", { tool: toolName });
+        if (opts.audit)
+            ctx.logger.info("tool invoked", { tool: toolName });
+        try {
+            const result = await fn(args);
+            const ms = Date.now() - started;
+            if (result.isError) {
+                // A handler that RETURNS isError (vs throws) is reporting bad user
+                // input — labeled "validation" so it doesn't pollute the operational
+                // error-rate signal that alerts page on.
+                metrics.inc("gitbook_tool_errors_total", { tool: toolName, kind: "validation" });
+                ctx.logger[opts.audit ? "warn" : "debug"]("tool returned error", { tool: toolName, ms });
+            }
+            else if (opts.audit) {
+                ctx.logger.info("tool ok", { tool: toolName, ms });
+            }
+            else {
+                ctx.logger.debug("tool ok", { tool: toolName, ms });
+            }
+            return result;
+        }
+        catch (err) {
+            metrics.inc("gitbook_tool_errors_total", { tool: toolName, kind: "operational" });
+            ctx.logger.error("tool failed", {
+                tool: toolName,
+                ms: Date.now() - started,
+                error: describeError(err),
+            });
+            return errorResult(err, ctx.config.token);
+        }
+    });
+}
+export const READ_ANNOTATIONS = {
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+export const WRITE_ANNOTATIONS = {
+    readOnlyHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+export const DESTRUCTIVE_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+};

package/dist/tools/write.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolContext } from "./shared.js";
+/**
+ * Register the change-request write tools. Only call this when NOT in read-only
+ * mode — gating registration (rather than rejecting at call time) keeps the
+ * write tools out of tools/list entirely. Returns the registered tool names.
+ */
+export declare function registerWriteTools(server: McpServer, ctx: ToolContext): string[];

package/dist/tools/write.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { jsonResult, guard, WRITE_ANNOTATIONS, DESTRUCTIVE_ANNOTATIONS, } from "./shared.js";
+import { isSafeImportUrl } from "../gitbook/import-url.js";
+/** Audit write/destructive tools at info level (invoke + ok lines). */
+const AUDIT = { audit: true };
+/**
+ * Register the change-request write tools. Only call this when NOT in read-only
+ * mode — gating registration (rather than rejecting at call time) keeps the
+ * write tools out of tools/list entirely. Returns the registered tool names.
+ */
+export function registerWriteTools(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));
+    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));
+    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));
+    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));
+    return [
+        "gitbook_create_change_request",
+        "gitbook_import_content",
+        "gitbook_comment_change_request",
+        "gitbook_merge_change_request",
+    ];
+}

package/dist/transports/http.d.ts

@@ -0,0 +1,20 @@
+import { type Config } from "../config.js";
+import type { Logger } from "../logger.js";
+import type { RunningTransport } from "./stdio.js";
+/** Constant-time string comparison that does not leak length. Exported for tests. */
+export declare function secretEquals(a: string, b: string): boolean;
+/**
+ * Run the server over Streamable HTTP with one transport+server per session.
+ *
+ * Security: binds to 127.0.0.1 by default, enables DNS-rebinding protection
+ * (Host/Origin allow-lists), and — when GITBOOK_HTTP_AUTH_TOKEN is set —
+ * requires a matching bearer token on every request. Running without an auth
+ * token is allowed only for localhost development and is logged as a warning.
+ *
+ * Operability: sessions are capped (new initializes past the cap get 503) and
+ * idle sessions are reaped on a TTL so the in-memory session store cannot grow
+ * unbounded; a per-IP rate limiter guards the endpoint; unauthenticated
+ * `/healthz` `/livez` `/readyz` serve orchestration probes; and a bearer-gated
+ * `/metrics` exposes Prometheus counters.
+ */
+export declare function runHttp(config: Config, logger: Logger): Promise<RunningTransport>;