@hiai-gg/docsmint 0.6.0 → 0.6.2

package/packages/mcp-server/src/tools/create-snapshot.ts

@@ -1,20 +1,14 @@
-import { z } from "zod";
-import { client } from "../client.js";
-import type { Version } from "../types.js";
+import { z } from 'zod';
+import { client, type HiaiDocsClient } from '../client.js';
+import type { Version } from '../types.js';
 
 export const definition = {
-  name: "create_snapshot",
-  description:
-    "Create a named snapshot (labelled version) of a document from its current content.",
+  name: 'create_snapshot',
+  description: 'Create a named snapshot (labelled version) of a document from its current content.',
   inputSchema: {
-    documentId: z.string().describe("Document ID to snapshot."),
-    label: z
-      .string()
-      .describe("Short label for the snapshot (e.g. 'v1.0-release')."),
-    description: z
-      .string()
-      .optional()
-      .describe("Optional longer description of the snapshot."),
+    documentId: z.string().describe('Document ID to snapshot.'),
+    label: z.string().describe("Short label for the snapshot (e.g. 'v1.0-release')."),
+    description: z.string().optional().describe('Optional longer description of the snapshot.'),
   },
 } as const;
 
@@ -24,7 +18,10 @@ export interface CreateSnapshotArgs {
   description?: string;
 }
 
-export async function handler(args: CreateSnapshotArgs): Promise<Version> {
-  const { documentId, ...input } = args;
-  return (await client.createSnapshot(documentId, input)) as Version;
-}
+export const createHandler = (api: HiaiDocsClient) =>
+  async function createSnapshot(args: CreateSnapshotArgs): Promise<Version> {
+    const { documentId, ...input } = args;
+    return (await api.createSnapshot(documentId, input)) as Version;
+  };
+
+export const handler = createHandler(client);

package/packages/mcp-server/src/tools/export-document.ts

@@ -1,13 +1,12 @@
-import { z } from "zod";
-import { client } from "../client.js";
-import type { ExportResponse } from "../types.js";
+import { z } from 'zod';
+import { client, type HiaiDocsClient } from '../client.js';
+import type { ExportResponse } from '../types.js';
 
 export const definition = {
-  name: "export_document",
-  description:
-    "Export a document as markdown. Returns the rendered markdown content.",
+  name: 'export_document',
+  description: 'Export a document as markdown. Returns the rendered markdown content.',
   inputSchema: {
-    id: z.string().describe("Document ID to export."),
+    id: z.string().describe('Document ID to export.'),
   },
 } as const;
 
@@ -15,8 +14,9 @@ export interface ExportDocumentArgs {
   id: string;
 }
 
-export async function handler(
-  args: ExportDocumentArgs,
-): Promise<ExportResponse> {
-  return (await client.exportDocument(args.id)) as ExportResponse;
-}
+export const createHandler = (api: HiaiDocsClient) =>
+  async function exportDocument(args: ExportDocumentArgs): Promise<ExportResponse> {
+    return (await api.exportDocument(args.id)) as ExportResponse;
+  };
+
+export const handler = createHandler(client);

package/packages/mcp-server/src/tools/get-document.ts

@@ -1,13 +1,12 @@
-import { z } from "zod";
-import { client } from "../client.js";
-import type { DocumentDetail } from "../types.js";
+import { z } from 'zod';
+import { client, type HiaiDocsClient } from '../client.js';
+import type { DocumentDetail } from '../types.js';
 
 export const definition = {
-  name: "get_document",
-  description:
-    "Fetch a single document by ID. Returns full content, metadata, and tags.",
+  name: 'get_document',
+  description: 'Fetch a single document by ID. Returns full content, metadata, and tags.',
   inputSchema: {
-    id: z.string().describe("Document ID."),
+    id: z.string().describe('Document ID.'),
   },
 } as const;
 
@@ -15,6 +14,9 @@ export interface GetDocumentArgs {
   id: string;
 }
 
