@hiai-gg/docsmint 0.6.8 → 0.7.1

package/packages/mcp-server/src/capabilities.ts

@@ -1,189 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-
-import type { HiaiDocsClient } from './client.js';
-
-export const capabilityCatalog = {
-  tools: [
-    'search_documents',
-    'get_document',
-    'create_document',
-    'update_document',
-    'list_documents',
-    'list_folders',
-    'create_folder',
-    'create_snapshot',
-    'get_version_history',
-    'export_document',
-    'list_categories',
-    'create_category',
-    'list_tags',
-    'get_related_documents',
-    'search_knowledge_graph',
-    'get_document_index_status',
-    'refresh_document_index',
-  ] as const,
-  prompts: ['organize_workspace', 'research_workspace'] as const,
-  resources: [
-    'docsmint://guide/editor',
-    'docsmint://guide/search',
-    'docsmint://workspace/catalog',
-  ] as const,
-};
-
-type TextResult = { content: Array<{ type: 'text'; text: string }> };
-
-function jsonResult(value: unknown): TextResult {
-  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
-}
-
-export function registerExtendedCapabilities(server: McpServer, client: HiaiDocsClient): void {
-  server.registerTool(
-    'list_categories',
-    {
-      description:
-        'List categories visible to the API key. Category keys receive only their bound category.',
-      inputSchema: z.object({}),
-    },
-    async () => jsonResult(await client.listCategories())
-  );
-  server.registerTool(
-    'create_category',
-    {
-      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(),
-      }),
-    },
-    async (input) => jsonResult(await client.createCategory(input))
-  );
-  server.registerTool(
-    'list_tags',
-    {
-      description: 'List tags visible in the workspace or bound category.',
-      inputSchema: z.object({}),
-    },
-    async () => jsonResult(await 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(),
-      }),
-    },
-    async ({ documentId, limit }) => jsonResult(await 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(),
-      }),
-    },
-    async (input) => jsonResult(await 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) }),
-    },
-    async ({ documentId }) => jsonResult(await 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) }),
-    },
-    async ({ documentId }) => jsonResult(await 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(),
-      }),
-    },
-    ({ objective, language }) => ({
-      messages: [
-        {
-          role: 'user',
-          content: {
-            type: 'text',
-            text: `Organize this DocsMint workspace for: ${objective}. Work in ${language ?? 'the document language'}. Inspect categories, folders, tags, and documents before proposing or applying changes. Preserve document content and obey the API key scope.`,
-          },
-        },
-      ],
-    })
-  );
-  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(),
-      }),
-    },
-    ({ question, language }) => ({
-      messages: [
-        {
-          role: 'user',
-          content: {
-            type: 'text',
-            text: `Answer this question from DocsMint: ${question}. Respond in ${language ?? 'the question language'}. Start with hybrid search, use graph traversal only from authorized result documents, and cite document IDs. Distinguish retrieved facts from inference.`,
-          },
-        },
-      ],
-    })
-  );
-
-  server.registerResource('editor-guide', 'docsmint://guide/editor', {}, async (uri) => ({
-    contents: [
-      {
-        uri: uri.href,
-        mimeType: 'text/markdown',
-        text: '# DocsMint editing rules\n\nRead a document before updating it. Preserve its language, title intent, TipTap/Markdown structure, category, folder, and tags unless the user explicitly requests a change. After content changes, verify index status and request refresh only when needed.',
-      },
-    ],
-  }));
-  server.registerResource('search-guide', 'docsmint://guide/search', {}, async (uri) => ({
-    contents: [
-      {
-        uri: uri.href,
-        mimeType: 'text/markdown',
-        text: '# DocsMint retrieval rules\n\nUse search_documents for normal retrieval. Use get_related_documents or search_knowledge_graph only with document IDs already authorized by the active API key. Keep multilingual queries in their original language and cite document IDs in answers.',
-      },
-    ],
-  }));
-  server.registerResource('workspace-catalog', 'docsmint://workspace/catalog', {}, async (uri) => {
-    const [categories, folders, tags] = await Promise.all([
-      client.listCategories(),
-      client.listFolders({}),
-      client.listTags(),
-    ]);
-    return {
-      contents: [
-        {
-          uri: uri.href,
-          mimeType: 'application/json',
-          text: JSON.stringify({ categories, folders, tags }, null, 2),
-        },
-      ],
-    };
-  });
-}

package/packages/mcp-server/src/client.ts

