@usewhisper/mcp-server 2.11.0 → 2.13.0

package/dist/server.js

@@ -3799,6 +3799,7 @@ var API_KEY = process.env.WHISPER_API_KEY || "";
 var DEFAULT_PROJECT = process.env.WHISPER_PROJECT || "";
 var BASE_URL = process.env.WHISPER_BASE_URL;
 var RUNTIME_MODE = (process.env.WHISPER_MCP_MODE || "remote").toLowerCase();
+var MCP_RETRIEVAL_PRECISION_V1_DEFAULT = /^true$/i.test(process.env.MCP_RETRIEVAL_PRECISION_V1_DEFAULT || "false");
 var CLI_ARGS = process.argv.slice(2);
 var IS_MANAGEMENT_ONLY = CLI_ARGS.includes("--print-tool-map") || CLI_ARGS[0] === "scope";
 function createWhisperMcpClient(options) {
@@ -3833,6 +3834,16 @@ var server = new McpServer({
 function createMcpServer() {
   return server;
 }
+var WORKSPACE_HEALTH_VALUES = ["unbound", "unindexed", "stale", "drifted", "healthy"];
+var RETRIEVAL_READINESS_VALUES = [
+  "no_project",
+  "project_unverified",
+  "project_bound_no_repo_source",
+  "project_repo_source_stale",
+  "project_repo_source_ready",
+  "local_fallback"
+];
+var RETRIEVAL_ROUTE_VALUES = ["project_repo", "local_workspace_fallback", "memory_only", "none"];
 var STATE_DIR = join(homedir(), ".whisper-mcp");
 var STATE_PATH = join(STATE_DIR, "state.json");
 var AUDIT_LOG_PATH = join(STATE_DIR, "forget-audit.log");
@@ -3874,6 +3885,75 @@ var ALIAS_TOOL_MAP = [
   { alias: "learn", target: "context.add_text | context.add_source | context.add_document" },
   { alias: "share_context", target: "context.share" }
 ];
+var MCP_RETRIEVAL_PROFILE_VALUES = ["legacy", "precision_v1"];
+var RECOMMENDED_NEXT_CALL_ALLOWLIST = /* @__PURE__ */ new Set([
+  "index.workspace_resolve",
+  "context.list_projects",
+  "index.workspace_status",
+  "index.workspace_run",
+  "search_code",
+  "grep",
+  "context.list_sources",
+  "context.add_source",
+  "index.local_scan_ingest",
+  "context.get_relevant"
+]);
+var UNTRUSTED_CODEBASE_HEALTH = /* @__PURE__ */ new Set(["unbound", "unindexed"]);
+var UNTRUSTED_CODEBASE_PROJECT_READINESS = /* @__PURE__ */ new Set([
+  "project_unverified",
+  "project_bound_no_repo_source"
+]);
+function sanitizeRecommendedNextCalls(nextCalls) {
+  return Array.from(
+    new Set(
+      nextCalls.map((entry) => String(entry || "").trim()).filter((entry) => RECOMMENDED_NEXT_CALL_ALLOWLIST.has(entry))
+    )
+  );
+}
+function getRepoReadinessNextCalls(readiness) {
+  if (readiness !== "project_bound_no_repo_source" && readiness !== "project_unverified") {
+    return [];
+  }
+  if (RUNTIME_MODE === "remote") {
+    return sanitizeRecommendedNextCalls([
+      "context.list_sources",
+      "context.add_source",
+      "index.workspace_status",
+      "context.get_relevant"
+    ]);
+  }
+  return sanitizeRecommendedNextCalls([
+    "context.list_sources",
+    "index.local_scan_ingest",
+    "index.workspace_status",
+    "context.get_relevant"
+  ]);
+}
+function resolveMcpRetrievalProfile(requested) {
+  if (requested && MCP_RETRIEVAL_PROFILE_VALUES.includes(requested)) {
+    return requested;
+  }
+  return MCP_RETRIEVAL_PRECISION_V1_DEFAULT ? "precision_v1" : "legacy";
+}
+function shouldAbstainForCodebaseTrust(args) {
+  if (args.retrievalProfile !== "precision_v1" || !args.codebaseIntent) return false;
+  return UNTRUSTED_CODEBASE_HEALTH.has(args.preflight.trust_state.health) || UNTRUSTED_CODEBASE_PROJECT_READINESS.has(args.preflight.project_retrieval_readiness);
+}
+function buildCodebaseTrustAbstainPayload(args) {
+  return {
+    status: "abstained",
+    reason: "stale_index",
+    message: args.preflight.warnings[0] || "Codebase retrieval is not trusted yet for this workspace/project. Resolve index trust before answering.",
+    query: args.query,
+    trust_state: args.preflight.trust_state,
+    retrieval_readiness: args.preflight.retrieval_readiness,
+    project_retrieval_readiness: args.preflight.project_retrieval_readiness,
+    retrieval_route: args.preflight.retrieval_route,
+    retrieval_profile: args.retrievalProfile,
+    warnings: args.preflight.warnings,
+    recommended_next_calls: sanitizeRecommendedNextCalls(args.preflight.recommended_next_calls)
+  };
+}
 function ensureStateDir() {
   if (!existsSync(STATE_DIR)) {
     mkdirSync(STATE_DIR, { recursive: true });
@@ -4044,16 +4124,25 @@ function classifyProjectRepoReadiness(args) {
 function classifyRepoGroundedQuery(args) {
   const query = args.query.toLowerCase();
   let score = 0;
-  if (/(^|[\s"'])where is\b|which file|what file|show me|wiring|handler|middleware|implementation|route|endpoint|function|class|module|repo|workspace|code/.test(query)) {
+  if (/(^|[\s"'])where is\b|which file|what file|show me|wiring|handler|middleware|implementation|route|endpoint|function|class|module|repo|workspace|code|project/.test(query)) {
     score += 1;
   }
   if (/\bauth\b|\burl\b|\bcookie\b|\bsession\b|\bapi\b/.test(query)) {
     score += 1;
   }
+  if (/\berror\b|\berrors\b|\bexception\b|\bexceptions\b/.test(query)) {
+    score += 1;
+  }
+  if (/\bretry\b/.test(query)) {
+    score += 1;
+  }
+  if (/\bflow\b|\blogic\b|\bstack\b|\btrace\b|\blogging\b|\bfailure\b|\bfailures\b|\bthrow\b|\bcatch\b|\bdebug\b/.test(query)) {
+    score += 1;
+  }
   if (/[A-Za-z0-9/_-]+\.[A-Za-z0-9]+/.test(args.query) || /\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]{2,}/.test(args.query)) {
     score += 2;
   }
-  if (/[A-Za-z_$][A-Za-z0-9_$-]*\(/.test(args.query) || /[A-Z][A-Za-z0-9]+/.test(args.query)) {
+  if (/[A-Za-z_$][A-Za-z0-9_$-]*\(/.test(args.query) || /\b[A-Z][a-z0-9]+[A-Z][A-Za-z0-9]*\b/.test(args.query)) {
     score += 1;
   }
   if ((args.chunk_types || []).some((chunkType) => ["code", "function", "class", "config", "schema", "api_spec"].includes(chunkType))) {
@@ -4181,9 +4270,9 @@ async function resolveProjectDescriptor(projectRef) {
   }
 }
 function getWorkspaceRecommendedNextCalls(health) {
-  if (health === "unbound") return ["index.workspace_resolve", "context.list_projects", "index.workspace_status"];
-  if (health === "unindexed") return ["index.workspace_status", "index.workspace_run", "search_code", "grep"];
-  if (health === "stale" || health === "drifted") return ["index.workspace_status", "index.workspace_run", "grep", "search_code"];
+  if (health === "unbound") return sanitizeRecommendedNextCalls(["index.workspace_resolve", "context.list_projects", "index.workspace_status"]);
+  if (health === "unindexed") return sanitizeRecommendedNextCalls(["index.workspace_status", "index.workspace_run", "search_code", "grep"]);
+  if (health === "stale" || health === "drifted") return sanitizeRecommendedNextCalls(["index.workspace_status", "index.workspace_run", "grep", "search_code"]);
   return [];
 }
 function getWorkspaceWarnings(args) {
@@ -4380,17 +4469,18 @@ async function resolveRepoGroundingPreflight(args) {
   }
   const recommendedNextCalls = [...trust.recommended_next_calls];
   if (sourceVerification.retrieval_readiness === "project_bound_no_repo_source" || sourceVerification.retrieval_readiness === "project_unverified") {
-    recommendedNextCalls.push("context.list_sources", "index.local_scan_ingest");
+    recommendedNextCalls.push(...getRepoReadinessNextCalls(sourceVerification.retrieval_readiness));
   }
   return {
     repo_grounded: repoGrounded,
     trust_state: trust,
+    project_retrieval_readiness: sourceVerification.retrieval_readiness,
     retrieval_readiness: retrievalReadiness,
     retrieval_route: retrievalRoute,
     matched_sources: sourceVerification.matched_sources,
     matched_source_ids: sourceVerification.matched_source_ids,
     warnings: Array.from(new Set(warnings)),
-    recommended_next_calls: Array.from(new Set(recommendedNextCalls))
+    recommended_next_calls: sanitizeRecommendedNextCalls(recommendedNextCalls)
   };
 }
 async function ingestSessionWithSyncFallback(params) {
@@ -4485,7 +4575,9 @@ function buildAbstain(args) {
     closest_evidence: args.closest_evidence,
     warnings: args.warnings || [],
     trust_state: args.trust_state,
-    recommended_next_calls: args.recommended_next_calls || ["index.workspace_status", "index.workspace_run", "grep", "context.get_relevant"],
+    recommended_next_calls: sanitizeRecommendedNextCalls(
+      args.recommended_next_calls || ["index.workspace_status", "index.workspace_run", "grep", "context.get_relevant"]
+    ),
     diagnostics: {
       claims_evaluated: args.claims_evaluated,
       evidence_items_found: args.evidence_items_found,
@@ -4656,6 +4748,8 @@ async function queryWithDegradedFallback(params) {
       user_id: params.user_id,
       session_id: params.session_id,
       source_ids: params.source_ids,
+      retrieval_profile: params.retrieval_profile,
+      include_parent_content: params.include_parent_content,
       hybrid: true,
       rerank: true
     });
@@ -4671,6 +4765,8 @@ async function queryWithDegradedFallback(params) {
       user_id: params.user_id,
       session_id: params.session_id,
       source_ids: params.source_ids,
+      retrieval_profile: params.retrieval_profile,
+      include_parent_content: params.include_parent_content,
       hybrid: false,
       rerank: false,
       vector_weight: 0,
@@ -5033,7 +5129,9 @@ function saveIngestManifest(manifest) {
 }
 async function ingestLocalPath(params) {
   if (RUNTIME_MODE === "remote") {
-    throw new Error("Local ingestion is disabled in remote mode. Set WHISPER_MCP_MODE=auto or local.");
+    throw new Error(
+      "Local ingestion is disabled in remote mode. Use context.add_source for remote projects, or run MCP with WHISPER_MCP_MODE=auto/local."
+    );
   }
   const rootPath = params.path || process.cwd();
   const gate = isPathAllowed(rootPath);
@@ -5311,12 +5409,10 @@ server.tool(
         health: trust.health,
         retrieval_readiness: repoVerification.retrieval_readiness,
         warnings: Array.from(/* @__PURE__ */ new Set([...trust.warnings, ...repoVerification.warnings])),
-        recommended_next_calls: Array.from(
-          /* @__PURE__ */ new Set([
-            ...trust.recommended_next_calls,
-            ...repoVerification.retrieval_readiness === "project_bound_no_repo_source" ? ["context.list_sources", "index.local_scan_ingest"] : []
-          ])
-        ),
+        recommended_next_calls: sanitizeRecommendedNextCalls([
+          ...trust.recommended_next_calls,
+          ...getRepoReadinessNextCalls(repoVerification.retrieval_readiness)
+        ]),
         freshness: trust.freshness,
         coverage: trust.coverage,
         last_indexed_commit: trust.last_indexed_commit,
@@ -5332,7 +5428,7 @@ server.tool(
 );
 server.tool(
   "index.workspace_run",
-  "Index workspace in full or incremental mode and update index metadata for freshness checks.",
+  "Refresh local workspace index metadata (coverage, commit, freshness) for trust checks. This does not upload files or create backend embeddings.",
   {
     workspace_id: z.string().optional(),
     path: z.string().optional(),
@@ -5374,7 +5470,7 @@ server.tool(
 );
 server.tool(
   "index.local_scan_ingest",
-  "Scan a local folder safely (allowlist + secret filters), ingest changed files, and persist incremental manifest.",
+  "Ingest local files into Whisper backend (chunk/embed/index) and persist incremental manifest. Requires WHISPER_MCP_MODE=auto or local.",
   {
     project: z.string().optional().describe("Project name or slug"),
     path: z.string().optional().describe("Local path to ingest. Defaults to current working directory."),
@@ -5410,7 +5506,7 @@ server.tool(
 );
 server.tool(
   "context.get_relevant",
-  "Default grounded retrieval step for workspace/project questions. Call this before answering when you need ranked evidence with file:line citations instead of relying on model memory.",
+  "Default grounded retrieval step for workspace/project questions. Returns ranked evidence with file:line citations and may abstain when workspace/repo trust is not ready.",
   {
     question: z.string().describe("Task/question to retrieve context for"),
     path: z.string().optional().describe("Workspace path. Defaults to current working directory."),
@@ -5420,11 +5516,25 @@ server.tool(
     include_memories: z.boolean().optional().default(true),
     include_graph: z.boolean().optional().default(true),
     session_id: z.string().optional(),
-    user_id: z.string().optional()
+    user_id: z.string().optional(),
+    include_parent_content: z.boolean().optional().default(false),
+    retrieval_profile: z.enum(MCP_RETRIEVAL_PROFILE_VALUES).optional()
   },
-  async ({ question, path, workspace_id, project, top_k, include_memories, include_graph, session_id, user_id }) => {
+  async ({ question, path, workspace_id, project, top_k, include_memories, include_graph, session_id, user_id, include_parent_content, retrieval_profile }) => {
     try {
       const preflight = await resolveRepoGroundingPreflight({ query: question, path, workspace_id, project });
+      const retrievalProfile = resolveMcpRetrievalProfile(retrieval_profile);
+      if (shouldAbstainForCodebaseTrust({
+        retrievalProfile,
+        codebaseIntent: preflight.repo_grounded,
+        preflight
+      })) {
+        return toTextResult(buildCodebaseTrustAbstainPayload({
+          query: question,
+          preflight,
+          retrievalProfile
+        }));
+      }
       if (preflight.retrieval_route === "local_workspace_fallback") {
         const localRetrieval = await runLocalWorkspaceRetrieval({
           query: question,
@@ -5480,7 +5590,9 @@ server.tool(
         include_graph,
         session_id,
         user_id,
-        source_ids: preflight.repo_grounded ? preflight.matched_source_ids : void 0
+        source_ids: preflight.repo_grounded ? preflight.matched_source_ids : void 0,
+        retrieval_profile: retrievalProfile,
+        include_parent_content
       });
       const response = queryResult.response;
       const rawResults = preflight.repo_grounded ? filterProjectRepoResults(response.results || [], preflight.matched_source_ids) : response.results || [];
@@ -5741,7 +5853,7 @@ server.tool(
 );
 server.tool(
   "context.query",
-  "Use this when answering from project knowledge rather than general model memory. Retrieves packed context for a query using hybrid vector+keyword search with optional memory/graph expansion.",
+  "Use this when answering from project knowledge rather than general model memory. Retrieves packed context and auto-falls back between repo, local, and memory routes based on trust/readiness.",
   {
     project: z.string().optional().describe("Project name or slug (optional if WHISPER_PROJECT is set)"),
     query: z.string().describe("What are you looking for?"),
@@ -5752,11 +5864,25 @@ server.tool(
     include_graph: z.boolean().optional().default(false).describe("Include knowledge graph traversal"),
     user_id: z.string().optional().describe("User ID for memory scoping"),
     session_id: z.string().optional().describe("Session ID for memory scoping"),
-    max_tokens: z.number().optional().describe("Max tokens for packed context")
+    max_tokens: z.number().optional().describe("Max tokens for packed context"),
+    include_parent_content: z.boolean().optional().default(false),
+    retrieval_profile: z.enum(MCP_RETRIEVAL_PROFILE_VALUES).optional()
   },
-  async ({ project, query, path, top_k, chunk_types, include_memories, include_graph, user_id, session_id, max_tokens }) => {
+  async ({ project, query, path, top_k, chunk_types, include_memories, include_graph, user_id, session_id, max_tokens, include_parent_content, retrieval_profile }) => {
     try {
       const preflight = await resolveRepoGroundingPreflight({ query, path, project, chunk_types });
+      const retrievalProfile = resolveMcpRetrievalProfile(retrieval_profile);
+      if (shouldAbstainForCodebaseTrust({
+        retrievalProfile,
+        codebaseIntent: preflight.repo_grounded,
+        preflight
+      })) {
+        return toTextResult(buildCodebaseTrustAbstainPayload({
+          query,
+          preflight,
+          retrievalProfile
+        }));
+      }
       const resolvedProject = preflight.trust_state.project_ref || await resolveProjectRef(project);
       if (!resolvedProject && !preflight.repo_grounded) {
         return { content: [{ type: "text", text: "Error: No project resolved. Set WHISPER_PROJECT or pass project." }] };
@@ -5795,7 +5921,9 @@ server.tool(
           include_graph,
           user_id: user_id || scope.userId,
           session_id: session_id || scope.sessionId,
-          source_ids: preflight.matched_source_ids
+          source_ids: preflight.matched_source_ids,
+          retrieval_profile: retrievalProfile,
+          include_parent_content
         });
         const repoResults = filterProjectRepoResults(queryResult2.response.results || [], preflight.matched_source_ids);
         if (repoResults.length > 0) {
@@ -5867,8 +5995,8 @@ workspace=${preflight.trust_state.workspace_id} identity_source=${preflight.trus
             const memoryRescue = include_memories !== false ? await runContextQueryMemoryRescue({
               project: resolvedProject,
               query,
-              user_id: user_id ? scope2.userId : void 0,
-              session_id: session_id ? scope2.sessionId : void 0,
+              user_id: user_id ? scope.userId : void 0,
+              session_id: session_id ? scope.sessionId : void 0,
               top_k
             }) : { results: [], rescue_mode: null };
             if (memoryRescue.results.length && memoryRescue.rescue_mode) {
@@ -5878,7 +6006,7 @@ workspace=${preflight.trust_state.workspace_id} identity_source=${preflight.trus
                   text: renderContextQueryMemoryRescue({
                     project: resolvedProject,
                     query,
-                    scope: scope2,
+                    scope,
                     results: memoryRescue.results,
                     rescue_mode: memoryRescue.rescue_mode
                   })
@@ -5897,11 +6025,11 @@ ${prepared.retrieval.warnings.join("\n")}` : "";
             `deduped=${prepared.retrieval.dedupedCount}`,
             `dropped_below_floor=${prepared.retrieval.droppedBelowFloor}`
           ].join(" ");
-          const scope2 = `project=${prepared.scope.project} user=${prepared.scope.userId} session=${prepared.scope.sessionId}`;
+          const scopeLabel = `project=${prepared.scope.project} user=${prepared.scope.userId} session=${prepared.scope.sessionId}`;
           return {
             content: [{
               type: "text",
-              text: `Found ${prepared.items.length} runtime-ranked items (${prepared.retrieval.durationMs}ms, ${scope2}, ${diagnostics}):
+              text: `Found ${prepared.items.length} runtime-ranked items (${prepared.retrieval.durationMs}ms, ${scopeLabel}, ${diagnostics}):
 
 ${prepared.context}${warnings}`
             }]
@@ -5915,7 +6043,9 @@ ${prepared.context}${warnings}`
             include_memories: include_memories === true,
             include_graph,
             user_id: user_id || scope.userId,
-            session_id: session_id || scope.sessionId
+            session_id: session_id || scope.sessionId,
+            retrieval_profile: retrievalProfile,
+            include_parent_content
           });
           const response2 = queryResult2.response;
           if (response2.results.length === 0) {
@@ -5968,7 +6098,9 @@ ${automaticWarning}${suffix2}` }] };
         include_memories: include_memories === true,
         include_graph,
         user_id: user_id || scope.userId,
-        session_id: session_id || scope.sessionId
+        session_id: session_id || scope.sessionId,
+        retrieval_profile: retrievalProfile,
+        include_parent_content
       });
       const response = queryResult.response;
       if (response.results.length === 0) {
@@ -7861,6 +7993,10 @@ if (process.argv[1] && /server\.(mjs|cjs|js|ts)$/.test(process.argv[1])) {
   main().catch(console.error);
 }
 export {
+  RECOMMENDED_NEXT_CALL_ALLOWLIST,
+  RETRIEVAL_READINESS_VALUES,
+  RETRIEVAL_ROUTE_VALUES,
+  WORKSPACE_HEALTH_VALUES,
   canonicalizeWorkspacePath,
   chooseWorkspaceProjectSource,
   classifyProjectRepoReadiness,
@@ -7873,5 +8009,7 @@ export {
   renderScopedMcpConfig,
   resolveForgetQueryCandidates,
   resolveWorkspaceIdentity,
-  runSearchCodeSearch
+  runSearchCodeSearch,
+  sanitizeRecommendedNextCalls,
+  shouldAbstainForCodebaseTrust
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usewhisper/mcp-server",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "whisperContractVersion": "2026.03.10",
   "scripts": {
     "build": "tsup ../src/mcp/server.ts --format esm --out-dir dist",