@hoyongjin/gitbook-mcp 1.0.0 → 2.0.0

package/dist/tools/factory.d.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ManifestRow } from "./manifest.js";
+import { type ToolContext } from "./shared.js";
+/**
+ * Manifest-driven registration for the generic (non-bespoke) tools. ONE factory
+ * covers every operation in every toolset — there are no per-op hand-written
+ * handlers, which is also what keeps v8 `functions` coverage healthy (one
+ * covered function, not hundreds of closures).
+ *
+ * Argument mapping needs no TS-signature parsing: the manifest gives `pathParams`
+ * (the leading positional args, in URL order) and `dataArg` (whether the method
+ * takes a body/query slot after them). The tool's input is therefore one string
+ * field per path param plus an optional freeform `body` object forwarded as the
+ * body (writes) or query (reads). Per-op typed body schemas are a deliberate
+ * non-goal here; high-value ops can be promoted to bespoke handlers later.
+ */
+export declare function registerGenericTool(server: McpServer, ctx: ToolContext, row: ManifestRow): void;

package/dist/tools/factory.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { jsonResult, guard, READ_ANNOTATIONS, WRITE_ANNOTATIONS, DESTRUCTIVE_ANNOTATIONS, } from "./shared.js";
+/**
+ * Manifest-driven registration for the generic (non-bespoke) tools. ONE factory
+ * covers every operation in every toolset — there are no per-op hand-written
+ * handlers, which is also what keeps v8 `functions` coverage healthy (one
+ * covered function, not hundreds of closures).
+ *
+ * Argument mapping needs no TS-signature parsing: the manifest gives `pathParams`
+ * (the leading positional args, in URL order) and `dataArg` (whether the method
+ * takes a body/query slot after them). The tool's input is therefore one string
+ * field per path param plus an optional freeform `body` object forwarded as the
+ * body (writes) or query (reads). Per-op typed body schemas are a deliberate
+ * non-goal here; high-value ops can be promoted to bespoke handlers later.
+ */
+export function registerGenericTool(server, ctx, row) {
+    server.registerTool(row.name, {
+        title: row.summary,
+        description: describe(row),
+        inputSchema: buildInputSchema(row),
+        annotations: annotationsFor(row.kind),
+    }, guard(ctx, row.name, async (input) => {
+        const args = row.pathParams.map((p) => input[p]);
+        if (row.dataArg && input.body !== undefined)
+            args.push(input.body);
+        const data = row.returnShape === "items"
+            ? await ctx.gitbook.callList(row.namespace, row.op, args)
+            : await ctx.gitbook.call(row.namespace, row.op, args);
+        return jsonResult(data);
+    }, row.kind === "read" ? undefined : { audit: true }));
+}
+function annotationsFor(kind) {
+    if (kind === "read")
+        return READ_ANNOTATIONS;
+    if (kind === "destructive")
+        return DESTRUCTIVE_ANNOTATIONS;
+    return WRITE_ANNOTATIONS;
+}
+function buildInputSchema(row) {
+    const shape = {};
+    for (const p of row.pathParams) {
+        shape[p] = z.string().describe(`Path parameter: ${p}.`);
+    }
+    if (row.dataArg) {
+        shape.body = z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe(row.kind === "read"
+            ? "Optional query parameters as a JSON object (e.g. { limit, page })."
+            : "Request body as a JSON object, per the GitBook API for this operation.");
+    }
+    return shape;
+}
+function describe(row) {
+    let d = `${row.summary}. (${row.verb} ${row.path})`;
+    if (row.kind === "destructive")
+        d += " DESTRUCTIVE / irreversible — changes or removes data.";
+    if (row.async) {
+        d +=
+            " Asynchronous — GitBook exposes no status endpoint, so treat the result as 'started, not confirmed' and verify in GitBook.";
+    }
+    return d;
+}

package/dist/tools/index.d.ts

@@ -1,9 +1,28 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ToolContext } from "./shared.js";
+import type { ToolsetKey } from "./toolsets.js";
+import { type ManifestRow } from "./manifest.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.
+ * Whether a manifest row should register under the current config. Three gates,
+ * composed (all must hold):
+ *   1. toolset       — the row's toolset is enabled.
+ *   2. readOnly      — read tools always; write/destructive only when !readOnly.
+ *   3. destructive   — NEW destructive ops require the GITBOOK_ALLOW_DESTRUCTIVE
+ *                      opt-in; `legacy` ops (the original merge tool) are exempt
+ *                      so back-compat is preserved.
+ * Excluded carve-outs (streaming / trivial) never register.
+ */
+export declare function shouldRegister(row: ManifestRow, cfg: {
+    enabledToolsets: ReadonlySet<ToolsetKey>;
+    readOnly: boolean;
+    allowDestructive: boolean;
+}): boolean;
+/**
+ * Register all tools the current config selects, driven by the generated
+ * manifest. Bespoke rows (the 11 original tools) use their hand-written
+ * registrar; every other row is generated by the factory. `gitbook_search`
+ * maps two API ops to one tool, so registration is de-duplicated by name.
+ * Returns the registered tool names.
  */
 export declare function registerTools(server: McpServer, ctx: ToolContext): string[];

