@gmickel/gno 0.10.4 → 0.11.0

package/assets/skill/SKILL.md

@@ -83,6 +83,18 @@ gno search "your query"               # BM25 keyword search
 --no-pager        Disable paging
 ```
 
+## Important: Embedding After Changes
+
+If you edit/create files that should be searchable via vector search:
+
+```bash
+gno index              # Full re-index (sync + embed)
+# or
+gno embed              # Embed only (if already synced)
+```
+
+MCP `gno.sync` and `gno.capture` do NOT auto-embed. Use CLI for embedding.
+
 ## Reference Documentation
 
 | Topic                                                 | File                                 |

package/assets/skill/mcp-reference.md

@@ -1,8 +1,23 @@
-# GNO MCP Reference
+# GNO MCP Installation
 
-GNO provides an MCP (Model Context Protocol) server for AI integration.
+GNO provides an MCP (Model Context Protocol) server for AI client integration.
 
-## Setup
+> **Full reference**: See [gno.sh/docs/MCP](https://www.gno.sh/docs/MCP) for complete tool documentation.
+
+## Quick Install
+
+```bash
+# Claude Desktop (default)
+gno mcp install
+
+# Claude Code
+gno mcp install -t claude-code
+
+# With write tools enabled
+gno mcp install --enable-write
+```
+
+## Manual Setup
 
 ### Claude Desktop
 
@@ -19,202 +34,28 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-Config location:
+Config locations:
 
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 - Linux: `~/.config/Claude/claude_desktop_config.json`
 
-### Start Server
+### Claude Code
 
 ```bash
-gno mcp
-```
-
-Runs JSON-RPC 2.0 over stdio.
-
-## Tools
-
-### gno.search
-
-BM25 keyword search.
-
-```json
-{
-  "query": "search terms",
-  "collection": "optional-collection",
-  "limit": 5,
-  "minScore": 0.5,
-  "lang": "en",
-  "tagsAny": ["project", "work"],
-  "tagsAll": ["reviewed"]
-}
-```
-
-| Parameter    | Description                         |
-| ------------ | ----------------------------------- |
-| `query`      | Search query (required)             |
-| `collection` | Filter by collection                |
-| `limit`      | Max results (default: 5)            |
-| `minScore`   | Minimum score 0-1                   |
-| `tagsAny`    | Filter: has ANY of these tags (OR)  |
-| `tagsAll`    | Filter: has ALL of these tags (AND) |
-
-### gno.vsearch
-
-Vector semantic search. Same parameters as `gno.search`.
-
-### gno.query
-
-Hybrid search (best quality).
-
-```json
-{
-  "query": "search terms",
-  "collection": "optional-collection",
-  "limit": 5
-}
-```
-
-**Search modes** (via parameters):
-
-| Mode     | Parameters       | Time  |
-| -------- | ---------------- | ----- |
-| Fast     | `fast: true`     | ~0.7s |
-| Default  | (none)           | ~2-3s |
-| Thorough | `thorough: true` | ~5-8s |
-
-Default skips expansion, with reranking. Use `thorough: true` for best recall.
-
-**Agent retry strategy**: Use default mode first. If no relevant results:
-
-1. Rephrase the query (free, often effective)
-2. Then try `thorough: true` for better recall
-
-### gno.get
-
-Retrieve document by reference.
-
-```json
-{
-  "ref": "gno://collection/path or #docid",
-  "fromLine": 1,
-  "lineCount": 100,
-  "lineNumbers": true
-}
-```
-
-### gno.multi_get
-
-Retrieve multiple documents.
-
-```json
-{
-  "refs": ["gno://work/doc1.md", "#a1b2c3d4"],
-  "maxBytes": 10240,
-  "lineNumbers": true
-}
-```
-
-Or by pattern:
-
-```json
-{
-  "pattern": "work/**/*.md",
-  "maxBytes": 10240
-}
-```
-
-### gno.status
-
-Get index status.
-
-```json
-{}
-```
-
-### gno.list_tags
-
-List tags with document counts.
-
-```json
-{
-  "collection": "optional-collection",
-  "prefix": "project/"
-}
-```
-
-| Parameter    | Description                             |
-| ------------ | --------------------------------------- |
-| `collection` | Filter by collection                    |
-| `prefix`     | Filter by tag prefix (e.g., `project/`) |
-
-### gno.tag
-
-Add or remove tag from document.
-
-```json
-{
-  "ref": "gno://work/readme.md",
-  "tag": "project/api",
-  "action": "add"
-}
+gno mcp install -t claude-code -s user    # User scope
+gno mcp install -t claude-code -s project # Project scope
 ```
 
-| Parameter | Description                        |
-| --------- | ---------------------------------- |
-| `ref`     | Document URI or docid (required)   |
-| `tag`     | Tag string (required)              |
-| `action`  | `add` or `remove` (default: `add`) |
+## Check Status
 
-## Resources
-
-Documents accessible as MCP resources:
-
-```
-gno://{collection}/{path}
-```
-
-Examples:
-
-- `gno://work/contracts/nda.docx`
-- `gno://notes/2025/01/meeting.md`
-
-Returns Markdown content with line numbers.
-
-## Response Format
-
-All tools return:
-
-```json
-{
-  "content": [
-    { "type": "text", "text": "Human-readable summary" }
-  ],
-  "structuredContent": {
-    "results": [...],
-    "meta": { "query": "...", "mode": "hybrid" }
-  }
-}
+```bash
+gno mcp status
 ```
 
-## Error Handling
+## Uninstall
 
-Errors return:
-
-```json
-{
-  "isError": true,
-  "content": [
-    { "type": "text", "text": "Error: Document not found" }
-  ]
-}
+```bash
+gno mcp uninstall
+gno mcp uninstall -t claude-code
 ```
