jishushell 0.6.5 → 0.7.3

package/dist/services/integrations/openclaw/jishukb-shim.js

@@ -0,0 +1,1357 @@
+/**
+ * JishuShell-KB MCP shim — exposes the user's installed jishu-kb as a
+ * typed MCP toolset for OpenClaw.
+ *
+ * Why a shim, not direct MCP:
+ *   jishu-kb speaks HTTP REST (`/api/kb/*`, `/api/admin/*`, `handbook.md`),
+ *   not MCP. This shim translates a narrow tool surface into those REST calls
+ *   and returns model-friendly text blocks or JSON summaries.
+ *
+ * Scope intentionally stays typed and bounded:
+ *   - Read/search: list KBs, search, list documents, read handbook, read
+ *     document metadata/source/chunks/FAQ, inspect ingest jobs, and read
+ *     sanitized config/capabilities
+ *   - Write: create KBs, upload documents, import URLs, retry jobs, and
+ *     reindex documents in a chosen KB
+ *   - Dangerous delete/cancel/reindex operations require explicit confirmation arguments
+ *   - No raw admin/provider passthrough: secrets and arbitrary provider edits
+ *     remain outside the agent surface
+ *
+ * Wiring: the OpenClaw integration writes this shim into
+ * `__mcp_shims__/jishukb/jishukb-shim.js` per instance and registers it under
+ * the stable `kb` server name.
+ *
+ * Non-secret config (baseUrl + default kbId + allowed upload roots) is baked into the
+ * source by `substituteJishukbShimPlaceholders` because OpenClaw scrubs env
+ * when spawning MCP subprocesses.
+ *
+ * Stdio framing: NDJSON JSON-RPC 2.0 (MCP standard). Pure Node builtins, no
+ * npm install needed inside the runtime image.
+ */
+export const JISHUKB_MCP_SHIM_VERSION = "0.3.0";
+/** Default topK when the caller doesn't specify one. Mirrors the manifest
+ * `JISHU_KB_TOPK` default so the agent and the backend agree on page size. */
+export const JISHUKB_DEFAULT_TOPK = 6;
+/** Per-request upstream timeout. */
+export const JISHUKB_FETCH_TIMEOUT_MS = 60_000;
+/** Soft guard for upload memory use. */
+export const JISHUKB_MAX_UPLOAD_BYTES = 30 * 1024 * 1024;
+/** Soft guard for text returned through MCP. */
+export const JISHUKB_MAX_TEXT_RESPONSE_CHARS = 12_000;
+export const JISHUKB_MCP_SHIM_SOURCE = `#!/usr/bin/env node
+// jishushell-jishukb-shim — generated, do not edit by hand.
+// Source: src/services/integrations/openclaw/jishukb-shim.ts
+
+const BASE_URL_LIT = "__JS_BASE_URL__";
+const KB_ID_LIT = "__JS_KB_ID__";
+const ALLOWED_UPLOAD_ROOTS_LIT = "__JS_ALLOWED_UPLOAD_ROOTS__";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { TextDecoder } = require("node:util");
+
+const BASE_URL = (BASE_URL_LIT.startsWith("__JS_") ? (process.env.JISHUKB_BASE_URL || "") : BASE_URL_LIT).replace(/\\/+$/, "");
+const KB_ID = KB_ID_LIT.startsWith("__JS_") ? trimString(process.env.JISHUKB_KB_ID || "") : trimString(KB_ID_LIT);
+const ALLOWED_UPLOAD_ROOTS = (
+  ALLOWED_UPLOAD_ROOTS_LIT.startsWith("__JS_")
+    ? JSON.parse(process.env.JISHUKB_ALLOWED_UPLOAD_ROOTS || "[]")
+    : JSON.parse(ALLOWED_UPLOAD_ROOTS_LIT)
+).map((value) => path.resolve(String(value)));
+const DEFAULT_TOPK = ${JISHUKB_DEFAULT_TOPK};
+const FETCH_TIMEOUT = ${JISHUKB_FETCH_TIMEOUT_MS};
+const MAX_UPLOAD_BYTES = ${JISHUKB_MAX_UPLOAD_BYTES};
+const MAX_TEXT_RESPONSE_CHARS = ${JISHUKB_MAX_TEXT_RESPONSE_CHARS};
+const OPEN_UPLOAD_FLAGS = fs.constants.O_RDONLY
+  | (typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0)
+  | (typeof fs.constants.O_NONBLOCK === "number" ? fs.constants.O_NONBLOCK : 0);
+
+function envCheck() {
+  if (!BASE_URL) {
+    throw new Error("jishukb-shim: missing env: JISHUKB_BASE_URL");
+  }
+}
+
+function trimString(raw) {
+  if (typeof raw === "string") return raw.trim();
+  if (typeof raw === "number" || typeof raw === "boolean") return String(raw).trim();
+  return "";
+}
+
+function jsonText(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+function clampTopK(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return DEFAULT_TOPK;
+  const i = Math.floor(n);
+  if (i < 1) return 1;
+  if (i > 20) return 20;
+  return i;
+}
+
+function defaultKbId(raw, toolName) {
+  const kbId = trimString(raw) || KB_ID;
+  if (!kbId) {
+    throw new Error(toolName + ": missing 'kbId' argument and no default KB is configured");
+  }
+  return kbId;
+}
+
+function requireKbId(raw, toolName) {
+  const kbId = trimString(raw);
+  if (!kbId) throw new Error(toolName + ": missing 'kbId' argument");
+  return kbId;
+}
+
+function requireConfirm(actual, expected, toolName, fieldName) {
+  if (trimString(actual) !== expected) {
+    throw new Error(toolName + ": confirmation field '" + fieldName + "' must exactly match '" + expected + "'");
+  }
+}
+
+function assertUploadRootsConfigured() {
+  if (!Array.isArray(ALLOWED_UPLOAD_ROOTS) || ALLOWED_UPLOAD_ROOTS.length === 0) {
+    throw new Error("jishukb-shim: missing configured upload roots");
+  }
+}
+
+function sameInode(left, right) {
+  return !!left && !!right && left.dev === right.dev && left.ino === right.ino;
+}
+
+function assertStableUploadRead(opened, buf) {
+  const afterStat = fs.fstatSync(opened.fd);
+  if (!sameInode(opened.stat, afterStat)) {
+    throw new Error("kb_upload: file changed during read");
+  }
+  if (afterStat.size !== opened.stat.size || buf.length !== opened.stat.size) {
+    throw new Error("kb_upload: file size changed during read");
+  }
+  if (buf.length > MAX_UPLOAD_BYTES) {
+    throw new Error("kb_upload: file exceeds soft limit of " + MAX_UPLOAD_BYTES + " bytes");
+  }
+}
+
+function readBoundedUploadBuffer(fd, size) {
+  if (!Number.isSafeInteger(size) || size < 0) {
+    throw new Error("kb_upload: invalid file size");
+  }
+  const buf = Buffer.alloc(size);
+  let offset = 0;
+  while (offset < size) {
+    const bytesRead = fs.readSync(fd, buf, offset, size - offset, offset);
+    if (bytesRead === 0) break;
+    offset += bytesRead;
+  }
+  return offset === size ? buf : buf.subarray(0, offset);
+}
+
+function findAllowedUploadRoot(absPath) {
+  for (const root of ALLOWED_UPLOAD_ROOTS) {
+    if (absPath === root || absPath.startsWith(root + path.sep)) {
+      return root;
+    }
+  }
+  return null;
+}
+
+function sanitizeBaseUrl(raw) {
+  const value = trimString(raw);
+  if (!value) return null;
+  try {
+    const parsed = new URL(value);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return null;
+  }
+}
+
+function openUploadFile(absPath) {
+  assertUploadRootsConfigured();
+  const input = trimString(absPath);
+  if (!input) throw new Error("kb_upload: missing 'path' argument");
+  if (!path.isAbsolute(input)) throw new Error("kb_upload: path must be absolute");
+  const normalized = path.resolve(input);
+  const lexicalRoot = findAllowedUploadRoot(normalized);
+  if (!lexicalRoot) {
+    throw new Error("kb_upload: path must stay under this instance's mounted files roots");
+  }
+  let fd;
+  try {
+    fd = fs.openSync(normalized, OPEN_UPLOAD_FLAGS);
+  } catch (error) {
+    if (error && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+      throw new Error("kb_upload: file not found: " + normalized);
+    }
+    if (error && (error.code === "ELOOP" || error.code === "EMLINK")) {
+      throw new Error("kb_upload: symlink targets are not allowed");
+    }
+    throw error;
+  }
+  try {
+    const realRoot = fs.realpathSync(lexicalRoot);
+    const realPath = fs.realpathSync(normalized);
+    if (!(realPath === realRoot || realPath.startsWith(realRoot + path.sep))) {
+      throw new Error("kb_upload: resolved path escapes this instance's mounted files roots");
+    }
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile()) throw new Error("kb_upload: not a regular file: " + realPath);
+    if (stat.nlink > 1) {
+      throw new Error("kb_upload: files with multiple hard links are not allowed");
+    }
+    if (stat.size > MAX_UPLOAD_BYTES) {
+      throw new Error("kb_upload: file exceeds soft limit of " + MAX_UPLOAD_BYTES + " bytes");
+    }
+    const pathStat = fs.statSync(realPath);
+    if (!sameInode(stat, pathStat)) {
+      throw new Error("kb_upload: file changed during validation");
+    }
+    return { absPath: realPath, stat, fd };
+  } catch (error) {
+    fs.closeSync(fd);
+    throw error;
+  }
+}
+
+async function fetchWithTimeout(toolName, relativePath, options) {
+  envCheck();
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT);
+  try {
+    return await fetch(BASE_URL + relativePath, {
+      ...options,
+      signal: ctrl.signal,
+    });
+  } catch (e) {
+    if (e && e.name === "AbortError") {
+      throw new Error(toolName + ": upstream timeout after " + Math.round(FETCH_TIMEOUT / 1000) + "s");
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function readJson(toolName, relativePath, options) {
+  const res = await fetchWithTimeout(toolName, relativePath, options);
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error(toolName + ": upstream " + res.status + ": " + txt.slice(0, 400));
+  }
+  return await res.json();
+}
+
+async function readText(toolName, relativePath, options) {
+  const res = await fetchWithTimeout(toolName, relativePath, options);
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error(toolName + ": upstream " + res.status + ": " + txt.slice(0, 400));
+  }
+  return await res.text();
+}
+
+function cappedText(raw, maxChars) {
+  const text = String(raw ?? "");
+  if (text.length <= maxChars) {
+    return { text, truncated: false, characters: text.length };
+  }
+  return {
+    text: text.slice(0, Math.max(0, maxChars - 1)) + "…",
+    truncated: true,
+    characters: text.length,
+  };
+}
+
+function optionalString(raw) {
+  const value = trimString(raw);
+  return value || null;
+}
+
+function positiveInt(raw, fallback, max) {
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return fallback;
+  const i = Math.floor(n);
+  if (i < 1) return fallback;
+  return Math.min(i, max);
+}
+
+function boolWithDefault(raw, fallback) {
+  if (raw === undefined || raw === null || raw === "") return fallback;
+  if (typeof raw === "boolean") return raw;
+  const text = trimString(raw).toLowerCase();
+  if (["1", "true", "yes", "y"].includes(text)) return true;
+  if (["0", "false", "no", "n"].includes(text)) return false;
+  return fallback;
+}
+
+function appendOptionalQuery(qs, key, value) {
+  const text = trimString(value);
+  if (text) qs.set(key, text);
+}
+
+function encodePathPart(value) {
+  return encodeURIComponent(value);
+}
+
+function normalizeBacklinks(raw) {
+  return Array.isArray(raw) ? raw : [];
+}
+
+function normalizeDocument(item, kbId) {
+  const doc = item && typeof item === "object" ? item : {};
+  return {
+    id: doc.id || null,
+    kbId: doc.kb_id || doc.kbId || kbId || null,
+    title: doc.title || null,
+    relPath: doc.rel_path || doc.relPath || null,
+    mime: doc.mime || null,
+    sha256: doc.sha256 || null,
+    bytes: doc.bytes ?? null,
+    status: doc.status || null,
+    createdAt: doc.created_at ?? doc.createdAt ?? null,
+    origin: doc.origin || null,
+    sourcePath: doc.source_path || doc.sourcePath || null,
+    sourceUrl: doc.source_url || doc.sourceUrl || null,
+    batchId: doc.batch_id || doc.batchId || null,
+    clientItemId: doc.client_item_id || doc.clientItemId || null,
+    externalAssetId: doc.external_asset_id || doc.externalAssetId || null,
+    backlinks: normalizeBacklinks(doc.backlinks),
+    chunkCount: doc.chunkCount ?? null,
+    faqCount: doc.faqCount ?? null,
+    jobCount: doc.jobCount ?? null,
+  };
+}
+
+function normalizeJob(item, kbId) {
+  const job = item && typeof item === "object" ? item : {};
+  return {
+    id: job.id || null,
+    docId: job.docId || job.doc_id || null,
+    kbId: job.kbId || job.kb_id || kbId || null,
+    filename: job.filename || null,
+    relPath: job.relPath || job.rel_path || null,
+    mime: job.mime || null,
+    sha256: job.sha256 || null,
+    bytes: job.bytes ?? null,
+    status: job.status || null,
+    stage: job.stage || null,
+    progressCurrent: job.progressCurrent ?? job.progress_current ?? null,
+    progressTotal: job.progressTotal ?? job.progress_total ?? null,
+    attempts: job.attempts ?? null,
+    error: job.error || null,
+    createdAt: job.createdAt ?? job.created_at ?? null,
+    updatedAt: job.updatedAt ?? job.updated_at ?? null,
+    origin: job.origin || null,
+    sourcePath: job.sourcePath || job.source_path || null,
+    sourceUrl: job.sourceUrl || job.source_url || null,
+    batchId: job.batchId || job.batch_id || null,
+    clientItemId: job.clientItemId || job.client_item_id || null,
+    externalAssetId: job.externalAssetId || job.external_asset_id || null,
+  };
+}
+
+function documentArrayFromPayload(payload) {
+  if (Array.isArray(payload)) return payload;
+  if (payload && Array.isArray(payload.documents)) return payload.documents;
+  if (payload && Array.isArray(payload.items)) return payload.items;
+  return null;
+}
+
+function jobArrayFromPayload(payload) {
+  if (Array.isArray(payload)) return payload;
+  if (payload && Array.isArray(payload.jobs)) return payload.jobs;
+  if (payload && Array.isArray(payload.items)) return payload.items;
+  return null;
+}
+
+function mediaType(raw) {
+  return trimString(raw).toLowerCase().split(";")[0].trim();
+}
+
+function isTextLikeContentType(raw) {
+  const type = mediaType(raw);
+  if (!type) return false;
+  if (type.startsWith("text/")) return true;
+  return [
+    "application/ecmascript",
+    "application/javascript",
+    "application/json",
+    "application/sql",
+    "application/toml",
+    "application/x-ndjson",
+    "application/x-yaml",
+    "application/xhtml+xml",
+    "application/xml",
+    "application/yaml",
+  ].includes(type) || type.endsWith("+json") || type.endsWith("+xml");
+}
+
+function contentLengthOf(headers) {
+  const raw = trimString(headers?.get?.("content-length"));
+  if (!raw) return null;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+async function readBoundedTextResponse(toolName, res, maxChars) {
+  const contentType = res.headers.get("content-type") || "";
+  const contentDisposition = res.headers.get("content-disposition") || null;
+  const contentLength = contentLengthOf(res.headers);
+  if (!isTextLikeContentType(contentType)) {
+    try { await res.body?.cancel?.(); } catch { /* ignore cleanup errors */ }
+    throw new Error(
+      toolName + ": raw document is not text-like" +
+      " (contentType=" + (contentType || "unknown") +
+      (contentLength != null ? ", contentLength=" + contentLength : "") +
+      (contentDisposition ? ", contentDisposition=" + contentDisposition : "") +
+      "). Use kb_get_document for metadata; binary originals should be opened through the file surface.",
+    );
+  }
+  if (!res.body || typeof res.body.getReader !== "function") {
+    throw new Error(toolName + ": upstream response does not support bounded streaming");
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  let text = "";
+  let bytesRead = 0;
+  let truncated = false;
+  try {
+    while (text.length <= maxChars) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      const value = chunk.value || new Uint8Array();
+      bytesRead += value.byteLength || 0;
+      text += decoder.decode(value, { stream: true });
+      if (text.length > maxChars) {
+        truncated = true;
+        try { await reader.cancel(); } catch { /* ignore cleanup errors */ }
+        break;
+      }
+    }
+    if (!truncated) {
+      text += decoder.decode();
+      if (text.length > maxChars) {
+        truncated = true;
+      }
+    }
+  } finally {
+    try { reader.releaseLock?.(); } catch { /* ignore cleanup errors */ }
+  }
+  if (truncated) {
+    text = text.slice(0, Math.max(0, maxChars - 1)) + "…";
+  }
+  return {
+    text,
+    truncated,
+    characters: text.length,
+    bytesRead,
+    contentLength,
+  };
+}
+
+function normalizeChunksResponse(payload) {
+  const j = payload && typeof payload === "object" ? payload : {};
+  const rawChunks = Array.isArray(j.chunks) ? j.chunks
+    : Array.isArray(j.citations) ? j.citations
+    : Array.isArray(j.results) ? j.results
+    : Array.isArray(j.hits) ? j.hits
+    : [];
+  return rawChunks.map((raw, idx) => {
+    const item = raw && typeof raw === "object" ? raw : { text: String(raw ?? "") };
+    const src = item.source && typeof item.source === "object" ? item.source : {};
+    const title = src.title
+      || src.filename
+      || src.docId
+      || item.docTitle
+      || item.filename
+      || item.docId
+      || src.url
+      || item.url
+      || ("chunk#" + (idx + 1));
+    return {
+      ...item,
+      source: {
+        ...src,
+        title,
+      },
+      text: item.text || item.content || item.chunk || item.context || "",
+      score: item.score != null ? item.score : item.relevanceScore,
+    };
+  });
+}
+
+function fmtChunk(c, idx) {
+  const src = c.source || {};
+  const title = src.title || src.filename || src.docId || src.url || ("chunk#" + (idx + 1));
+  const scoreStr = c.score != null && Number.isFinite(Number(c.score))
+    ? " [score " + Number(c.score).toFixed(3) + "]"
+    : "";
+  const body = (c.text || c.content || c.chunk || "").toString();
+  const capped = body.length > 1200 ? body.slice(0, 1200) + "…" : body;
+  return "[" + (idx + 1) + "] " + title + scoreStr + "\\n" + capped;
+}
+
+function fmtSearchResult(chunks) {
+  if (!chunks.length) return "(no results)";
+  return chunks.map(fmtChunk).join("\\n\\n");
+}
+
+function normalizeHeading(text) {
+  return trimString(text).toLowerCase().replace(/\\s+/g, " ");
+}
+
+function extractMarkdownSection(markdown, section) {
+  const headingRe = /^(#{1,6})\\s+(.+)$/gm;
+  const headings = [];
+  let match;
+  while ((match = headingRe.exec(markdown)) !== null) {
+    headings.push({
+      level: match[1].length,
+      title: trimString(match[2]),
+      index: match.index,
+    });
+  }
+  const wanted = normalizeHeading(section);
+  const idx = headings.findIndex((h) => normalizeHeading(h.title) === wanted);
+  if (idx < 0) {
+    return {
+      found: false,
+      headings: headings.map((h) => h.title),
+    };
+  }
+  const current = headings[idx];
+  let end = markdown.length;
+  for (let i = idx + 1; i < headings.length; i++) {
+    if (headings[i].level <= current.level) {
+      end = headings[i].index;
+      break;
+    }
+  }
+  return {
+    found: true,
+    headings: headings.map((h) => h.title),
+    text: markdown.slice(current.index, end).trim(),
+  };
+}
+
+function sanitizeConfig(config) {
+  const cfg = config && typeof config === "object" ? config : {};
+  const generation = cfg.generation && typeof cfg.generation === "object" ? cfg.generation : {};
+  const retrieval = cfg.retrieval && typeof cfg.retrieval === "object" ? cfg.retrieval : {};
+  const embed = cfg.embed && typeof cfg.embed === "object" ? cfg.embed : {};
+  const rerank = cfg.rerank && typeof cfg.rerank === "object" ? cfg.rerank : {};
+  return {
+    version: cfg.version || null,
+    defaultKbId: KB_ID || null,
+    answerableGate: !!cfg.answerableGate,
+    dataDir: cfg.dataDir || null,
+    retrieval: {
+      topK: retrieval.topK ?? null,
+      candidatePool: retrieval.candidatePool ?? null,
+      rerankPool: retrieval.rerankPool ?? null,
+      rejectThreshold: retrieval.rejectThreshold ?? null,
+      chunkMode: retrieval.chunkMode || null,
+      parentChunkChars: retrieval.parentChunkChars ?? null,
+      childChunkChars: retrieval.childChunkChars ?? null,
+    },
+    embed: {
+      backend: embed.backend || null,
+      model: embed.model || null,
+      dim: embed.dim ?? null,
+      ollamaModel: embed.ollamaModel || null,
+    },
+    rerank: {
+      enabled: !!rerank.enabled,
+      external: !!rerank.external,
+      model: rerank.model || null,
+    },
+    generation: {
+      configured: !!(generation.baseUrl || generation.model || generation.apiKey),
+      baseUrl: sanitizeBaseUrl(generation.baseUrl),
+      model: generation.model || null,
+      apiKeyConfigured: !!generation.apiKey,
+    },
+  };
+}
+
+async function kbList() {
+  const payload = await readJson("kb_list", "/api/kb");
+  if (!Array.isArray(payload)) {
+    throw new Error("kb_list: upstream returned a non-array payload");
+  }
+  const rows = await Promise.all(payload.map(async (item) => {
+    const id = trimString(item?.id);
+    const row = {
+      id: id || null,
+      name: item?.name || null,
+      description: item?.description ?? null,
+      chunks: item?.chunks ?? null,
+      documents: item?.documents ?? item?.docCount ?? item?.documentCount ?? null,
+      createdAt: item?.created_at ?? null,
+      usable: false,
+      unavailableReason: null,
+    };
+    if (!id) {
+      row.unavailableReason = "missing id";
+      return row;
+    }
+    try {
+      const res = await fetchWithTimeout(
+        "kb_list",
+        "/api/kb/" + encodeURIComponent(id) + "/documents",
+        { headers: { Accept: "application/json" } },
+      );
+      if (res.ok) {
+        const docs = await res.json();
+        const docRows = documentArrayFromPayload(docs);
+        if (docRows) {
+          row.documents = docRows.length;
+        }
+        row.usable = true;
+        return row;
+      }
+      const txt = await res.text();
+      row.unavailableReason = "documents endpoint " + res.status + (txt ? ": " + txt.slice(0, 160) : "");
+      return row;
+    } catch (e) {
+      row.unavailableReason = e && e.message ? e.message : String(e);
+      return row;
+    }
+  }));
+  return rows;
+}
+
+async function kbCreate(name, kbId, description) {
+  const trimmedName = trimString(name);
+  if (!trimmedName) throw new Error("kb_create: missing 'name' argument");
+  const payload = { name: trimmedName };
+  const explicitId = trimString(kbId);
+  const explicitDescription = trimString(description);
+  if (explicitId) payload.id = explicitId;
+  if (explicitDescription) payload.description = explicitDescription;
+  const result = await readJson("kb_create", "/api/kb", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  return {
+    id: result?.id || payload.id || null,
+    name: result?.name || trimmedName,
+    description: result?.description ?? payload.description ?? null,
+    createdAt: result?.created_at ?? null,
+  };
+}
+
+async function kbGetCapabilities() {
+  const payload = await readJson("kb_get_capabilities", "/api/service/capabilities");
+  return {
+    contractVersion: payload?.contractVersion || null,
+    serviceVersion: payload?.serviceVersion || null,
+    auth: payload?.auth || null,
+    features: payload?.features || {},
+    limits: payload?.limits || {},
+    upload: payload?.upload ? {
+      shortFormats: payload.upload.shortFormats || [],
+      formatsDetail: payload.upload.formatsDetail || null,
+      extensions: payload.upload.extensions || [],
+    } : null,
+    routes: payload?.routes || null,
+  };
+}
+
+async function kbGet(kbIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_get");
+  const payload = await readJson(
+    "kb_get",
+    "/api/kb/" + encodePathPart(kbId),
+  );
+  return {
+    id: payload?.id || kbId,
+    name: payload?.name || null,
+    description: payload?.description ?? null,
+    documents: payload?.documents ?? payload?.docCount ?? payload?.documentCount ?? null,
+    chunks: payload?.chunks ?? null,
+    jobs: payload?.jobs ?? payload?.jobCount ?? null,
+    createdAt: payload?.created_at ?? payload?.createdAt ?? null,
+    config: payload?.config || payload?.retrieval || null,
+  };
+}
+
+async function kbSearch(query, kbIdRaw, topK) {
+  const trimmedQuery = trimString(query);
+  if (!trimmedQuery) throw new Error("kb_search: missing 'query' argument");
+  const kbId = defaultKbId(kbIdRaw, "kb_search");
+  const payload = await readJson(
+    "kb_search",
+    "/api/kb/" + encodeURIComponent(kbId) + "/search",
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ query: trimmedQuery, topK: clampTopK(topK) }),
+    },
+  );
+  return normalizeChunksResponse(payload);
+}
+
+async function kbUpload(absPath, kbIdRaw) {
+  const kbId = requireKbId(kbIdRaw, "kb_upload");
+  const checked = openUploadFile(absPath);
+  const filename = path.basename(checked.absPath);
+  let buf;
+  try {
+    buf = readBoundedUploadBuffer(checked.fd, checked.stat.size);
+    assertStableUploadRead(checked, buf);
+  } finally {
+    fs.closeSync(checked.fd);
+  }
+  const fd = new FormData();
+  fd.append("file", new Blob([buf]), filename);
+  const payload = await readJson(
+    "kb_upload",
+    "/api/kb/" + encodeURIComponent(kbId) + "/documents",
+    {
+      method: "POST",
+      body: fd,
+    },
+  );
+  const doc = payload?.doc && typeof payload.doc === "object" ? payload.doc : {};
+  return {
+    kbId,
+    documentId: doc.id || null,
+    title: doc.title || filename,
+    bytes: doc.bytes ?? checked.stat.size,
+    status: doc.status || null,
+    chunks: payload?.chunks ?? null,
+  };
+}
+
+async function kbListDocuments(kbIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_list_documents");
+  const payload = await readJson(
+    "kb_list_documents",
+    "/api/kb/" + encodeURIComponent(kbId) + "/documents",
+  );
+  const docs = documentArrayFromPayload(payload);
+  if (!docs) {
+    throw new Error("kb_list_documents: upstream returned a non-array document payload");
+  }
+  return docs.map((item) => normalizeDocument(item, kbId));
+}
+
+async function kbGetDocument(kbIdRaw, documentIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_get_document");
+  const documentId = trimString(documentIdRaw);
+  if (!documentId) throw new Error("kb_get_document: missing 'documentId' argument");
+  const payload = await readJson(
+    "kb_get_document",
+    "/api/kb/" + encodePathPart(kbId) + "/documents/" + encodePathPart(documentId),
+  );
+  return normalizeDocument(payload, kbId);
+}
+
+async function kbListDocumentChunks(kbIdRaw, documentIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_list_document_chunks");
+  const documentId = trimString(documentIdRaw);
+  if (!documentId) throw new Error("kb_list_document_chunks: missing 'documentId' argument");
+  const payload = await readJson(
+    "kb_list_document_chunks",
+    "/api/kb/" + encodePathPart(kbId) + "/documents/" + encodePathPart(documentId) + "/chunks",
+  );
+  const rawChunks = Array.isArray(payload) ? payload : Array.isArray(payload?.chunks) ? payload.chunks : null;
+  if (!rawChunks) {
+    throw new Error("kb_list_document_chunks: upstream returned a non-array chunks payload");
+  }
+  return rawChunks.map((item, idx) => {
+    const chunk = item && typeof item === "object" ? item : { text: String(item ?? "") };
+    const capped = cappedText(chunk.text || chunk.content || "", 1600);
+    return {
+      id: chunk.id ?? null,
+      chunkIndex: chunk.chunk_index ?? chunk.chunkIndex ?? idx,
+      page: chunk.page ?? null,
+      text: capped.text,
+      truncated: capped.truncated,
+      characters: capped.characters,
+    };
+  });
+}
+
+async function kbReadDocumentRaw(kbIdRaw, documentIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_read_document_raw");
+  const documentId = trimString(documentIdRaw);
+  if (!documentId) throw new Error("kb_read_document_raw: missing 'documentId' argument");
+  const res = await fetchWithTimeout(
+    "kb_read_document_raw",
+    "/api/kb/" + encodePathPart(kbId) + "/documents/" + encodePathPart(documentId) + "/raw",
+    { headers: { Accept: "text/plain, application/octet-stream;q=0.5, */*;q=0.1" } },
+  );
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error("kb_read_document_raw: upstream " + res.status + ": " + txt.slice(0, 400));
+  }
+  const capped = await readBoundedTextResponse("kb_read_document_raw", res, MAX_TEXT_RESPONSE_CHARS);
+  return {
+    kbId,
+    documentId,
+    contentType: res.headers.get("content-type") || null,
+    contentDisposition: res.headers.get("content-disposition") || null,
+    text: capped.text,
+    truncated: capped.truncated,
+    characters: capped.characters,
+    bytesRead: capped.bytesRead,
+    contentLength: capped.contentLength,
+  };
+}
+
+async function kbListDocumentFaq(kbIdRaw, documentIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_list_document_faq");
+  const documentId = trimString(documentIdRaw);
+  if (!documentId) throw new Error("kb_list_document_faq: missing 'documentId' argument");
+  const payload = await readJson(
+    "kb_list_document_faq",
+    "/api/kb/" + encodePathPart(kbId) + "/documents/" + encodePathPart(documentId) + "/faq",
+  );
+  const faqs = Array.isArray(payload) ? payload : Array.isArray(payload?.faqs) ? payload.faqs : null;
+  if (!faqs) {
+    throw new Error("kb_list_document_faq: upstream returned a non-array FAQ payload");
+  }
+  return faqs;
+}
+
+async function kbReindexDocument(kbIdRaw, documentIdRaw, confirmDocumentIdRaw) {
+  const kbId = requireKbId(kbIdRaw, "kb_reindex_document");
+  const documentId = trimString(documentIdRaw);
+  if (!documentId) throw new Error("kb_reindex_document: missing 'documentId' argument");
+  requireConfirm(confirmDocumentIdRaw, documentId, "kb_reindex_document", "confirmDocumentId");
+  const payload = await readJson(
+    "kb_reindex_document",
+    "/api/kb/" + encodePathPart(kbId) + "/documents/" + encodePathPart(documentId) + "/reindex",
+    { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}" },
+  );
+  return {
+    kbId,
+    documentId,
+    doc: payload?.doc ? normalizeDocument(payload.doc, kbId) : null,
+    parents: payload?.parents ?? null,
+    chunks: payload?.chunks ?? null,
+    removedChunks: payload?.removedChunks ?? null,
+    faqRegeneration: payload?.faqRegeneration || null,
+    sourceGeneration: payload?.sourceGeneration || null,
+  };
+}
+
+async function kbImportUrl(args) {
+  const kbId = requireKbId(args?.kbId, "kb_import_url");
+  const url = trimString(args?.url);
+  if (!url) throw new Error("kb_import_url: missing 'url' argument");
+  const asyncMode = boolWithDefault(args?.async, true);
+  const payload = { url };
+  for (const key of ["origin", "sourcePath", "batchId", "clientItemId", "externalAssetId"]) {
+    const value = optionalString(args?.[key]);
+    if (value) payload[key] = value;
+  }
+  const headers = { "Content-Type": "application/json" };
+  const idempotencyKey = optionalString(args?.idempotencyKey);
+  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+  const result = await readJson(
+    "kb_import_url",
+    "/api/kb/" + encodePathPart(kbId) + "/import" + (asyncMode ? "?async=true" : ""),
+    { method: "POST", headers, body: JSON.stringify(payload) },
+  );
+  return {
+    kbId,
+    async: asyncMode,
+    sourceUrl: result?.sourceUrl || null,
+    job: result?.job ? normalizeJob(result.job, kbId) : null,
+    doc: result?.doc ? normalizeDocument(result.doc, kbId) : null,
+    chunks: result?.chunks ?? null,
+    parents: result?.parents ?? null,
+    idempotencyKey: result?.idempotencyKey || idempotencyKey || null,
+    replayed: !!result?.replayed,
+  };
+}
+
+async function kbListJobs(args) {
+  const kbId = defaultKbId(args?.kbId, "kb_list_jobs");
+  const qs = new URLSearchParams();
+  const limit = positiveInt(args?.limit, null, 100);
+  if (limit) qs.set("limit", String(limit));
+  appendOptionalQuery(qs, "cursor", args?.cursor);
+  appendOptionalQuery(qs, "status", args?.status);
+  appendOptionalQuery(qs, "clientItemId", args?.clientItemId);
+  appendOptionalQuery(qs, "batchId", args?.batchId);
+  const query = qs.toString();
+  const payload = await readJson(
+    "kb_list_jobs",
+    "/api/kb/" + encodePathPart(kbId) + "/jobs" + (query ? "?" + query : ""),
+  );
+  const jobs = jobArrayFromPayload(payload);
+  if (!jobs) {
+    throw new Error("kb_list_jobs: upstream returned a non-array jobs payload");
+  }
+  return {
+    jobs: jobs.map((item) => normalizeJob(item, kbId)),
+    nextCursor: payload?.nextCursor ?? null,
+    totalEstimate: payload?.totalEstimate ?? null,
+    limit: payload?.limit ?? limit ?? null,
+  };
+}
+
+async function kbGetJob(kbIdRaw, jobIdRaw) {
+  const kbId = defaultKbId(kbIdRaw, "kb_get_job");
+  const jobId = trimString(jobIdRaw);
+  if (!jobId) throw new Error("kb_get_job: missing 'jobId' argument");
+  const payload = await readJson(
+    "kb_get_job",
+    "/api/kb/" + encodePathPart(kbId) + "/jobs/" + encodePathPart(jobId),
+  );
+  return normalizeJob(payload, kbId);
+}
+
+async function kbRetryJob(kbIdRaw, jobIdRaw) {
+  const kbId = requireKbId(kbIdRaw, "kb_retry_job");
+  const jobId = trimString(jobIdRaw);
+  if (!jobId) throw new Error("kb_retry_job: missing 'jobId' argument");
+  const payload = await readJson(
+    "kb_retry_job",
+    "/api/kb/" + encodePathPart(kbId) + "/jobs/" + encodePathPart(jobId) + "/retry",
+    { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}" },
+  );
+  return normalizeJob(payload, kbId);
+}
+
+async function kbCancelJob(kbIdRaw, jobIdRaw, confirmJobIdRaw) {
+  const kbId = requireKbId(kbIdRaw, "kb_cancel_job");
+  const jobId = trimString(jobIdRaw);
+  if (!jobId) throw new Error("kb_cancel_job: missing 'jobId' argument");
+  requireConfirm(confirmJobIdRaw, jobId, "kb_cancel_job", "confirmJobId");
+  const payload = await readJson(
+    "kb_cancel_job",
+    "/api/kb/" + encodePathPart(kbId) + "/jobs/" + encodePathPart(jobId) + "/cancel",
+    { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}" },
+  );
+  return normalizeJob(payload, kbId);
+}
+
+async function kbReadHandbook(section) {
+  const markdown = await readText("kb_read_handbook", "/handbook.md");
+  const wanted = trimString(section);
+  if (!wanted) return markdown;
+  const extracted = extractMarkdownSection(markdown, wanted);
+  if (!extracted.found) {
+    throw new Error(
+      "kb_read_handbook: section not found: " + wanted +
+      ". Available sections: " + extracted.headings.join(", "),
+    );
+  }
+  return extracted.text;
+}
+
+async function kbGetConfig() {
+  const payload = await readJson("kb_get_config", "/api/admin/config");
+  return sanitizeConfig(payload);
+}
+
+async function kbDeleteDocument(kbIdRaw, documentIdRaw, confirmDocumentIdRaw) {
+  const kbId = requireKbId(kbIdRaw, "kb_delete_document");
+  const documentId = trimString(documentIdRaw);
+  if (!documentId) throw new Error("kb_delete_document: missing 'documentId' argument");
+  requireConfirm(confirmDocumentIdRaw, documentId, "kb_delete_document", "confirmDocumentId");
+  const payload = await readJson(
+    "kb_delete_document",
+    "/api/kb/" + encodeURIComponent(kbId) + "/documents/" + encodeURIComponent(documentId),
+    { method: "DELETE" },
+  );
+  return {
+    ok: payload?.ok !== false,
+    kbId,
+    documentId,
+  };
+}
+
+async function kbDeleteKb(kbIdRaw, confirmKbIdRaw) {
+  const kbId = requireKbId(kbIdRaw, "kb_delete_kb");
+  requireConfirm(confirmKbIdRaw, kbId, "kb_delete_kb", "confirmKbId");
+  const payload = await readJson(
+    "kb_delete_kb",
+    "/api/kb/" + encodeURIComponent(kbId),
+    { method: "DELETE" },
+  );
+  return {
+    ok: payload?.ok !== false,
+    kbId,
+  };
+}
+
+const TOOLS = [
+  {
+    name: "kb_list",
+    description: "List knowledge bases and validate whether each id can be used by document/search APIs. Returns documents=file count and chunks=index chunk count; use documents when the user asks how many files are in a KB. Only use entries with usable=true for follow-up calls.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "kb_get_capabilities",
+    description: "Read the JishuShell-KB external-control capability summary, including enabled features, upload formats, limits, and route inventory pointer. Does not expose secrets.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "kb_create",
+    description: "Create a new knowledge base. Use when the user asks to create a new KB before uploading or organizing documents.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Human-readable KB name" },
+        id: { type: "string", description: "Optional explicit KB id" },
+        description: { type: "string", description: "Optional KB description" },
+      },
+      required: ["name"],
+    },
+  },
+  {
+    name: "kb_get",
+    description: "Read one knowledge base's metadata, counts, and safe retrieval/config summary. If kbId is omitted the wired default KB is used.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+      },
+    },
+  },
+  {
+    name: "kb_search",
+    description: "Search a knowledge base for chunks relevant to a question. Use whenever the user asks something likely answered by indexed documents. If kbId is omitted the default KB is used.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "The user question, in their original language" },
+        kbId: { type: "string", description: "Optional explicit KB id; defaults to the wired default KB" },
+        topK: { type: "number", description: "Optional number of chunks to retrieve (1-20, default 6)" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "kb_upload",
+    description: "Upload and index a host-side file into a specific knowledge base. Use after drive_resolve_local_path. Only files under this instance's mounted files roots are accepted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute host path from drive_resolve_local_path" },
+        kbId: { type: "string", description: "Target KB id (required for writes)" },
+      },
+      required: ["path", "kbId"],
+    },
+  },
+  {
+    name: "kb_list_documents",
+    description: "List indexed documents in a knowledge base. Use before document deletion or when the user asks what a KB currently contains.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+      },
+    },
+  },
+  {
+    name: "kb_get_document",
+    description: "Read one indexed document's metadata and derived counts. Use after kb_list_documents when the user asks about a specific document.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+        documentId: { type: "string", description: "Document id to inspect" },
+      },
+      required: ["documentId"],
+    },
+  },
+  {
+    name: "kb_list_document_chunks",
+    description: "List indexed chunks for a document. Use to inspect why search matched a document or to debug chunking. Chunk text is capped in the MCP response.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+        documentId: { type: "string", description: "Document id to inspect" },
+      },
+      required: ["documentId"],
+    },
+  },
+  {
+    name: "kb_read_document_raw",
+    description: "Read the original stored document text for a document id. Use only when the user asks to inspect the source document or search snippets are insufficient. Output is capped.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+        documentId: { type: "string", description: "Document id to read" },
+      },
+      required: ["documentId"],
+    },
+  },
+  {
+    name: "kb_list_document_faq",
+    description: "List generated FAQ suggestions for a document, if the KB has generated any.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+        documentId: { type: "string", description: "Document id to inspect" },
+      },
+      required: ["documentId"],
+    },
+  },
+  {
+    name: "kb_reindex_document",
+    description: "Rebuild one document's chunks, vectors, and FAQ suggestions from the stored raw file. This is a write/repair action; only use after explicit user confirmation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Target KB id" },
+        documentId: { type: "string", description: "Document id to reindex" },
+        confirmDocumentId: { type: "string", description: "Must exactly equal documentId" },
+      },
+      required: ["kbId", "documentId", "confirmDocumentId"],
+    },
+  },
+  {
+    name: "kb_import_url",
+    description: "Fetch a readable remote URL and index its extracted text into a specific KB. Defaults to async=true and returns an ingest job; use kb_get_job to check progress.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Target KB id (required for writes)" },
+        url: { type: "string", description: "User-provided URL to import" },
+        async: { type: "boolean", description: "Whether to enqueue async ingest; defaults to true" },
+        idempotencyKey: { type: "string", description: "Optional idempotency key for safe retries" },
+        origin: { type: "string", description: "Optional provenance origin" },
+        sourcePath: { type: "string", description: "Optional caller-visible source path" },
+        batchId: { type: "string", description: "Optional batch id" },
+        clientItemId: { type: "string", description: "Optional caller item id" },
+        externalAssetId: { type: "string", description: "Optional external asset id" },
+      },
+      required: ["kbId", "url"],
+    },
+  },
+  {
+    name: "kb_list_jobs",
+    description: "List recent ingest jobs for a KB, with optional status/clientItemId/batchId filters and pagination.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+        limit: { type: "number", description: "Optional page size, max 100" },
+        cursor: { type: "string", description: "Optional pagination cursor" },
+        status: { type: "string", description: "Optional job status filter" },
+        clientItemId: { type: "string", description: "Optional client item id filter" },
+        batchId: { type: "string", description: "Optional batch id filter" },
+      },
+    },
+  },
+  {
+    name: "kb_get_job",
+    description: "Read one ingest job's current status and provenance.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Optional KB id; defaults to the wired default KB" },
+        jobId: { type: "string", description: "Ingest job id" },
+      },
+      required: ["jobId"],
+    },
+  },
+  {
+    name: "kb_retry_job",
+    description: "Retry one failed or cancelled ingest job. This is a write/repair action; use only when the user asks to retry.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Target KB id" },
+        jobId: { type: "string", description: "Ingest job id to retry" },
+      },
+      required: ["kbId", "jobId"],
+    },
+  },
+  {
+    name: "kb_cancel_job",
+    description: "Cancel one queued or running ingest job. Only use after explicit user confirmation. The confirmation field must exactly equal the target job id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Target KB id" },
+        jobId: { type: "string", description: "Ingest job id to cancel" },
+        confirmJobId: { type: "string", description: "Must exactly equal jobId" },
+      },
+      required: ["kbId", "jobId", "confirmJobId"],
+    },
+  },
+  {
+    name: "kb_read_handbook",
+    description: "Read the JishuShell-KB handbook. Use this to answer how the KB settings work or what a handbook section says. Section matching uses exact heading text after whitespace normalization.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        section: { type: "string", description: "Optional exact handbook heading to extract" },
+      },
+    },
+  },
+  {
+    name: "kb_get_config",
+    description: "Read a sanitized summary of the current JishuShell-KB configuration. Secrets are redacted; this is safe for explaining retrieval/model settings to the user.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "kb_delete_document",
+    description: "Delete a document from a specific knowledge base. Only use after explicit user confirmation. The confirmation field must exactly equal the target document id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "Target KB id" },
+        documentId: { type: "string", description: "Document id to delete" },
+        confirmDocumentId: { type: "string", description: "Must exactly equal documentId" },
+      },
+      required: ["kbId", "documentId", "confirmDocumentId"],
+    },
+  },
+  {
+    name: "kb_delete_kb",
+    description: "Delete an entire knowledge base. Only use after explicit user confirmation. The confirmation field must exactly equal the target kbId.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kbId: { type: "string", description: "KB id to delete" },
+        confirmKbId: { type: "string", description: "Must exactly equal kbId" },
+      },
+      required: ["kbId", "confirmKbId"],
+    },
+  },
+];
+
+function reply(id, result, error) {
+  const msg = { jsonrpc: "2.0", id: id };
+  if (error) msg.error = { code: -32603, message: error.message || String(error) };
+  else msg.result = result;
+  process.stdout.write(JSON.stringify(msg) + "\\n");
+}
+
+async function handle(req) {
+  const { id, method, params } = req;
+  try {
+    if (method === "initialize") {
+      reply(id, {
+        protocolVersion: "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "jishukb-shim", version: ${JSON.stringify(JISHUKB_MCP_SHIM_VERSION)} },
+      });
+      return;
+    }
+    if (method === "tools/list") {
+      reply(id, { tools: TOOLS });
+      return;
+    }
+    if (method === "tools/call") {
+      const tool = params?.name;
+      const a = params?.arguments || {};
+      if (tool === "kb_list") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbList()) }] });
+      } else if (tool === "kb_get_capabilities") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbGetCapabilities()) }] });
+      } else if (tool === "kb_create") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbCreate(a.name, a.id, a.description)) }] });
+      } else if (tool === "kb_get") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbGet(a.kbId)) }] });
+      } else if (tool === "kb_search") {
+        reply(id, { content: [{ type: "text", text: fmtSearchResult(await kbSearch(a.query, a.kbId, a.topK)) }] });
+      } else if (tool === "kb_upload") {
+        const result = await kbUpload(a.path, a.kbId);
+        reply(id, {
+          content: [{ type: "text", text:
+            "✅ indexed into KB " + result.kbId +
+            ": " + result.title +
+            " (documentId=" + (result.documentId || "?") +
+            ", bytes=" + result.bytes +
+            ", chunks=" + (result.chunks != null ? result.chunks : "?") + ")"
+          }],
+        });
+      } else if (tool === "kb_list_documents") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbListDocuments(a.kbId)) }] });
+      } else if (tool === "kb_get_document") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbGetDocument(a.kbId, a.documentId)) }] });
+      } else if (tool === "kb_list_document_chunks") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbListDocumentChunks(a.kbId, a.documentId)) }] });
+      } else if (tool === "kb_read_document_raw") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbReadDocumentRaw(a.kbId, a.documentId)) }] });
+      } else if (tool === "kb_list_document_faq") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbListDocumentFaq(a.kbId, a.documentId)) }] });
+      } else if (tool === "kb_reindex_document") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbReindexDocument(a.kbId, a.documentId, a.confirmDocumentId)) }] });
+      } else if (tool === "kb_import_url") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbImportUrl(a)) }] });
+      } else if (tool === "kb_list_jobs") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbListJobs(a)) }] });
+      } else if (tool === "kb_get_job") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbGetJob(a.kbId, a.jobId)) }] });
+      } else if (tool === "kb_retry_job") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbRetryJob(a.kbId, a.jobId)) }] });
+      } else if (tool === "kb_cancel_job") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbCancelJob(a.kbId, a.jobId, a.confirmJobId)) }] });
+      } else if (tool === "kb_read_handbook") {
+        reply(id, { content: [{ type: "text", text: await kbReadHandbook(a.section) }] });
+      } else if (tool === "kb_get_config") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbGetConfig()) }] });
+      } else if (tool === "kb_delete_document") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbDeleteDocument(a.kbId, a.documentId, a.confirmDocumentId)) }] });
+      } else if (tool === "kb_delete_kb") {
+        reply(id, { content: [{ type: "text", text: jsonText(await kbDeleteKb(a.kbId, a.confirmKbId)) }] });
+      } else {
+        throw new Error("unknown tool: " + tool);
+      }
+      return;
+    }
+    if (method === "notifications/initialized") {
+      return;
+    }
+    if (typeof method === "string" && method.startsWith("notifications/")) {
+      return;
+    }
+    if (id !== undefined) {
+      reply(id, null, new Error("method not implemented: " + method));
+    }
+  } catch (e) {
+    reply(id, null, e);
+  }
+}
+
+let inbuf = "";
+process.stdin.setEncoding("utf-8");
+process.stdin.on("data", (chunk) => {
+  inbuf += chunk;
+  let idx;
+  while ((idx = inbuf.indexOf("\\n")) >= 0) {
+    const line = inbuf.slice(0, idx).trim();
+    inbuf = inbuf.slice(idx + 1);
+    if (!line) continue;
+    let req;
+    try { req = JSON.parse(line); } catch { continue; }
+    void handle(req);
+  }
+});
+process.stdin.on("end", () => process.exit(0));
+`;
+/**
+ * Substitute baked-in NON-SECRET values into the shim source.
+ *
+ * Same pattern as `substituteAnythingllmShimPlaceholders` — done at install
+ * time because OpenClaw scrubs env on MCP subprocess spawn.
+ */
+export function substituteJishukbShimPlaceholders(params) {
+    const escapeStr = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    return JISHUKB_MCP_SHIM_SOURCE
+        .replace(/__JS_BASE_URL__/g, escapeStr(params.baseUrl))
+        .replace(/__JS_KB_ID__/g, escapeStr(params.kbId || ""))
+        .replace(/__JS_ALLOWED_UPLOAD_ROOTS__/g, escapeStr(JSON.stringify(params.allowedUploadRoots)));
+}
+//# sourceMappingURL=jishukb-shim.js.map