@hiai-gg/docsmint 0.6.0 → 0.6.2

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

@@ -14,159 +14,212 @@ 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 };
+	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";
-  }
+	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 } = {},
+	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;
+	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("/");
+	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 }) {
-    return request("POST", "/api/documents", { body: input });
-  },
-
-  updateDocument(id: string, input: { title?: string; content?: string }) {
-    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 }) {
-    return request("POST", "/api/folders", { body: input });
-  },
-
-  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 };
-  },
+	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,109 +1,8 @@
 #!/usr/bin/env bun
-/**
- * hiai-docs MCP Server
- *
- * Exposes hiai-docs operations as MCP tools via the stdio transport.
- *
- * Environment:
- *   HIAI_DOCS_URL      — base URL of the hiai-docs API
- *                        (default: http://localhost:50700)
- *   HIAI_DOCS_API_KEY  — bearer token used for Authorization header
- */
+/** DocsMint MCP stdio entry point. */
 
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { HiaiDocsError } from "./client.js";
-import type { ZodRawShape } from "zod";
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
 
-import * as search from "./tools/search.js";
-import * as getDocument from "./tools/get-document.js";
-import * as createDocument from "./tools/create-document.js";
-import * as updateDocument from "./tools/update-document.js";
-import * as listDocuments from "./tools/list-documents.js";
-import * as listFolders from "./tools/list-folders.js";
-import * as createFolder from "./tools/create-folder.js";
-import * as createSnapshot from "./tools/create-snapshot.js";
-import * as versionHistory from "./tools/version-history.js";
-import * as exportDocument from "./tools/export-document.js";
+import { createDocsmintMcpServer } from './server.js';
 
-type ToolHandler = (args: Record<string, unknown>) => Promise<unknown>;
-
-interface McpToolResult {
-  content: Array<{ type: "text"; text: string }>;
-  isError?: boolean;
-}
-
-const server = new McpServer({
-	name: "hiai-docs",
-	version: "0.6.0",
-});
-
-/**
- * Wraps a tool handler to convert errors into MCP-formatted responses.
- * The SDK's tool callback returns CallToolResult; we return either success
- * with JSON-stringified content or an error with `isError: true`.
- */
-function wrapHandler(
-  name: string,
-  handler: ToolHandler,
-): (args: Record<string, unknown>) => Promise<McpToolResult> {
-  return async (args) => {
-    try {
-      const result = await handler(args);
-      return {
-        content: [
-          {
-            type: "text" as const,
-            text: JSON.stringify(result, null, 2),
-          },
-        ],
-      };
-    } catch (err) {
-      if (err instanceof HiaiDocsError) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: "text" as const,
-              text: `hiai-docs API error (${err.status}): ${err.message}`,
-            },
-          ],
-        };
-      }
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        isError: true,
-        content: [
-          {
-            type: "text" as const,
-            text: `Tool '${name}' failed: ${message}`,
-          },
-        ],
-      };
-    }
-  };
-}
-
-function register<Args>(
-  name: string,
-  description: string,
-  inputSchema: ZodRawShape,
-  handler: (args: Args) => Promise<unknown>,
-): void {
-  server.tool(name, description, inputSchema as never, wrapHandler(name, handler as ToolHandler) as never);
-}
-
-register(search.definition.name, search.definition.description, search.definition.inputSchema as ZodRawShape, search.handler);
-register(getDocument.definition.name, getDocument.definition.description, getDocument.definition.inputSchema as ZodRawShape, getDocument.handler);
-register(createDocument.definition.name, createDocument.definition.description, createDocument.definition.inputSchema as ZodRawShape, createDocument.handler);
-register(updateDocument.definition.name, updateDocument.definition.description, updateDocument.definition.inputSchema as ZodRawShape, updateDocument.handler);
-register(listDocuments.definition.name, listDocuments.definition.description, listDocuments.definition.inputSchema as ZodRawShape, listDocuments.handler);
-register(listFolders.definition.name, listFolders.definition.description, listFolders.definition.inputSchema as ZodRawShape, listFolders.handler);
-register(createFolder.definition.name, createFolder.definition.description, createFolder.definition.inputSchema as ZodRawShape, createFolder.handler);
-register(createSnapshot.definition.name, createSnapshot.definition.description, createSnapshot.definition.inputSchema as ZodRawShape, createSnapshot.handler);
-register(versionHistory.definition.name, versionHistory.definition.description, versionHistory.definition.inputSchema as ZodRawShape, versionHistory.handler);
-register(exportDocument.definition.name, exportDocument.definition.description, exportDocument.definition.inputSchema as ZodRawShape, exportDocument.handler);
-
-const transport = new StdioServerTransport();
-
-await server.connect(transport);
+serveStdio(() => createDocsmintMcpServer());

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

@@ -0,0 +1,87 @@
+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.2' });
+  registerDocsmintMcpCapabilities(server, options.client ?? defaultClient);
+  return server;
+}

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

@@ -1,21 +1,21 @@
-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: "create_document",
+  name: 'create_document',
   description:
-    "Create a new document. Optionally provide initial markdown content and a folder ID.",
+    'Create a new document. Optionally provide initial markdown content and a folder ID.',
   inputSchema: {
-    title: z.string().describe("Document title."),
-    content: z
+    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("Initial markdown content for the document."),
-    folderId: z
-      .string()
-      .optional()
-      .describe("Optional folder ID to place the document in."),
+      .describe(
+        'Optional category ID. Category keys are always rebound to their configured category.'
+      ),
   },
 } as const;
 
@@ -23,10 +23,12 @@ export interface CreateDocumentArgs {
   title: string;
   content?: string;
   folderId?: string;
+  categoryId?: string;
 }
 
-export async function handler(
-  args: CreateDocumentArgs,
-): Promise<DocumentDetail> {
-  return (await client.createDocument(args)) as DocumentDetail;
-}
+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,24 +1,31 @@
-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: "create_folder",
-  description: "Create a new folder, optionally nested under a parent folder.",
+  name: 'create_folder',
+  description: 'Create a new folder, optionally nested under a parent folder.',
   inputSchema: {
-    name: z.string().describe("Folder name."),
-    parentId: z
+    name: z.string().describe('Folder name.'),
+    parentId: z.string().optional().describe('Optional parent folder ID for nesting.'),
+    categoryId: z
       .string()
       .optional()
-      .describe("Optional parent folder ID for nesting."),
+      .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 async function handler(args: CreateFolderArgs): Promise<Folder> {
-  return (await client.createFolder(args)) as Folder;
-}
+export const createHandler = (api: HiaiDocsClient) =>
+  async function createFolder(args: CreateFolderArgs): Promise<Folder> {
+    return (await api.createFolder(args)) as Folder;
+  };
+
+export const handler = createHandler(client);