@gmickel/gno 1.17.0 → 1.19.0

package/src/mcp/resources/index.ts

@@ -92,6 +92,9 @@ function formatResourceContent(
  * Register gno:// resources with the MCP server.
  */
 export function registerResources(server: McpServer, ctx: ToolContext): void {
+  const withSnapshot = <T>(operation: () => Promise<T>): Promise<T> =>
+    ctx.runWithSnapshot?.(operation) ?? operation();
+
   // Resource template for gno://{collection}/{path} URIs
   const template = new ResourceTemplate(`${URI_PREFIX}{collection}/{+path}`, {
     list: async () => {
@@ -113,101 +116,103 @@ export function registerResources(server: McpServer, ctx: ToolContext): void {
   });
 
   // Register the template-based resource handler
-  server.resource("gno-document", template, {}, async (uri, _variables) => {
-    // Check shutdown before acquiring mutex
-    if (ctx.isShuttingDown()) {
-      throw new Error("Server is shutting down");
-    }
-
-    // Serialize resource reads same as tools (prevent concurrent DB access + shutdown race)
-    const release = await ctx.toolMutex.acquire();
-    try {
-      // Use parseUri for proper URL decoding (handles %20, etc.)
-      const parsed = parseUri(uri.href);
-      if (!parsed) {
-        throw new Error(`Invalid gno:// URI: ${uri.href}`);
-      }
-
-      const resolution = resolveEffectiveIndex([uri.href], ctx.indexName);
-      if (!resolution.ok) {
-        throw new Error(resolution.error);
+  server.resource("gno-document", template, {}, (uri, _variables) =>
+    withSnapshot(async () => {
+      // Check shutdown before acquiring mutex
+      if (ctx.isShuttingDown()) {
+        throw new Error("Server is shutting down");
       }
-      const scoped = await openScopedIndexStore({
-        activeStore: ctx.store,
-        activeIndexName: ctx.indexName,
-        requestedIndexName: resolution.value.indexName,
-        config: ctx.config,
-        configPath: ctx.actualConfigPath,
-      });
 
+      // Serialize resource reads same as tools (prevent concurrent DB access + shutdown race)
+      const release = await ctx.toolMutex.acquire();
       try {
-        const { collection, path } = parsed;
-
-        // Validate collection exists
-        const collectionExists = ctx.collections.some(
-          (c) => c.name === collection
-        );
-        if (!collectionExists) {
-          throw new Error(`Collection not found: ${collection}`);
+        // Use parseUri for proper URL decoding (handles %20, etc.)
+        const parsed = parseUri(uri.href);
+        if (!parsed) {
+          throw new Error(`Invalid gno:// URI: ${uri.href}`);
         }
 
-        // Look up document (path is properly decoded by parseUri)
-        const docResult = await scoped.store.getDocument(collection, path);
-        if (!docResult.ok) {
-          throw new Error(
-            `Failed to lookup document: ${docResult.error.message}`
-          );
+        const resolution = resolveEffectiveIndex([uri.href], ctx.indexName);
+        if (!resolution.ok) {
+          throw new Error(resolution.error);
         }
+        const scoped = await openScopedIndexStore({
+          activeStore: ctx.store,
+          activeIndexName: ctx.indexName,
+          requestedIndexName: resolution.value.indexName,
+          config: ctx.config,
+          configPath: ctx.actualConfigPath,
+        });
+
+        try {
+          const { collection, path } = parsed;
+
+          // Validate collection exists
+          const collectionExists = ctx.collections.some(
+            (c) => c.name === collection
+          );
+          if (!collectionExists) {
+            throw new Error(`Collection not found: ${collection}`);
+          }
 
-        const doc = docResult.value;
-        if (!doc) {
-          throw new Error(`Document not found: ${uri.href}`);
-        }
+          // Look up document (path is properly decoded by parseUri)
+          const docResult = await scoped.store.getDocument(collection, path);
+          if (!docResult.ok) {
+            throw new Error(
+              `Failed to lookup document: ${docResult.error.message}`
+            );
+          }
 
-        // Get content
-        if (!doc.mirrorHash) {
-          throw new Error(`Document has no indexed content: ${uri.href}`);
-        }
+          const doc = docResult.value;
+          if (!doc) {
+            throw new Error(`Document not found: ${uri.href}`);
+          }
+
+          // Get content
+          if (!doc.mirrorHash) {
+            throw new Error(`Document has no indexed content: ${uri.href}`);
+          }
+
+          const contentResult = await scoped.store.getContent(doc.mirrorHash);
+          if (!contentResult.ok) {
+            throw new Error(
+              `Failed to read content: ${contentResult.error.message}`
+            );
+          }
+
+          const content = contentResult.value ?? "";
 
-        const contentResult = await scoped.store.getContent(doc.mirrorHash);
-        if (!contentResult.ok) {
-          throw new Error(
-            `Failed to read content: ${contentResult.error.message}`
+          // Format with header and line numbers
+          const formattedContent = formatResourceContent(
+            doc,
+            content,
+            ctx,
+            scoped.indexName
+          );
+
+          // Build canonical URI
+          const canonicalUri = decorateUriForIndex(
+            buildUri(collection, path),
+            scoped.indexName
           );
-        }
 
-        const content = contentResult.value ?? "";
-
-        // Format with header and line numbers
-        const formattedContent = formatResourceContent(
-          doc,
-          content,
-          ctx,
-          scoped.indexName
-        );
-
-        // Build canonical URI
-        const canonicalUri = decorateUriForIndex(
-          buildUri(collection, path),
-          scoped.indexName
-        );
-
-        return {
-          contents: [
-            {
-              uri: canonicalUri,
-              mimeType: "text/markdown",
-              text: formattedContent,
-            },
-          ],
-        };
+          return {
+            contents: [
+              {
+                uri: canonicalUri,
+                mimeType: "text/markdown",
+                text: formattedContent,
+              },
+            ],
+          };
+        } finally {
+          await scoped.close();
+        }
       } finally {
-        await scoped.close();
+        release();
       }
-    } finally {
-      release();
-    }
-  });
+    })
+  );
 
   // Register gno://tags resource for listing tags
   // Use ResourceTemplate with RFC6570 query expansion for proper routing
@@ -231,65 +236,67 @@ export function registerResources(server: McpServer, ctx: ToolContext): void {
     "gno-tags",
     tagsTemplate,
     { mimeType: "application/json" },
-    async (uri) => {
-      // Check shutdown before acquiring mutex
-      if (ctx.isShuttingDown()) {
-        throw new Error("Server is shutting down");
-      }
-
-      const release = await ctx.toolMutex.acquire();
-      try {
-        // Parse query params from URI
-        const url = new URL(uri.href);
-        const collectionParam = url.searchParams.get("collection") || undefined;
-        const prefixParam = url.searchParams.get("prefix") || undefined;
-
-        // Normalize and validate collection (case-insensitive)
-        let collection: string | undefined;
-        if (collectionParam) {
-          collection = normalizeCollectionName(collectionParam);
-          const exists = ctx.collections.some(
-            (c) => c.name.toLowerCase() === collection
-          );
-          if (!exists) {
-            throw new Error(
-              `${MCP_ERRORS.NOT_FOUND.code}: Collection not found: ${collectionParam}`
-            );
-          }
+    (uri) =>
+      withSnapshot(async () => {
+        // Check shutdown before acquiring mutex
+        if (ctx.isShuttingDown()) {
+          throw new Error("Server is shutting down");
         }
 
-        // Normalize and validate prefix
-        let prefix: string | undefined;
-        if (prefixParam) {
-          const trimmed = prefixParam.trim().replace(/\/+$/, "");
-          if (trimmed.length > 0) {
-            prefix = normalizeTag(trimmed);
-            if (!validateTag(prefix)) {
+        const release = await ctx.toolMutex.acquire();
+        try {
+          // Parse query params from URI
+          const url = new URL(uri.href);
+          const collectionParam =
+            url.searchParams.get("collection") || undefined;
+          const prefixParam = url.searchParams.get("prefix") || undefined;
+
+          // Normalize and validate collection (case-insensitive)
+          let collection: string | undefined;
+          if (collectionParam) {
+            collection = normalizeCollectionName(collectionParam);
+            const exists = ctx.collections.some(
+              (c) => c.name.toLowerCase() === collection
+            );
+            if (!exists) {
               throw new Error(
-                `${MCP_ERRORS.INVALID_INPUT.code}: Invalid tag prefix "${prefixParam}"`
+                `${MCP_ERRORS.NOT_FOUND.code}: Collection not found: ${collectionParam}`
               );
             }
           }
-        }
 
-        // Get tag counts
-        const result = await ctx.store.getTagCounts({ collection, prefix });
-        if (!result.ok) {
-          throw new Error(`Failed to get tags: ${result.error.message}`);
-        }
+          // Normalize and validate prefix
+          let prefix: string | undefined;
+          if (prefixParam) {
+            const trimmed = prefixParam.trim().replace(/\/+$/, "");
+            if (trimmed.length > 0) {
+              prefix = normalizeTag(trimmed);
+              if (!validateTag(prefix)) {
+                throw new Error(
+                  `${MCP_ERRORS.INVALID_INPUT.code}: Invalid tag prefix "${prefixParam}"`
+                );
+              }
+            }
+          }
 
-        return {
-          contents: [
-            {
-              uri: uri.href,
-              mimeType: "application/json",
-              text: formatTagsContent(result.value, collection, prefix),
-            },
-          ],
-        };
-      } finally {
-        release();
-      }
-    }
+          // Get tag counts
+          const result = await ctx.store.getTagCounts({ collection, prefix });
+          if (!result.ok) {
+            throw new Error(`Failed to get tags: ${result.error.message}`);
+          }
+
+          return {
+            contents: [
+              {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: formatTagsContent(result.value, collection, prefix),
+              },
+            ],
+          };
+        } finally {
+          release();
+        }
+      })
   );
 }

package/src/mcp/server.ts

@@ -5,14 +5,10 @@
  * @module src/mcp/server
  */
 
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 // node:path for join/dirname (no Bun path utils)
 import { dirname, join } from "node:path";
 
-import type { Collection, Config } from "../config/types";
-import type { SqliteAdapter } from "../store/sqlite/adapter";
-
 import {
   DEFAULT_INDEX_NAME,
   MCP_SERVER_NAME,
@@ -23,55 +19,14 @@ import { canonicalizeIndexName } from "../app/index-name";
 import { JobManager } from "../core/job-manager";
 import { envIsSet } from "../llm/policy";
 import { MCP_ACTIVATION_VERIFICATION_ENV } from "./activation-verification-mode";
+import {
+  createMcpServerSurface,
+  createToolContext,
+  Mutex,
+  type ToolContext,
+} from "./context";
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Simple Promise Mutex (avoids async-mutex dependency)
-// ─────────────────────────────────────────────────────────────────────────────
-
-class Mutex {
-  #locked = false;
-  readonly #queue: Array<() => void> = [];
-
-  acquire(): Promise<() => void> {
-    return new Promise((resolve) => {
-      const tryAcquire = () => {
-        if (this.#locked) {
-          this.#queue.push(tryAcquire);
-        } else {
-          this.#locked = true;
-          resolve(() => this.#release());
-        }
-      };
-      tryAcquire();
-    });
-  }
-
-  #release(): void {
-    this.#locked = false;
-    const next = this.#queue.shift();
-    if (next) {
-      next();
-    }
-  }
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Tool Context
-// ─────────────────────────────────────────────────────────────────────────────
-
-export interface ToolContext {
-  store: SqliteAdapter;
-  config: Config;
-  collections: Collection[];
-  actualConfigPath: string;
-  indexName: string;
-  toolMutex: Mutex;
-  jobManager: JobManager;
-  serverInstanceId: string;
-  writeLockPath: string;
-  enableWrite: boolean;
-  isShuttingDown: () => boolean;
-}
+export type { ToolContext } from "./context";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Server Options
@@ -136,21 +91,7 @@ export async function startMcpServer(options: McpServerOptions): Promise<void> {
     process.exit(1);
   }
 
-  const { store, config, collections, actualConfigPath } = init;
-
-  // Create MCP server
-  const server = new McpServer(
-    {
-      name: MCP_SERVER_NAME,
-      version: VERSION,
-    },
-    {
-      capabilities: {
-        tools: { listChanged: false },
-        resources: { subscribe: false, listChanged: false },
-      },
-    }
-  );
+  const { store, config, actualConfigPath } = init;
 
   // Sequential execution mutex
   const toolMutex = new Mutex();
@@ -173,10 +114,13 @@ export async function startMcpServer(options: McpServerOptions): Promise<void> {
   let shuttingDown = false;
 
   // Tool context (passed to all handlers)
-  const ctx: ToolContext = {
+  let currentConfig = config;
+  const ctx: ToolContext = createToolContext({
     store,
-    config,
-    collections,
+    getConfig: () => currentConfig,
+    setConfig: (nextConfig) => {
+      currentConfig = nextConfig;
+    },
     actualConfigPath,
     indexName: canonicalizeIndexName(options.indexName ?? DEFAULT_INDEX_NAME),
     toolMutex,
@@ -185,15 +129,11 @@ export async function startMcpServer(options: McpServerOptions): Promise<void> {
     writeLockPath,
     enableWrite,
     isShuttingDown: () => shuttingDown,
-  };
-
-  // Register tools (T10.2)
-  const { registerTools } = await import("./tools/index.js");
-  registerTools(server, ctx);
-
-  // Register resources (T10.3)
-  const { registerResources } = await import("./resources/index.js");
-  registerResources(server, ctx);
+  });
+  const server = createMcpServerSurface(ctx, {
+    name: MCP_SERVER_NAME,
+    version: VERSION,
+  });
 
   if (options.verbose) {
     console.error(

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

@@ -14,6 +14,7 @@ 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 { recordContentMutation } from "../../core/mutation-generations";
 import {
   normalizeCollectionName,
   validateCollectionRoot,
@@ -152,9 +153,10 @@ export function handleAddCollection(
                   gitPull: args.gitPull ?? false,
                   runUpdateCmd: false,
                 },
-                ctx.config
+                mutationResult.config
               )
             );
+            recordContentMutation(result, ctx.markContentMutation);
 
             return {
               collections: [result],

package/src/mcp/tools/capture.ts

@@ -210,6 +210,9 @@ export function handleCapture(
             serverInstanceId: ctx.serverInstanceId,
           }) as McpCaptureResult;
         }
+        if (syncResult.status === "added" || syncResult.status === "updated") {
+          ctx.markContentMutation?.();
+        }
 
         let docid = syncResult.docid;
         let documentId: number | undefined;

package/src/mcp/tools/clear-collection-embeddings.ts

@@ -8,6 +8,7 @@ import type { ToolContext } from "../server";
 
 import { MCP_ERRORS } from "../../core/errors";
 import { withWriteLock } from "../../core/file-lock";
+import { recordIndexMutation } from "../../core/mutation-generations";
 import { resolveModelUri } from "../../llm/registry";
 import { runTool, type ToolResult } from "./index";
 
@@ -81,6 +82,7 @@ export function handleClearCollectionEmbeddings(
         if (!result.ok) {
           throw new Error(`${result.error.code}: ${result.error.message}`);
         }
+        recordIndexMutation(result.value.deletedVectors, ctx.markIndexMutation);
 
         return {
           ...result.value,

package/src/mcp/tools/context.ts

@@ -1,5 +1,7 @@
 /** MCP Context Capsule tools over the shared application runtime. */
 
+import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
+import type { ModelLease } from "../../llm/nodeLlamaCpp/lifecycle";
 import type { EmbeddingPort, RerankPort } from "../../llm/types";
 import type { VectorIndexPort } from "../../store/vector";
 import type { ToolContext } from "../server";
@@ -19,6 +21,10 @@ import {
   parseContextVerifySurfaceInput,
 } from "../../app/context-surface";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
+import {
+  finishRetrievalTraceAfterError,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
 import { resolveModelUri } from "../../llm/registry";
@@ -27,11 +33,15 @@ import { createVectorIndexPort } from "../../store/vector";
 interface ContextToolResultData {
   structuredContent: Record<string, unknown>;
   text: string;
+  traceId?: string;
 }
 
 const asToolResult = (data: ContextToolResultData): ToolResult => ({
   content: [{ type: "text", text: data.text }],
   structuredContent: data.structuredContent,
+  ...(data.traceId
+    ? { _meta: { gno: { retrievalTrace: { traceId: data.traceId } } } }
+    : {}),
 });
 
 const asToolError = (error: unknown): ToolResult => {
@@ -64,7 +74,8 @@ const runContextTool = async (
   }
   const release = await context.toolMutex.acquire();
   try {
-    return asToolResult(await operation());
+    const data = await (context.runWithSnapshot?.(operation) ?? operation());
+    return asToolResult(data);
   } catch (error) {
     return asToolError(error);
   } finally {
@@ -82,19 +93,17 @@ interface McpModelPorts {
 interface McpModelPortFactory {
   createEmbeddingPort: LlmAdapter["createEmbeddingPort"];
   createRerankPort: LlmAdapter["createRerankPort"];
-  dispose: LlmAdapter["dispose"];
+  acquireModelLease?: LlmAdapter["acquireModelLease"];
 }
 
 export const disposeContextModelOwners = async (
   portOwners: readonly { dispose(): Promise<void> }[],
-  managerOwner: { dispose(): Promise<void> }
+  lease?: ModelLease
 ): Promise<void> => {
   await Promise.allSettled(
     portOwners.map((owner) => Promise.resolve().then(() => owner.dispose()))
   );
-  await Promise.allSettled([
-    Promise.resolve().then(() => managerOwner.dispose()),
-  ]);
+  lease?.release();
 };
 
 export const createMcpModelPorts = async (
@@ -104,6 +113,7 @@ export const createMcpModelPorts = async (
 ): Promise<McpModelPorts> => {
   const llm = new LlmAdapter(context.config);
   const factory = factoryOverride ?? llm;
+  const lease = factory.acquireModelLease?.();
   const policy = resolveDownloadPolicy(process.env, {});
   const progress = createNonTtyProgressRenderer();
   const embedUri = resolveModelUri(
@@ -151,7 +161,7 @@ export const createMcpModelPorts = async (
           [ownedEmbedPort, rerankPort].filter(
             (port): port is EmbeddingPort | RerankPort => port !== null
           ),
-          factory
+          lease
         );
       },
     };
@@ -160,7 +170,7 @@ export const createMcpModelPorts = async (
       [ownedEmbedPort, rerankPort].filter(
         (port): port is EmbeddingPort | RerankPort => port !== null
       ),
-      factory
+      lease
     );
     throw error;
   }
@@ -179,15 +189,50 @@ export const handleContext = (
       context.config.collections.map((collection) => collection.name)
     );
     const useModels = parsed.input.depthPolicy !== "fast";
-    const modelPorts = useModels
-      ? await createMcpModelPorts(
-          context,
-          parsed.input.collections?.length === 1
-            ? parsed.input.collections[0]
-            : undefined
-        )
-      : null;
+    const collection =
+      parsed.input.collections?.length === 1
+        ? parsed.input.collections[0]
+        : undefined;
+    const modelUris = useModels
+      ? [
+          resolveModelUri(context.config, "embed", undefined, collection),
+          resolveModelUri(context.config, "rerank", undefined, collection),
+        ]
+      : [];
+    let modelPorts: Awaited<ReturnType<typeof createMcpModelPorts>> | null =
+      null;
+    let traceSession: RetrievalTraceSession | undefined;
     try {
+      const traceStart = await startRetrievalTraceRequest({
+        store: context.store,
+        config: context.config,
+        query: parsed.input.query ?? parsed.input.goal,
+        goal: parsed.input.goal,
+        filters: {
+          limit: parsed.input.limit,
+          collection,
+          collections: [...(parsed.input.collections ?? [])].sort(),
+          lang: parsed.input.lang,
+          tagsAll: parsed.input.tagsAll,
+          tagsAny: parsed.input.tagsAny,
+          since: parsed.input.since,
+          until: parsed.input.until,
+          categories: parsed.input.categories,
+          author: parsed.input.author,
+          graph: parsed.input.graph,
+          candidateLimit: parsed.input.candidateLimit,
+          queryModes: parsed.input.queryModes,
+          uriPrefix: parsed.input.uriPrefix ?? undefined,
+        },
+        pipeline: "context",
+        indexName: context.indexName,
+        modelUris,
+      });
+      if (!traceStart.ok) throw new Error(traceStart.error.message);
+      traceSession = traceStart.value ?? undefined;
+      modelPorts = useModels
+        ? await createMcpModelPorts(context, collection)
+        : null;
       const capsule = await buildContextCapsule(parsed.input, {
         store: context.store,
         config: context.config,
@@ -195,14 +240,21 @@ export const handleContext = (
         vectorIndex: modelPorts?.vectorIndex ?? null,
         embedPort: modelPorts?.embedPort ?? null,
         rerankPort: modelPorts?.rerankPort ?? null,
+        traceSession,
       });
+      const finalized = await traceSession?.finish("completed");
+      if (finalized && !finalized.ok) throw new Error(finalized.error.message);
       return {
         structuredContent: capsule as unknown as Record<string, unknown>,
         // MCP model context receives this projection exactly once. The full
         // canonical capsule remains available to application clients through
         // structuredContent and is deliberately not duplicated in text.
         text: formatContextCapsuleAgentJson(capsule),
+        traceId: traceSession?.metadata()?.traceId,
       };
+    } catch (cause) {
+      await finishRetrievalTraceAfterError(traceSession, cause);
+      throw cause;
     } finally {
       await modelPorts?.dispose();
     }