-export async function handler(args: GetDocumentArgs): Promise<DocumentDetail> {
-  return (await client.getDocument(args.id)) as DocumentDetail;
-}
+export const createHandler = (api: HiaiDocsClient) =>
+  async function getDocument(args: GetDocumentArgs): Promise<DocumentDetail> {
+    return (await api.getDocument(args.id)) as DocumentDetail;
+  };
+
+export const handler = createHandler(client);

package/packages/mcp-server/src/tools/list-documents.ts

@@ -1,30 +1,21 @@
-import { z } from "zod";
-import { client } from "../client.js";
-import type { ListDocumentsResponse } from "../types.js";
+import { z } from 'zod';
+import { client, type HiaiDocsClient } from '../client.js';
+import type { ListDocumentsResponse } from '../types.js';
 
 export const definition = {
-  name: "list_documents",
-  description:
-    "List documents with pagination, optionally filtered by folder or tag.",
+  name: 'list_documents',
+  description: 'List documents with pagination, optionally filtered by folder or tag.',
   inputSchema: {
-    folderId: z
-      .string()
-      .optional()
-      .describe("Optional folder ID to filter by."),
-    tag: z.string().optional().describe("Optional tag ID to filter by."),
-    page: z
-      .number()
-      .int()
-      .positive()
-      .optional()
-      .describe("Page number (1-indexed, default 1)."),
+    folderId: z.string().optional().describe('Optional folder ID to filter by.'),
+    tag: z.string().optional().describe('Optional tag ID to filter by.'),
+    page: z.number().int().positive().optional().describe('Page number (1-indexed, default 1).'),
     limit: z
       .number()
       .int()
       .positive()
       .max(100)
       .optional()
-      .describe("Items per page (default 20, max 100)."),
+      .describe('Items per page (default 20, max 100).'),
   },
 } as const;
 
@@ -35,8 +26,9 @@ export interface ListDocumentsArgs {
   limit?: number;
 }
 
-export async function handler(
-  args: ListDocumentsArgs,
-): Promise<ListDocumentsResponse> {
-  return (await client.listDocuments(args)) as ListDocumentsResponse;
-}
+export const createHandler = (api: HiaiDocsClient) =>
+  async function listDocuments(args: ListDocumentsArgs): Promise<ListDocumentsResponse> {
+    return (await api.listDocuments(args)) as ListDocumentsResponse;
+  };
+
+export const handler = createHandler(client);

package/packages/mcp-server/src/tools/list-folders.ts

@@ -1,18 +1,16 @@
-import { z } from "zod";
-import { client } from "../client.js";
-import type { Folder } from "../types.js";
+import { z } from 'zod';
+import { client, type HiaiDocsClient } from '../client.js';
+import type { Folder } from '../types.js';
 
 export const definition = {
-  name: "list_folders",
+  name: 'list_folders',
   description:
-    "List folders, optionally scoped to a parent folder. Returns a flat list of immediate children.",
+    'List folders, optionally scoped to a parent folder. Returns a flat list of immediate children.',
   inputSchema: {
     parentId: z
       .string()
       .optional()
-      .describe(
-        "Optional parent folder ID. Omit to list top-level (root) folders.",
-      ),
+      .describe('Optional parent folder ID. Omit to list top-level (root) folders.'),
   },
 } as const;
 
@@ -20,6 +18,9 @@ export interface ListFoldersArgs {
   parentId?: string;
 }
 
-export async function handler(args: ListFoldersArgs): Promise<Folder[]> {
-  return (await client.listFolders(args)) as Folder[];
-}
+export const createHandler = (api: HiaiDocsClient) =>
+  async function listFolders(args: ListFoldersArgs): Promise<Folder[]> {
+    return (await api.listFolders(args)) as Folder[];
+  };
+
+export const handler = createHandler(client);

package/packages/mcp-server/src/tools/search.ts

