smart-context-mcp 1.13.0 → 1.15.0

package/README.md

@@ -56,7 +56,7 @@ Restart your AI client. Done.
 # Check installed version
 npm list -g smart-context-mcp
 
-# Should show: smart-context-mcp@1.13.0 (or later)
+# Should show: smart-context-mcp@1.15.0 (or later)
 
 # Update to latest version
 npm update -g smart-context-mcp

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "smart-context-mcp",
   "mcpName": "io.github.Arrayo/smart-context-mcp",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "MCP server that reduces agent token usage by 90% with intelligent context compression, task checkpoint persistence, and workflow-aware agent guidance.",
   "author": "Francisco Caballero Portero <fcp1978@hotmail.com>",
   "type": "module",
@@ -60,6 +60,7 @@
     "init:clients": "node ./scripts/init-clients.js",
     "smoke:formats": "node ./scripts/format-smoke.js",
     "test": "node --test --test-concurrency=1 ./tests/*.test.js",
+    "test:fast": "node --test --test-concurrency=4 ./tests/*.test.js",
     "verify": "node ./scripts/verify-features-direct.js",
     "benchmark": "node ./scripts/run-benchmark.js",
     "benchmark:orchestration": "node ./evals/orchestration-benchmark.js",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/Arrayo/smart-context-mcp",
     "source": "github"
   },
-  "version": "1.13.0",
+  "version": "1.15.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "smart-context-mcp",
-      "version": "1.13.0",
+      "version": "1.15.0",
       "transport": {
         "type": "stdio"
       },

package/src/server.js

@@ -146,18 +146,19 @@ export const createDevctxServer = () => {
 
   server.tool(
     'smart_search',
-    'Search code across the project using ripgrep (with filesystem fallback). Returns grouped, ranked results. Optional intent (implementation/debug/tests/config/docs/explore) adjusts ranking. Use instead of native Grep for ranked, deduplicated results with index boosting.',
+    'Search code with ranked, deduplicated results and index boosting. Best for: finding where a symbol is defined/used, understanding call chains, locating implementations. NOT ideal for: exact string matching (use Grep), finding files by name (use Glob), broad multi-word queries (generates noise). Optional intent adjusts ranking. maxFiles caps the number of files returned (default 15). When >30 files match, results include a hint suggesting Grep instead.',
     {
       query: z.string(),
       cwd: z.string().optional(),
       intent: z.enum(['implementation', 'debug', 'tests', 'config', 'docs', 'explore']).optional(),
+      maxFiles: z.number().int().min(1).max(50).optional(),
     },
-    async ({ query, cwd = '.', intent }) => asTextResult(await smartSearch({ query, cwd, intent })),
+    async ({ query, cwd = '.', intent, maxFiles }) => asTextResult(await smartSearch({ query, cwd, intent, maxFiles })),
   );
 
   server.tool(
     'smart_context',
-    'PREFERRED for multi-file tasks. Gets curated context in one call — replaces the manual search → read → read cycle. Combines search + graph expansion + selective reading. Returns relevant files with symbols and content, optimized for tokens. Options: intent, maxTokens (budget), diff (true for HEAD or branch name), detail (minimal/balanced/deep), include (content/graph/hints/symbolDetail), prefetch (true for predictive loading). Call this FIRST before individual smart_read/smart_search calls.',
+    'PREFERRED for multi-file tasks. Gets curated context in one call — replaces the manual search → read → read cycle. Combines search + graph expansion + selective reading. Primary files always include content (signatures) in balanced mode — reduces follow-up smart_read calls. Options: intent, maxTokens (budget, default 12000), diff (true for HEAD or branch name), detail (minimal/balanced/deep), include (content/graph/hints/symbolDetail), prefetch (true for predictive loading). Call this FIRST before individual smart_read/smart_search calls.',
     {
       task: z.string(),
       intent: z.enum(['implementation', 'debug', 'tests', 'config', 'docs', 'explore']).optional(),

package/src/tools/smart-context.js

@@ -196,9 +196,7 @@ export const allocateReads = (files, maxTokens, intent, detailMode = 'balanced')
 
     const mode = detailMode === 'deep'
       ? 'full'
-      : best.role === 'primary' && !tightBudget
-        ? 'outline'
-        : 'signatures';
+      : 'signatures';
 
     roleLimits[best.role]--;
     selected.push(best);
@@ -269,8 +267,7 @@ const shouldReadContentForItem = (item, payload, detailMode, includeSet, intent)
   const strongIndexSignal = hasStrongIndexSignal(payload);
 
   if (item.role === 'primary') {
-    if ((item.matchedSymbols?.length ?? 0) > 0) return false;
-    return !strongIndexSignal;
+    return true;
   }
 
   if (item.role === 'test' && intent === 'tests') {
@@ -353,7 +350,7 @@ const DEFAULT_INCLUDE = ['content', 'graph', 'hints', 'symbolDetail'];
 export const smartContext = async ({
   task,
   intent,
-  maxTokens = 8000,
+  maxTokens = 12000,
   entryFile,
   diff,
   detail = 'balanced',
@@ -518,7 +515,7 @@ export const smartContext = async ({
           primarySeeds.unshift({ rel, absPath: abs, evidence: [{ type: 'entryFile' }] });
         }
       }
-    } catch { /* invalid path — skip */ }
+    } catch (err) { process.stderr.write(`[devctx] smart_context: entryFile "${entryFile}" skipped: ${err.message}\n`); }
   }
 
   await ensureIndexReady({ root });
@@ -549,7 +546,7 @@ export const smartContext = async ({
                 });
               }
             }
-          } catch {}
+          } catch (err) { process.stderr.write(`[devctx] smart_context: prefetch path "${predicted.path}" skipped: ${err.message}\n`); }
         }
       }
     } catch (error) {
@@ -759,7 +756,7 @@ export const smartContext = async ({
           order: idx
         }))
       });