@@ -1,225 +0,0 @@
-/**
- * REST client for hiai-docs.
- *
- * Reads configuration from environment:
- *   HIAI_DOCS_URL       — base URL (default: http://localhost:50700)
- *   HIAI_DOCS_API_KEY   — bearer token for the API
- *
- * Bun-native. Uses global `fetch`. Throws on non-2xx responses with the
- * error message extracted from the response body when possible.
- */
-
-import type { ExportResponse } from "./types.js";
-
-const DEFAULT_BASE_URL = "http://localhost:50700";
-
-function readConfig() {
-	const baseUrl = (process.env.HIAI_DOCS_URL ?? DEFAULT_BASE_URL).replace(
-		/\/+$/,
-		"",
-	);
-	const apiKey = process.env.HIAI_DOCS_API_KEY ?? "";
-	return { baseUrl, apiKey };
-}
-
-export class HiaiDocsError extends Error {
-	constructor(
-		message: string,
-		readonly status: number,
-		readonly body: unknown,
-	) {
-		super(message);
-		this.name = "HiaiDocsError";
-	}
-}
-
-type QueryValue = string | number | boolean | string[] | undefined;
-
-async function request<T>(
-	method: string,
-	path: string,
-	options: { query?: Record<string, QueryValue>; body?: unknown } = {},
-): Promise<T> {
-	const { baseUrl, apiKey } = readConfig();
-
-	const url = new URL(path.startsWith("/") ? path : `/${path}`, `${baseUrl}/`);
-	if (options.query) {
-		for (const [key, value] of Object.entries(options.query)) {
-			if (value === undefined) continue;
-			if (Array.isArray(value)) {
-				if (value.length > 0) url.searchParams.set(key, value.join(","));
-			} else {
-				url.searchParams.set(key, String(value));
-			}
-		}
-	}
-
-	const headers: Record<string, string> = {
-		Accept: "application/json",
-	};
-	if (apiKey) {
-		headers.Authorization = `Bearer ${apiKey}`;
-	}
-
-	let body: BodyInit | undefined;
-	if (options.body !== undefined) {
-		headers["Content-Type"] = "application/json";
-		body = JSON.stringify(options.body);
-	}
-
-	const response = await fetch(url, { method, headers, body });
-
-	const contentType = response.headers.get("content-type") ?? "";
-	const isJson = contentType.includes("application/json");
-	const payload: unknown = isJson
-		? await response.json().catch(() => null)
-		: await response.text().catch(() => null);
-
-	if (!response.ok) {
-		const message =
-			(isJson && payload && typeof payload === "object" && "error" in payload
-				? String((payload as { error: unknown }).error)
-				: typeof payload === "string" && payload.length > 0
-					? payload
-					: `HTTP ${response.status} ${response.statusText}`) ||
-			`HTTP ${response.status}`;
-		throw new HiaiDocsError(message, response.status, payload);
-	}
-
-	return payload as T;
-}
-
-function joinId(...segments: string[]): string {
-	return segments.map((s) => encodeURIComponent(s)).join("/");
-}
-
-export const client = {
-	search(params: {
-		query: string;
-		folder?: string;
-		tags?: string[];
-		limit?: number;
-	}) {
-		return request("GET", "/api/search", {
-			query: {
-				q: params.query,
-				folder: params.folder,
-				tags: params.tags,
-				limit: params.limit,
-			},
-		});
-	},
-
-	getDocument(id: string) {
-		return request("GET", `/api/${joinId("documents", id)}`);
-	},
-
-	createDocument(input: {
-		title: string;
-		content?: string;
-		folderId?: string | null;
-		categoryId?: string | null;
-	}) {
-		return request("POST", "/api/documents", { body: input });
-	},
-
-	updateDocument(
-		id: string,
-		input: {
-			title?: string;
-			content?: string;
-			folderId?: string | null;
-			categoryId?: string | null;
-		},
-	) {
-		return request("PATCH", `/api/${joinId("documents", id)}`, { body: input });
-	},
-
-	listDocuments(params: {
-		folderId?: string;
-		tag?: string;
-		page?: number;
-		limit?: number;
-	}) {
-		return request("GET", "/api/documents", { query: params });
-	},
-
-	listFolders(params: { parentId?: string }) {
-		return request("GET", "/api/folders", {
-			query: { parentId: params.parentId },
-		});
-	},
-
-	createFolder(input: {
-		name: string;
-		parentId?: string;
-		categoryId?: string;
-	}) {
-		return request("POST", "/api/folders", { body: input });
-	},
-
-	listCategories() {
-		return request("GET", "/api/categories");
-	},
-
-	createCategory(input: { name: string; description?: string }) {
-		return request("POST", "/api/categories", { body: input });
-	},
-
-	listTags() {
-		return request("GET", "/api/tags");
-	},
-
-	getRelatedDocuments(documentId: string, limit?: number) {
-		return request("GET", `/api/${joinId("graph", "related", documentId)}`, {
-			query: { limit },
-		});
-	},
-
-	searchGraph(input: { query: string; docIds: string[]; limit?: number }) {
-		return request("POST", "/api/graph/search", { body: input });
-	},
-
-	getDocumentIndexStatus(documentId: string) {
-		return request(
-			"GET",
-			`/api/${joinId("documents", documentId, "index-status")}`,
-		);
-	},
-
-	refreshDocumentIndex(documentId: string) {
-		return request(
-			"POST",
-			`/api/${joinId("documents", documentId, "index", "refresh")}`,
-		);
-	},
-
-	createSnapshot(
-		documentId: string,
-		input: { label: string; description?: string },
-	) {
-		return request(
-			"POST",
-			`/api/${joinId("documents", documentId, "versions")}`,
-			{ body: input },
-		);
-	},
-
-	getVersionHistory(documentId: string, onlySnapshots?: boolean) {
-		return request(
-			"GET",
-			`/api/${joinId("documents", documentId, "versions")}`,
-			{ query: { onlySnapshots } },
-		);
-	},
-
-	async exportDocument(id: string): Promise<ExportResponse> {
-		const markdown = await request<string>(
-			"GET",
-			`/api/${joinId("documents", id, "export")}`,
-		);
-		return { markdown };
-	},
-};
-
-export type HiaiDocsClient = typeof client;

