@hiai-gg/docsmint 0.8.5 → 0.8.7

package/README.md

@@ -10,15 +10,22 @@ agents access to the same documents through MCP, REST, the SDK, or CLI.
 operating the stack, or **[self-host with Docker](#quickstart)** to run the
 Apache-2.0 application on your own infrastructure.
 
-[![Apache-2.0 License](https://img.shields.io/badge/License-Apache--2.0-green.svg)](https://github.com/HiAi-gg/docsmint/blob/main/LICENSE)
+[![Apache-2.0 License](https://img.shields.io/badge/License-Apache--2.0-green.svg)](LICENSE)
 [![Release](https://img.shields.io/github/v/release/hiai-gg/docsmint?sort=semver)](https://github.com/hiai-gg/docsmint/releases)
 [![npm](https://img.shields.io/npm/v/@hiai-gg/docsmint?logo=npm)](https://www.npmjs.com/package/@hiai-gg/docsmint)
+[![Docker Pulls](https://img.shields.io/docker/pulls/vgalibov/docsmint?logo=docker)](https://hub.docker.com/r/vgalibov/docsmint)
+[![Stars](https://img.shields.io/github/stars/hiai-gg/docsmint)](https://github.com/hiai-gg/docsmint/stargazers)
 [![CI](https://github.com/hiai-gg/docsmint/actions/workflows/ci.yml/badge.svg)](https://github.com/hiai-gg/docsmint/actions/workflows/ci.yml)
-
-[GitHub](https://github.com/HiAi-gg/docsmint) ·
-[Docker Hub](https://hub.docker.com/r/vgalibov/docsmint) ·
-[npm](https://www.npmjs.com/package/@hiai-gg/docsmint) ·
-[LobeHub MCP](https://lobehub.com/mcp/hiai-gg-docsmint)
+[![Bun](https://img.shields.io/badge/Runtime-Bun_1.4-black?logo=bun&logoColor=white)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![Svelte](https://img.shields.io/badge/Svelte-5.x-FF3E00?logo=svelte&logoColor=white)](https://svelte.dev)
+[![Elysia](https://img.shields.io/badge/Elysia-1.4-lightgrey?logo=elysia&logoColor=white)](https://elysiajs.com)
+[![Tailwind_CSS](https://img.shields.io/badge/Tailwind_CSS-v4-06B6D4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com)
+[![Drizzle_ORM](https://img.shields.io/badge/Drizzle_ORM-0.45-C5F74F?logo=drizzle&logoColor=black)](https://orm.drizzle.team)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+[![MCP Badge](https://lobehub.com/badge/mcp/hiai-gg-docsmint)](https://lobehub.com/mcp/hiai-gg-docsmint)
+[![DocsMint Cloud](https://img.shields.io/badge/DocsMint_Cloud-Connect-16a34a)](https://docsmint.com/mcp/connect?source=github_mcp)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-Listed-0891b2)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.HiAi-gg%2Fdocsmint/versions/latest)
 
 <img width="1920" height="974" alt="DocsMint installable document workspace" src="https://github.com/user-attachments/assets/94701d01-a361-4ca1-b16d-de2a0c64d684" />
 
@@ -63,18 +70,21 @@ bridge to your running deployment, not a server installer. See the
 - **Choose how you run it.** Use [managed DocsMint](https://docsmint.com) or
   self-host the application, database, search, queues, and files.
 
-## What's new in 0.8.5?
+## What's new in 0.8.7?
+
+Agents can now complete more document workflows without leaving MCP:
 
-This release makes DocsMint easier to discover, install, and evaluate:
+- Move documents to trash, remove folders or categories, and restore saved versions.
+- Keep changes within workspace/category permissions; version restoration requires edit access.
+- Discover clearer tool descriptions, parameter guidance, and destructive-operation annotations.
+- Apply GraphRAG query text and related-document result limits consistently.
 
-- Clearer guides for choosing DocsMint Cloud or a self-hosted workspace.
-- One public package, `@hiai-gg/docsmint`, for the SDK, CLI, and MCP bridge.
-- A Docker image guide that distinguishes the API, web application, and Caddy proxy.
-- Consistent release notes and package documentation, with links that also work on npm.
+The MCP surface grows additively from 17 to 21 tools. Existing tool names remain
+available. No database migration is required. Hosted clients receive these tools
+when their DocsMint host adopts this release.
 
-No database migration or public API change is required. Read the
-[release notes](https://github.com/HiAi-gg/docsmint/releases/tag/v0.8.5),
-[changelog](https://github.com/HiAi-gg/docsmint/blob/main/CHANGELOG.md), or [roadmap](https://github.com/HiAi-gg/docsmint/blob/main/docs/ROADMAP.md).
+Read the [release notes](https://github.com/HiAi-gg/docsmint/releases/tag/v0.8.7)
+and [changelog](https://github.com/HiAi-gg/docsmint/blob/main/CHANGELOG.md).
 
 ## Install with an AI agent
 
@@ -126,7 +136,7 @@ docker pull vgalibov/docsmint:web-latest
 docker pull vgalibov/docsmint:caddy-latest
 ```
 
-Use versioned tags `api-v0.8.5`, `web-v0.8.5`, and `caddy-v0.8.5` for
+Use versioned tags `api-v0.8.7`, `web-v0.8.7`, and `caddy-v0.8.7` for
 reproducible deploys. Caddy is the supporting reverse proxy with rate limiting;
 it is separate from the API and web application. The quickstart still builds the Compose stack from this repository so PostgreSQL,
 Redis, and SeaweedFS start together with the application.
@@ -211,7 +221,7 @@ command and configuration precedence.
 ## Connect an MCP client
 
 Give agents a secure path to search, read, and maintain your knowledge without
-database or filesystem access. DocsMint publishes 17 tools plus ready-made
+database or filesystem access. DocsMint publishes 21 tools plus ready-made
 research prompts, scoped resources, and a document-manager skill.
 
 ### Hosted DocsMint

package/dist/backend/index.js

@@ -231613,6 +231613,106 @@ function stripQuotes(value) {
   return trimmed;
 }
 
+// ../../backend/src/lib/graph/search-query.ts
+init_drizzle_orm();
+
+// ../../backend/src/search/query-analyzer.ts
+var CYRILLIC_LETTER = /\p{Script=Cyrillic}/u;
+var LATIN_LETTER = /\p{Script=Latin}/u;
+var LETTER2 = /\p{L}/u;
+function normalizeQuery(query) {
+  const normalized = query.normalize("NFC");
+  let result = "";
+  let inQuotedPhrase = false;
+  let escaped = false;
+  let pendingWhitespace = false;
+  for (const character of normalized) {
+    if (inQuotedPhrase) {
+      result += character;
+      if (escaped) {
+        escaped = false;
+      } else if (character === "\\") {
+        escaped = true;
+      } else if (character === '"') {
+        inQuotedPhrase = false;
+      }
+      continue;
+    }
+    if (character === '"') {
+      if (pendingWhitespace && result.length > 0)
+        result += " ";
+      pendingWhitespace = false;
+      result += character;
+      inQuotedPhrase = true;
+      continue;
+    }
+    if (/\s/u.test(character)) {
+      pendingWhitespace = true;
+      continue;
+    }
+    if (pendingWhitespace && result.length > 0)
+      result += " ";
+    pendingWhitespace = false;
+    result += character;
+  }
+  return result;
+}
+function detectLanguage(query) {
+  const normalized = normalizeQuery(query);
+  let cyrillic = 0;
+  let latin = 0;
+  for (const token of normalized.split(" ")) {
+    if (token.includes("/"))
+      continue;
+    for (const character of token) {
+      if (!LETTER2.test(character))
+        continue;
+      if (CYRILLIC_LETTER.test(character))
+        cyrillic += 1;
+      else if (LATIN_LETTER.test(character))
+        latin += 1;
+    }
+  }
+  if (cyrillic > 0 && latin > 0)
+    return "mixed";
+  if (cyrillic > 0)
+    return "ru";
+  if (latin > 0)
+    return "en";
+  return "und";
+}
+function analyzeQuery(query) {
+  return {
+    original: query,
+    normalized: normalizeQuery(query),
+    detectedLanguage: detectLanguage(query),
+    translations: [],
+    synonyms: [],
+    concepts: [],
+    namedEntities: []
+  };
+}
+
+// ../../backend/src/lib/graph/search-query.ts
+function graphSearchDocumentQuery(ctx, documentIds, query) {
+  const normalized = normalizeQuery(query ?? "");
+  const english = sql`websearch_to_tsquery('english', ${normalized})`;
+  const simple = sql`websearch_to_tsquery('simple', ${normalized})`;
+  const exact = sql`lower(trim(d.title)) = lower(${normalized})`;
+  const match2 = normalized ? sql`AND (${exact} OR d.search_vector @@ ${english} OR d.search_vector_simple @@ ${simple})` : sql``;
+  const order = normalized ? sql`${exact} DESC, GREATEST(ts_rank(d.search_vector, ${english}), ts_rank(d.search_vector_simple, ${simple})) DESC,` : sql``;
+  const allowed2 = documentIds.length ? sql`d.id IN (${sql.join(documentIds.map((id3) => sql`${id3}`), sql`, `)})` : sql`false`;
+  return sql`
+  SELECT d.id, d.title, d.content
+  FROM documents d
+  WHERE ${tenantOwnerSql("d", ctx)}
+   AND d.deleted_at IS NULL
+   AND ${allowed2}
+   ${match2}
+  ORDER BY ${order} d.id ASC
+ `;
+}
+
 // ../../backend/src/api/routes/graph.ts
 init_logger3();
 var entitiesQuerySchema = exports_external2.object({
@@ -231621,8 +231721,11 @@ var entitiesQuerySchema = exports_external2.object({
 var relatedParamsSchema = exports_external2.object({
   docId: exports_external2.string().min(1)
 });
+var relatedQuerySchema = exports_external2.object({
+  limit: exports_external2.coerce.number().int().min(1).max(100).default(20)
+});
 var graphSearchBodySchema = exports_external2.object({
-  query: exports_external2.string().optional(),
+  query: exports_external2.string().max(2000).optional(),
   docIds: exports_external2.array(exports_external2.string().min(1)).min(1).max(50),
   maxResults: exports_external2.number().int().min(1).max(100).optional()
 });
@@ -231668,7 +231771,7 @@ var graphRoutes = new Elysia({ prefix: "/api/graph" }).get("/entities", async ({
     tags: ["Graph"],
     summary: "List entities linked to a document"
   }
-}).get("/related/:docId", async ({ params: params2, set: set2, request }) => {
+}).get("/related/:docId", async ({ params: params2, query, set: set2, request }) => {
   const rl = await applyRateLimit(request, set2);
   if (!rl.ok)
     return rl.response;
@@ -231687,6 +231790,11 @@ var graphRoutes = new Elysia({ prefix: "/api/graph" }).get("/entities", async ({
     set2.status = 400;
     return { error: "Invalid params", details: parsed.error.flatten() };
   }
+  const parsedQuery = relatedQuerySchema.safeParse(query);
+  if (!parsedQuery.success) {
+    set2.status = 400;
+    return { error: "Invalid query", details: parsedQuery.error.flatten() };
+  }
   try {
     const seedIds = await allowedGraphDocumentIds(access, [
       parsed.data.docId
@@ -231698,7 +231806,7 @@ var graphRoutes = new Elysia({ prefix: "/api/graph" }).get("/entities", async ({
     if (!config3.GRAPH_SEARCH_ENABLED)
       return { related: [] };
     const related = await fetchRelatedDocuments(ctx, parsed.data.docId, access);
-    return { related };
+    return { related: related.slice(0, parsedQuery.data.limit) };
   } catch (err) {
     logger3.warn({ err, docId: parsed.data.docId }, "Graph related lookup failed \u2014 returning empty");
     return { related: [] };
@@ -231737,7 +231845,7 @@ var graphRoutes = new Elysia({ prefix: "/api/graph" }).get("/entities", async ({
     if (!config3.GRAPH_SEARCH_ENABLED) {
       return { query, entities: [], relatedDocs: [] };
     }
-    const result = await graphRagLookup(ctx, docIds, maxResults, access);
+    const result = await graphRagLookup(ctx, docIds, maxResults, access, query);
     return { query, ...result };
   } catch (err) {
     logger3.warn({ err, docIds: docIds.length }, "Graph RAG search failed \u2014 returning empty");
@@ -231805,7 +231913,7 @@ async function fetchRelatedDocuments(ctx, docId, access) {
   const allowedIds = access ? await allowedGraphDocumentIds(access, neighborIds) : await filterToOwnedDocuments(ctx, neighborIds);
   return current.filter((neighbor) => allowedIds.has(neighbor.docId));
 }
-async function graphRagLookup(ctx, docIds, maxResults, access) {
+async function graphRagLookup(ctx, docIds, maxResults, access, query) {
   const sql6 = await getGraphDb();
   if (!sql6)
     return { entities: [], relatedDocs: [] };
@@ -231838,12 +231946,13 @@ async function graphRagLookup(ctx, docIds, maxResults, access) {
   if (ownedNeighborIds.length === 0) {
     return { entities: Array.from(entityMap.values()), relatedDocs: [] };
   }
-  const rows = await loadDocumentSummaries(ctx, ownedNeighborIds);
+  const rows = await loadDocumentSummaries(ctx, ownedNeighborIds, query);
   const byId = new Map;
   for (const r4 of rows)
     byId.set(r4.id, r4);
   const relatedDocs = [];
-  for (const id3 of ownedNeighborIds) {
+  const rankedIds = query?.trim() ? rows.map((row) => row.id) : ownedNeighborIds;
+  for (const id3 of rankedIds) {
     const meta3 = neighborMap.get(id3);
     const row = byId.get(id3);
     if (!meta3 || !row)
@@ -231919,19 +232028,11 @@ function currentGraphNeighbors(expansion, activeGenerations) {
   }
   return [...current.values()].sort((left, right) => left.hopDistance - right.hopDistance || left.docId.localeCompare(right.docId));
 }
-async function loadDocumentSummaries(ctx, docIds) {
+async function loadDocumentSummaries(ctx, docIds, query) {
   if (docIds.length === 0)
     return [];
   return withTenant(ctx, async (tx) => {
-    return tx.select({
-      id: documents.id,
-      title: documents.title,
-      content: documents.content,
-      folderId: documents.folderId,
-      folderName: folders.name,
-      createdAt: documents.createdAt,
-      updatedAt: documents.updatedAt
-    }).from(documents).leftJoin(folders, eq(folders.id, documents.folderId)).where(and(tenantOwnerCondition(documents.ownerId, documents.workspaceId, ctx), inArray(documents.id, docIds), isNull(documents.deletedAt)));
+    return await tx.execute(graphSearchDocumentQuery(ctx, docIds, query));
   });
 }
 function cypherDocReplace(cypher, docId) {
@@ -232493,83 +232594,6 @@ function evaluateConfidence(results, _plan, thresholds = { vectorMinSimilarity:
   return { confident: reasons.length === 0, reasons };
 }
 
-// ../../backend/src/search/query-analyzer.ts
-var CYRILLIC_LETTER = /\p{Script=Cyrillic}/u;
-var LATIN_LETTER = /\p{Script=Latin}/u;
-var LETTER2 = /\p{L}/u;
-function normalizeQuery(query) {
-  const normalized = query.normalize("NFC");
-  let result = "";
-  let inQuotedPhrase = false;
-  let escaped = false;
-  let pendingWhitespace = false;
-  for (const character of normalized) {
-    if (inQuotedPhrase) {
-      result += character;
-      if (escaped) {
-        escaped = false;
-      } else if (character === "\\") {
-        escaped = true;
-      } else if (character === '"') {
-        inQuotedPhrase = false;
-      }
-      continue;
-    }
-    if (character === '"') {
-      if (pendingWhitespace && result.length > 0)
-        result += " ";
-      pendingWhitespace = false;
-      result += character;
-      inQuotedPhrase = true;
-      continue;
-    }
-    if (/\s/u.test(character)) {
-      pendingWhitespace = true;
-      continue;
-    }
-    if (pendingWhitespace && result.length > 0)
-      result += " ";
-    pendingWhitespace = false;
-    result += character;
-  }
-  return result;
-}
-function detectLanguage(query) {
-  const normalized = normalizeQuery(query);
-  let cyrillic = 0;
-  let latin = 0;
-  for (const token of normalized.split(" ")) {
-    if (token.includes("/"))
-      continue;
-    for (const character of token) {
-      if (!LETTER2.test(character))
-        continue;
-      if (CYRILLIC_LETTER.test(character))
-        cyrillic += 1;
-      else if (LATIN_LETTER.test(character))
-        latin += 1;
-    }
-  }
-  if (cyrillic > 0 && latin > 0)
-    return "mixed";
-  if (cyrillic > 0)
-    return "ru";
-  if (latin > 0)
-    return "en";
-  return "und";
-}
-function analyzeQuery(query) {
-  return {
-    original: query,
-    normalized: normalizeQuery(query),
-    detectedLanguage: detectLanguage(query),
-    translations: [],
-    synonyms: [],
-    concepts: [],
-    namedEntities: []
-  };
-}
-
 // ../../backend/src/search/query-expander.ts
 init_zod();
 init_config();
@@ -238398,7 +238422,7 @@ var swaggerConfig = {
     },
     info: {
       title: "DocsMint API",
-      version: "0.8.5",
+      version: "0.8.7",
       description: "Self-hosted AI-native knowledge workspace and installable PWA with hybrid search, GraphRAG, REST, SDK, CLI, and MCP access for people and AI agents.",
       contact: { name: "HiAi-gg", url: "https://github.com/HiAi-gg/docsmint" },
       license: {

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.5" });
+  const server = new McpServer({ name: "docsmint", version: "0.8.7" });
   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>;

package/dist/mcp-server.js

@@ -16,7 +16,7 @@ var __export = (target, all) => {
 
 // ../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");
@@ -577,52 +577,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: [
@@ -637,9 +672,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: [
@@ -730,6 +765,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(","),
@@ -776,15 +815,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) {
@@ -799,14 +838,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) {
@@ -821,14 +860,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) {
@@ -844,12 +883,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) {
@@ -864,12 +903,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) {
@@ -884,15 +923,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) {
@@ -907,12 +946,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) {
@@ -927,15 +966,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) {
@@ -955,16 +994,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) {
@@ -980,13 +1019,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) {
@@ -1028,7 +1067,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,
@@ -1046,9 +1090,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.5" });
+  const server = new McpServer({ name: "docsmint", version: "0.8.7" });
   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.8.5",
+  "version": "0.8.7",
   "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.8.5';
+const VERSION = '0.8.7';
 
 const program = new Command();
 program.name('docsmint').description('CLI for the DocsMint knowledge workspace').version(VERSION);

package/server.json

@@ -10,7 +10,7 @@
     "id": "1249550690",
     "subfolder": "packages/mcp-server"
   },
-  "version": "0.8.5",
+  "version": "0.8.7",
   "icons": [
     {
       "src": "https://raw.githubusercontent.com/HiAi-gg/docsmint/main/frontend/static/logo-dark.png",
@@ -30,7 +30,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@hiai-gg/docsmint",
-      "version": "0.8.5",
+      "version": "0.8.7",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"