@hiai-gg/docsmint 0.10.0 → 1.0.2

package/dist/mcp-server.js

@@ -571,7 +571,7 @@ var RESOURCE_PERMISSIONS = new Set([
   "write"
 ]);
 // ../mcp-server/src/compact.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // ../mcp-server/src/output-schemas.ts
 import { z } from "zod";
@@ -850,140 +850,339 @@ var toolOutputSchemas = {
   explore_graph: z.union([
     variant("neighbors", operationOutputSchemas.get_related_documents),
     variant("search", operationOutputSchemas.search_knowledge_graph)
+  ]),
+  batch_documents: z.looseObject({
+    action: z.enum(["move", "set_category", "add_tag", "remove_tag", "trash", "restore", "refresh_index"]),
+    total: z.number().int().min(1).max(25),
+    succeeded: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    aborted: z.boolean(),
+    results: z.array(z.union([
+      z.looseObject({ id: z.string().uuid(), status: z.literal("ok") }),
+      z.looseObject({ id: z.string().uuid(), status: z.literal("error"), error: z.looseObject({ status: z.number().int(), code: z.string(), message: z.string() }) }),
+      z.looseObject({ id: z.string().uuid(), status: z.literal("skipped") })
+    ]))
+  }),
+  get_workspace_item: z.union([
+    variant("folder", folderSchema),
+    variant("category", categoryListItemSchema),
+    variant("tag", tagSchema)
   ])
 };
 
