@hiai-gg/docsmint 0.3.0

package/packages/db/src/with-tenant.ts

@@ -0,0 +1,75 @@
+import { sql } from "drizzle-orm";
+import { db } from "./client";
+
+export interface TenantContext {
+	userId: string;
+	role: "admin" | "user" | "none";
+	workspaceId?: string;
+	source?: "personal" | "external";
+	actorRole?: "owner" | "admin" | "editor" | "viewer";
+}
+
+export const ZERO_UUID = "00000000-0000-0000-0000-000000000000";
+
+/**
+ * Build an admin TenantContext.
+ *
+ * `ownerId` SHOULD be passed explicitly by the caller (typically resolved
+ * from the hiai-docs `config.OWNER_ID` via the `tenant.ts` middleware).
+ * If omitted, falls back to `process.env.OWNER_ID` so this package can
+ * remain dependency-free while still working stand-alone.
+ */
+export function adminTenantContext(ownerId?: string): TenantContext {
+	const resolved = ownerId ?? process.env.OWNER_ID;
+	if (!resolved) {
+		console.warn(
+			"[hiai-docs/db] adminTenantContext: ownerId not provided and OWNER_ID env not set, using empty string",
+		);
+	}
+	return {
+		userId: resolved ?? "",
+		role: "admin",
+	};
+}
+
+export function shareGuestTenantContext(ownerId: string): TenantContext {
+	return {
+		userId: ownerId,
+		role: "user",
+	};
+}
+
+/**
+ * Run `fn` inside a `db.transaction(...)` with the per-request RLS
+ * GUCs (`app.current_user_id`, `app.current_user_role`) installed
+ * on the transaction's connection.
+ *
+ * The transaction pins a single pooled connection for the duration
+ * of `fn`, so every query inside `fn` runs on the same connection
+ * where the GUCs were installed. This works around the
+ * `postgres-js` connection-pool round-robin: a single
+ * `set_config(..., false)` outside a transaction would land on a
+ * different connection than the route handler's first query, and
+ * RLS would fail closed.
+ *
+ * GUCs use `set_config(..., true)` (transaction-local), so they
+ * automatically reset when the transaction commits/rolls back and
+ * cannot leak into the next request that reuses the connection.
+ */
+export async function withTenant<T>(
+	ctx: TenantContext,
+	fn: (tx: Parameters<Parameters<typeof db.transaction>[0]>[0]) => Promise<T>,
+): Promise<T> {
+	return db.transaction(async (tx) => {
+		await tx.execute(
+			sql`SELECT set_config('app.current_user_id', ${ctx.userId}, true)`,
+		);
+		await tx.execute(
+			sql`SELECT set_config('app.current_user_role', ${ctx.role}, true)`,
+		);
+		await tx.execute(
+			sql`SELECT set_config('app.current_workspace_id', ${ctx.workspaceId ?? ""}, true)`,
+		);
+		return fn(tx);
+	});
+}

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

@@ -0,0 +1,172 @@
+/**
+ * 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 }) {
+    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 };
+  },
+};
+
+export type HiaiDocsClient = typeof client;

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

@@ -0,0 +1,109 @@
+#!/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
+ */
+
+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 * 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";
+
+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.3.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);

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

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { client } 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."),
+  },
+} as const;
+
+export interface CreateDocumentArgs {
+  title: string;
+  content?: string;
+  folderId?: string;
+}
+
+export async function handler(
+  args: CreateDocumentArgs,
+): Promise<DocumentDetail> {
+  return (await client.createDocument(args)) as DocumentDetail;
+}

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

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { client } 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."),
+  },
+} as const;
+
+export interface CreateFolderArgs {
+  name: string;
+  parentId?: string;
+}
+
+export async function handler(args: CreateFolderArgs): Promise<Folder> {
+  return (await client.createFolder(args)) as Folder;
+}

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

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { client } 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 async function handler(args: CreateSnapshotArgs): Promise<Version> {
+  const { documentId, ...input } = args;
+  return (await client.createSnapshot(documentId, input)) as Version;
+}

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

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { client } 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 async function handler(
+  args: ExportDocumentArgs,
+): Promise<ExportResponse> {
+  return (await client.exportDocument(args.id)) as ExportResponse;
+}

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

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { client } 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 async function handler(args: GetDocumentArgs): Promise<DocumentDetail> {
+  return (await client.getDocument(args.id)) as DocumentDetail;
+}

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

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { client } 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 async function handler(
+  args: ListDocumentsArgs,
+): Promise<ListDocumentsResponse> {
+  return (await client.listDocuments(args)) as ListDocumentsResponse;
+}

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

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { client } from "../client.js";
+import type { Folder } from "../types.js";
+
+export const definition = {
+  name: "list_folders",
+  description:
+    "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.",
+      ),
+  },
+} as const;
+
+export interface ListFoldersArgs {
+  parentId?: string;
+}
+
+export async function handler(args: ListFoldersArgs): Promise<Folder[]> {
+  return (await client.listFolders(args)) as Folder[];
+}

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

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { client } from "../client.js";
+import type { SearchResponse } from "../types.js";
+
+export const definition = {
+  name: "search_documents",
+  description:
+    "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."),
+    limit: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe("Maximum number of results to return (default 20)."),
+  },
+} as const;
+
+export type SearchArgs = {
+  query: string;
+  folder?: string;
+  tags?: string[];
+  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;
+}

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

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { client } from "../client.js";
+import type { DocumentDetail } from "../types.js";
+
+export const definition = {
+  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
+      .string()
+      .optional()
+      .describe("New markdown content for the document."),
+  },
+} as const;
+
+export interface UpdateDocumentArgs {
+  id: string;
+  title?: string;
+  content?: string;
+}
+
+export async function handler(
+  args: UpdateDocumentArgs,
+): Promise<DocumentDetail> {
+  const { id, ...patch } = args;
+  return (await client.updateDocument(id, patch)) as DocumentDetail;
+}

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

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { client } 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.",
+  inputSchema: {
+    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).",
+      ),
+  },
+} as const;
+
+export interface VersionHistoryArgs {
+  documentId: string;
+  onlySnapshots?: boolean;
+}
+
+export async function handler(args: VersionHistoryArgs): Promise<Version[]> {
+  return (await client.getVersionHistory(
+    args.documentId,
+    args.onlySnapshots,
+  )) as Version[];
+}