package/packages/mcp-server/src/index.ts

@@ -1,8 +0,0 @@
-#!/usr/bin/env bun
-/** DocsMint MCP stdio entry point. */
-
-import { serveStdio } from '@modelcontextprotocol/server/stdio';
-
-import { createDocsmintMcpServer } from './server.js';
-
-serveStdio(() => createDocsmintMcpServer());

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

@@ -1,87 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/server';
-import { z, type ZodRawShape } from 'zod';
-
-import { registerExtendedCapabilities } from './capabilities.js';
-import { client as defaultClient, HiaiDocsError, type HiaiDocsClient } from './client.js';
-import * as createDocument from './tools/create-document.js';
-import * as createFolder from './tools/create-folder.js';
-import * as createSnapshot from './tools/create-snapshot.js';
-import * as exportDocument from './tools/export-document.js';
-import * as getDocument from './tools/get-document.js';
-import * as listDocuments from './tools/list-documents.js';
-import * as listFolders from './tools/list-folders.js';
-import * as search from './tools/search.js';
-import * as updateDocument from './tools/update-document.js';
-import * as versionHistory from './tools/version-history.js';
-
-type ToolHandler = (args: Record<string, unknown>) => Promise<unknown>;
-interface McpToolResult {
-  content: Array<{ type: 'text'; text: string }>;
-  isError?: boolean;
-}
-
-function wrapHandler(
-  name: string,
-  handler: ToolHandler
-): (args: Record<string, unknown>) => Promise<McpToolResult> {
-  return async (args) => {
-    try {
-      return {
-        content: [{ type: 'text', text: JSON.stringify(await handler(args), null, 2) }],
-      };
-    } catch (error) {
-      const message =
-        error instanceof HiaiDocsError
-          ? `DocsMint API error (${error.status}): ${error.message}`
-          : `Tool '${name}' failed: ${error instanceof Error ? error.message : String(error)}`;
-      return { isError: true, content: [{ type: 'text', text: message }] };
-    }
-  };
-}
-
-export function registerDocsmintMcpCapabilities(server: McpServer, client: HiaiDocsClient): void {
-  const register = <Args>(
-    name: string,
-    description: string,
-    inputSchema: ZodRawShape,
-    handler: (args: Args) => Promise<unknown>
-  ): void => {
-    server.registerTool(
-      name,
-      { description, inputSchema: z.object(inputSchema) },
-      wrapHandler(name, handler as ToolHandler) as never
-    );
-  };
-
-  const tools = [
-    search,
-    getDocument,
-    createDocument,
-    updateDocument,
-    listDocuments,
-    listFolders,
-    createFolder,
-    createSnapshot,
-    versionHistory,
-    exportDocument,
-  ] as const;
-  for (const tool of tools) {
-    register(
-      tool.definition.name,
-      tool.definition.description,
-      tool.definition.inputSchema as ZodRawShape,
-      tool.createHandler(client) as ToolHandler
-    );
-  }
-  registerExtendedCapabilities(server, client);
-}
-
-export interface CreateDocsmintMcpServerOptions {
-  client?: HiaiDocsClient;
-}
-
-export function createDocsmintMcpServer(options: CreateDocsmintMcpServerOptions = {}): McpServer {
-  const server = new McpServer({ name: 'docsmint', version: '0.6.8' });
-  registerDocsmintMcpCapabilities(server, options.client ?? defaultClient);
-  return server;
-}

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