-
-## Graceful Degradation
-
-`gno.query` degrades gracefully:
-
-- No vectors → BM25 only
-- No expansion model → skips expansion
-- No rerank model → skips reranking

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/src/cli/commands/embed.ts

@@ -161,13 +161,12 @@ async function processBatches(ctx: BatchContext): Promise<BatchResult> {
       continue;
     }
 
-    // Store vectors
+    // Store vectors (embeddedAt set by DB)
     const vectors: VectorRow[] = batch.map((b, idx) => ({
       mirrorHash: b.mirrorHash,
       seq: b.seq,
       model: ctx.modelUri,
       embedding: new Float32Array(embeddings[idx] as number[]),
-      embeddedAt: new Date().toISOString(),
     }));
 
     const storeResult = await ctx.vectorIndex.upsertVectors(vectors);

package/src/core/job-manager.ts

@@ -13,17 +13,38 @@ const JOB_EXPIRATION_MS = 60 * 60 * 1000;
 const JOB_MAX_RECENT = 100;
 const DEFAULT_LOCK_TIMEOUT_MS = 5000;
 
-export type JobType = "add" | "sync";
+export type JobType = "add" | "sync" | "embed" | "index";
 
 export type JobStatus = "running" | "completed" | "failed";
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Discriminated union for job results
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface EmbedJobResult {
+  embedded: number;
+  errors: number;
+}
+
+export interface IndexJobResult {
+  sync: SyncResult;
+  embed: EmbedJobResult;
+}
+
+export type JobResult =
+  | { kind: "sync"; value: SyncResult }
+  | { kind: "embed"; value: EmbedJobResult }
+  | { kind: "index"; value: IndexJobResult };
+
 export interface JobRecord {
   id: string;
   type: JobType;
   status: JobStatus;
   startedAt: number;
   completedAt?: number;
+  /** @deprecated Use typedResult for new job types */
   result?: SyncResult;
+  typedResult?: JobResult;
   error?: string;
   serverInstanceId: string;
 }
@@ -101,6 +122,27 @@ export class JobManager {
     return this.#startJobWithLock(type, fn, lock);
   }
 
