@hiai-gg/docsmint 0.8.6 → 0.8.8

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 z12 } from "zod";
+import { z as z13 } from "zod";
 
 // dist/client.js
 var docsApiErrorBrand = Symbol.for("io.github.hiai-gg.docsmint.DocsApiError");
@@ -581,52 +581,87 @@ var RESOURCE_PERMISSIONS = new Set([
   "edit",
   "write"
 ]);
-// ../mcp-server/src/capabilities.ts
+// ../mcp-server/src/lifecycle.ts
 import { z } from "zod";
+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." }
+  ];
+  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 }) => {
+      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.",
+    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")));
+}
+
+// ../mcp-server/src/capabilities.ts
+import { z as z2 } 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: z.object({})
+    inputSchema: z2.object({})
   }, wrapHandler(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: z.object({
-      name: z.string().min(1),
-      description: z.string().optional()
+    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)));
   server.registerTool("list_tags", {
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     description: "List tags visible in the workspace or bound category.",
-    inputSchema: z.object({})
+    inputSchema: z2.object({})
   }, wrapHandler(async () => client.listTags()));
   server.registerTool("get_related_documents", {
-    description: "Traverse the knowledge graph from one authorized document.",
-    inputSchema: z.object({
-      documentId: z.string().min(1),
-      limit: z.number().int().min(1).max(50).optional()
+    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)));
   server.registerTool("search_knowledge_graph", {
-    description: "Search connected knowledge using authorized seed documents. Category keys may use only documents in their category.",
-    inputSchema: z.object({
-      query: z.string().min(1).max(1000),
-      docIds: z.array(z.string().min(1)).min(1),
-      limit: z.number().int().min(1).max(50).optional()
+    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)));
   server.registerTool("get_document_index_status", {
-    description: "Read the current indexing and knowledge-pipeline status of a document.",
-    inputSchema: z.object({ documentId: z.string().min(1) })
+    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)));
   server.registerTool("refresh_document_index", {
-    description: "Request reindexing after a document or metadata change. Requires write access.",
-    inputSchema: z.object({ documentId: z.string().min(1) })
+    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)));
   server.registerPrompt("organize_workspace", {
     description: "Plan safe document organization using DocsMint categories and folders.",
-    argsSchema: z.object({
-      objective: z.string(),
-      language: z.string().optional()
+    argsSchema: z2.object({
+      objective: z2.string(),
+      language: z2.string().optional()
     })
   }, ({ objective, language }) => ({
     messages: [
@@ -641,9 +676,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: z.object({
-      question: z.string(),
-      language: z.string().optional()
+    argsSchema: z2.object({
+      question: z2.string(),
+      language: z2.string().optional()
     })
   }, ({ question, language }) => ({
     messages: [
@@ -734,6 +769,10 @@ function sanitizeMcpRequestContext(context) {
 function createMcpDocsClient(docsClient, requestContext) {
   const context = sanitizeMcpRequestContext(requestContext);
   return {
+    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(","),
@@ -780,15 +819,15 @@ __export(exports_create_document, {
   definition: () => definition,
   handler: () => handler
 });
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 var definition = {
   name: "create_document",
   description: "Create a new document. Optionally provide initial markdown content and a folder ID.",
   inputSchema: {
-    title: z2.string().describe("Document title."),
-    content: z2.string().optional().describe("Initial markdown content for the document."),
-    folderId: z2.string().optional().describe("Optional folder ID to place the document in."),
-    categoryId: z2.string().optional().describe("Optional category ID. Category keys are always rebound to their configured category.")
+    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.")
   }
 };
 var createHandler = (api) => async function createDocument(args) {
@@ -803,14 +842,14 @@ __export(exports_create_folder, {
   definition: () => definition2,
   handler: () => handler2
 });
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var definition2 = {
   name: "create_folder",
   description: "Create a new folder, optionally nested under a parent folder.",
   inputSchema: {
-    name: z3.string().describe("Folder name."),
-    parentId: z3.string().optional().describe("Optional parent folder ID for nesting."),
-    categoryId: z3.string().optional().describe("Optional category ID. Category keys are always rebound to their configured category.")
+    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.")
   }
 };
 var createHandler2 = (api) => async function createFolder(args) {
@@ -825,14 +864,14 @@ __export(exports_create_snapshot, {
   definition: () => definition3,
   handler: () => handler3
 });
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 var definition3 = {
   name: "create_snapshot",
   description: "Create a named snapshot (labelled version) of a document from its current content.",
   inputSchema: {
-    documentId: z4.string().describe("Document ID to snapshot."),
-    label: z4.string().describe("Short label for the snapshot (e.g. 'v1.0-release')."),
-    description: z4.string().optional().describe("Optional longer description of the snapshot.")
+    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.")
   }
 };
 var createHandler3 = (api) => async function createSnapshot(args) {
@@ -848,12 +887,12 @@ __export(exports_export_document, {
   definition: () => definition4,
   handler: () => handler4
 });
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var definition4 = {
   name: "export_document",
-  description: "Export a document as markdown. Returns the rendered markdown content.",
+  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: z5.string().describe("Document ID to export.")
+    id: z6.string().describe("Document ID to export.")
   }
 };
 var createHandler4 = (api) => async function exportDocument(args) {
@@ -868,12 +907,12 @@ __export(exports_get_document, {
   definition: () => definition5,
   handler: () => handler5
 });
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var definition5 = {
   name: "get_document",
-  description: "Fetch a single document by ID. Returns full content, metadata, and tags.",
+  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.",
   inputSchema: {
-    id: z6.string().describe("Document ID.")
+    id: z7.string().describe("Document ID.")
   }
 };
 var createHandler5 = (api) => async function getDocument(args) {
@@ -888,15 +927,15 @@ __export(exports_list_documents, {
   definition: () => definition6,
   handler: () => handler6
 });
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var definition6 = {
   name: "list_documents",
   description: "List documents with pagination, optionally filtered by folder or tag.",
   inputSchema: {
-    folderId: z7.string().optional().describe("Optional folder ID to filter by."),
-    tag: z7.string().optional().describe("Optional tag ID to filter by."),
-    page: z7.number().int().positive().optional().describe("Page number (1-indexed, default 1)."),
-    limit: z7.number().int().positive().max(100).optional().describe("Items per page (default 20, max 100).")
+    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).")
   }
 };
 var createHandler6 = (api) => async function listDocuments(args) {
@@ -911,12 +950,12 @@ __export(exports_list_folders, {
   definition: () => definition7,
   handler: () => handler7
 });
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var definition7 = {
   name: "list_folders",
   description: "List folders, optionally scoped to a parent folder. Returns a flat list of immediate children.",
   inputSchema: {
-    parentId: z8.string().optional().describe("Optional parent folder ID. Omit to list top-level (root) folders.")
+    parentId: z9.string().optional().describe("Optional parent folder ID. Omit to list top-level (root) folders.")
   }
 };
 var createHandler7 = (api) => async function listFolders(args) {
@@ -931,15 +970,15 @@ __export(exports_search, {
   definition: () => definition8,
   handler: () => handler8
 });
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var definition8 = {
   name: "search_documents",
   description: "Hybrid search across documents (full-text + semantic). Supports filtering by folder and tags.",
   inputSchema: {
-    query: z9.string().describe("Search query string."),
-    folder: z9.string().optional().describe("Optional folder ID to scope the search to."),
-    tags: z9.array(z9.string()).optional().describe("Optional tag IDs to filter by."),
-    limit: z9.number().int().positive().optional().describe("Maximum number of results to return (default 20).")
+    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).")
   }
 };
 var createHandler8 = (api) => async function searchDocuments(args) {
@@ -959,16 +998,16 @@ __export(exports_update_document, {
   definition: () => definition9,
   handler: () => handler9
 });
-import { z as z10 } from "zod";
+import { z as z11 } 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.",
   inputSchema: {
-    id: z10.string().describe("Document ID to update."),
-    title: z10.string().optional().describe("New title for the document."),
-    content: z10.string().optional().describe("New markdown content for the document."),
-    folderId: z10.string().nullable().optional().describe("Move the document to a folder."),
-    categoryId: z10.string().nullable().optional().describe("Move the document to a category. Category keys cannot escape their configured category.")
+    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.")
   }
 };
 var createHandler9 = (api) => async function updateDocument(args) {
@@ -984,13 +1023,13 @@ __export(exports_version_history, {
   definition: () => definition10,
   handler: () => handler10
 });
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var definition10 = {
   name: "get_version_history",
   description: "List the version history for a document. Optionally restrict to named snapshots.",
   inputSchema: {
-    documentId: z11.string().describe("Document ID whose versions should be listed."),
-    onlySnapshots: z11.boolean().optional().describe("When true, only return named snapshots (skip auto-saved revisions).")
+    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).")
   }
 };
 var createHandler10 = (api) => async function getVersionHistory(args) {
@@ -1032,7 +1071,12 @@ function wrapHandler(name, handler11) {
 }
 function registerDocsmintMcpCapabilities(server, client2) {
   const register = (name, description, inputSchema, handler11) => {
-    server.registerTool(name, { description, inputSchema: z12.object(inputSchema) }, wrapHandler(name, 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));
   };
   const tools = [
     exports_search,
@@ -1050,9 +1094,10 @@ function registerDocsmintMcpCapabilities(server, client2) {
     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));
 }
 function createDocsmintMcpServer(options = {}) {
-  const server = new McpServer({ name: "docsmint", version: "0.8.6" });
+  const server = new McpServer({ name: "docsmint", version: "0.8.8" });
   const client2 = options.docsClient ? createMcpDocsClient(options.docsClient, options.requestContext) : options.client ?? createMcpDocsClient(createDefaultDocsClient(), options.requestContext);
   registerDocsmintMcpCapabilities(server, client2);
   return server;

package/dist/mcp-server.d.ts

@@ -3,6 +3,10 @@ import type { McpServer } from "@modelcontextprotocol/server";
 import type { DocsClient, DocsRequestContext } from "./index.js";
 
 export interface HiaiDocsClient {
+	deleteDocument?(id: string): Promise<void>;
+	deleteFolder?(id: string): Promise<void>;
+	deleteCategory?(id: string): Promise<void>;
+	restoreDocumentVersion?(documentId: string, versionId: string): Promise<unknown>;
 	search(params: { query: string; folder?: string; tags?: string[]; limit?: number }): Promise<unknown>;
 	getDocument(id: string): Promise<unknown>;
 	createDocument(input: { title: string; content?: string; folderId?: string | null; categoryId?: string | null }): Promise<unknown>;