@hiai-gg/docsmint 0.8.8 → 0.9.0

package/dist/mcp-cli.js

@@ -20,7 +20,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 
 // ../mcp-server/src/server.ts
 import { McpServer } from "@modelcontextprotocol/server";
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 
 // dist/client.js
 var docsApiErrorBrand = Symbol.for("io.github.hiai-gg.docsmint.DocsApiError");
@@ -582,86 +582,372 @@ var RESOURCE_PERMISSIONS = new Set([
   "write"
 ]);
 // ../mcp-server/src/lifecycle.ts
+import { z as z2 } from "zod";
+
+// ../mcp-server/src/output-schemas.ts
 import { z } from "zod";
+var tagSchema = z.looseObject({
+  id: z.string(),
+  name: z.string(),
+  color: z.string().nullable(),
+  createdAt: z.string().optional(),
+  documentCount: z.number().optional()
+});
+var documentSchema = z.looseObject({
+  id: z.string(),
+  ownerId: z.string(),
+  folderId: z.string().nullable(),
+  categoryId: z.string().nullable(),
+  title: z.string(),
+  content: z.string(),
+  contentJson: z.unknown().optional(),
+  metadata: z.unknown().optional(),
+  visibility: z.enum(["private", "shared", "public"]),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  tags: z.array(tagSchema).optional(),
+  folderName: z.string().nullable().optional()
+});
+var documentListItemSchema = z.looseObject({
+  id: z.string(),
+  title: z.string(),
+  content: z.string(),
+  folderId: z.string().nullable(),
+  folderName: z.string().nullable(),
+  categoryId: z.string().nullable(),
+  categoryName: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  tags: z.array(tagSchema)
+});
+var searchChunkSchema = z.looseObject({
+  chunkIndex: z.number(),
+  chunkText: z.string(),
+  charStart: z.number(),
+  charEnd: z.number(),
+  score: z.number()
+});
+var searchResultSchema = z.looseObject({
+  id: z.string(),
+  title: z.string(),
+  snippet: z.string(),
+  score: z.number(),
+  folder_id: z.string().nullable(),
+  folder_name: z.string().nullable(),
+  created_at: z.string(),
+  updated_at: z.string(),
+  tags: z.array(tagSchema).optional(),
+  chunks: z.array(searchChunkSchema).optional()
+});
+var categoryBaseSchema = z.looseObject({
+  id: z.string(),
+  name: z.string(),
+  order: z.number(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  documentCount: z.number().optional(),
+  folderCount: z.number().optional()
+});
+var categorySchema = categoryBaseSchema.extend({
+  apiMode: z.enum(["unavailable", "global", "category"]),
+  apiPermissionRead: z.boolean(),
+  apiPermissionEdit: z.boolean(),
+  apiPermissionWrite: z.boolean()
+});
+var categoryListItemSchema = z.union([
+  categorySchema,
+  categoryBaseSchema
+]);
+var graphEntitySchema = z.looseObject({
+  name: z.string(),
+  type: z.string()
+});
+var pipelineStatusSchema = z.enum([
+  "pending",
+  "processing",
+  "ready",
+  "retrying",
+  "failed",
+  "ready_with_warnings",
+  "skipped",
+  "cancelled"
+]);
+var pipelineSchema = z.looseObject({
+  documentId: z.string(),
+  generationId: z.string(),
+  status: pipelineStatusSchema,
+  revision: z.string(),
+  stages: z.looseObject({
+    prepare: pipelineStatusSchema,
+    embed: pipelineStatusSchema,
+    graph: pipelineStatusSchema,
+    summarize: pipelineStatusSchema,
+    finalize: pipelineStatusSchema
+  }),
+  batches: z.looseObject({
+    total: z.number(),
+    completed: z.number(),
+    failed: z.number()
+  }),
+  warnings: z.array(z.looseObject({
+    stage: z.enum(["graph", "summarize"]),
+    code: z.string(),
+    retryable: z.boolean()
+  })),
+  updatedAt: z.string()
+});
+var indexStatusSchema = z.looseObject({
+  documentId: z.string(),
+  embeddingStatus: z.enum(["pending", "processing", "ready", "failed", "stale"]),
+  activeGenerationId: z.string().nullable(),
+  pendingGenerationId: z.string().nullable(),
+  embeddingProfile: z.string().nullable(),
+  embeddingErrorCode: z.string().nullable(),
+  embeddingUpdatedAt: z.string().nullable(),
+  searchable: z.boolean(),
+  pipeline: pipelineSchema.nullable()
+});
+var versionSchema = z.looseObject({
+  id: z.string(),
+  documentId: z.string(),
+  content: z.string(),
+  contentJson: z.unknown().optional(),
+  createdBy: z.string(),
+  createdAt: z.string(),
+  label: z.string().nullable().optional(),
+  description: z.string().nullable().optional(),
+  isSnapshot: z.boolean().optional(),
+  restoredFrom: z.string().nullable().optional()
+});
+var folderSchema = z.looseObject({
+  id: z.string(),
+  ownerId: z.string(),
+  parentId: z.string().nullable(),
+  name: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  categoryId: z.string().nullable().optional(),
+  order: z.number().optional(),
+  documentCount: z.number().optional(),
+  subfolderCount: z.number().optional(),
+  children: z.array(z.lazy(() => folderSchema)).optional(),
+  documents: z.array(documentListItemSchema).optional()
+});
+var exportedDocumentSchema = z.looseObject({
+  markdown: z.string(),
+  filename: z.string().optional()
+});
+var relatedDocumentsSchema = z.looseObject({
+  related: z.array(z.looseObject({
+    docId: z.string(),
+    relationType: z.string(),
+    hopDistance: z.number()
+  }))
+});
+var graphSearchSchema = z.looseObject({
+  query: z.string().optional(),
+  entities: z.array(graphEntitySchema),
+  relatedDocs: z.array(z.looseObject({
+    docId: z.string(),
+    relationType: z.string(),
+    hopDistance: z.number(),
+    title: z.string(),
+    snippet: z.string()
+  }))
+});
+var deleteAcknowledgmentSchema = z.looseObject({
+  id: z.string().uuid(),
+  deleted: z.literal(true)
+});
+var toolOutputSchemas = {
+  search_documents: z.looseObject({
+    items: z.array(searchResultSchema),
+    total: z.number(),
+    page: z.number(),
+    limit: z.number(),
+    diagnostics: z.looseObject({
+      graphAttempted: z.boolean(),
+      graphFailed: z.boolean(),
+      graphContribution: z.boolean()
+    }).optional()
+  }),
+  get_document: documentSchema,
+  create_document: documentSchema,
+  update_document: documentSchema,
+  list_documents: z.looseObject({
+    items: z.array(documentListItemSchema),
+    total: z.number(),
+    page: z.number(),
+    limit: z.number()
+  }),
+  list_folders: z.array(folderSchema),
+  create_folder: folderSchema,
+  create_snapshot: versionSchema,
+  get_version_history: z.array(versionSchema),
+  export_document: exportedDocumentSchema,
+  list_categories: z.array(categoryListItemSchema),
+  create_category: categorySchema,
+  list_tags: z.array(tagSchema),
+  get_related_documents: relatedDocumentsSchema,
+  search_knowledge_graph: graphSearchSchema,
+  get_document_index_status: indexStatusSchema,
+  refresh_document_index: z.looseObject({
+    documentId: z.string(),
+    generationId: z.string(),
+    deduplicated: z.boolean()
+  }),
+  delete_document: deleteAcknowledgmentSchema,
+  delete_folder: deleteAcknowledgmentSchema,
+  delete_category: deleteAcknowledgmentSchema,
+  restore_document_version: documentSchema
+};
+
+// ../mcp-server/src/lifecycle.ts
 function unsupported(name) {
   throw new Error(`The injected legacy MCP client does not support ${name}; use a public DocsClient.`);
 }
 var annotations = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
 function registerLifecycleCapabilities(server, client, wrap) {
   const deletions = [
-    { name: "delete_document", description: "Move a document to trash. Requires write access to the document; category keys are limited to their category. Does not permanently purge content. Returns the document ID and deleted=true. Use only when the user intends deletion.", action: (id) => client.deleteDocument ? client.deleteDocument(id) : unsupported("delete_document"), idDescription: "UUID of the document to move to trash; obtain it from search_documents, list_documents, or get_document." },
-    { name: "delete_folder", description: "Delete a folder while preserving its documents. Direct child folders and documents are detached according to the server folder rules, and reindexing is queued for affected documents. Requires write access in the permitted workspace or category. Returns the folder ID and deleted=true.", action: (id) => client.deleteFolder ? client.deleteFolder(id) : unsupported("delete_folder"), idDescription: "UUID of the folder to delete; obtain it from list_folders. This does not delete the documents inside it." },
-    { name: "delete_category", description: "Delete a category and detach its folders and documents without deleting their content. Requires full workspace write access; category-scoped keys cannot delete any category, including their own. Returns the category ID and deleted=true.", action: (id) => client.deleteCategory ? client.deleteCategory(id) : unsupported("delete_category"), idDescription: "UUID of the category to delete; obtain it from list_categories using a workspace key." }
+    {
+      name: "delete_document",
+      description: "Move an existing document to trash; this is a soft delete and does not permanently purge its content or version history. Requires write access in the active workspace/category. Returns {id, deleted:true}. Use only when the user intends to delete it.",
+      action: (id) => client.deleteDocument ? client.deleteDocument(id) : unsupported("delete_document"),
+      idDescription: "UUID of the document to move to trash; obtain it from search_documents, list_documents, or get_document."
+    },
+    {
+      name: "delete_folder",
+      description: "Delete a folder while preserving its documents. Direct child folders and documents are detached according to the server folder rules, and reindexing is queued for affected documents. Requires write access in the active workspace/category. Returns {id, deleted:true}.",
+      action: (id) => client.deleteFolder ? client.deleteFolder(id) : unsupported("delete_folder"),
+      idDescription: "UUID of the folder to delete; obtain it from list_folders. This detaches, but does not delete, the documents inside it."
+    },
+    {
+      name: "delete_category",
+      description: "Delete a category and detach its folders and documents without deleting their content. Requires full workspace write access; category-scoped credentials cannot delete any category, including their configured one. Returns {id, deleted:true}.",
+      action: (id) => client.deleteCategory ? client.deleteCategory(id) : unsupported("delete_category"),
+      idDescription: "UUID of the category to delete; obtain it from list_categories using a workspace-scoped credential."
+    }
   ];
   for (const tool of deletions) {
-    server.registerTool(tool.name, { description: tool.description, annotations, inputSchema: z.object({ id: z.string().uuid().describe(tool.idDescription) }) }, wrap(async ({ id }) => {
+    server.registerTool(tool.name, {
+      description: tool.description,
+      annotations,
+      inputSchema: z2.object({ id: z2.string().uuid().describe(tool.idDescription) }),
+      outputSchema: toolOutputSchemas[tool.name]
+    }, wrap(tool.name, async ({ id }) => {
       await tool.action(id);
       return { id, deleted: true };
     }));
   }
   server.registerTool("restore_document_version", {
-    description: "Restore document content from a version or named snapshot returned by get_version_history. Requires edit access to that document. The server backs up the current content, records the restoration, and queues document reindexing. Returns the updated document. Does not restore a document from trash or restore folder/category placement.",
+    description: "Restore content for an existing document from a version or named snapshot returned by get_version_history. Requires edit access. The server saves current content in history, records the restoration, and queues indexing. Returns the updated document; it does not recover a trashed document or change folder/category placement.",
     annotations,
-    inputSchema: z.object({
-      documentId: z.string().uuid().describe("UUID of the document whose content should be restored; it must be visible in the active workspace or category."),
-      versionId: z.string().uuid().describe("UUID of a version belonging to this document, from get_version_history. Use the version ID, not a snapshot label.")
-    })
-  }, wrap(async ({ documentId, versionId }) => client.restoreDocumentVersion ? client.restoreDocumentVersion(documentId, versionId) : unsupported("restore_document_version")));
+    inputSchema: z2.object({
+      documentId: z2.string().uuid().describe("UUID of the document whose content should be restored; it must be visible in the active workspace or category."),
+      versionId: z2.string().uuid().describe("UUID of a version belonging to this document, from get_version_history. Use the version ID, not a snapshot label.")
+    }),
+    outputSchema: toolOutputSchemas.restore_document_version
+  }, wrap("restore_document_version", async ({ documentId, versionId }) => client.restoreDocumentVersion ? client.restoreDocumentVersion(documentId, versionId) : unsupported("restore_document_version")));
 }
 
 // ../mcp-server/src/capabilities.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 function registerExtendedCapabilities(server, client, wrapHandler) {
   server.registerTool("list_categories", {
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    description: "List categories visible to the API key. Category keys receive only their bound category.",
-    inputSchema: z2.object({})
-  }, wrapHandler(async () => client.listCategories()));
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    description: "List categories visible in the active workspace or category scope. Requires read access; a category-scoped credential sees only its configured category. Use this before create_document or create_folder when you need an existing category ID.",
+    inputSchema: z3.object({}),
+    outputSchema: toolOutputSchemas.list_categories
+  }, wrapHandler("list_categories", async () => client.listCategories()));
   server.registerTool("create_category", {
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    description: "Create a category. Requires a workspace key with write access; category keys cannot mutate categories.",
-    inputSchema: z2.object({
-      name: z2.string().min(1).describe("Non-empty display name for the new category, for example Project notes."),
-      description: z2.string().optional().describe("Optional plain-text explanation of the category purpose; omit if not needed.")
-    })
-  }, wrapHandler(async (input) => client.createCategory(input)));
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    },
+    description: "Create a new category for the active workspace. Requires workspace-level write access; category-scoped credentials cannot create categories. Returns the created category. Use list_categories to inspect existing categories.",
+    inputSchema: z3.object({
+      name: z3.string().trim().min(1).max(255).describe("Non-empty display name, up to 255 characters, for example Project notes.")
+    }),
+    outputSchema: toolOutputSchemas.create_category
+  }, wrapHandler("create_category", async (input) => client.createCategory(input)));
   server.registerTool("list_tags", {
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    description: "List tags visible in the workspace or bound category.",
-    inputSchema: z2.object({})
-  }, wrapHandler(async () => client.listTags()));
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    description: "List tags visible in the active workspace or configured category scope. Requires read access; use returned tag IDs to filter list_documents and returned tag names to filter search_documents.",
+    inputSchema: z3.object({}),
+    outputSchema: toolOutputSchemas.list_tags
+  }, wrapHandler("list_tags", async () => client.listTags()));
   server.registerTool("get_related_documents", {
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    description: "Find graph-related documents from one readable document, without a text query. Returns related documents and relation metadata. Use search_knowledge_graph to filter graph neighbors by text, or search_documents for normal retrieval. Results stay within the active scope and may be empty when graph data is unavailable.",
-    inputSchema: z2.object({
-      documentId: z2.string().min(1).describe("Document UUID returned by search_documents or list_documents; must be readable in the active scope."),
-      limit: z2.number().int().min(1).max(50).optional().describe("Maximum related documents to return, from 1 to 50. Omit to use the server default.")
-    })
-  }, wrapHandler(async ({ documentId, limit }) => client.getRelatedDocuments(documentId, limit)));
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    description: "Traverse graph relations from one readable document without a text query. Requires read access and returns related document IDs plus relation metadata. Use search_knowledge_graph to rank graph neighbors with query text, or search_documents for normal hybrid retrieval. Results stay in the active scope and may be empty when graph data is unavailable.",
+    inputSchema: z3.object({
+      documentId: z3.string().min(1).describe("Document ID returned by search_documents or list_documents; it must be readable in the active scope."),
+      limit: z3.number().int().min(1).max(100).optional().describe("Maximum related documents to return, from 1 to 100. Omit to use the server default.")
+    }),
+    outputSchema: toolOutputSchemas.get_related_documents
+  }, wrapHandler("get_related_documents", async ({ documentId, limit }) => client.getRelatedDocuments(documentId, limit)));
   server.registerTool("search_knowledge_graph", {
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    description: "Retrieve graph context from one or more readable seed documents and filter/rank related documents by query text. Returns seed entities and relatedDocs; use search_documents first to obtain seed IDs. Returned documents stay within the active category. Graph data may be empty when unavailable.",
-    inputSchema: z2.object({
-      query: z2.string().min(1).max(1000).describe("Search text used to filter and rank graph-related documents. Preserve the original query language."),
-      docIds: z2.array(z2.string().min(1)).min(1).max(50).describe("Between 1 and 50 authorized document UUIDs from search_documents or list_documents to use as graph traversal seeds."),
-      limit: z2.number().int().min(1).max(50).optional().describe("Maximum related documents to return, from 1 to 50. Omit to use the server default.")
-    })
-  }, wrapHandler(async (input) => client.searchGraph(input)));
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    description: "Search graph relations from one or more readable seed documents, optionally using query text to filter and rank related documents. Requires read access and returns seed entities plus relatedDocs. Use search_documents first to obtain authorized seed IDs; use get_related_documents for one-seed neighbors without graph search. Results stay in the active scope and graph data may be empty when unavailable.",
+    inputSchema: z3.object({
+      query: z3.string().max(2000).optional().describe("Optional search text up to 2,000 characters to filter and rank graph-related documents; omit it to inspect relations without query filtering."),
+      docIds: z3.array(z3.string().min(1)).min(1).max(50).describe("Between 1 and 50 document IDs returned by search_documents or list_documents; each seed must be readable in the active scope."),
+      limit: z3.number().int().min(1).max(100).optional().describe("Maximum related documents to return, from 1 to 100. Omit to use the server default.")
+    }),
+    outputSchema: toolOutputSchemas.search_knowledge_graph
+  }, wrapHandler("search_knowledge_graph", async (input) => client.searchGraph(input)));
   server.registerTool("get_document_index_status", {
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    description: "Read a document indexing and knowledge-pipeline status without starting any work. Use after a save or refresh_document_index to inspect progress and failures. Requires read access to the document.",
-    inputSchema: z2.object({ documentId: z2.string().min(1).describe("Document UUID returned by search_documents or list_documents; must be readable in the active scope.") })
-  }, wrapHandler(async ({ documentId }) => client.getDocumentIndexStatus(documentId)));
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    description: "Read indexing and knowledge-pipeline status for an existing document without starting work. Requires read access. Use after a save or refresh_document_index to check progress or failures.",
+    inputSchema: z3.object({
+      documentId: z3.string().uuid().describe("UUID of a document returned by search_documents or list_documents; it must be readable in the active scope.")
+    }),
+    outputSchema: toolOutputSchemas.get_document_index_status
+  }, wrapHandler("get_document_index_status", async ({ documentId }) => client.getDocumentIndexStatus(documentId)));
   server.registerTool("refresh_document_index", {
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    description: "Queue document reindexing and return the server acknowledgment; processing completes asynchronously. Requires write access. Normal saves already schedule indexing; use this for an explicit refresh and inspect progress with get_document_index_status.",
-    inputSchema: z2.object({ documentId: z2.string().min(1).describe("Document UUID returned by search_documents or list_documents; must be readable in the active scope.") })
-  }, wrapHandler(async ({ documentId }) => client.refreshDocumentIndex(documentId)));
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    },
+    description: "Queue an explicit reindex for an existing document; processing is asynchronous and the response acknowledges the generation. Requires write access. Normal content and placement changes schedule indexing when needed, so use get_document_index_status first and refresh only when a retry is intended.",
+    inputSchema: z3.object({
+      documentId: z3.string().uuid().describe("UUID of the document to refresh, obtained from search_documents or list_documents and visible in the active scope.")
+    }),
+    outputSchema: toolOutputSchemas.refresh_document_index
+  }, wrapHandler("refresh_document_index", async ({ documentId }) => client.refreshDocumentIndex(documentId)));
   server.registerPrompt("organize_workspace", {
     description: "Plan safe document organization using DocsMint categories and folders.",
-    argsSchema: z2.object({
-      objective: z2.string(),
-      language: z2.string().optional()
+    argsSchema: z3.object({
+      objective: z3.string(),
+      language: z3.string().optional()
     })
   }, ({ objective, language }) => ({
     messages: [
@@ -676,9 +962,9 @@ function registerExtendedCapabilities(server, client, wrapHandler) {
   }));
   server.registerPrompt("research_workspace", {
     description: "Research a question with hybrid search and GraphRAG while citing DocsMint document IDs.",
-    argsSchema: z2.object({
-      question: z2.string(),
-      language: z2.string().optional()
+    argsSchema: z3.object({
+      question: z3.string(),
+      language: z3.string().optional()
     })
   }, ({ question, language }) => ({
     messages: [
@@ -819,15 +1105,15 @@ __export(exports_create_document, {
   definition: () => definition,
   handler: () => handler
 });
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var definition = {
   name: "create_document",
-  description: "Create a new document. Optionally provide initial markdown content and a folder ID.",
+  description: "Create a new DocsMint document when no existing document should be modified. Optionally set a title, initial Markdown content, and folder or category placement; an omitted title defaults to \u201CUntitled\u201D. Requires write access in the target scope. A category-scoped credential must create inside its configured category, by selecting that category or a folder within it. Normal creation schedules indexing asynchronously and returns the created document. Use update_document for an existing document.",
   inputSchema: {
-    title: z3.string().describe("Document title."),
-    content: z3.string().optional().describe("Initial markdown content for the document."),
-    folderId: z3.string().optional().describe("Optional folder ID to place the document in."),
-    categoryId: z3.string().optional().describe("Optional category ID. Category keys are always rebound to their configured category.")
+    title: z4.string().min(1).max(500).optional().describe("Optional title from 1 to 500 characters; omit to use the API default \u201CUntitled\u201D."),
+    content: z4.string().optional().describe("Optional initial Markdown content; omit to create an empty document."),
+    folderId: z4.string().uuid().optional().describe("Optional folder UUID from list_folders; the folder must be writable in the active workspace or category."),
+    categoryId: z4.string().uuid().nullable().optional().describe("Optional category UUID from list_categories; omit or pass null to leave the explicit category unset. A categorized folder still supplies the document\u2019s effective category; without one the document remains uncategorized. Category-scoped credentials stay bound to their configured category.")
   }
 };
 var createHandler = (api) => async function createDocument(args) {
@@ -842,14 +1128,14 @@ __export(exports_create_folder, {
   definition: () => definition2,
   handler: () => handler2
 });
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 var definition2 = {
   name: "create_folder",
-  description: "Create a new folder, optionally nested under a parent folder.",
+  description: "Create a new folder in the active workspace or category scope. Requires write access and returns the created folder. A nested folder inherits its parent category; for a root folder, pass categoryId when using a category-scoped credential. Category-scoped credentials cannot create outside their configured category.",
   inputSchema: {
-    name: z4.string().describe("Folder name."),
-    parentId: z4.string().optional().describe("Optional parent folder ID for nesting."),
-    categoryId: z4.string().optional().describe("Optional category ID. Category keys are always rebound to their configured category.")
+    name: z5.string().min(1).max(255).describe("Non-empty folder name up to 255 characters."),
+    parentId: z5.string().uuid().nullable().optional().describe("Optional parent folder UUID from list_folders; omit or pass null to create a root-level folder."),
+    categoryId: z5.string().uuid().nullable().optional().describe("Optional category UUID from list_categories for a root-level folder. A nested folder inherits its parent category; category-scoped credentials cannot escape their configured category.")
   }
 };
 var createHandler2 = (api) => async function createFolder(args) {
@@ -864,14 +1150,14 @@ __export(exports_create_snapshot, {
   definition: () => definition3,
   handler: () => handler3
 });
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var definition3 = {
   name: "create_snapshot",
-  description: "Create a named snapshot (labelled version) of a document from its current content.",
+  description: "Save a named, retained snapshot of an existing document\u2019s current content before a planned change. Requires edit access and adds an entry to get_version_history without changing the document itself. Use restore_document_version with the returned version ID to restore its content later.",
   inputSchema: {
-    documentId: z5.string().describe("Document ID to snapshot."),
-    label: z5.string().describe("Short label for the snapshot (e.g. 'v1.0-release')."),
-    description: z5.string().optional().describe("Optional longer description of the snapshot.")
+    documentId: z6.string().uuid().describe("UUID of the existing document, obtained from search_documents or list_documents and visible in the active scope."),
+    label: z6.string().min(1).max(200).describe("Non-empty snapshot label up to 200 characters, for example 'v1.0-release'."),
+    description: z6.string().max(1000).optional().describe("Optional snapshot note up to 1,000 characters; omit if not needed.")
   }
 };
 var createHandler3 = (api) => async function createSnapshot(args) {
@@ -887,12 +1173,12 @@ __export(exports_export_document, {
   definition: () => definition4,
   handler: () => handler4
 });
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var definition4 = {
   name: "export_document",
   description: "Render one readable document as portable Markdown and return a markdown string in the response object. Does not modify the document or include its complete metadata; use get_document to inspect the editable document.",
   inputSchema: {
-    id: z6.string().describe("Document ID to export.")
+    id: z7.string().uuid().describe("UUID of the readable document to export, obtained from search_documents or list_documents.")
   }
 };
 var createHandler4 = (api) => async function exportDocument(args) {
@@ -907,12 +1193,12 @@ __export(exports_get_document, {
   definition: () => definition5,
   handler: () => handler5
 });
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var definition5 = {
   name: "get_document",
-  description: "Read one document with its content, metadata, and tags before editing or citing it. Requires read access. Use export_document when you only need portable Markdown.",
+  description: "Read an existing document by UUID with its content, metadata, and tags before editing or citing it. Requires read access in the active workspace/category. Use export_document when you only need the portable Markdown body.",
   inputSchema: {
-    id: z7.string().describe("Document ID.")
+    id: z8.string().uuid().describe("UUID of the document, obtained from search_documents or list_documents, and visible in the active scope.")
   }
 };
 var createHandler5 = (api) => async function getDocument(args) {
@@ -927,15 +1213,15 @@ __export(exports_list_documents, {
   definition: () => definition6,
   handler: () => handler6
 });
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var definition6 = {
   name: "list_documents",
-  description: "List documents with pagination, optionally filtered by folder or tag.",
+  description: "List readable documents in the active workspace or category with page-based results. Optionally filter by folder or tag; page defaults to 1 and limit to 20 (maximum 1,000). Use search_documents for text or semantic retrieval.",
   inputSchema: {
-    folderId: z8.string().optional().describe("Optional folder ID to filter by."),
-    tag: z8.string().optional().describe("Optional tag ID to filter by."),
-    page: z8.number().int().positive().optional().describe("Page number (1-indexed, default 1)."),
-    limit: z8.number().int().positive().max(100).optional().describe("Items per page (default 20, max 100).")
+    folderId: z9.string().uuid().optional().describe("Optional folder UUID from list_folders to limit the listing."),
+    tag: z9.string().uuid().optional().describe("Optional tag UUID from list_tags to filter the documents."),
+    page: z9.number().int().min(1).optional().describe("1-indexed result page; defaults to 1."),
+    limit: z9.number().int().min(1).max(1000).optional().describe("Number of documents per page, from 1 to 1,000; defaults to 20.")
   }
 };
 var createHandler6 = (api) => async function listDocuments(args) {
@@ -950,12 +1236,12 @@ __export(exports_list_folders, {
   definition: () => definition7,
   handler: () => handler7
 });
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var definition7 = {
   name: "list_folders",
-  description: "List folders, optionally scoped to a parent folder. Returns a flat list of immediate children.",
+  description: "List folders readable in the active workspace/category. Omit parentId to list root folders, or supply a parent UUID to list its immediate children as a flat list. Use create_folder to add a folder.",
   inputSchema: {
-    parentId: z9.string().optional().describe("Optional parent folder ID. Omit to list top-level (root) folders.")
+    parentId: z10.string().uuid().optional().describe("Optional parent folder UUID from list_folders; omit to list root folders.")
   }
 };
 var createHandler7 = (api) => async function listFolders(args) {
@@ -970,15 +1256,15 @@ __export(exports_search, {
   definition: () => definition8,
   handler: () => handler8
 });
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 var definition8 = {
   name: "search_documents",
-  description: "Hybrid search across documents (full-text + semantic). Supports filtering by folder and tags.",
+  description: "Search readable DocsMint documents with hybrid full-text and semantic retrieval, optionally filtered by folder and tag names. Requires read access and stays within the active workspace/category. Use search_knowledge_graph for graph relations from seed documents or get_related_documents for neighbors without a text query.",
   inputSchema: {
-    query: z10.string().describe("Search query string."),
-    folder: z10.string().optional().describe("Optional folder ID to scope the search to."),
-    tags: z10.array(z10.string()).optional().describe("Optional tag IDs to filter by."),
-    limit: z10.number().int().positive().optional().describe("Maximum number of results to return (default 20).")
+    query: z11.string().describe("Text to search for; preserve the language and terms relevant to the user request."),
+    folder: z11.string().optional().describe("Optional folder UUID from list_folders to scope retrieval."),
+    tags: z11.array(z11.string()).optional().describe("Optional tag names as shown by list_tags; documents match when they have any supplied tag name."),
+    limit: z11.number().int().positive().max(100).optional().describe("Maximum result count, from 1 to 100; defaults to 20.")
   }
 };
 var createHandler8 = (api) => async function searchDocuments(args) {
@@ -998,16 +1284,16 @@ __export(exports_update_document, {
   definition: () => definition9,
   handler: () => handler9
 });
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var definition9 = {
   name: "update_document",
-  description: "Update an existing document's title and/or content. The server creates a new version on each update.",
+  description: "Modify an existing document by UUID after reading its current state. Omitted fields remain unchanged; null folderId removes folder placement and null categoryId clears the explicit category, while a categorized folder can still supply the effective category. Changing title or Markdown content requires edit access, while moving placement requires write access in the active workspace/category. The server stores the prior content in version history and queues indexing when content or placement changes. Returns the updated document. Use create_document for new content.",
   inputSchema: {
-    id: z11.string().describe("Document ID to update."),
-    title: z11.string().optional().describe("New title for the document."),
-    content: z11.string().optional().describe("New markdown content for the document."),
-    folderId: z11.string().nullable().optional().describe("Move the document to a folder."),
-    categoryId: z11.string().nullable().optional().describe("Move the document to a category. Category keys cannot escape their configured category.")
+    id: z12.string().uuid().describe("UUID of the existing document, obtained from search_documents, list_documents, or get_document."),
+    title: z12.string().min(1).max(500).optional().describe("Optional replacement title, 1 to 500 characters; omit to leave the current title unchanged."),
+    content: z12.string().optional().describe("New markdown content for the document."),
+    folderId: z12.string().uuid().nullable().optional().describe("Optional destination folder UUID from list_folders; omit to keep current placement or pass null to remove folder placement."),
+    categoryId: z12.string().uuid().nullable().optional().describe("Optional destination category UUID from list_categories; omit to keep the explicit category or pass null to clear it. A categorized folder may still supply the effective category. Category-scoped credentials cannot move outside their configured category.")
   }
 };
 var createHandler9 = (api) => async function updateDocument(args) {
@@ -1023,13 +1309,13 @@ __export(exports_version_history, {
   definition: () => definition10,
   handler: () => handler10
 });
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var definition10 = {
   name: "get_version_history",
-  description: "List the version history for a document. Optionally restrict to named snapshots.",
+  description: "Read versions for an existing document, including saved snapshots. Requires read access and returns version IDs with content and timestamps; pass a version ID to restore_document_version when the user asks to restore content. This is read-only and does not change the document.",
   inputSchema: {
-    documentId: z12.string().describe("Document ID whose versions should be listed."),
-    onlySnapshots: z12.boolean().optional().describe("When true, only return named snapshots (skip auto-saved revisions).")
+    documentId: z13.string().uuid().describe("UUID of the readable document whose version history you need; obtain it from search_documents or list_documents."),
+    onlySnapshots: z13.boolean().optional().describe("When true, return only named snapshots and omit auto-saved revisions; omit or use false for the full history.")
   }
 };
 var createHandler10 = (api) => async function getVersionHistory(args) {
@@ -1038,11 +1324,17 @@ var createHandler10 = (api) => async function getVersionHistory(args) {
 var handler10 = createHandler10(client);
 
 // ../mcp-server/src/server.ts
-function wrapHandler(name, handler11) {
+function wrapHandler(name, handler11, outputSchema) {
   return async (args) => {
     try {
+      const output = await handler11(args);
+      const parsedOutput = outputSchema ? await outputSchema.safeParseAsync(output) : undefined;
+      if (parsedOutput && !parsedOutput.success) {
+        throw new Error(`Tool '${name}' returned a result outside its published output schema`);
+      }
       return {
-        content: [{ type: "text", text: JSON.stringify(await handler11(args), null, 2) }]
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+        ...parsedOutput?.success ? { structuredContent: parsedOutput.data } : {}
       };
     } catch (error) {
       if (isDocsApiError(error) || error instanceof HiaiDocsError) {
@@ -1071,12 +1363,27 @@ function wrapHandler(name, handler11) {
 }
 function registerDocsmintMcpCapabilities(server, client2) {
   const register = (name, description, inputSchema, handler11) => {
-    server.registerTool(name, { description, inputSchema: z13.object(inputSchema), annotations: {
-      readOnlyHint: !["create_document", "update_document", "create_folder", "create_snapshot"].includes(name),
-      destructiveHint: name === "update_document",
-      idempotentHint: !["create_document", "update_document", "create_folder", "create_snapshot"].includes(name),
-      openWorldHint: false
-    } }, wrapHandler(name, handler11));
+    server.registerTool(name, {
+      description,
+      inputSchema: z14.object(inputSchema),
+      annotations: {
+        readOnlyHint: ![
+          "create_document",
+          "update_document",
+          "create_folder",
+          "create_snapshot"
+        ].includes(name),
+        destructiveHint: name === "update_document",
+        idempotentHint: ![
+          "create_document",
+          "update_document",
+          "create_folder",
+          "create_snapshot"
+        ].includes(name),
+        openWorldHint: false
+      },
+      outputSchema: toolOutputSchemas[name]
+    }, wrapHandler(name, handler11, toolOutputSchemas[name]));
   };
   const tools = [
     exports_search,
@@ -1093,11 +1400,11 @@ function registerDocsmintMcpCapabilities(server, client2) {
   for (const tool of tools) {
     register(tool.definition.name, tool.definition.description, tool.definition.inputSchema, tool.createHandler(client2));
   }
-  registerExtendedCapabilities(server, client2, (handler11) => wrapHandler("extended", handler11));
-  registerLifecycleCapabilities(server, client2, (handler11) => wrapHandler("lifecycle", handler11));
+  registerExtendedCapabilities(server, client2, (name, handler11) => wrapHandler(name, handler11, toolOutputSchemas[name]));
+  registerLifecycleCapabilities(server, client2, (name, handler11) => wrapHandler(name, handler11, toolOutputSchemas[name]));
 }
 function createDocsmintMcpServer(options = {}) {
-  const server = new McpServer({ name: "docsmint", version: "0.8.8" });
+  const server = new McpServer({ name: "docsmint", version: "0.9.0" });
   const client2 = options.docsClient ? createMcpDocsClient(options.docsClient, options.requestContext) : options.client ?? createMcpDocsClient(createDefaultDocsClient(), options.requestContext);
   registerDocsmintMcpCapabilities(server, client2);
   return server;