scythe-context-mcp 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -6,6 +6,12 @@ This project follows semantic versioning before npm publication where practical.
 
 ## [Unreleased]
 
+## [0.1.4] - 2026-06-14
+
+### Added
+
+- Add keyword-only fallback for hybrid search/context-pack calls when query embedding is unavailable, while preserving explicit `embedding_unavailable` diagnostics for semantic-only mode.
+
 ## [0.1.3] - 2026-06-14
 
 ### Changed

package/README.en.md

@@ -244,6 +244,8 @@ Use `PWD/p` only if you intentionally run a Windows Node process and need WSL to
 | `repo_related_files` | Shows symbols, imports, and importedBy for one file. |
 | `gemini_embedding_probe` | Tests Gemini or proxy compatibility and returns endpoint, latency, error classification, and remediation hints. |
 
+`repo_context_pack(mode="hybrid")` and `repo_semantic_search(mode="hybrid")` degrade to keyword-only results when query embedding is unavailable, returning `effectiveMode: "keyword"` and `fallback.reason: "embedding_unavailable"`. `mode="semantic"` does not degrade and returns `status: "embedding_unavailable"` because pure semantic search requires query embedding. Use `rg` / direct file reads for exact strings, known paths, or small targeted checks.
+
 ## Feature Status
 
 Implemented: repo scanning, chunking, SQLite metadata, SQLite FTS5, sqlite-vec, Gemini Embedding 2 provider, semantic/keyword/hybrid search, lightweight symbol/dependency graph, related-file lookup, `repo_context_pack`, provider diagnostics, and index freshness diagnostics.

package/README.md

@@ -244,6 +244,8 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 | `repo_related_files` | 查看單一檔案的 symbols、imports、importedBy。 |
 | `gemini_embedding_probe` | 測試 Gemini 或 proxy 相容性，回傳 endpoint、latency、錯誤分類與可修復建議。 |
 
+`repo_context_pack(mode="hybrid")` 和 `repo_semantic_search(mode="hybrid")` 在 query embedding 不可用時會降級成 keyword-only 結果，並回傳 `effectiveMode: "keyword"` 與 `fallback.reason: "embedding_unavailable"`。`mode="semantic"` 不會降級，會回傳 `status: "embedding_unavailable"`，因為純 semantic search 必須有 query embedding。精確字串、已知路徑或小範圍檢查仍建議直接用 `rg` / 直接讀檔。
+
 ## 功能狀態
 
 已完成：repo 掃描、chunking、SQLite metadata、SQLite FTS5、sqlite-vec、Gemini Embedding 2 provider、semantic/keyword/hybrid search、輕量 symbol/dependency graph、related-file lookup、`repo_context_pack`、provider diagnostics、index freshness diagnostics。

package/README.zh-CN.md

@@ -244,6 +244,8 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 | `repo_related_files` | 查看单一文件的 symbols、imports、importedBy。 |
 | `gemini_embedding_probe` | 测试 Gemini 或 proxy 兼容性，返回 endpoint、latency、错误分类与可修复建议。 |
 
+`repo_context_pack(mode="hybrid")` 和 `repo_semantic_search(mode="hybrid")` 在 query embedding 不可用时会降级成 keyword-only 结果，并返回 `effectiveMode: "keyword"` 与 `fallback.reason: "embedding_unavailable"`。`mode="semantic"` 不会降级，会返回 `status: "embedding_unavailable"`，因为纯 semantic search 必须有 query embedding。精确字符串、已知路径或小范围检查仍建议直接用 `rg` / 直接读文件。
+
 ## 功能状态
 
 已完成：repo 扫描、chunking、SQLite metadata、SQLite FTS5、sqlite-vec、Gemini Embedding 2 provider、semantic/keyword/hybrid search、轻量 symbol/dependency graph、related-file lookup、`repo_context_pack`、provider diagnostics、index freshness diagnostics。

package/dist/cli.js