-    } catch {}
+    } catch (err) { process.stderr.write(`[devctx] smart_context: recordContextAccess failed: ${err.message}\n`); }
   }
 
   const COVERAGE_RANK = { full: 2, partial: 1, none: 0 };

package/src/tools/smart-search.js

@@ -324,16 +324,20 @@ const buildZeroResultsMessage = (query, searchMode, provenance) => {
   return lines.join('\n');
 };
 
-const buildCompactResult = (groups, totalMatches, query, root, searchMode, provenance) => {
+const MAX_RESULT_FILES = 15;
+
+const buildCompactResult = (groups, totalMatches, query, root, searchMode, provenance, totalFiles) => {
   if (totalMatches === 0) {
     return buildZeroResultsMessage(query, searchMode, provenance);
   }
 
   const modeLabel = searchMode === 'exact' ? '' : searchMode === 'regex' ? ' [regex fallback]' : ` [term expansion: ${(provenance?.expandedTerms ?? []).join(', ')}]`;
 
+  const topGroups = groups.slice(0, MAX_RESULT_FILES);
+
   if (totalMatches <= 20) {
     const header = modeLabel ? `# Search mode:${modeLabel}\n\n` : '';
-    return header + groups
+    return header + topGroups
       .flatMap((group) => group.matches)
       .map(formatMatch)
       .join('\n');
@@ -341,29 +345,34 @@ const buildCompactResult = (groups, totalMatches, query, root, searchMode, prove
 
   const lines = [
     `query: ${query}${modeLabel}`,
-    `root: ${root}`,
-    `total matches: ${totalMatches}`,
-    `matched files: ${groups.length}`,
+    `total: ${totalMatches} matches in ${totalFiles ?? groups.length} files${totalFiles && totalFiles > groups.length ? ` (showing top ${groups.length})` : ''}`,
     '',
     '# Top files',
   ];
 
-  for (const group of groups.slice(0, 10)) {
+  for (const group of topGroups.slice(0, 10)) {
     lines.push(`${group.count} match(es), score ${group.score} :: ${group.file}`);
   }
 
   lines.push('', '# Sample matches');
 
-  for (const group of groups.slice(0, 5)) {
-    for (const match of group.matches.slice(0, 3)) {
+  const topScore = topGroups[0]?.score ?? 0;
+  for (const group of topGroups.slice(0, 5)) {
+    const linesPerFile = group.score >= topScore * 0.7 ? 5 : 2;
+    for (const match of group.matches.slice(0, linesPerFile)) {
       lines.push(formatMatch(match));
     }
   }
 
+  const fileCount = totalFiles ?? groups.length;
+  if (fileCount > 30) {
+    lines.push('', `# Note: ${fileCount} files matched — query may be too broad. Use Grep for exact pattern matching.`);
+  }
+
   return lines.join('\n');
 };
 
-export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = false, progress: enableProgress = false }) => {
+export const smartSearch = async ({ query, cwd = '.', intent, maxFiles, _testForceWalk = false, progress: enableProgress = false }) => {
   const progress = enableProgress ? createProgressReporter('smart_search') : null;
   const startTime = Date.now();
   
@@ -463,8 +472,11 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
     }
   }
 
+  const effectiveMaxFiles = maxFiles ?? MAX_RESULT_FILES;
+  const cappedGroups = groups.slice(0, effectiveMaxFiles);
+
   const rawText = dedupedMatches.map(formatMatch).join('\n');
-  const compressedText = truncate(buildCompactResult(groups, dedupedMatches.length, query, root, searchMode, provenance), 5000);
+  const compressedText = truncate(buildCompactResult(cappedGroups, dedupedMatches.length, query, root, searchMode, provenance, groups.length), 5000);
   const metrics = buildMetrics({
     tool: 'smart_search',
     target: `${root} :: ${query}`,
@@ -522,7 +534,7 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
     ...(indexHits ? { indexBoosted: indexHits.size } : {}),
     totalMatches: dedupedMatches.length,
     matchedFiles: groups.length,
-    topFiles: groups.slice(0, 10).map((group) => ({ file: group.file, count: group.count, score: group.score })),
+    topFiles: cappedGroups.slice(0, 10).map((group) => ({ file: group.file, count: group.count, score: group.score })),
     matches: compressedText,
   };
 

package/src/utils/context-scoring.js

@@ -277,6 +277,7 @@ export const scorePrimarySeed = (seed, task, intent) => {
   let score = 0;
 
   for (const evidence of seed.evidence ?? []) {
+    if (evidence.type === 'entryFile') { score += 100; continue; }
     if (evidence.type !== 'searchHit') continue;
     score += Math.max(0, 40 - ((evidence.rank ?? 1) - 1) * 8);
     if (!evidence.query) continue;