@@ -1,27 +1,21 @@
-import { z } from "zod";
-import { client } from "../client.js";
-import type { SearchResponse } from "../types.js";
+import { z } from 'zod';
+import { client, type HiaiDocsClient } from '../client.js';
+import type { SearchResponse } from '../types.js';
 
 export const definition = {
-  name: "search_documents",
+  name: 'search_documents',
   description:
-    "Hybrid search across documents (full-text + semantic). Supports filtering by folder and tags.",
+    'Hybrid search across documents (full-text + semantic). Supports filtering by folder and tags.',
   inputSchema: {
-    query: z.string().describe("Search query string."),
-    folder: z
-      .string()
-      .optional()
-      .describe("Optional folder ID to scope the search to."),
-    tags: z
-      .array(z.string())
-      .optional()
-      .describe("Optional tag IDs to filter by."),
+    query: z.string().describe('Search query string.'),
+    folder: z.string().optional().describe('Optional folder ID to scope the search to.'),
+    tags: z.array(z.string()).optional().describe('Optional tag IDs to filter by.'),
     limit: z
       .number()
       .int()
       .positive()
       .optional()
-      .describe("Maximum number of results to return (default 20)."),
+      .describe('Maximum number of results to return (default 20).'),
   },
 } as const;
 
@@ -32,11 +26,14 @@ export type SearchArgs = {
   limit?: number;
 };
 
-export async function handler(args: SearchArgs): Promise<SearchResponse> {
-  return (await client.search({
-    query: args.query,
-    folder: args.folder,
-    tags: args.tags,
-    limit: args.limit,
-  })) as SearchResponse;
-}
+export const createHandler = (api: HiaiDocsClient) =>
+  async function searchDocuments(args: SearchArgs): Promise<SearchResponse> {
+    return (await api.search({
+      query: args.query,
+      folder: args.folder,
+      tags: args.tags,
+      limit: args.limit,
+    })) as SearchResponse;
+  };
+
+export const handler = createHandler(client);

package/packages/mcp-server/src/tools/update-document.ts

@@ -1,18 +1,23 @@
-import { z } from "zod";
-import { client } from "../client.js";
-import type { DocumentDetail } from "../types.js";
+import { z } from 'zod';
+import { client, type HiaiDocsClient } from '../client.js';
+import type { DocumentDetail } from '../types.js';
 
 export const definition = {
-  name: "update_document",
+  name: 'update_document',
   description:
     "Update an existing document's title and/or content. The server creates a new version on each update.",
   inputSchema: {
-    id: z.string().describe("Document ID to update."),
-    title: z.string().optional().describe("New title for the document."),
-    content: z
+    id: z.string().describe('Document ID to update.'),
+    title: z.string().optional().describe('New title for the document.'),
+    content: z.string().optional().describe('New markdown content for the document.'),
+    folderId: z.string().nullable().optional().describe('Move the document to a folder.'),
+    categoryId: z
       .string()
+      .nullable()
       .optional()
-      .describe("New markdown content for the document."),
+      .describe(
+        'Move the document to a category. Category keys cannot escape their configured category.'
+      ),
   },
 } as const;
 
@@ -20,11 +25,14 @@ export interface UpdateDocumentArgs {
   id: string;
   title?: string;
   content?: string;
+  folderId?: string | null;
+  categoryId?: string | null;
 }
 
-export async function handler(
-  args: UpdateDocumentArgs,
-): Promise<DocumentDetail> {
-  const { id, ...patch } = args;
-  return (await client.updateDocument(id, patch)) as DocumentDetail;
-}
+export const createHandler = (api: HiaiDocsClient) =>
+  async function updateDocument(args: UpdateDocumentArgs): Promise<DocumentDetail> {
+    const { id, ...patch } = args;
+    return (await api.updateDocument(id, patch)) as DocumentDetail;
+  };
+
+export const handler = createHandler(client);

package/packages/mcp-server/src/tools/version-history.ts

