@hoyongjin/gitbook-mcp 1.0.0

package/dist/transports/http.js

@@ -0,0 +1,336 @@
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import express from "express";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { ConfigError } from "../config.js";
+import { createServer } from "../server.js";
+import { metrics } from "../metrics.js";
+import { SERVER_NAME, SERVER_VERSION } from "../version.js";
+const SESSION_HEADER = "mcp-session-id";
+function jsonRpcError(res, status, code, message) {
+    res.status(status).json({ jsonrpc: "2.0", error: { code, message }, id: null });
+}
+/** Constant-time string comparison that does not leak length. Exported for tests. */
+export function secretEquals(a, b) {
+    const ah = createHash("sha256").update(a).digest();
+    const bh = createHash("sha256").update(b).digest();
+    return timingSafeEqual(ah, bh);
+}
+/** Bound on distinct rate-limit buckets so a spoofable-IP flood cannot grow the map without limit. */
+const RATE_MAP_MAX = 50_000;
+/**
+ * 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 async function runHttp(config, logger) {
+    const { host, port, authToken, maxSessions, sessionIdleTtlMs, sessionMaxLifetimeMs, trustProxy, allowedHosts: extraHosts, allowedOrigins: extraOrigins, rateLimit, } = config.http;
+    const loopbackHosts = new Set(["127.0.0.1", "::1", "localhost", "[::1]"]);
+    const isLoopback = loopbackHosts.has(host);
+    // The SDK matches the FULL incoming Host header (host:port) exactly against this
+    // list. The derived entries only cover the bind host + loopback, so any proxied
+    // or non-loopback access MUST add its public host via GITBOOK_HTTP_ALLOWED_HOSTS
+    // (e.g. "mcp.example.com" / "mcp.example.com:8080") or every request 403s.
+    const allowedHosts = [
+        `${host}:${port}`,
+        `localhost:${port}`,
+        `127.0.0.1:${port}`,
+        `[::1]:${port}`,
+        ...extraHosts,
+    ];
+    const allowedOrigins = [
+        `http://${host}:${port}`,
+        `http://localhost:${port}`,
+        `http://127.0.0.1:${port}`,
+        `http://[::1]:${port}`,
+        ...extraOrigins,
+    ];
+    // A wildcard bind (0.0.0.0 / ::) is only reachable externally, where the Host
+    // header is the public name — never "0.0.0.0:port". Without an explicit
+    // allow-list entry, DNS-rebinding protection rejects all such traffic, so warn
+    // loudly (the Docker image binds 0.0.0.0 by default).
+    const isWildcardBind = host === "0.0.0.0" || host === "::" || host === "[::]";
+    if (isWildcardBind && extraHosts.length === 0) {
+        logger.warn("HTTP bound to a wildcard host with no GITBOOK_HTTP_ALLOWED_HOSTS — DNS-rebinding protection will 403 any request whose Host header is not localhost/127.0.0.1. Set GITBOOK_HTTP_ALLOWED_HOSTS to your public host(s) (e.g. mcp.example.com) for proxied/hosted access.", { host, port });
+    }
+    if (!authToken) {
+        // Fail closed: an unauthenticated server reachable beyond loopback is a
+        // remote-write exposure (esp. with the change-request write tools).
+        if (!isLoopback) {
+            throw new ConfigError(`Refusing to bind the HTTP transport to non-loopback host "${host}" without GITBOOK_HTTP_AUTH_TOKEN. ` +
+                `Set GITBOOK_HTTP_AUTH_TOKEN, or bind to 127.0.0.1.`);
+        }
+        logger.warn("HTTP transport has NO auth token (GITBOOK_HTTP_AUTH_TOKEN unset) — only safe on a trusted local interface", { host, port });
+    }
+    const app = express();
+    app.disable("x-powered-by");
+    // Only trust X-Forwarded-* when explicitly placed behind a trusted proxy.
+    if (trustProxy)
+        app.set("trust proxy", true);
+    /** Bearer check, constant-time. True when no auth token is configured. */
+    const bearerOk = (req) => {
+        if (!authToken)
+            return true;
+        const header = req.headers.authorization ?? "";
+        const match = /^Bearer\s+(.+)$/i.exec(header);
+        return Boolean(match && secretEquals(match[1], authToken));
+    };
+    const sessions = new Map();
+    // In-flight initializes hold a synchronous reservation so the cap is a true
+    // hard limit even under a concurrent burst (the real insert happens later, in
+    // the SDK's onsessioninitialized callback).
+    let pendingInits = 0;
+    const setSessionGauge = () => metrics.setGauge("gitbook_http_sessions_active", sessions.size);
+    // ── orchestration probes: unauthenticated, no rate limit, no access log
+    //    (registered first so they never touch the heavier middleware below).
+    app.get("/healthz", (_req, res) => {
+        res.json({ status: "ok", name: SERVER_NAME, version: SERVER_VERSION });
+    });
+    app.get("/livez", (_req, res) => {
+        res.json({ status: "ok" });
+    });
+    app.get("/readyz", (_req, res) => {
+        res.json({ status: "ok", sessions: sessions.size, maxSessions });
+    });
+    // ── access log for everything below (probes already responded above)
+    app.use((req, res, next) => {
+        const startedAt = Date.now();
+        res.on("finish", () => {
+            logger.info("http request", {
+                method: req.method,
+                path: req.path,
+                status: res.statusCode,
+                ms: Date.now() - startedAt,
+                sessionId: req.headers[SESSION_HEADER],
+            });
+        });
+        next();
+    });
+    // ── metrics: bearer-gated when an auth token is configured.
+    app.get("/metrics", (req, res) => {
+        if (!bearerOk(req)) {
+            jsonRpcError(res, 401, -32001, "Unauthorized");
+            return;
+        }
+        res.setHeader("content-type", "text/plain; version=0.0.4");
+        res.send(metrics.render());
+    });
+    // ── per-IP rate limiting on /mcp (fixed window). max=0 disables.
+    const rateHits = new Map();
+    app.use("/mcp", (req, res, next) => {
+        if (rateLimit.max <= 0)
+            return next();
+        const now = Date.now();
+        const key = req.ip ?? req.socket.remoteAddress ?? "unknown";
+        let entry = rateHits.get(key);
+        if (!entry || now >= entry.resetAt) {
+            // Bound peak memory: evict the oldest bucket before inserting a brand-new
+            // key once at the ceiling (Map preserves insertion order → oldest first).
+            if (!entry && rateHits.size >= RATE_MAP_MAX) {
+                const oldest = rateHits.keys().next().value;
+                if (oldest !== undefined)
+                    rateHits.delete(oldest);
+            }
+            entry = { count: 0, resetAt: now + rateLimit.windowMs };
+            rateHits.set(key, entry);
+        }
+        entry.count++;
+        if (entry.count > rateLimit.max) {
+            res.setHeader("Retry-After", String(Math.ceil((entry.resetAt - now) / 1000)));
+            metrics.inc("gitbook_http_rate_limited_total");
+            jsonRpcError(res, 429, -32000, "Too Many Requests");
+            return;
+        }
+        next();
+    });
+    // ── bearer auth BEFORE body parsing so unauthenticated requests are rejected
+    //    before any body is buffered.
+    app.use("/mcp", (req, res, next) => {
+        if (bearerOk(req))
+            return next();
+        jsonRpcError(res, 401, -32001, "Unauthorized");
+    });
+    app.use("/mcp", express.json({ limit: "4mb" }));
+    app.post("/mcp", async (req, res) => {
+        try {
+            const sessionId = req.headers[SESSION_HEADER];
+            const existing = sessionId ? sessions.get(sessionId) : undefined;
+            if (existing) {
+                existing.lastActivity = Date.now();
+                await existing.transport.handleRequest(req, res, req.body);
+                return;
+            }
+            // No existing session: must be a fresh initialize with no session header.
+            if (sessionId || !isInitializeRequest(req.body)) {
+                jsonRpcError(res, 400, -32000, "No valid session; send an initialize request first");
+                return;
+            }
+            // Enforce the cap BEFORE allocating, counting in-flight initializes so a
+            // concurrent burst cannot overshoot it (reservation released below).
+            if (sessions.size + pendingInits >= maxSessions) {
+                metrics.inc("gitbook_http_sessions_rejected_total");
+                logger.warn("http session cap reached; rejecting initialize", {
+                    maxSessions,
+                    sessions: sessions.size,
+                    pending: pendingInits,
+                });
+                res.setHeader("Retry-After", "5");
+                jsonRpcError(res, 503, -32000, "Server at capacity; try again later");
+                return;
+            }
+            // New session: build a dedicated transport + server, logger bound to the id.
+            const newSessionId = randomUUID();
+            pendingInits++;
+            let reserved = true;
+            const releaseReservation = () => {
+                if (reserved) {
+                    reserved = false;
+                    pendingInits--;
+                }
+            };
+            try {
+                const transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => newSessionId,
+                    enableDnsRebindingProtection: true,
+                    allowedHosts,
+                    allowedOrigins,
+                    onsessioninitialized: (id) => {
+                        sessions.set(id, {
+                            transport,
+                            createdAt: Date.now(),
+                            lastActivity: Date.now(),
+                            sseStreams: 0,
+                        });
+                        releaseReservation(); // reservation becomes a real session
+                        setSessionGauge();
+                        logger.info("http session opened", { sessionId: id, sessions: sessions.size });
+                    },
+                });
+                transport.onclose = () => {
+                    const id = transport.sessionId;
+                    if (id && sessions.delete(id)) {
+                        setSessionGauge();
+                        logger.info("http session closed", { sessionId: id, sessions: sessions.size });
+                    }
+                };
+                const { server } = createServer(config, logger.child({ sessionId: newSessionId }));
+                await server.connect(transport);
+                await transport.handleRequest(req, res, req.body);
+            }
+            finally {
+                // If the init failed before onsessioninitialized fired, free the slot.
+                releaseReservation();
+            }
+        }
+        catch (err) {
+            logger.error("http POST /mcp failed", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            if (!res.headersSent)
+                jsonRpcError(res, 500, -32603, "Internal server error");
+        }
+    });
+    // GET = open the SSE stream for an existing session; DELETE = terminate it.
+    const bySession = async (req, res) => {
+        const sessionId = req.headers[SESSION_HEADER];
+        const session = sessionId ? sessions.get(sessionId) : undefined;
+        if (!session) {
+            jsonRpcError(res, 400, -32000, "Unknown or missing session id");
+            return;
+        }
+        session.lastActivity = Date.now();
+        // A GET opens a long-lived standalone SSE stream — mark it so the idle reaper
+        // doesn't close a connected-but-quiet client mid-stream.
+        if (req.method === "GET") {
+            session.sseStreams++;
+            res.on("close", () => {
+                session.sseStreams = Math.max(0, session.sseStreams - 1);
+                session.lastActivity = Date.now();
+            });
+        }
+        await session.transport.handleRequest(req, res);
+    };
+    app.get("/mcp", bySession);
+    app.delete("/mcp", bySession);
+    // ── session reaper: bounds the in-memory session store regardless of client
+    //    behavior. A session is closed when it exceeds its absolute lifetime
+    //    (always — defeats a keep-alive slow-loris that pins a slot forever), OR
+    //    when it has been idle past the TTL AND has no open SSE stream (so a quiet
+    //    but connected notification stream is not dropped mid-flight). The reaper
+    //    deletes the map entry itself so cap relief never waits on the SDK's
+    //    onclose firing.
+    const closeSession = (id, s, reason, detail) => {
+        logger.info("http session reaped", { sessionId: id, reason, ...detail });
+        if (sessions.delete(id))
+            setSessionGauge();
+        s.transport.close().catch(() => { });
+    };
+    const reaper = setInterval(() => {
+        const now = Date.now();
+        for (const [id, s] of sessions) {
+            if (now - s.createdAt > sessionMaxLifetimeMs) {
+                closeSession(id, s, "max-lifetime", { ageMs: now - s.createdAt });
+            }
+            else if (s.sseStreams === 0 && now - s.lastActivity > sessionIdleTtlMs) {
+                closeSession(id, s, "idle", { idleMs: now - s.lastActivity });
+            }
+        }
+    }, Math.max(1000, Math.floor(sessionIdleTtlMs / 2)));
+    reaper.unref(); // never keep the process alive on the reaper alone
+    // Expired rate-limit buckets are swept on their own cadence (the rate window),
+    // decoupled from the session TTL which can be set to many hours.
+    const rateSweep = setInterval(() => {
+        const now = Date.now();
+        for (const [key, entry] of rateHits) {
+            if (now >= entry.resetAt)
+                rateHits.delete(key);
+        }
+    }, Math.max(1000, rateLimit.windowMs));
+    rateSweep.unref();
+    const httpServer = app.listen(port, host);
+    // Await bind so a startup failure (EADDRINUSE/EACCES) REJECTS runHttp and is
+    // reported by index.ts's clean fatal path, instead of escalating to an
+    // unhandled 'error' event / uncaughtException stack.
+    await new Promise((resolve, reject) => {
+        const onStartupError = (err) => reject(err);
+        httpServer.once("error", onStartupError);
+        httpServer.once("listening", () => {
+            httpServer.removeListener("error", onStartupError);
+            logger.info("listening on http", {
+                host,
+                port,
+                readOnly: config.readOnly,
+                gated: Boolean(authToken), // bearer auth required? (field name avoids log redaction)
+                maxSessions,
+                version: SERVER_VERSION,
+            });
+            resolve();
+        });
+    });
+    // Steady-state: a post-startup server error must not crash the process.
+    httpServer.on("error", (err) => {
+        logger.error("http server error", { code: err.code, error: err.message });
+    });
+    return {
+        close: async () => {
+            clearInterval(reaper);
+            clearInterval(rateSweep);
+            // Close per-session transports FIRST — this ends their SSE streams so the
+            // keep-alive connections drain; otherwise httpServer.close() never fires.
+            for (const { transport } of sessions.values()) {
+                await transport.close().catch(() => { });
+            }
+            httpServer.closeAllConnections();
+            await new Promise((resolve) => httpServer.close(() => resolve()));
+        },
+    };
+}