@@ -1,4 +1,4 @@
-export const PACKAGE_VERSION = "0.1.3";
+export const PACKAGE_VERSION = "0.1.4";
 export function parseCliArgs(args) {
     if (args.length === 0)
         return { kind: "serve" };

package/dist/indexing/hybridSearch.js

@@ -65,3 +65,12 @@ export function searchHybrid(options) {
     });
     return mergeHybridResults(semanticResults, keywordResults, options.maxResults);
 }
+export function searchKeywordOnly(options) {
+    const keywordResults = searchByKeyword({
+        dbPath: options.dbPath,
+        query: options.query,
+        maxResults: Math.max(options.maxResults * 2, options.maxResults),
+        maxSnippetChars: options.maxSnippetChars,
+    });
+    return mergeHybridResults([], keywordResults, options.maxResults);
+}

package/dist/tools/registerTools.js

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { buildContextPack } from "../indexing/contextPack.js";
 import { reindexDryRun } from "../indexing/dryRun.js";
 import { indexMissingEmbeddings } from "../indexing/embeddingWriter.js";
-import { searchHybrid } from "../indexing/hybridSearch.js";
+import { searchHybrid, searchKeywordOnly } from "../indexing/hybridSearch.js";
 import { readDetailedIndexStatus, readIndexFreshness, recommendedNextActions } from "../indexing/indexStatus.js";
 import { persistentReindexMetadata } from "../indexing/indexWriter.js";
 import { readRelatedFileGraph, readRelatedFiles } from "../indexing/relatedFiles.js";
@@ -35,6 +35,37 @@ function searchIndexedChunks(options) {
             maxSnippetChars: options.maxSnippetChars,
         });
 }
+function searchKeywordOnlyChunks(options) {
+    return searchKeywordOnly({
+        dbPath: options.dbPath,
+        query: options.query,
+        maxResults: options.maxResults,
+        maxSnippetChars: options.maxSnippetChars,
+    });
+}
+function embeddingFailureDetails(error) {
+    const geminiError = error instanceof GeminiEmbeddingError ? error : undefined;
+    return {
+        type: error instanceof Error ? error.name : "UnknownError",
+        message: error instanceof Error ? error.message : String(error),
+        httpStatus: geminiError?.status,
+        retryable: geminiError?.retryable ?? false,
+        bodySnippet: geminiError?.bodySnippet,
+    };
+}
+function embeddingUnavailablePayload(error) {
+    return {
+        status: "embedding_unavailable",
+        fallbackAvailable: "Use mode=hybrid to allow keyword-only fallback, or use rg/direct file reads for exact strings and known paths.",
+        error: embeddingFailureDetails(error),
+        recommendedNextActions: [
+            "Run gemini_embedding_probe with a short test string.",
+            "Verify GEMINI_API_KEY, GEMINI_BASE_URL, GEMINI_AUTH_MODE, and GEMINI_OUTPUT_DIMENSIONALITY.",
+            "Use repo_context_pack with mode=hybrid for keyword-only degraded results while embeddings are unavailable.",
+            "Use rg/direct file reads for exact strings, known paths, or small targeted checks.",
+        ],
+    };
+}
 function buildGeminiDiagnostics(config, expectedDimensions) {
     const diagnostics = {
         baseUrl: config.baseUrl,
@@ -223,20 +254,50 @@ export function registerTools(server, config) {
                 message: "Run repo_reindex with dry_run=false and index_embeddings=true before semantic search.",
             });
         }
-        const queryEmbedding = await embeddingProvider.embed({ kind: "query", text: query });
         const dimensions = expectedDimensions;
