@gmickel/gno 0.8.6 → 0.9.0

package/src/mcp/tools/add-collection.ts

@@ -0,0 +1,190 @@
+/**
+ * MCP gno_add_collection tool - add collection and sync.
+ *
+ * @module src/mcp/tools/add-collection
+ */
+
+// node:path for basename (no Bun path utils)
+import { basename } from "node:path";
+
+import type { ToolContext } from "../server";
+
+import { addCollection } from "../../collection/add";
+import { applyConfigChange } from "../../core/config-mutation";
+import { MCP_ERRORS } from "../../core/errors";
+import { acquireWriteLock, type WriteLockHandle } from "../../core/file-lock";
+import { JobError } from "../../core/job-manager";
+import {
+  normalizeCollectionName,
+  validateCollectionRoot,
+} from "../../core/validation";
+import { defaultSyncService } from "../../ingestion";
+import { runTool, type ToolResult } from "./index";
+
+interface AddCollectionInput {
+  path: string;
+  name?: string;
+  pattern?: string;
+  include?: string[];
+  exclude?: string[];
+  gitPull?: boolean;
+}
+
+interface AddCollectionResult {
+  jobId: string;
+  collection: string;
+  status: "started";
+}
+
+function formatAddCollectionResult(result: AddCollectionResult): string {
+  return [
+    `Job: ${result.jobId}`,
+    `Collection: ${result.collection}`,
+    `Status: ${result.status}`,
+  ].join("\n");
+}
+
+function mapConfigError(code: string, message: string): Error {
+  switch (code) {
+    case "DUPLICATE":
+      return new Error(`${MCP_ERRORS.DUPLICATE.code}: ${message}`);
+    case "PATH_NOT_FOUND":
+      return new Error(`${MCP_ERRORS.PATH_NOT_FOUND.code}: ${message}`);
+    case "VALIDATION":
+      return new Error(`${MCP_ERRORS.INVALID_PATH.code}: ${message}`);
+    default:
+      return new Error(`RUNTIME: ${message}`);
+  }
+}
+
+export function handleAddCollection(
+  args: AddCollectionInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_add_collection",
+    async () => {
+      if (!ctx.enableWrite) {
+        throw new Error("Write tools disabled. Start MCP with --enable-write.");
+      }
+
+      let lock: WriteLockHandle | null = null;
+      let handedOff = false;
+
+      try {
+        lock = await acquireWriteLock(ctx.writeLockPath);
+        if (!lock) {
+          throw new Error(
+            `${MCP_ERRORS.LOCKED.code}: ${MCP_ERRORS.LOCKED.message}`
+          );
+        }
+
+        let absPath: string;
+        try {
+          absPath = await validateCollectionRoot(args.path);
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : String(error);
+          throw new Error(`${MCP_ERRORS.INVALID_PATH.code}: ${message}`);
+        }
+
+        const rawName = args.name ?? basename(absPath);
+        const collectionName = normalizeCollectionName(rawName);
+        if (!collectionName) {
+          throw new Error(
+            `${MCP_ERRORS.INVALID_PATH.code}: Collection name cannot be empty`
+          );
+        }
+
+        const mutationResult = await applyConfigChange(
+          {
+            store: ctx.store,
+            configPath: ctx.actualConfigPath,
+            onConfigUpdated: (config) => {
+              ctx.config = config;
+              ctx.collections = config.collections;
+            },
+          },
+          async (config) => {
+            const addResult = await addCollection(config, {
+              path: absPath,
+              name: collectionName,
+              pattern: args.pattern,
+              include: args.include,
+              exclude: args.exclude,
+            });
+
+            if (!addResult.ok) {
+              return {
+                ok: false,
+                error: addResult.message,
+                code: addResult.code,
+              };
+            }
+
+            return {
+              ok: true,
+              config: addResult.config,
+              value: addResult.collection,
+            };
+          }
+        );
+
+        if (!mutationResult.ok) {
+          throw mapConfigError(mutationResult.code, mutationResult.error);
+        }
+
+        const collection = mutationResult.value;
+        if (!collection) {
+          throw new Error("RUNTIME: Collection missing after add");
+        }
+
+        const jobId = await ctx.jobManager.startJobWithLock(
+          "add",
+          lock,
+          async () => {
+            const result = await defaultSyncService.syncCollection(
+              collection,
+              ctx.store,
+              {
+                gitPull: args.gitPull ?? false,
+                runUpdateCmd: false,
+              }
+            );
+
+            return {
+              collections: [result],
+              totalDurationMs: result.durationMs,
+              totalFilesProcessed: result.filesProcessed,
+              totalFilesAdded: result.filesAdded,
+              totalFilesUpdated: result.filesUpdated,
+              totalFilesErrored: result.filesErrored,
+              totalFilesSkipped: result.filesSkipped,
+            };
+          }
+        );
+
+        handedOff = true;
+
+        const result: AddCollectionResult = {
+          jobId,
+          collection: collection.name,
+          status: "started",
+        };
+
+        return result;
+      } catch (error) {
+        if (error instanceof JobError) {
+          throw new Error(`${error.code}: ${error.message}`);
+        }
+        throw error;
+      } finally {
+        if (lock && !handedOff) {
+          await lock.release();
+        }
+      }
+    },
+    formatAddCollectionResult
+  );
+}