package/dist/tools/index.js

@@ -1,17 +1,56 @@
-import { registerReadTools } from "./read.js";
-import { registerWriteTools } from "./write.js";
+import { MANIFEST } from "./manifest.js";
+import { BESPOKE_TOOLS } from "./bespoke.js";
+import { registerGenericTool } from "./factory.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.
+ * Whether a manifest row should register under the current config. Three gates,
+ * composed (all must hold):
+ *   1. toolset       — the row's toolset is enabled.
+ *   2. readOnly      — read tools always; write/destructive only when !readOnly.
+ *   3. destructive   — NEW destructive ops require the GITBOOK_ALLOW_DESTRUCTIVE
+ *                      opt-in; `legacy` ops (the original merge tool) are exempt
+ *                      so back-compat is preserved.
+ * Excluded carve-outs (streaming / trivial) never register.
+ */
+export function shouldRegister(row, cfg) {
+    if (row.exclude)
+        return false;
+    if (!cfg.enabledToolsets.has(row.toolset))
+        return false;
+    if (row.kind !== "read" && cfg.readOnly)
+        return false;
+    if (row.kind === "destructive" && !row.legacy && !cfg.allowDestructive)
+        return false;
+    return true;
+}
+/**
+ * Register all tools the current config selects, driven by the generated
+ * manifest. Bespoke rows (the 11 original tools) use their hand-written
+ * registrar; every other row is generated by the factory. `gitbook_search`
+ * maps two API ops to one tool, so registration is de-duplicated by name.
+ * Returns the registered tool names.
  */
 export function registerTools(server, ctx) {
-    const names = registerReadTools(server, ctx);
-    if (!ctx.config.readOnly) {
-        names.push(...registerWriteTools(server, ctx));
+    const names = [];
+    const seen = new Set();
+    for (const row of MANIFEST) {
+        if (!shouldRegister(row, ctx.config))
+            continue;
+        if (seen.has(row.name))
+            continue;
+        if (row.bespoke) {
+            const register = BESPOKE_TOOLS[row.name];
+            if (!register)
+                throw new Error(`Manifest marks ${row.name} bespoke but no registrar exists`);
+            register(server, ctx);
+        }
+        else {
+            registerGenericTool(server, ctx, row);
+        }
+        seen.add(row.name);
+        names.push(row.name);
     }
-    else {
-        ctx.logger.info("read-only mode: write tools not registered");
+    if (ctx.config.readOnly) {
+        ctx.logger.info("read-only mode: write/destructive tools not registered");
     }
     return names;
 }

package/dist/tools/manifest.d.ts

@@ -0,0 +1,35 @@
+export type ToolKind = "read" | "write" | "destructive";
+export type ReturnShape = "items" | "pages" | "scalar" | "void" | "stream";
+export interface ManifestRow {
+    /** MCP tool name (grandfathered for the 11 legacy tools, else gitbook_<op>). */
+    readonly name: string;
+    /** @gitbook/api method name. */
+    readonly op: string;
+    /** @gitbook/api client namespace the method lives on. */
+    readonly namespace: ApiNamespace;
+    readonly verb: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    readonly path: string;
+    /** One-line @summary from the API spec; used as the tool description base. */
+    readonly summary: string;
+    /** Path-parameter names in URL order — the leading positional args to the op. */
+    readonly pathParams: readonly string[];
+    /** Name of the body/query positional arg, or null if the op takes none (e.g. most DELETEs). */
+    readonly dataArg: string | null;
+    /** Primary @tags group. */
+    readonly tag: string;
+    readonly toolset: string;
+    readonly kind: ToolKind;
+    readonly returnShape: ReturnShape;
+    /** Async op with no status-poll endpoint (import/export): "started, not confirmed". */
+    readonly async?: boolean;
+    /** True for the 11 existing tools (hand-written handlers, not the factory). */
+    readonly bespoke?: boolean;
+    /** Exempt from the GITBOOK_ALLOW_DESTRUCTIVE opt-in (back-compat). */
+    readonly legacy?: boolean;
+    /** Carve-out: never registered (streaming / trivial / auth-only ops). */
+    readonly exclude?: boolean;
+}
+/** Every @gitbook/api client namespace (generated from the Api class). */
+export declare const VALID_NAMESPACES: readonly ["ads", "collections", "customHostnames", "emailDomains", "git", "integrations", "org", "orgs", "spaces", "subdomains", "urls", "user", "users"];
+export type ApiNamespace = (typeof VALID_NAMESPACES)[number];
+export declare const MANIFEST: readonly ManifestRow[];