+  /**
+   * Start a job with typed result (for embed/index jobs).
+   * Uses discriminated union for type-safe results.
+   */
+  async startTypedJobWithLock(
+    type: JobType,
+    lock: WriteLockHandle,
+    fn: () => Promise<JobResult>
+  ): Promise<string> {
+    this.#cleanupExpiredJobs();
+
+    if (this.#activeJobId) {
+      throw new JobError(
+        "JOB_CONFLICT",
+        `${MCP_ERRORS.JOB_CONFLICT.message} (${this.#activeJobId})`
+      );
+    }
+
+    return this.#startTypedJobWithLock(type, fn, lock);
+  }
+
   getJob(jobId: string): JobRecord | undefined {
     this.#cleanupExpiredJobs();
     return this.#jobs.get(jobId);
@@ -185,6 +227,57 @@ export class JobManager {
     return jobId;
   }
 
+  #startTypedJobWithLock(
+    type: JobType,
+    fn: () => Promise<JobResult>,
+    lock: WriteLockHandle
+  ): string {
+    const jobId = crypto.randomUUID();
+    const job: JobRecord = {
+      id: jobId,
+      type,
+      status: "running",
+      startedAt: Date.now(),
+      serverInstanceId: this.#serverInstanceId,
+    };
+
+    this.#jobs.set(jobId, job);
+    this.#activeJobId = jobId;
+
+    const jobPromise = this.#runTypedJob(job, fn, lock);
+    this.#track(jobPromise);
+
+    return jobId;
+  }
+
+  async #runTypedJob(
+    job: JobRecord,
+    fn: () => Promise<JobResult>,
+    lock: { release: () => Promise<void> }
+  ): Promise<void> {
+    try {
+      const release = await this.#toolMutex.acquire();
+      try {
+        const result = await fn();
+        job.status = "completed";
+        job.typedResult = result;
+      } catch (e) {
+        job.status = "failed";
+        job.error = e instanceof Error ? e.message : String(e);
+      } finally {
+        release();
+      }
+    } catch (e) {
+      job.status = "failed";
+      job.error = e instanceof Error ? e.message : String(e);
+    } finally {
+      job.completedAt = Date.now();
+      this.#activeJobId = null;
+      await lock.release().catch(() => undefined);
+      this.#cleanupExpiredJobs();
+    }
+  }
+
   #cleanupExpiredJobs(now: number = Date.now()): void {
     for (const [id, job] of this.#jobs) {
       if (job.status === "running") {

package/src/embed/backlog.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared embedding backlog processor.
+ * Used by CLI embed, Web scheduler, and MCP tools.
+ *
+ * @module src/embed/backlog
+ */
+
+import type { EmbeddingPort } from "../llm/types";
+import type { StoreResult } from "../store/types";
+import type {
+  BacklogItem,
+  VectorIndexPort,
+  VectorRow,
+  VectorStatsPort,
+} from "../store/vector";
+
+import { formatDocForEmbedding } from "../pipeline/contextual";
+import { err, ok } from "../store/types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface EmbedBacklogDeps {
+  statsPort: VectorStatsPort;
+  embedPort: EmbeddingPort;
+  vectorIndex: VectorIndexPort;
+  modelUri: string;
+  batchSize?: number;
+}
+
+export interface EmbedBacklogResult {
+  embedded: number;
+  errors: number;
+}
+
+interface Cursor {
+  mirrorHash: string;
+  seq: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Process embedding backlog in batches.
+ * Cursor-based pagination, batch embedding, vector storage.
+ */
+export async function embedBacklog(
+  deps: EmbedBacklogDeps
+): Promise<StoreResult<EmbedBacklogResult>> {
+  const { statsPort, embedPort, vectorIndex, modelUri } = deps;
+  const batchSize = deps.batchSize ?? 32;
+
+  let embedded = 0;
+  let errors = 0;
+  let cursor: Cursor | undefined;
+
+  try {
+    while (true) {
+      // Get next batch using seek pagination
+      const batchResult = await statsPort.getBacklog(modelUri, {
+        limit: batchSize,
+        after: cursor,
+      });
+
+      if (!batchResult.ok) {
+        return err("QUERY_FAILED", batchResult.error.message);
+      }
+
+      const batch = batchResult.value;
+      if (batch.length === 0) {
+        break;
+      }
+
+      // Advance cursor (even on failure, to avoid infinite loops)
+      const lastItem = batch.at(-1);
+      if (lastItem) {
+        cursor = { mirrorHash: lastItem.mirrorHash, seq: lastItem.seq };
+      }
+
+      // Embed batch with contextual formatting (title prefix)
+      const embedResult = await embedPort.embedBatch(
+        batch.map((b: BacklogItem) =>
+          formatDocForEmbedding(b.text, b.title ?? undefined)
+        )
+      );
+
+      if (!embedResult.ok) {
+        errors += batch.length;
+        continue;
+      }
+
+      // Validate batch/embedding count match
+      const embeddings = embedResult.value;
+      if (embeddings.length !== batch.length) {
+        errors += batch.length;
+        continue;
+      }
+
+      // Store vectors (embeddedAt set by DB)
+      const vectors: VectorRow[] = batch.map((b: BacklogItem, idx: number) => ({
+        mirrorHash: b.mirrorHash,
+        seq: b.seq,
+        model: modelUri,
+        embedding: new Float32Array(embeddings[idx] as number[]),
+      }));
+
+      const storeResult = await vectorIndex.upsertVectors(vectors);
+      if (!storeResult.ok) {
+        errors += batch.length;
+        continue;
+      }
+
+      embedded += batch.length;
+    }
+
+    return ok({ embedded, errors });
+  } catch (e) {
+    return err(
+      "INTERNAL",
+      `Embedding failed: ${e instanceof Error ? e.message : String(e)}`
+    );
+  }
+}

package/src/embed/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Embedding module - shared embedding utilities.
+ *
+ * @module src/embed
+ */
+
+export {
+  embedBacklog,
+  type EmbedBacklogDeps,
+  type EmbedBacklogResult,
+} from "./backlog";

package/src/mcp/tools/embed.ts

@@ -0,0 +1,151 @@
+/**
+ * MCP gno_embed tool - embed unembedded chunks.
+ *
+ * @module src/mcp/tools/embed
+ */
+
+import type { ToolContext } from "../server";
+
+import { MCP_ERRORS } from "../../core/errors";
+import { acquireWriteLock, type WriteLockHandle } from "../../core/file-lock";
+import { JobError } from "../../core/job-manager";
+import { embedBacklog } from "../../embed";
+import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
+import { getActivePreset } from "../../llm/registry";
+import {
+  createVectorIndexPort,
+  createVectorStatsPort,
+} from "../../store/vector";
+import { runTool, type ToolResult } from "./index";
+
+type EmbedInput = Record<string, never>;
+
+interface EmbedResultOutput {
+  jobId: string;
+  status: "started";
+  model: string;
+}
+
+function formatEmbedResult(result: EmbedResultOutput): string {
+  const lines: string[] = [];
+  lines.push(`Job: ${result.jobId}`);
+  lines.push(`Status: ${result.status}`);
+  lines.push(`Model: ${result.model}`);
+  return lines.join("\n");
+}
+
+export function handleEmbed(
+  args: EmbedInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_embed",
+    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}`
+          );
+        }
+
+        // Get model from active preset
+        const preset = getActivePreset(ctx.config);
+        const modelUri = preset.embed;
+
+        const jobId = await ctx.jobManager.startTypedJobWithLock(
+          "embed",
+          lock,
+          async () => {
+            // Create LLM adapter with offline policy (fail-fast, no download)
+            const llm = new LlmAdapter(ctx.config);
+            const embedResult = await llm.createEmbeddingPort(modelUri, {
+              policy: { offline: true, allowDownload: false },
+            });
+
+            if (!embedResult.ok) {
+              throw new Error(
+                `MODEL_NOT_FOUND: Embedding model not cached. ` +
+                  `Model: ${modelUri}, Preset: ${preset.name}. ` +
+                  `Run 'gno models pull embed' first.`
+              );
+            }
+
+            const embedPort = embedResult.value;
+
+            try {
+              // Initialize and get dimensions from port interface
+              const initResult = await embedPort.init();
+              if (!initResult.ok) {
+                throw new Error(initResult.error.message);
+              }
+              const dimensions = embedPort.dimensions();
+
+              // Create vector index port
+              const db = ctx.store.getRawDb();
+              const vectorResult = await createVectorIndexPort(db, {
+                model: modelUri,
+                dimensions,
+              });
+              if (!vectorResult.ok) {
+                throw new Error(vectorResult.error.message);
+              }
+              const vectorIndex = vectorResult.value;
+
+              // Create stats port for backlog
+              const statsPort = createVectorStatsPort(db);
+
+              // Run embedding
+              const result = await embedBacklog({
+                statsPort,
+                embedPort,
+                vectorIndex,
+                modelUri,
+                batchSize: 32,
+              });
+
+              if (!result.ok) {
+                throw new Error(result.error.message);
+              }
+
+              return {
+                kind: "embed" as const,
+                value: result.value,
+              };
+            } finally {
+              await embedPort.dispose();
+            }
+          }
+        );
+
+        handedOff = true;
+
+        const result: EmbedResultOutput = {
+          jobId,
+          status: "started",
+          model: modelUri,
+        };
+
+        return result;
+      } catch (error) {
+        if (error instanceof JobError) {
+          throw new Error(`${error.code}: ${error.message}`);
+        }
+        throw error;
+      } finally {
+        if (lock && !handedOff) {
+          await lock.release();
+        }
+      }
+    },
+    formatEmbedResult
+  );
+}