package/src/mcp/tools/capture.ts

@@ -0,0 +1,193 @@
+/**
+ * MCP gno_capture tool - create a new document.
+ *
+ * @module src/mcp/tools/capture
+ */
+
+// node:fs/promises for mkdir (no Bun equivalent for structure ops)
+import { mkdir } from "node:fs/promises";
+// node:path for path utils (no Bun path utils)
+import { dirname, extname, join } from "node:path";
+
+import type { ToolContext } from "../server";
+
+import { buildUri } from "../../app/constants";
+import { MCP_ERRORS } from "../../core/errors";
+import { withWriteLock } from "../../core/file-lock";
+import { atomicWrite } from "../../core/file-ops";
+import {
+  normalizeCollectionName,
+  validateRelPath,
+} from "../../core/validation";
+import { defaultSyncService } from "../../ingestion";
+import { extractTitle } from "../../pipeline/contextual";
+import { runTool, type ToolResult } from "./index";
+
+interface CaptureInput {
+  collection: string;
+  content: string;
+  title?: string;
+  path?: string;
+  overwrite?: boolean;
+}
+
+interface CaptureResult {
+  docid: string;
+  uri: string;
+  absPath: string;
+  collection: string;
+  relPath: string;
+  created: boolean;
+  overwritten: boolean;
+  serverInstanceId: string;
+}
+
+const SENSITIVE_SUBPATHS = new Set([
+  ".ssh",
+  ".gnupg",
+  ".aws",
+  ".config",
+  ".git",
+  "node_modules",
+]);
+
+function sanitizeFilename(title: string): string {
+  return title
+    .toLowerCase()
+    .trim()
+    .replaceAll(/[^\w\s-]/g, "")
+    .replaceAll(/\s+/g, "-")
+    .replaceAll(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function ensureMarkdownExtension(relPath: string): string {
+  return extname(relPath) ? relPath : `${relPath}.md`;
+}
+
+function assertNotSensitive(relPath: string): void {
+  const firstSegment = relPath.split(/[\\/]/)[0];
+  if (firstSegment && SENSITIVE_SUBPATHS.has(firstSegment)) {
+    throw new Error(
+      `${MCP_ERRORS.INVALID_PATH.code}: Cannot write to sensitive directory: ${firstSegment}`
+    );
+  }
+}
+
+function generateFilename(title: string | undefined, content: string): string {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const fallback = `note-${timestamp}.md`;
+  const baseTitle = title?.trim() || extractTitle(content, fallback);
+  const slug = sanitizeFilename(baseTitle);
+  const safeSlug = slug || `note-${timestamp}`;
+  return `${safeSlug}.md`;
+}
+
+function formatCaptureResult(result: CaptureResult): string {
+  const lines: string[] = [];
+  lines.push(`Doc: ${result.docid}`);
+  lines.push(`URI: ${result.uri}`);
+  lines.push(`Path: ${result.absPath}`);
+  lines.push(`Created: ${result.created ? "yes" : "no"}`);
+  lines.push(`Overwritten: ${result.overwritten ? "yes" : "no"}`);
+  return lines.join("\n");
+}
+
+export function handleCapture(
+  args: CaptureInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_capture",
+    async () => {
+      if (!ctx.enableWrite) {
+        throw new Error("Write tools disabled. Start MCP with --enable-write.");
+      }
+
+      return await withWriteLock(ctx.writeLockPath, async () => {
+        const collectionName = normalizeCollectionName(args.collection);
+        const collection = ctx.collections.find(
+          (c) => c.name.toLowerCase() === collectionName
+        );
+        if (!collection) {
+          throw new Error(
+            `${MCP_ERRORS.NOT_FOUND.code}: Collection not found: ${args.collection}`
+          );
+        }
+
+        let relPath: string;
+        if (args.path) {
+          try {
+            relPath = ensureMarkdownExtension(validateRelPath(args.path));
+          } catch (error) {
+            const message =
+              error instanceof Error ? error.message : String(error);
+            throw new Error(`${MCP_ERRORS.INVALID_PATH.code}: ${message}`);
+          }
+        } else {
+          relPath = generateFilename(args.title, args.content);
+        }
+
+        assertNotSensitive(relPath);
+
+        const absPath = join(collection.path, relPath);
+        const file = Bun.file(absPath);
+        const exists = await file.exists();
+        if (exists && !args.overwrite) {
+          throw new Error(
+            `${MCP_ERRORS.CONFLICT.code}: File exists: ${relPath}`
+          );
+        }
+
+        await mkdir(dirname(absPath), { recursive: true });
+        await atomicWrite(absPath, args.content);
+
+        const results = await defaultSyncService.syncFiles(
+          collection,
+          ctx.store,
+          [relPath],
+          { runUpdateCmd: false, gitPull: false }
+        );
+        const syncResult = results[0];
+        if (!syncResult) {
+          throw new Error("RUNTIME: Sync result missing");
+        }
+        if (syncResult.status === "error") {
+          throw new Error(
+            `INGEST_ERROR: ${syncResult.errorCode ?? "ERROR"} - ${
+              syncResult.errorMessage ?? "Unknown error"
+            }`
+          );
+        }
+
+        let docid = syncResult.docid;
+        if (!docid) {
+          const docResult = await ctx.store.getDocument(
+            collectionName,
+            relPath
+          );
+          if (!docResult.ok) {
+            throw new Error(docResult.error.message);
+          }
+          if (!docResult.value) {
+            throw new Error("RUNTIME: Document missing after sync");
+          }
+          docid = docResult.value.docid;
+        }
+
+        return {
+          docid,
+          uri: buildUri(collectionName, relPath),
+          absPath,
+          collection: collectionName,
+          relPath,
+          created: !exists,
+          overwritten: exists,
+          serverInstanceId: ctx.serverInstanceId,
+        };
+      });
+    },
+    formatCaptureResult
+  );
+}

package/src/mcp/tools/index.ts

@@ -10,11 +10,17 @@ import { z } from "zod";
 
 import type { ToolContext } from "../server";
 
+import { handleAddCollection } from "./add-collection";
+import { handleCapture } from "./capture";
 import { handleGet } from "./get";
+import { handleJobStatus } from "./job-status";
+import { handleListJobs } from "./list-jobs";
 import { handleMultiGet } from "./multi-get";
 import { handleQuery } from "./query";
+import { handleRemoveCollection } from "./remove-collection";
 import { handleSearch } from "./search";
 import { handleStatus } from "./status";
+import { handleSync } from "./sync";
 import { handleVsearch } from "./vsearch";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -29,6 +35,33 @@ const searchInputSchema = z.object({
   lang: z.string().optional(),
 });
 
+const captureInputSchema = z.object({
+  collection: z.string().min(1, "Collection cannot be empty"),
+  content: z.string(),
+  title: z.string().optional(),
+  path: z.string().optional(),
+  overwrite: z.boolean().default(false),
+});
+
+const addCollectionInputSchema = z.object({
+  path: z.string().min(1, "Path cannot be empty"),
+  name: z.string().optional(),
+  pattern: z.string().optional(),
+  include: z.array(z.string()).optional(),
+  exclude: z.array(z.string()).optional(),
+  gitPull: z.boolean().default(false),
+});
+
+const syncInputSchema = z.object({
+  collection: z.string().optional(),
+  gitPull: z.boolean().default(false),
+  runUpdateCmd: z.boolean().default(false),
+});
+
+const removeCollectionInputSchema = z.object({
+  collection: z.string().min(1, "Collection cannot be empty"),
+});
+
 const vsearchInputSchema = z.object({
   query: z.string().min(1, "Query cannot be empty"),
   collection: z.string().optional(),
@@ -65,6 +98,14 @@ const multiGetInputSchema = z.object({
 
 const statusInputSchema = z.object({});
 
+const jobStatusInputSchema = z.object({
+  jobId: z.string().min(1, "Job ID cannot be empty"),
+});
+
+const listJobsInputSchema = z.object({
+  limit: z.number().int().min(1).max(100).default(10),
+});
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Tool Result Type
 // ─────────────────────────────────────────────────────────────────────────────
@@ -106,15 +147,31 @@ export async function runTool<T>(
     // Exception firewall: never throw, always return isError
     const message = e instanceof Error ? e.message : String(e);
     console.error(`[MCP] ${name} error:`, message);
+    const parsedError = parseErrorMessage(message);
     return {
       isError: true,
       content: [{ type: "text", text: `Error: ${message}` }],
+      structuredContent: parsedError,
     };
   } finally {
     release();
   }
 }
 
+function parseErrorMessage(message: string): { [x: string]: unknown } {
+  const match = message.match(/^([A-Z_]+):\s*(.*)$/);
+  if (match) {
+    return {
+      error: match[1],
+      message: match[2] || message,
+    };
+  }
+  return {
+    error: "RUNTIME",
+    message,
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Tool Registration
 // ─────────────────────────────────────────────────────────────────────────────
@@ -162,4 +219,48 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
     statusInputSchema.shape,
     (args) => handleStatus(args, ctx)
   );
+
+  if (ctx.enableWrite) {
+    server.tool(
+      "gno_capture",
+      "Create a new document",
+      captureInputSchema.shape,
+      (args) => handleCapture(args, ctx)
+    );
+
+    server.tool(
+      "gno_add_collection",
+      "Add a collection and start indexing",
+      addCollectionInputSchema.shape,
+      (args) => handleAddCollection(args, ctx)
+    );
+
+    server.tool(
+      "gno_sync",
+      "Sync one or all collections",
+      syncInputSchema.shape,
+      (args) => handleSync(args, ctx)
+    );
+
+    server.tool(
+      "gno_remove_collection",
+      "Remove a collection from config",
+      removeCollectionInputSchema.shape,
+      (args) => handleRemoveCollection(args, ctx)
+    );
+  }
+
+  server.tool(
+    "gno_job_status",
+    "Get status of an async job",
+    jobStatusInputSchema.shape,
+    (args) => handleJobStatus(args, ctx)
+  );
+
+  server.tool(
+    "gno_list_jobs",
+    "List active and recent jobs",
+    listJobsInputSchema.shape,
+    (args) => handleListJobs(args, ctx)
+  );
 }

package/src/mcp/tools/job-status.ts

@@ -0,0 +1,87 @@
+/**
+ * MCP gno_job_status tool - job status lookup.
+ *
+ * @module src/mcp/tools/job-status
+ */
+
+import type { JobRecord } from "../../core/job-manager";
+import type { SyncResult } from "../../ingestion";
+import type { ToolContext } from "../server";
+
+import { runTool, type ToolResult } from "./index";
+
+interface JobStatusInput {
+  jobId: string;
+}
+
+interface JobStatusResult {
+  jobId: string;
+  type: JobRecord["type"];
+  status: JobRecord["status"];
+  startedAt: string;
+  completedAt?: string;
+  result?: SyncResult;
+  error?: string;
+  serverInstanceId: string;
+}
+
+function formatJobStatus(result: JobStatusResult): string {
+  const lines: string[] = [];
+
+  lines.push(`Job: ${result.jobId}`);
+  lines.push(`Type: ${result.type}`);
+  lines.push(`Status: ${result.status}`);
+  lines.push(`Started: ${result.startedAt}`);
+
+  if (result.completedAt) {
+    lines.push(`Completed: ${result.completedAt}`);
+  }
+
+  if (result.error) {
+    lines.push(`Error: ${result.error}`);
+  }
+
+  if (result.result) {
+    lines.push(
+      `Total: ${result.result.totalFilesAdded} added, ${result.result.totalFilesUpdated} updated, ` +
+        `${result.result.totalFilesErrored} errors`
+    );
+    lines.push(`Duration: ${result.result.totalDurationMs}ms`);
+  }
+
+  return lines.join("\n");
+}
+
+function toJobStatusResult(job: JobRecord): JobStatusResult {
+  return {
+    jobId: job.id,
+    type: job.type,
+    status: job.status,
+    startedAt: new Date(job.startedAt).toISOString(),
+    completedAt: job.completedAt
+      ? new Date(job.completedAt).toISOString()
+      : undefined,
+    result: job.result,
+    error: job.error,
+    serverInstanceId: job.serverInstanceId,
+  };
+}
+
+export function handleJobStatus(
+  args: JobStatusInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_job_status",
+    async () => {
+      const job = ctx.jobManager.getJob(args.jobId);
+      if (!job) {
+        throw new Error(`NOT_FOUND: Job not found: ${args.jobId}`);
+      }
+
+      return toJobStatusResult(job);
+    },
+    formatJobStatus
+  );
+}

package/src/mcp/tools/list-jobs.ts

@@ -0,0 +1,81 @@
+/**
+ * MCP gno_list_jobs tool - list active/recent jobs.
+ *
+ * @module src/mcp/tools/list-jobs
+ */
+
+import type { JobRecord } from "../../core/job-manager";
+import type { ToolContext } from "../server";
+
+import { runTool, type ToolResult } from "./index";
+
+interface ListJobsInput {
+  limit?: number;
+}
+
+interface ListJobsResult {
+  active: Array<{
+    jobId: string;
+    type: JobRecord["type"];
+    startedAt: string;
+  }>;
+  recent: Array<{
+    jobId: string;
+    type: JobRecord["type"];
+    status: "completed" | "failed";
+    completedAt: string;
+  }>;
+}
+
+function formatListJobs(result: ListJobsResult): string {
+  const lines: string[] = [];
+
+  lines.push(`Active: ${result.active.length}`);
+  for (const job of result.active) {
+    lines.push(`  ${job.jobId} (${job.type}) started ${job.startedAt}`);
+  }
+
+  lines.push("");
+  lines.push(`Recent: ${result.recent.length}`);
+  for (const job of result.recent) {
+    lines.push(
+      `  ${job.jobId} (${job.type}) ${job.status} at ${job.completedAt}`
+    );
+  }
+
+  return lines.join("\n");
+}
+
+function toListJobsResult(
+  active: JobRecord[],
+  recent: JobRecord[]
+): ListJobsResult {
+  return {
+    active: active.map((job) => ({
+      jobId: job.id,
+      type: job.type,
+      startedAt: new Date(job.startedAt).toISOString(),
+    })),
+    recent: recent.map((job) => ({
+      jobId: job.id,
+      type: job.type,
+      status: job.status === "failed" ? "failed" : "completed",
+      completedAt: new Date(job.completedAt ?? job.startedAt).toISOString(),
+    })),
+  };
+}
+
+export function handleListJobs(
+  args: ListJobsInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_list_jobs",
+    async () => {
+      const { active, recent } = ctx.jobManager.listJobs(args.limit ?? 10);
+      return toListJobsResult(active, recent);
+    },
+    formatListJobs
+  );
+}