@@ -1,34 +0,0 @@
-import { z } from 'zod';
-import { client, type HiaiDocsClient } from '../client.js';
-import type { DocumentDetail } from '../types.js';
-
-export const definition = {
-  name: 'create_document',
-  description:
-    'Create a new document. Optionally provide initial markdown content and a folder ID.',
-  inputSchema: {
-    title: z.string().describe('Document title.'),
-    content: z.string().optional().describe('Initial markdown content for the document.'),
-    folderId: z.string().optional().describe('Optional folder ID to place the document in.'),
-    categoryId: z
-      .string()
-      .optional()
-      .describe(
-        'Optional category ID. Category keys are always rebound to their configured category.'
-      ),
-  },
-} as const;
-
-export interface CreateDocumentArgs {
-  title: string;
-  content?: string;
-  folderId?: string;
-  categoryId?: string;
-}
-
-export const createHandler = (api: HiaiDocsClient) =>
-  async function createDocument(args: CreateDocumentArgs): Promise<DocumentDetail> {
-    return (await api.createDocument(args)) as DocumentDetail;
-  };
-
-export const handler = createHandler(client);

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

@@ -1,31 +0,0 @@
-import { z } from 'zod';
-import { client, type HiaiDocsClient } from '../client.js';
-import type { Folder } from '../types.js';
-
-export const definition = {
-  name: 'create_folder',
-  description: 'Create a new folder, optionally nested under a parent folder.',
-  inputSchema: {
-    name: z.string().describe('Folder name.'),
-    parentId: z.string().optional().describe('Optional parent folder ID for nesting.'),
-    categoryId: z
-      .string()
-      .optional()
-      .describe(
-        'Optional category ID. Category keys are always rebound to their configured category.'
-      ),
-  },
-} as const;
-
-export interface CreateFolderArgs {
-  name: string;
-  parentId?: string;
-  categoryId?: string;
-}
-
-export const createHandler = (api: HiaiDocsClient) =>
-  async function createFolder(args: CreateFolderArgs): Promise<Folder> {
-    return (await api.createFolder(args)) as Folder;
-  };
-
-export const handler = createHandler(client);

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

@@ -1,27 +0,0 @@
-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.',
-  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.'),
-  },
-} as const;
-
-export interface CreateSnapshotArgs {
-  documentId: string;
-  label: string;
-  description?: string;
-}
-
-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,22 +0,0 @@
-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.',
-  inputSchema: {
-    id: z.string().describe('Document ID to export.'),
-  },
-} as const;
-
-export interface ExportDocumentArgs {
-  id: string;
-}
-
-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,22 +0,0 @@
-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.',
-  inputSchema: {
-    id: z.string().describe('Document ID.'),
-  },
-} as const;
-
-export interface GetDocumentArgs {
-  id: string;
-}
-
-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,34 +0,0 @@
-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.',
-  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).'),
-    limit: z
-      .number()
-      .int()
-      .positive()
-      .max(100)
-      .optional()
-      .describe('Items per page (default 20, max 100).'),
-  },
-} as const;
-
-export interface ListDocumentsArgs {
-  folderId?: string;
-  tag?: string;
-  page?: number;
-  limit?: number;
-}
-
-export const createHandler = (api: HiaiDocsClient) =>
-  async function listDocuments(args: ListDocumentsArgs): Promise<ListDocumentsResponse> {
-    return (await api.listDocuments(args)) as ListDocumentsResponse;
-  };
-
-export const handler = createHandler(client);