@hoyongjin/gitbook-mcp 1.0.0 → 2.0.0

package/dist/tools/toolsets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Toolset keys — the gating groups a user enables via `GITBOOK_TOOLSETS`. Every
+ * row in the generated manifest carries a `toolset` that is one of these keys.
+ *
+ * `core` + `change-requests` are enabled by DEFAULT (≈ the original 11 tools plus
+ * the change-request review/merge loop); everything else is opt-in. The `all`
+ * sentinel (handled in config) enables every key. Keeping the default surface
+ * small avoids flooding `tools/list` with hundreds of schemas and keeps the
+ * model's tool-selection sharp.
+ *
+ * This list is the source of truth for config validation; a conformance test
+ * asserts every manifest `toolset` is one of these keys (no orphans).
+ */
+export declare const TOOLSET_KEYS: readonly ["core", "change-requests", "collections", "sites", "site-ai", "site-insights", "integrations", "data", "git", "public", "org-admin"];
+export type ToolsetKey = (typeof TOOLSET_KEYS)[number];
+/** Enabled when `GITBOOK_TOOLSETS` is unset/empty — keeps back-compat with the 11-tool server. */
+export declare const DEFAULT_TOOLSETS: readonly ToolsetKey[];

package/dist/tools/toolsets.js

@@ -0,0 +1,28 @@
+/**
+ * Toolset keys — the gating groups a user enables via `GITBOOK_TOOLSETS`. Every
+ * row in the generated manifest carries a `toolset` that is one of these keys.
+ *
+ * `core` + `change-requests` are enabled by DEFAULT (≈ the original 11 tools plus
+ * the change-request review/merge loop); everything else is opt-in. The `all`
+ * sentinel (handled in config) enables every key. Keeping the default surface
+ * small avoids flooding `tools/list` with hundreds of schemas and keeps the
+ * model's tool-selection sharp.
+ *
+ * This list is the source of truth for config validation; a conformance test
+ * asserts every manifest `toolset` is one of these keys (no orphans).
+ */
+export const TOOLSET_KEYS = [
+    "core",
+    "change-requests",
+    "collections",
+    "sites",
+    "site-ai",
+    "site-insights",
+    "integrations",
+    "data",
+    "git",
+    "public",
+    "org-admin",
+];
+/** Enabled when `GITBOOK_TOOLSETS` is unset/empty — keeps back-compat with the 11-tool server. */
+export const DEFAULT_TOOLSETS = ["core", "change-requests"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoyongjin/gitbook-mcp",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Model Context Protocol server for GitBook — read content and drive a change-request write workflow over stdio or streamable HTTP.",
   "keywords": [
     "gitbook",
@@ -35,6 +35,7 @@
   ],
   "scripts": {
     "build": "shx rm -rf dist && tsc -p tsconfig.json && shx chmod +x dist/index.js",
+    "generate:manifest": "node scripts/generate-manifest.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
     "lint": "eslint .",
     "format": "prettier --write .",
@@ -48,7 +49,7 @@
     "prepublishOnly": "npm run typecheck && npm run lint && npm test"
   },
   "dependencies": {
-    "@gitbook/api": "^0.183.0",
+    "@gitbook/api": "0.183.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "express": "^5.2.1",
     "zod": "^4.4.3"
@@ -67,6 +68,7 @@
     "vitest": "^4.1.8"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   }
 }

package/dist/tools/read.d.ts

@@ -1,4 +0,0 @@
-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

@@ -1,91 +0,0 @@
-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/write.d.ts

@@ -1,8 +0,0 @@
-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

@@ -1,88 +0,0 @@
-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",
-    ];
-}