+// ../mcp-server/src/batch-workspace.ts
+import { z as z2 } from "zod";
+
+// ../mcp-server/src/client.ts
+var DEFAULT_BASE_URL = "http://localhost:50700";
+function readConfig() {
+  const baseUrl = (process.env.HIAI_DOCS_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const apiKey = process.env.HIAI_DOCS_API_KEY;
+  return { baseUrl, apiKey: apiKey || undefined };
+}
+
+class HiaiDocsError extends Error {
+  status;
+  body;
+  code;
+  constructor(message, status, body, code = `http_${status}`) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.code = code;
+    this.name = "HiaiDocsError";
+  }
+}
+function sanitizeMcpRequestContext(context) {
+  if (!context)
+    return;
+  const headers = new Headers(context.headers);
+  if (context.workspaceAssertion) {
+    headers.delete("Authorization");
+    headers.delete("Cookie");
+  }
+  return {
+    ...context,
+    authorization: context.workspaceAssertion ? undefined : context.authorization,
+    cookie: context.workspaceAssertion ? undefined : context.cookie,
+    headers
+  };
+}
+function createMcpDocsClient(docsClient, requestContext) {
+  const context = sanitizeMcpRequestContext(requestContext);
+  return {
+    getFolder: (id) => docsClient.getFolder(id, context),
+    createTag: (input) => docsClient.createTag(input, context),
+    updateTag: (id, input) => docsClient.updateTag(id, input, context),
+    deleteTag: (id) => docsClient.deleteTag(id, context),
+    addTagToDocument: (documentId, tagId) => docsClient.addTagToDoc(documentId, tagId, context),
+    removeTagFromDocument: (documentId, tagId) => docsClient.removeTagFromDoc(documentId, tagId, context),
+    updateFolder: (id, input) => docsClient.updateFolder(id, input, context),
+    updateCategory: (id, input) => docsClient.updateCategory(id, input, context),
+    listTrash: () => docsClient.listTrash(context),
+    restoreTrashedDocument: (id) => docsClient.restoreTrashedDocument(id, context),
+    permanentlyDeleteDocument: (id) => docsClient.permanentlyDeleteDocument(id, context),
+    deleteDocument: (id) => docsClient.deleteDoc(id, context),
+    deleteFolder: (id) => docsClient.deleteFolder(id, context),
+    deleteCategory: (id) => docsClient.deleteCategory(id, context),
+    restoreDocumentVersion: (documentId, versionId) => docsClient.restoreVersion(documentId, versionId, context),
+    search: (params) => docsClient.search(params.query, {
+      folder: params.folder,
+      tags: params.tags?.join(","),
+      limit: params.limit
+    }, context),
+    getDocument: (id) => docsClient.getDoc(id, context),
+    createDocument: (input) => docsClient.createDoc({
+      ...input,
+      folderId: input.folderId ?? undefined,
+      categoryId: input.categoryId ?? undefined
+    }, context),
+    updateDocument: (id, input) => docsClient.updateDoc(id, input, context),
+    listDocuments: (params) => docsClient.listDocs(params, context),
+    listFolders: (params) => docsClient.listFolders(params.parentId, context),
+    createFolder: (input) => docsClient.createFolder(input, context),
+    listCategories: () => docsClient.listCategories(context),
+    createCategory: (input) => docsClient.createCategory(input, context),
+    listTags: () => docsClient.listTags(context),
+    getRelatedDocuments: (documentId, limit) => docsClient.getRelatedDocuments(documentId, context, { limit }),
+    searchGraph: (input) => docsClient.searchGraph({ query: input.query, docIds: input.docIds, maxResults: input.limit }, context),
+    getDocumentIndexStatus: (documentId) => docsClient.getDocumentIndexStatus(documentId, context),
+    refreshDocumentIndex: (documentId) => docsClient.refreshDocumentIndex(documentId, context),
+    createSnapshot: (documentId, input) => docsClient.createSnapshot(documentId, input, context),
+    getVersionHistory: (documentId, onlySnapshots) => docsClient.listVersions(documentId, { onlySnapshots }, context),
+    exportDocument: async (id) => ({ markdown: await docsClient.exportDoc(id, context) })
+  };
+}
+function createDefaultDocsClient() {
+  const { baseUrl, apiKey } = readConfig();
+  return new DocsClient({ baseUrl, apiKey, retries: 1 });
+}
+var client = new Proxy({}, {
+  get(_target, property) {
+    const configured = createMcpDocsClient(createDefaultDocsClient());
+    const value = configured[property];
+    return typeof value === "function" ? value.bind(configured) : value;
+  }
+});
+
+// ../mcp-server/src/batch-workspace.ts
+var uuid = z2.string().uuid().describe("UUID of an item visible to the active API key.");
+var documentIds = z2.array(uuid).min(1).max(25).refine((ids) => new Set(ids).size === ids.length, "Document IDs must be unique.").describe("One to 25 distinct document UUIDs, explicitly selected by the user; no search expansion.");
+var base = { documentIds };
+var batchInput = z2.discriminatedUnion("action", [
+  z2.strictObject({ ...base, action: z2.literal("move").describe("Move each document to the same folder."), folderId: uuid.nullable().describe("Destination folder UUID, or null for no folder.") }),
+  z2.strictObject({ ...base, action: z2.literal("set_category").describe("Set one explicit category on every document."), categoryId: uuid.nullable().describe("Category UUID, or null to clear explicit category.") }),
+  z2.strictObject({ ...base, action: z2.literal("add_tag").describe("Assign one existing tag to every document."), tagId: uuid.describe("Existing tag UUID to assign to each document.") }),
+  z2.strictObject({ ...base, action: z2.literal("remove_tag").describe("Remove one tag assignment from every document."), tagId: uuid.describe("Existing tag UUID to unassign from each document.") }),
+  z2.strictObject({ ...base, action: z2.literal("trash").describe("Move every document to trash without permanent deletion.") }),
+  z2.strictObject({ ...base, action: z2.literal("restore").describe("Restore every selected document from trash.") }),
+  z2.strictObject({ ...base, action: z2.literal("refresh_index").describe("Request explicit indexing retry for every document.") })
+]);
+function required(method, name) {
+  if (!method)
+    throw new Error(`The injected legacy MCP client does not support ${name}; use a public DocsClient.`);
+  return method;
+}
+function registerBatchAndWorkspaceCapabilities(server, client2, wrap) {
+  async function batch(input) {
+    const results = [];
+    let aborted = false;
+    for (const id of input.documentIds) {
+      if (aborted) {
+        results.push({ id, status: "skipped" });
+        continue;
+      }
+      try {
+        switch (input.action) {
+          case "move":
+            await client2.updateDocument(id, { folderId: input.folderId });
+            break;
+          case "set_category":
+            await client2.updateDocument(id, { categoryId: input.categoryId });
+            break;
+          case "add_tag":
+            await required(client2.addTagToDocument, "add_tag")(id, input.tagId);
+            break;
+          case "remove_tag":
+            await required(client2.removeTagFromDocument, "remove_tag")(id, input.tagId);
+            break;
+          case "trash":
+            await required(client2.deleteDocument, "trash")(id);
+            break;
+          case "restore":
+            await required(client2.restoreTrashedDocument, "restore")(id);
+            break;
+          case "refresh_index":
+            await client2.refreshDocumentIndex(id);
+            break;
+        }
+        results.push({ id, status: "ok" });
+      } catch (error) {
+        const known = isDocsApiError(error) || error instanceof HiaiDocsError;
+        const status = known ? error.status : 500;
+        const code = known ? error.code : "INTERNAL_ERROR";
+        results.push({ id, status: "error", error: { status, code, message: known ? error.message : "Document operation failed" } });
+        if (status === 401 || status === 429)
+          aborted = true;
+      }
+    }
+    const succeeded = results.filter((result) => result.status === "ok").length;
+    return { action: input.action, total: input.documentIds.length, succeeded, failed: results.filter((result) => result.status === "error").length, aborted, results };
+  }
+  server.registerTool("batch_documents", {
+    description: "Use for multiple explicitly selected documents that need the same action; for one document prefer the matching single-document tool. Accepts 1\u201325 IDs for automation compatibility. Supports move, set_category, add_tag, remove_tag, trash, restore, or refresh_index. Processes sequentially through the existing API with a permission check per document and a per-ID result; partial success is possible. Stops after authentication or rate-limit failure. Never expands a search result or permanently purges documents; version restore is separate.",
+    inputSchema: batchInput,
+    outputSchema: toolOutputSchemas.batch_documents,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+  }, wrap("batch_documents", batch, toolOutputSchemas.batch_documents));
+  server.registerTool("get_workspace_item", {
+    description: "Read one visible folder, category, or tag by UUID. Folder uses its direct API getter; category and tag lookup uses the complete permission-filtered lists. An absent or out-of-scope ID is reported as not found. Use list_workspace_structure to discover IDs first.",
+    inputSchema: z2.strictObject({ kind: z2.enum(["folder", "category", "tag"]).describe("The workspace resource type to read by ID."), id: uuid }),
+    outputSchema: toolOutputSchemas.get_workspace_item,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, wrap("get_workspace_item", async ({ kind, id }) => {
+    if (kind === "folder")
+      return { operation: kind, result: await required(client2.getFolder, "get_workspace_item(folder)")(id) };
+    const listed = kind === "category" ? await client2.listCategories() : await client2.listTags();
+    const result = Array.isArray(listed) ? listed.find((item) => item.id === id) : undefined;
+    if (!result)
+      throw new HiaiDocsError(`${kind} not found`, 404, null, "NOT_FOUND");
+    return { operation: kind, result };
+  }, toolOutputSchemas.get_workspace_item));
+}
+
 // ../mcp-server/src/compact.ts
-var uuid = z2.string().uuid().describe("UUID returned by the corresponding list or read operation.");
-var text = z2.string().min(1).describe("Non-empty human-readable name or title.");
-var title = z2.string().min(1).max(500).describe("Document title, from 1 to 500 characters.");
-var content = z2.string().describe("Markdown document content; an empty string clears the content on update.");
+var uuid2 = z3.string().uuid().describe("UUID returned by the corresponding list or read operation.");
+var text = z3.string().min(1).describe("Non-empty human-readable name or title.");
+var title = z3.string().min(1).max(500).describe("Document title, from 1 to 500 characters.");
+var content = z3.string().describe("Markdown document content; an empty string clears the content on update.");
 var read = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 var write = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
 var destructive = { ...write, destructiveHint: true };
-function required(value, name) {
+function required2(value, name) {
   if (!value)
     throw new Error(`The injected legacy MCP client does not support ${name}; use a public DocsClient.`);
   return value;
 }
-function registerCompactCapabilities(server, client, wrap) {
+function registerCompactCapabilities(server, client2, wrap) {
   function register(name, description, inputSchema, annotations, handler) {
     server.registerTool(name, { description, inputSchema, outputSchema: toolOutputSchemas[name], annotations }, wrap(name, handler, toolOutputSchemas[name]));
   }
-  register("find_documents", "Find readable documents in the active scope. Use mode=list for paginated browsing by folder or tag UUID; use mode=search for hybrid text and semantic retrieval with tag names.", z2.discriminatedUnion("mode", [
-    z2.strictObject({ mode: z2.literal("list").describe("Select the list operation explicitly."), folderId: uuid.optional(), tag: uuid.optional(), page: z2.number().int().min(1).optional().describe("One-based page number; defaults to the API first page."), limit: z2.number().int().min(1).max(1000).optional().describe("Maximum documents per page, up to 1000.") }),
-    z2.strictObject({ mode: z2.literal("search").describe("Select the search operation explicitly."), query: text.describe("Text to search in the original language."), folder: z2.string().optional().describe("Optional folder UUID filter for search."), tags: z2.array(z2.string()).optional().describe("Optional tag names; all supplied names must match."), limit: z2.number().int().min(1).max(100).optional().describe("Maximum results to return, up to 100.") })
-  ]), read, async (input) => input.mode === "list" ? { operation: "list", result: await client.listDocuments(input) } : { operation: "search", result: await client.search(input) });
-  register("read_document", "Read one document by UUID. Choose detail for content and metadata, markdown for portable export, or versions for saved revisions and snapshots. All views are read-only.", z2.discriminatedUnion("view", [
-    z2.strictObject({ view: z2.literal("detail").describe("Select the detail operation explicitly."), id: uuid }),
-    z2.strictObject({ view: z2.literal("markdown").describe("Select the markdown operation explicitly."), id: uuid }),
-    z2.strictObject({ view: z2.literal("versions").describe("Select the versions operation explicitly."), id: uuid, onlySnapshots: z2.boolean().optional().describe("When true, return only named snapshots.") })
+  register("find_documents", "Find readable documents in the active scope. Use mode=list for paginated browsing by folder or tag UUID; use mode=search for hybrid text and semantic retrieval with tag names.", z3.discriminatedUnion("mode", [
+    z3.strictObject({ mode: z3.literal("list").describe("Select the list operation explicitly."), folderId: uuid2.optional(), tag: uuid2.optional(), page: z3.number().int().min(1).optional().describe("One-based page number; defaults to the API first page."), limit: z3.number().int().min(1).max(1000).optional().describe("Maximum documents per page, up to 1000.") }),
+    z3.strictObject({ mode: z3.literal("search").describe("Select the search operation explicitly."), query: text.describe("Text to search in the original language."), folder: z3.string().optional().describe("Optional folder UUID filter for search."), tags: z3.array(z3.string()).optional().describe("Optional tag names; all supplied names must match."), limit: z3.number().int().min(1).max(100).optional().describe("Maximum results to return, up to 100.") })
+  ]), read, async (input) => input.mode === "list" ? { operation: "list", result: await client2.listDocuments(input) } : { operation: "search", result: await client2.search(input) });
+  register("read_document", "Read one document by UUID. Choose detail for content and metadata, markdown for portable export, or versions for saved revisions and snapshots. All views are read-only.", z3.discriminatedUnion("view", [
+    z3.strictObject({ view: z3.literal("detail").describe("Select the detail operation explicitly."), id: uuid2 }),
+    z3.strictObject({ view: z3.literal("markdown").describe("Select the markdown operation explicitly."), id: uuid2 }),
+    z3.strictObject({ view: z3.literal("versions").describe("Select the versions operation explicitly."), id: uuid2, onlySnapshots: z3.boolean().optional().describe("When true, return only named snapshots.") })
   ]), read, async (input) => {
     if (input.view === "detail")
-      return { operation: "detail", result: await client.getDocument(input.id) };
+      return { operation: "detail", result: await client2.getDocument(input.id) };
     if (input.view === "markdown")
-      return { operation: "markdown", result: await client.exportDocument(input.id) };
-    return { operation: "versions", result: await client.getVersionHistory(input.id, input.onlySnapshots) };
+      return { operation: "markdown", result: await client2.exportDocument(input.id) };
+    return { operation: "versions", result: await client2.getVersionHistory(input.id, input.onlySnapshots) };
   });
-  register("save_document", "Create a new document or update an existing document. action=create requires write access; action=update requires edit access for content, and placement changes may require write access. Content or placement changes queue normal indexing.", z2.discriminatedUnion("action", [
-    z2.strictObject({ action: z2.literal("create").describe("Select the create operation explicitly."), title: title.optional(), content: content.optional(), folderId: uuid.optional(), categoryId: uuid.nullable().optional().describe("Optional category UUID; null clears the explicit category.") }),
-    z2.strictObject({ action: z2.literal("update").describe("Select the update operation explicitly."), id: uuid, title: title.optional(), content: content.optional(), folderId: uuid.nullable().optional().describe("Optional folder UUID; null clears the placement on update."), categoryId: uuid.nullable().optional().describe("Optional category UUID; null clears the explicit category.") }).refine((value) => value.title !== undefined || value.content !== undefined || value.folderId !== undefined || value.categoryId !== undefined)
+  register("save_document", "Create or update one document. Use action=create for a new document or action=update for an existing one; batch_documents handles the same placement change across multiple existing documents. Creation requires write access; content edits require edit access, and placement changes may require write access. Content or placement changes queue normal indexing.", z3.discriminatedUnion("action", [
+    z3.strictObject({ action: z3.literal("create").describe("Select the create operation explicitly."), title: title.optional(), content: content.optional(), folderId: uuid2.optional(), categoryId: uuid2.nullable().optional().describe("Optional category UUID; null clears the explicit category.") }),
+    z3.strictObject({ action: z3.literal("update").describe("Select the update operation explicitly."), id: uuid2, title: title.optional(), content: content.optional(), folderId: uuid2.nullable().optional().describe("Optional folder UUID; null clears the placement on update."), categoryId: uuid2.nullable().optional().describe("Optional category UUID; null clears the explicit category.") }).refine((value) => value.title !== undefined || value.content !== undefined || value.folderId !== undefined || value.categoryId !== undefined)
   ]), destructive, async (input) => {
     if (input.action === "create") {
       const { action: _action2, ...data2 } = input;
-      return { operation: "create", result: await client.createDocument(data2) };
+      return { operation: "create", result: await client2.createDocument(data2) };
     }
     const { action: _action, id, ...data } = input;
-    return { operation: "update", result: await client.updateDocument(id, data) };
+    return { operation: "update", result: await client2.updateDocument(id, data) };
   });
-  register("delete_document", "Move a writable document to trash without purging content or versions. Use only on an explicit delete request; permanently_delete_document is a separate irreversible action.", z2.strictObject({ id: uuid }), destructive, async ({ id }) => {
-    await required(client.deleteDocument, "delete_document")(id);
+  register("delete_document", "Move one document to trash without purging content or versions. Use batch_documents(action=trash) for multiple explicit IDs. Requires write access and an explicit delete request; permanently_delete_document is a separate irreversible action.", z3.strictObject({ id: uuid2 }), destructive, async ({ id }) => {
+    await required2(client2.deleteDocument, "delete_document")(id);
     return { id, deleted: true };
   });
-  register("list_workspace_structure", "List visible folders, categories, or tags in the active workspace or category scope. Set kind=folders to inspect root folders or children of parentId.", z2.discriminatedUnion("kind", [
-    z2.strictObject({ kind: z2.literal("folders").describe("Select the folders operation explicitly."), parentId: uuid.optional() }),
-    z2.strictObject({ kind: z2.literal("categories").describe("Select the categories operation explicitly.") }),
-    z2.strictObject({ kind: z2.literal("tags").describe("Select the tags operation explicitly.") })
+  register("list_workspace_structure", "List visible folders, categories, or tags in the active workspace or category scope. Set kind=folders to inspect root folders or children of parentId.", z3.discriminatedUnion("kind", [
+    z3.strictObject({ kind: z3.literal("folders").describe("Select the folders operation explicitly."), parentId: uuid2.optional() }),
+    z3.strictObject({ kind: z3.literal("categories").describe("Select the categories operation explicitly.") }),
+    z3.strictObject({ kind: z3.literal("tags").describe("Select the tags operation explicitly.") })
   ]), read, async (input) => {
     if (input.kind === "folders")
-      return { operation: "folders", result: await client.listFolders({ parentId: input.parentId }) };
+      return { operation: "folders", result: await client2.listFolders({ parentId: input.parentId }) };
     if (input.kind === "categories")
-      return { operation: "categories", result: await client.listCategories() };
-    return { operation: "tags", result: await client.listTags() };
+      return { operation: "categories", result: await client2.listCategories() };
+    return { operation: "tags", result: await client2.listTags() };
   });
-  register("save_folder", "Create or update a folder. action=update can rename or move an existing folder; the API enforces category boundaries and queues affected documents for reindexing.", z2.discriminatedUnion("action", [
-    z2.strictObject({ action: z2.literal("create").describe("Select the create operation explicitly."), name: text.max(255), parentId: uuid.nullable().optional().describe("Optional parent folder UUID; null selects the root."), categoryId: uuid.nullable().optional().describe("Optional category UUID; null clears the explicit category.") }),
-    z2.strictObject({ action: z2.literal("update").describe("Select the update operation explicitly."), id: uuid, name: text.max(255).optional(), parentId: uuid.nullable().optional().describe("Optional parent folder UUID; null selects the root."), categoryId: uuid.nullable().optional().describe("Optional category UUID; null clears the explicit category."), order: z2.number().int().nonnegative().optional().describe("New non-negative display order.") }).refine((value) => value.name !== undefined || value.parentId !== undefined || value.categoryId !== undefined || value.order !== undefined)
+  register("save_folder", "Create or update a folder. action=update can rename or move an existing folder; the API enforces category boundaries and queues affected documents for reindexing.", z3.discriminatedUnion("action", [
+    z3.strictObject({ action: z3.literal("create").describe("Select the create operation explicitly."), name: text.max(255), parentId: uuid2.nullable().optional().describe("Optional parent folder UUID; null selects the root."), categoryId: uuid2.nullable().optional().describe("Optional category UUID; null clears the explicit category.") }),
+    z3.strictObject({ action: z3.literal("update").describe("Select the update operation explicitly."), id: uuid2, name: text.max(255).optional(), parentId: uuid2.nullable().optional().describe("Optional parent folder UUID; null selects the root."), categoryId: uuid2.nullable().optional().describe("Optional category UUID; null clears the explicit category."), order: z3.number().int().nonnegative().optional().describe("New non-negative display order.") }).refine((value) => value.name !== undefined || value.parentId !== undefined || value.categoryId !== undefined || value.order !== undefined)
   ]), destructive, async (input) => {
     if (input.action === "create") {
       const { action: _action2, ...data2 } = input;
-      return { operation: "create", result: await client.createFolder(data2) };
+      return { operation: "create", result: await client2.createFolder(data2) };
     }
     const { action: _action, id, ...data } = input;
-    return { operation: "update", result: await required(client.updateFolder, "update_folder")(id, data) };
+    return { operation: "update", result: await required2(client2.updateFolder, "update_folder")(id, data) };
   });
-  register("delete_folder", "Delete a folder while preserving its documents; child folders and documents are detached under the API rules. Requires write access.", z2.strictObject({ id: uuid }), destructive, async ({ id }) => {
-    await required(client.deleteFolder, "delete_folder")(id);
+  register("delete_folder", "Delete a folder while preserving its documents; child folders and documents are detached under the API rules. Requires write access.", z3.strictObject({ id: uuid2 }), destructive, async ({ id }) => {
+    await required2(client2.deleteFolder, "delete_folder")(id);
     return { id, deleted: true };
   });
-  register("save_category", "Create or update a workspace category. Full workspace write access is required; category-scoped credentials cannot manage categories.", z2.discriminatedUnion("action", [
-    z2.strictObject({ action: z2.literal("create").describe("Select the create operation explicitly."), name: text.max(255) }),
-    z2.strictObject({ action: z2.literal("update").describe("Select the update operation explicitly."), id: uuid, name: text.max(255).optional(), order: z2.number().int().nonnegative().optional().describe("New non-negative display order.") }).refine((value) => value.name !== undefined || value.order !== undefined)
+  register("save_category", "Create or update a workspace category. Full workspace write access is required; category-scoped credentials cannot manage categories.", z3.discriminatedUnion("action", [
+    z3.strictObject({ action: z3.literal("create").describe("Select the create operation explicitly."), name: text.max(255) }),
+    z3.strictObject({ action: z3.literal("update").describe("Select the update operation explicitly."), id: uuid2, name: text.max(255).optional(), order: z3.number().int().nonnegative().optional().describe("New non-negative display order.") }).refine((value) => value.name !== undefined || value.order !== undefined)
   ]), destructive, async (input) => {
     if (input.action === "create")
-      return { operation: "create", result: await client.createCategory({ name: input.name }) };
+      return { operation: "create", result: await client2.createCategory({ name: input.name }) };
     const { action: _action, id, ...data } = input;
-    return { operation: "update", result: await required(client.updateCategory, "update_category")(id, data) };
+    return { operation: "update", result: await required2(client2.updateCategory, "update_category")(id, data) };
   });
-  register("delete_category", "Delete a workspace category and detach its documents without deleting them. Requires full workspace write access; category-scoped credentials are denied.", z2.strictObject({ id: uuid }), destructive, async ({ id }) => {
-    await required(client.deleteCategory, "delete_category")(id);
+  register("delete_category", "Delete a workspace category and detach its documents without deleting them. Requires full workspace write access; category-scoped credentials are denied.", z3.strictObject({ id: uuid2 }), destructive, async ({ id }) => {
+    await required2(client2.deleteCategory, "delete_category")(id);
     return { id, deleted: true };
   });
-  register("save_tag", "Create or update a workspace tag. Full workspace write access is required; renaming or recoloring a tag causes affected documents to be reindexed.", z2.discriminatedUnion("action", [
-    z2.strictObject({ action: z2.literal("create").describe("Select the create operation explicitly."), name: text.max(100), color: z2.string().max(20).optional().describe("Optional tag color, at most 20 characters.") }),
-    z2.strictObject({ action: z2.literal("update").describe("Select the update operation explicitly."), id: uuid, name: text.max(100).optional(), color: z2.string().max(20).optional().describe("Optional tag color, at most 20 characters.") }).refine((value) => value.name !== undefined || value.color !== undefined)
+  register("save_tag", "Create or update a workspace tag. Full workspace write access is required; renaming or recoloring a tag causes affected documents to be reindexed.", z3.discriminatedUnion("action", [
+    z3.strictObject({ action: z3.literal("create").describe("Select the create operation explicitly."), name: text.max(100), color: z3.string().max(20).optional().describe("Optional tag color, at most 20 characters.") }),
+    z3.strictObject({ action: z3.literal("update").describe("Select the update operation explicitly."), id: uuid2, name: text.max(100).optional(), color: z3.string().max(20).optional().describe("Optional tag color, at most 20 characters.") }).refine((value) => value.name !== undefined || value.color !== undefined)
   ]), destructive, async (input) => {
     if (input.action === "create")
-      return { operation: "create", result: await required(client.createTag, "create_tag")({ name: input.name, color: input.color }) };
+      return { operation: "create", result: await required2(client2.createTag, "create_tag")({ name: input.name, color: input.color }) };
     const { action: _action, id, ...data } = input;
-    return { operation: "update", result: await required(client.updateTag, "update_tag")(id, data) };
+    return { operation: "update", result: await required2(client2.updateTag, "update_tag")(id, data) };
   });
-  register("delete_tag", "Delete a workspace tag and remove its document assignments. Full workspace write access is required; documents themselves remain.", z2.strictObject({ id: uuid }), destructive, async ({ id }) => {
-    await required(client.deleteTag, "delete_tag")(id);
+  register("delete_tag", "Delete a workspace tag and remove its document assignments. Full workspace write access is required; documents themselves remain.", z3.strictObject({ id: uuid2 }), destructive, async ({ id }) => {
+    await required2(client2.deleteTag, "delete_tag")(id);
     return { id, deleted: true };
   });
-  register("set_document_tag", "Add or remove one existing tag assignment on a readable document. Requires edit access to that document; action=remove preserves the tag itself.", z2.strictObject({ action: z2.enum(["add", "remove"]).describe("Add or remove exactly one tag assignment."), documentId: uuid, tagId: uuid }), destructive, async ({ action, documentId, tagId }) => {
+  register("set_document_tag", "Add or remove an existing tag assignment on one document. Use batch_documents for the same tag action across multiple explicit IDs. Requires edit access to each document; action=remove preserves the tag itself.", z3.strictObject({ action: z3.enum(["add", "remove"]).describe("Add or remove exactly one tag assignment."), documentId: uuid2, tagId: uuid2 }), destructive, async ({ action, documentId, tagId }) => {
     if (action === "add") {
-      await required(client.addTagToDocument, "add_tag_to_document")(documentId, tagId);
+      await required2(client2.addTagToDocument, "add_tag_to_document")(documentId, tagId);
       return { operation: "add", result: { documentId, tagId, assigned: true } };
     }
-    await required(client.removeTagFromDocument, "remove_tag_from_document")(documentId, tagId);
+    await required2(client2.removeTagFromDocument, "remove_tag_from_document")(documentId, tagId);
     return { operation: "remove", result: { documentId, tagId, removed: true } };
   });
-  register("create_snapshot", "Save a named snapshot of an existing document before a planned change. The snapshot can later be restored with restore_document_version.", z2.strictObject({ documentId: uuid, label: text.max(200).describe("Snapshot label, from 1 to 200 characters."), description: z2.string().max(1000).optional().describe("Optional snapshot note, at most 1000 characters.") }), write, async ({ documentId, label, description }) => client.createSnapshot(documentId, { label, description }));
-  register("restore_document_version", "Restore content from a version or snapshot listed by read_document(view=versions). This changes current content and queues indexing; it does not restore a trashed document.", z2.strictObject({ documentId: uuid, versionId: uuid }), destructive, async ({ documentId, versionId }) => required(client.restoreDocumentVersion, "restore_document_version")(documentId, versionId));
-  register("explore_graph", "Explore graph relations from readable seed documents. mode=neighbors traverses one document without a query; mode=search ranks relations from one or more seed IDs with optional query text.", z2.discriminatedUnion("mode", [
-    z2.strictObject({ mode: z2.literal("neighbors").describe("Select the neighbors operation explicitly."), documentId: uuid, limit: z2.number().int().min(1).max(100).optional().describe("Maximum results to return, up to 100.") }),
-    z2.strictObject({ mode: z2.literal("search").describe("Select the search operation explicitly."), docIds: z2.array(uuid).min(1).max(50).describe("One to 50 authorized seed document UUIDs."), query: z2.string().max(2000).optional().describe("Optional graph relevance query, at most 2000 characters."), limit: z2.number().int().min(1).max(100).optional().describe("Maximum results to return, up to 100.") })
-  ]), read, async (input) => input.mode === "neighbors" ? { operation: "neighbors", result: await client.getRelatedDocuments(input.documentId, input.limit) } : { operation: "search", result: await client.searchGraph(input) });
-  register("get_document_index_status", "Read current indexing and pipeline status for one document without starting work. Use refresh_document_index only when an explicit retry is intended.", z2.strictObject({ documentId: uuid }), read, async ({ documentId }) => client.getDocumentIndexStatus(documentId));
-  register("refresh_document_index", "Queue an explicit asynchronous reindex for one document. Routine content and placement changes already schedule indexing; check get_document_index_status first.", z2.strictObject({ documentId: uuid }), write, async ({ documentId }) => client.refreshDocumentIndex(documentId));
-  register("list_trash", "List soft-deleted documents visible to the active workspace or category scope. Requires read access and does not restore or purge anything.", z2.strictObject({}), read, async () => required(client.listTrash, "list_trash")());
-  register("restore_trashed_document", "Return one soft-deleted document to the active library. This restores the document itself, unlike restore_document_version which changes content.", z2.strictObject({ id: uuid }), write, async ({ id }) => required(client.restoreTrashedDocument, "restore_trashed_document")(id));
-  register("permanently_delete_document", "Irreversibly purge a document already in trash, including its version history. Use only on an explicit user request after checking list_trash.", z2.strictObject({ id: uuid }), destructive, async ({ id }) => {
-    await required(client.permanentlyDeleteDocument, "permanently_delete_document")(id);
+  register("create_snapshot", "Save a named snapshot of an existing document before a planned change. The snapshot can later be restored with restore_document_version.", z3.strictObject({ documentId: uuid2, label: text.max(200).describe("Snapshot label, from 1 to 200 characters."), description: z3.string().max(1000).optional().describe("Optional snapshot note, at most 1000 characters.") }), write, async ({ documentId, label, description }) => client2.createSnapshot(documentId, { label, description }));
+  register("restore_document_version", "Restore content from a version or snapshot listed by read_document(view=versions). This changes current content and queues indexing; it does not restore a trashed document.", z3.strictObject({ documentId: uuid2, versionId: uuid2 }), destructive, async ({ documentId, versionId }) => required2(client2.restoreDocumentVersion, "restore_document_version")(documentId, versionId));
+  register("explore_graph", "Explore graph relations from readable seed documents. mode=neighbors traverses one document without a query; mode=search ranks relations from one or more seed IDs with optional query text.", z3.discriminatedUnion("mode", [
+    z3.strictObject({ mode: z3.literal("neighbors").describe("Select the neighbors operation explicitly."), documentId: uuid2, limit: z3.number().int().min(1).max(100).optional().describe("Maximum results to return, up to 100.") }),
+    z3.strictObject({ mode: z3.literal("search").describe("Select the search operation explicitly."), docIds: z3.array(uuid2).min(1).max(50).describe("One to 50 authorized seed document UUIDs."), query: z3.string().max(2000).optional().describe("Optional graph relevance query, at most 2000 characters."), limit: z3.number().int().min(1).max(100).optional().describe("Maximum results to return, up to 100.") })
+  ]), read, async (input) => input.mode === "neighbors" ? { operation: "neighbors", result: await client2.getRelatedDocuments(input.documentId, input.limit) } : { operation: "search", result: await client2.searchGraph(input) });
+  register("get_document_index_status", "Read current indexing and pipeline status for one document without starting work. Use refresh_document_index only when an explicit retry is intended.", z3.strictObject({ documentId: uuid2 }), read, async ({ documentId }) => client2.getDocumentIndexStatus(documentId));
+  register("refresh_document_index", "Queue an explicit asynchronous reindex for one document; use batch_documents(action=refresh_index) for multiple explicit IDs. Routine content and placement changes already schedule indexing; check get_document_index_status first.", z3.strictObject({ documentId: uuid2 }), write, async ({ documentId }) => client2.refreshDocumentIndex(documentId));
+  register("list_trash", "List soft-deleted documents visible to the active workspace or category scope. Requires read access and does not restore or purge anything.", z3.strictObject({}), read, async () => required2(client2.listTrash, "list_trash")());
+  register("restore_trashed_document", "Return one document from trash to the active library; use batch_documents(action=restore) for multiple explicit IDs. This restores the document itself, unlike restore_document_version which changes content.", z3.strictObject({ id: uuid2 }), write, async ({ id }) => required2(client2.restoreTrashedDocument, "restore_trashed_document")(id));
+  register("permanently_delete_document", "Irreversibly purge a document already in trash, including its version history. Use only on an explicit user request after checking list_trash.", z3.strictObject({ id: uuid2 }), destructive, async ({ id }) => {
+    await required2(client2.permanentlyDeleteDocument, "permanently_delete_document")(id);
     return { id, deleted: true };
   });
+  registerBatchAndWorkspaceCapabilities(server, client2, wrap);
 }
 
 // ../mcp-server/src/prompts-resources.ts
-import { z as z3 } from "zod";
-function registerPromptsAndResources(server, client) {
+import { z as z4 } from "zod";
+function registerPromptsAndResources(server, client2) {
   server.registerPrompt("organize_workspace", {
     description: "Plan safe document organization using DocsMint categories and folders.",
-    argsSchema: z3.object({
-      objective: z3.string(),
-      language: z3.string().optional()
+    argsSchema: z4.object({
+      objective: z4.string(),
+      language: z4.string().optional()
     })
   }, ({ objective, language }) => ({
     messages: [
@@ -998,9 +1197,9 @@ function registerPromptsAndResources(server, client) {
   }));
   server.registerPrompt("research_workspace", {
     description: "Research a question with hybrid search and GraphRAG while citing DocsMint document IDs.",
-    argsSchema: z3.object({
-      question: z3.string(),
-      language: z3.string().optional()
+    argsSchema: z4.object({
+      question: z4.string(),
+      language: z4.string().optional()
     })
   }, ({ question, language }) => ({
     messages: [
@@ -1037,9 +1236,9 @@ Use find_documents(mode=search) for normal retrieval. Use explore_graph only wit
   }));
   server.registerResource("workspace-catalog", "docsmint://workspace/catalog", {}, async (uri) => {
     const [categories, folders, tags] = await Promise.all([
-      client.listCategories(),
-      client.listFolders({}),
-      client.listTags()
+      client2.listCategories(),
+      client2.listFolders({}),
+      client2.listTags()
     ]);
     return {
       contents: [
@@ -1053,97 +1252,6 @@ Use find_documents(mode=search) for normal retrieval. Use explore_graph only wit
   });
 }
 
-// ../mcp-server/src/client.ts
-var DEFAULT_BASE_URL = "http://localhost:50700";
-function readConfig() {
-  const baseUrl = (process.env.HIAI_DOCS_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-  const apiKey = process.env.HIAI_DOCS_API_KEY;
-  return { baseUrl, apiKey: apiKey || undefined };
-}
-
-class HiaiDocsError extends Error {
-  status;
-  body;
-  code;
-  constructor(message, status, body, code = `http_${status}`) {
-    super(message);
-    this.status = status;
-    this.body = body;
-    this.code = code;
-    this.name = "HiaiDocsError";
-  }
-}
-function sanitizeMcpRequestContext(context) {
-  if (!context)
-    return;
-  const headers = new Headers(context.headers);
-  if (context.workspaceAssertion) {
-    headers.delete("Authorization");
-    headers.delete("Cookie");
-  }
-  return {
-    ...context,
-    authorization: context.workspaceAssertion ? undefined : context.authorization,
-    cookie: context.workspaceAssertion ? undefined : context.cookie,
-    headers
-  };
-}
-function createMcpDocsClient(docsClient, requestContext) {
-  const context = sanitizeMcpRequestContext(requestContext);
-  return {
-    createTag: (input) => docsClient.createTag(input, context),
-    updateTag: (id, input) => docsClient.updateTag(id, input, context),
-    deleteTag: (id) => docsClient.deleteTag(id, context),
-    addTagToDocument: (documentId, tagId) => docsClient.addTagToDoc(documentId, tagId, context),
-    removeTagFromDocument: (documentId, tagId) => docsClient.removeTagFromDoc(documentId, tagId, context),
-    updateFolder: (id, input) => docsClient.updateFolder(id, input, context),
-    updateCategory: (id, input) => docsClient.updateCategory(id, input, context),
-    listTrash: () => docsClient.listTrash(context),
-    restoreTrashedDocument: (id) => docsClient.restoreTrashedDocument(id, context),
-    permanentlyDeleteDocument: (id) => docsClient.permanentlyDeleteDocument(id, context),
-    deleteDocument: (id) => docsClient.deleteDoc(id, context),
-    deleteFolder: (id) => docsClient.deleteFolder(id, context),
-    deleteCategory: (id) => docsClient.deleteCategory(id, context),
-    restoreDocumentVersion: (documentId, versionId) => docsClient.restoreVersion(documentId, versionId, context),
-    search: (params) => docsClient.search(params.query, {
-      folder: params.folder,
-      tags: params.tags?.join(","),
-      limit: params.limit
-    }, context),
-    getDocument: (id) => docsClient.getDoc(id, context),
-    createDocument: (input) => docsClient.createDoc({
-      ...input,
-      folderId: input.folderId ?? undefined,
-      categoryId: input.categoryId ?? undefined
-    }, context),
-    updateDocument: (id, input) => docsClient.updateDoc(id, input, context),
-    listDocuments: (params) => docsClient.listDocs(params, context),
-    listFolders: (params) => docsClient.listFolders(params.parentId, context),
-    createFolder: (input) => docsClient.createFolder(input, context),
-    listCategories: () => docsClient.listCategories(context),
-    createCategory: (input) => docsClient.createCategory(input, context),
-    listTags: () => docsClient.listTags(context),
-    getRelatedDocuments: (documentId, limit) => docsClient.getRelatedDocuments(documentId, context, { limit }),
-    searchGraph: (input) => docsClient.searchGraph({ query: input.query, docIds: input.docIds, maxResults: input.limit }, context),
-    getDocumentIndexStatus: (documentId) => docsClient.getDocumentIndexStatus(documentId, context),
-    refreshDocumentIndex: (documentId) => docsClient.refreshDocumentIndex(documentId, context),
-    createSnapshot: (documentId, input) => docsClient.createSnapshot(documentId, input, context),
-    getVersionHistory: (documentId, onlySnapshots) => docsClient.listVersions(documentId, { onlySnapshots }, context),
-    exportDocument: async (id) => ({ markdown: await docsClient.exportDoc(id, context) })
-  };
-}
-function createDefaultDocsClient() {
-  const { baseUrl, apiKey } = readConfig();
-  return new DocsClient({ baseUrl, apiKey, retries: 1 });
-}
-var client = new Proxy({}, {
-  get(_target, property) {
-    const configured = createMcpDocsClient(createDefaultDocsClient());
-    const value = configured[property];
-    return typeof value === "function" ? value.bind(configured) : value;
-  }
-});
-
 // ../mcp-server/src/capabilities.ts
 var capabilityCatalog = {
   tools: [
@@ -1166,7 +1274,9 @@ var capabilityCatalog = {
     "refresh_document_index",
     "list_trash",
     "restore_trashed_document",
-    "permanently_delete_document"
+    "permanently_delete_document",
+    "batch_documents",
+    "get_workspace_item"
   ],
   prompts: ["organize_workspace", "research_workspace"],
   resources: [
@@ -1219,7 +1329,7 @@ function registerDocsmintMcpCapabilities(server, client2) {
   registerPromptsAndResources(server, client2);
 }
 function createDocsmintMcpServer(options = {}) {
-  const server = new McpServer({ name: "docsmint", version: "0.10.0" });
+  const server = new McpServer({ name: "docsmint", version: "1.0.2" });
   const client2 = options.docsClient ? createMcpDocsClient(options.docsClient, options.requestContext) : options.client ?? createMcpDocsClient(createDefaultDocsClient(), options.requestContext);
   registerDocsmintMcpCapabilities(server, client2);
   return server;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hiai-gg/docsmint",
   "mcpName": "io.github.HiAi-gg/docsmint",
-  "version": "0.10.0",
+  "version": "1.0.2",
   "type": "module",
   "browser": {
     "./dist/backend-launcher.js": false,

package/packages/cli/src/index.ts

@@ -25,7 +25,7 @@ import { registerSearch } from './commands/search.js';
 import { registerSnapshot } from './commands/snapshot.js';
 import { registerUpdate } from './commands/update.js';
 
-const VERSION = '0.10.0';
+const VERSION = '1.0.2';
 
 const program = new Command();
 program.name('docsmint').description('CLI for the DocsMint knowledge workspace').version(VERSION);