package/dist/transports/stdio.d.ts

@@ -0,0 +1,7 @@
+import type { Config } from "../config.js";
+import type { Logger } from "../logger.js";
+export interface RunningTransport {
+    close(): Promise<void>;
+}
+/** Connect a single MCP server over stdio. */
+export declare function runStdio(config: Config, logger: Logger): Promise<RunningTransport>;

package/dist/transports/stdio.js

@@ -0,0 +1,17 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "../server.js";
+/** Connect a single MCP server over stdio. */
+export async function runStdio(config, logger) {
+    const { server, registeredTools } = createServer(config, logger);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("listening on stdio", {
+        tools: registeredTools.length,
+        readOnly: config.readOnly,
+    });
+    return {
+        close: async () => {
+            await server.close();
+        },
+    };
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const SERVER_NAME = "gitbook-mcp";
+export declare const SERVER_VERSION: string;

package/dist/version.js

@@ -0,0 +1,9 @@
+import { createRequire } from "node:module";
+// Stable MCP server identity (independent of the npm package's scope/name).
+export const SERVER_NAME = "gitbook-mcp";
+// Version is read from package.json at runtime so it never drifts from the
+// published manifest. dist/version.js → ../package.json resolves both in-repo
+// (dist/ sibling of package.json) and when installed (package root).
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+export const SERVER_VERSION = pkg.version;

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@hoyongjin/gitbook-mcp",
+  "version": "1.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",
+    "mcp",
+    "model-context-protocol",
+    "modelcontextprotocol",
+    "claude",
+    "documentation"
+  ],
+  "license": "MIT",
+  "author": "JHY",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HoYongJin/gitbook-mcp.git"
+  },
+  "homepage": "https://github.com/HoYongJin/gitbook-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/HoYongJin/gitbook-mcp/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "gitbook-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "shx rm -rf dist && tsc -p tsconfig.json && shx chmod +x dist/index.js",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "start": "node dist/index.js",
+    "dev": "npm run build && node dist/index.js",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm test"
+  },
+  "dependencies": {
+    "@gitbook/api": "^0.183.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^5.2.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.9.3",
+    "@vitest/coverage-v8": "^4.1.8",
+    "eslint": "^10.4.1",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.4",
+    "shx": "^0.4.0",
+    "typescript": "5.7.3",
+    "typescript-eslint": "^8.61.0",
+    "vitest": "^4.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}