-        if (queryEmbedding.dimensions !== dimensions) {
-            throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${queryEmbedding.dimensions}`);
+        let effectiveMode = mode;
+        let fallback;
+        let rawResults;
+        try {
+            const queryEmbedding = await embeddingProvider.embed({ kind: "query", text: query });
+            if (queryEmbedding.dimensions !== dimensions) {
+                throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${queryEmbedding.dimensions}`);
+            }
+            rawResults = searchIndexedChunks({
+                dbPath,
+                query,
+                dimensions,
+                queryVector: queryEmbedding.vector,
+                maxResults: max_results,
+                maxSnippetChars: max_snippet_chars,
+                mode,
+            });
+        }
+        catch (error) {
+            if (mode === "semantic") {
+                return asJsonText({
+                    query,
+                    projectPath,
+                    dbPath,
+                    dimensions,
+                    mode,
+                    ...embeddingUnavailablePayload(error),
+                });
+            }
+            effectiveMode = "keyword";
+            fallback = {
+                reason: "embedding_unavailable",
+                fromMode: mode,
+                toMode: "keyword",
+                error: embeddingFailureDetails(error),
+            };
+            rawResults = searchKeywordOnlyChunks({
+                dbPath,
+                query,
+                maxResults: max_results,
+                maxSnippetChars: max_snippet_chars,
+            });
         }
-        const rawResults = searchIndexedChunks({
-            dbPath,
-            query,
-            dimensions,
-            queryVector: queryEmbedding.vector,
-            maxResults: max_results,
-            maxSnippetChars: max_snippet_chars,
-            mode,
-        });
         const formatted = formatSearchResults(query, rawResults, { maxContextChars: max_context_chars });
         return asJsonText({
             query,
@@ -244,6 +305,8 @@ export function registerTools(server, config) {
             dbPath,
             dimensions,
             mode,
+            effectiveMode,
+            fallback,
             results: formatted.results,
             context: formatted.summary,
             resultCount: rawResults.length,
@@ -308,20 +371,50 @@ export function registerTools(server, config) {
                 message: "Run repo_reindex with dry_run=false and index_embeddings=true before building a context pack.",
             });
         }
-        const queryEmbedding = await embeddingProvider.embed({ kind: "query", text: query });
         const dimensions = expectedDimensions;
-        if (queryEmbedding.dimensions !== dimensions) {
-            throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${queryEmbedding.dimensions}`);
+        let effectiveMode = mode;
+        let fallback;
+        let rawResults;
+        try {
+            const queryEmbedding = await embeddingProvider.embed({ kind: "query", text: query });
+            if (queryEmbedding.dimensions !== dimensions) {
+                throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${queryEmbedding.dimensions}`);
+            }
+            rawResults = searchIndexedChunks({
+                dbPath,
+                query,
+                dimensions,
+                queryVector: queryEmbedding.vector,
+                maxResults: max_results,
+                maxSnippetChars: max_snippet_chars,
+                mode,
+            });
+        }
+        catch (error) {
+            if (mode === "semantic") {
+                return asJsonText({
+                    query,
+                    projectPath,
+                    dbPath,
+                    dimensions,
+                    mode,
+                    ...embeddingUnavailablePayload(error),
+                });
+            }
+            effectiveMode = "keyword";
+            fallback = {
+                reason: "embedding_unavailable",
+                fromMode: mode,
+                toMode: "keyword",
+                error: embeddingFailureDetails(error),
+            };
+            rawResults = searchKeywordOnlyChunks({
+                dbPath,
+                query,
+                maxResults: max_results,
+                maxSnippetChars: max_snippet_chars,
+            });
         }
-        const rawResults = searchIndexedChunks({
-            dbPath,
-            query,
-            dimensions,
-            queryVector: queryEmbedding.vector,
-            maxResults: max_results,
-            maxSnippetChars: max_snippet_chars,
-            mode,
-        });
         const relatedPaths = Array.from(new Set(rawResults.map((result) => result.path))).slice(0, Math.min(max_seed_files, max_related_files));
         const relatedFiles = readRelatedFileGraph({
             dbPath,
@@ -355,6 +448,8 @@ export function registerTools(server, config) {
             dbPath,
             dimensions,
             mode,
+            effectiveMode,
+            fallback,
             relatedDepth: related_depth,
             relatedSeedCount: relatedPaths.length,
             includeRelatedSnippets: include_related_snippets,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scythe-context-mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Local MCP context engine for Codex with Gemini Embedding 2 support.",
   "type": "module",
   "license": "Apache-2.0",