@@ -1,21 +1,16 @@
-import { z } from "zod";
-import { client } from "../client.js";
-import type { Version } from "../types.js";
+import { z } from 'zod';
+import { client, type HiaiDocsClient } from '../client.js';
+import type { Version } from '../types.js';
 
 export const definition = {
-  name: "get_version_history",
-  description:
-    "List the version history for a document. Optionally restrict to named snapshots.",
+  name: 'get_version_history',
+  description: 'List the version history for a document. Optionally restrict to named snapshots.',
   inputSchema: {
-    documentId: z
-      .string()
-      .describe("Document ID whose versions should be listed."),
+    documentId: z.string().describe('Document ID whose versions should be listed.'),
     onlySnapshots: z
       .boolean()
       .optional()
-      .describe(
-        "When true, only return named snapshots (skip auto-saved revisions).",
-      ),
+      .describe('When true, only return named snapshots (skip auto-saved revisions).'),
   },
 } as const;
 
@@ -24,9 +19,9 @@ export interface VersionHistoryArgs {
   onlySnapshots?: boolean;
 }
 
-export async function handler(args: VersionHistoryArgs): Promise<Version[]> {
-  return (await client.getVersionHistory(
-    args.documentId,
-    args.onlySnapshots,
-  )) as Version[];
-}
+export const createHandler = (api: HiaiDocsClient) =>
+  async function getVersionHistory(args: VersionHistoryArgs): Promise<Version[]> {
+    return (await api.getVersionHistory(args.documentId, args.onlySnapshots)) as Version[];
+  };
+
+export const handler = createHandler(client);

package/server.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.hiai-gg/docsmint",
+  "title": "DocsMint",
+  "description": "Manage scoped DocsMint documents, folders, categories, search, GraphRAG, and indexing through MCP.",
+  "repository": {
+    "url": "https://github.com/HiAi-gg/docsmint",
+    "source": "github",
+    "id": "1249550690"
+  },
+  "version": "0.6.2",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@hiai-gg/docsmint",
+      "version": "0.6.2",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "HIAI_DOCS_URL",
+          "description": "Base URL of the DocsMint API.",
+          "default": "http://localhost:50700"
+        },
+        {
+          "name": "HIAI_DOCS_API_KEY",
+          "description": "Workspace or category scoped DocsMint API key.",
+          "isRequired": true,
+          "isSecret": true
+        }
+      ]
+    }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://docsmint.com/mcp",
+      "headers": [
+        {
+          "name": "Authorization",
+          "description": "Bearer DocsMint API key.",
+          "isRequired": true,
+          "isSecret": true
+        },
+        {
+          "name": "X-Docsmint-Workspace",
+          "description": "Optional workspace override for a workspace scoped key.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

package/skills/docsmint-document-manager/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: docsmint-document-manager
+description: Manage and research DocsMint documents through its scoped MCP tools, including categories, folders, hybrid search, GraphRAG, and index refresh.
+---
+
+# DocsMint Document Manager
+
+Use this skill when an agent must create, organize, edit, or research documents in a DocsMint workspace.
+
+## Safety and access
+
+- Treat the configured API key as the complete authority boundary.
+- A workspace key may manage categories, folders, tags, and documents according to its role.
+- A category key may access only its bound category, folders and documents inside that category, and explicitly granted `read`, `edit`, or `write` operations.
+- Never attempt to manage API keys, members, billing, or workspace settings through document tools.
+- Read a document before changing it. Preserve its language and structure unless the user asks otherwise.
+
+## Retrieval workflow
+
+1. Use `search_documents` with the user's original language.
+2. Read the most relevant documents with `get_document`.
+3. Use `get_related_documents` or `search_knowledge_graph` only with authorized document IDs returned by search.
+4. Cite document IDs and distinguish retrieved facts from inference.
+
+## Document management workflow
+
+1. Inspect `list_categories`, `list_folders`, and `list_tags` before organizing content.
+2. Create categories only with a workspace-scoped key.
+3. Create folders and documents within the active scope.
+4. After an update, inspect `get_document_index_status`; use `refresh_document_index` only when indexing is stale or failed.
+5. Use snapshots before a substantial rewrite when version history is important.
+
+DocsMint owns chunking, embeddings, multilingual hybrid retrieval, entity extraction, and GraphRAG indexing. Agents must use the MCP tools and never write those persistence layers directly.