smart-context-mcp 1.10.0 → 1.11.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.10.0 (or later)
+# Should show: smart-context-mcp@1.11.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.10.0",
+  "version": "1.11.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",

package/scripts/init-clients.js

@@ -461,11 +461,9 @@ const updateCursorRule = (targetDir, dryRun) => {
   const rulesDir = path.join(targetDir, '.cursor', 'rules');
   const profilesDir = path.join(rulesDir, 'profiles-compact');
   
-  // Write base rule (always active)
   const baseFilePath = path.join(rulesDir, 'devctx.mdc');
   writeFile(baseFilePath, cursorRuleContent, dryRun);
-  
-  // Write profiles README
+
   const profilesReadmePath = path.join(profilesDir, 'README.md');
   writeFile(profilesReadmePath, cursorProfilesNote, dryRun);
   

package/scripts/report-adoption-metrics.js

@@ -73,7 +73,6 @@ const calculateAdoptionMetrics = (days = 30) => {
   return withStateDb((db) => {
     const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
 
-    // Get all sessions since cutoff
     const sessions = db
       .prepare(
         `
@@ -94,7 +93,6 @@ const calculateAdoptionMetrics = (days = 30) => {
       toolUsage: {},
     };
 
-    // Initialize workflow stats
     Object.keys(WORKFLOW_DEFINITIONS).forEach((type) => {
       results.byWorkflow[type] = {
         total: 0,
@@ -103,12 +101,10 @@ const calculateAdoptionMetrics = (days = 30) => {
       };
     });
 
-    // Analyze each session
     sessions.forEach((session) => {
       const snapshot = JSON.parse(session.snapshot_json || '{}');
       const sessionId = session.session_id;
 
-      // Get events for this session
       const sessionEvents = db
         .prepare('SELECT * FROM session_events WHERE session_id = ?')
         .all(sessionId);
@@ -117,25 +113,21 @@ const calculateAdoptionMetrics = (days = 30) => {
         .prepare('SELECT * FROM metrics_events WHERE session_id = ?')
         .all(sessionId);
 
-      // Check if non-trivial
       if (!isNonTrivialTask(sessionEvents, metricsEvents)) {
         return;
       }
 
       results.nonTrivialTasks++;
 
-      // Check if used devctx
       const hasDevctx = usedDevctx(metricsEvents);
       if (hasDevctx) {
         results.tasksWithDevctx++;
       }
 
-      // Track tool usage
       metricsEvents.forEach((m) => {
         results.toolUsage[m.tool] = (results.toolUsage[m.tool] || 0) + 1;
       });
 
-      // Classify by workflow if possible
       const goal = snapshot.goal || '';
       let workflowType = null;
 
@@ -154,7 +146,6 @@ const calculateAdoptionMetrics = (days = 30) => {
       }
     });
 
-    // Calculate rates
     if (results.nonTrivialTasks > 0) {
       results.adoptionRate = (results.tasksWithDevctx / results.nonTrivialTasks) * 100;
     }

package/scripts/report-workflow-metrics.js

@@ -171,7 +171,6 @@ const printSummary = (summary) => {
   console.log('─'.repeat(120));
   console.log('');
 
-  // Show detailed breakdown for each workflow type
   console.log('Detailed Breakdown:');
   console.log('');
 

package/server.json

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

package/src/index.js

@@ -726,9 +726,7 @@ export const buildIndex = (root, progress = null) => {
         if (sym.snippet) entry.snippet = sym.snippet;
         invertedIndex[key].push(entry);
       }
-    } catch {
-      // skip unreadable files
-    }
+    } catch { /* unreadable */ }
 
     processed++;
     

package/src/missed-opportunities.js

@@ -141,7 +141,6 @@ export const formatMissedOpportunities = () => {
   lines.push('⚠️ **Missed devctx opportunities detected:**');
   lines.push('');
   
-  // Show session stats
   lines.push(`**Session stats:**`);
   lines.push(`- Duration: ${analysis.sessionDuration}s`);
   lines.push(`- devctx operations: ${analysis.devctxOperations}`);

package/src/server.js

@@ -57,10 +57,8 @@ export const createDevctxServer = () => {
     version,
   });
 
-  // Enable streaming progress notifications
   setServerForStreaming(server);
 
-  // Register prompts
   server.prompt(
     'use-devctx',
     'Force the agent to use devctx tools for the current task. Use this prompt at the start of your message to ensure devctx is used instead of native tools.',
@@ -128,7 +126,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_read',
-    'Read a file with token-efficient modes. outline/signatures: compact structure (~90% savings). range: specific line range with line numbers. symbol: extract function/class/method by name (string or array for batch). full: file content capped at 12k chars. maxTokens: token budget — auto-selects the most detailed mode that fits (full -> outline -> signatures -> truncated). context=true (symbol mode only): includes callers, tests, and referenced types from the dependency graph; returns graphCoverage (imports/tests: full|partial|none) so the agent knows how reliable the cross-file context is. Responses are cached in memory per session and invalidated by file mtime; cached=true when served from cache. Every response includes a unified confidence block: { parser, truncated, cached, graphCoverage? }. Supports JS/TS, Python, Go, Rust, Java, C#, Kotlin, PHP, Swift, shell, Terraform, Dockerfile, SQL, JSON, TOML, YAML.',
+    'Read a file with token-efficient modes. PREFER outline/signatures/symbol — full mode saves 0 tokens (same content as native Read, capped at 12k chars). Mode guide: outline (~90% savings): file structure, exports, top-level symbols — use for orientation, code review, deciding what to read next. signatures (~85% savings): function/method signatures only — use when you need parameter names and return types without bodies. symbol: extract one or more functions/classes/methods by name (string or array for batch) — use when you know exactly what to read; add context=true to include callers, tests, and referenced types from the dependency graph (returns graphCoverage: full|partial|none). range: specific line range with line numbers — use only when you need exact lines. full: raw file content, no compression, no savings — only use when the exact byte-for-byte content is required (e.g. config files, lock files). maxTokens: token budget — auto-selects the most detailed mode that fits (full → outline → signatures → truncated). Responses are cached in memory per session and invalidated by file mtime; cached=true when served from cache. Every response includes a unified confidence block: { parser, truncated, cached, graphCoverage? }. Supports JS/TS, Python, Go, Rust, Java, C#, Kotlin, PHP, Swift, shell, Terraform, Dockerfile, SQL, JSON, TOML, YAML.',
     {
       filePath: z.string(),
       mode: z.enum(['full', 'outline', 'signatures', 'range', 'symbol']).optional(),
@@ -144,7 +142,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_read_batch',
-    'Read multiple files in one call. Each item accepts path, mode, symbol, startLine, endLine, maxTokens (per-file budget). Optional global maxTokens budget with early stop when exceeded. Max 20 files per call.',
+    'Read multiple files in one call. Each item accepts path, mode (prefer outline/signatures/symbol — full saves 0 tokens), symbol, startLine, endLine, maxTokens (per-file budget). Optional global maxTokens budget with early stop when exceeded. Max 20 files per call.',
     {
       files: z.array(z.object({
         path: z.string(),
@@ -190,7 +188,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_shell',
-    'Run a diagnostic shell command from an allowlist. Allowed: pwd, ls, find, rg, git (status/diff/show/log/branch/rev-parse), npm/pnpm/yarn/bun (test/run/lint/build/typecheck/check). Blocks shell operators, pipes, and unsafe commands. Includes a unified confidence block: { blocked, timedOut }.',
+    'Run a diagnostic shell command from an allowlist. Allowed: pwd, ls, find, rg, git (status/diff/show/log/branch/rev-parse), npm/pnpm/yarn/bun (test/run/lint/build/typecheck/check). Blocks shell operators, pipes, and unsafe commands. For large diffs: output is split by file (up to 8 files, 60 lines each) with a hint to run git show -- <file> for the full body of any truncated file; prefer git diff --stat first to see which files changed, then git show -- <file> per file for targeted reading. Includes a unified confidence block: { blocked, timedOut }.',
     {
       command: z.string(),
     },
@@ -487,7 +485,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_turn',
-    'Orchestrate start/end of a meaningful agent turn so context usage becomes almost mandatory with low token overhead. `phase: "start"` rehydrates persisted context, classifies prompt continuity against the saved session, optionally auto-creates a planning session for a new substantial task, returns `recommendedPath` guidance for the next safe devctx actions, and can include compact metrics. `phase: "end"` writes a checkpoint through smart_summary, returns follow-up `recommendedPath` guidance, and can optionally include compact metrics. Both phases expose `mutationSafety` when repo-safety blocks persisted writes and now surface `storageHealth` when SQLite state is missing, oversized, locked, or corrupted. Use this instead of manually chaining `smart_summary(get)` and `smart_summary(checkpoint)` when you want a single context-first turn workflow.',
+    'Orchestrate start/end of a meaningful agent turn for multi-session tasks where context continuity matters. SKIP for single-session point-in-time tasks (reviewing a specific commit, answering a quick question, one-off lookup) — the setup overhead exceeds the benefit if the session will never be resumed. USE when: the task spans multiple chat sessions, you may return to it the next day, or the codebase context is large enough that re-reading is expensive. `phase: "start"` rehydrates persisted context, classifies prompt continuity against the saved session, optionally auto-creates a planning session for a new substantial task, returns `recommendedPath` guidance for the next safe devctx actions, and can include compact metrics. `phase: "end"` writes a checkpoint through smart_summary, returns follow-up `recommendedPath` guidance, and can optionally include compact metrics. Both phases expose `mutationSafety` when repo-safety blocks persisted writes and surface `storageHealth` when SQLite state is missing, oversized, locked, or corrupted.',
     {
       phase: z.enum(['start', 'end']),
       sessionId: z.string().optional(),

package/src/tools/smart-context.js

@@ -412,17 +412,11 @@ export const smartContext = async ({
     
     await ensureIndexReady({ root });
     
-    // Get detailed diff stats
     const detailedChanges = await getDetailedDiff(changed.ref, root);
     const index = loadIndex(root);
-    
-    // Analyze impact and prioritize
     const prioritized = analyzeChangeImpact(detailedChanges, index);
-    
-    // Expand to include related files (importers, dependencies, tests)
     const expandedFiles = expandChangedContext(changed.files, index, 10);
-    
-    // Build primary seeds with priority and impact data
+
     primarySeeds = Array.from(expandedFiles).map(rel => {
       const changeInfo = prioritized.find(c => c.file === rel);
       const evidence = [{ 
@@ -432,7 +426,6 @@ export const smartContext = async ({
         impact: changeInfo?.impactScore || 0,
       }];
       
-      // Mark files that were expanded (not directly changed)
       if (!changed.files.includes(rel)) {
         evidence[0].expanded = true;
       }
@@ -444,7 +437,6 @@ export const smartContext = async ({
       };
     });
     
-    // Sort by impact (critical changes first)
     primarySeeds.sort((a, b) => {
       const impactA = a.evidence[0].impact || 0;
       const impactB = b.evidence[0].impact || 0;
@@ -771,17 +763,13 @@ export const smartContext = async ({
     timestamp: new Date().toISOString(),
   });
   
-  // Record usage for feedback
   recordToolUsage({
     tool: 'smart_context',
     savedTokens,
     target: task,
   });
-  
-  // Record devctx operation for missed opportunity detection
   recordDevctxOperation();
-  
-  // Record decision explanation
+
   let reason = DECISION_REASONS.TASK_CONTEXT;
   if (diff) {
     reason = DECISION_REASONS.DIFF_ANALYSIS;

package/src/tools/smart-read.js

@@ -536,17 +536,12 @@ export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine
 
   await persistMetrics(metrics);
   
-  // Record usage for feedback
   recordToolUsage({
     tool: 'smart_read',
     savedTokens: metrics.savedTokens,
     target: path.relative(effectiveRoot, fullPath),
   });
-  
-  // Record devctx operation for missed opportunity detection
   recordDevctxOperation();
-  
-  // Record decision explanation
   const lineCount = content.split('\n').length;
   let reason = DECISION_REASONS.LARGE_FILE;
   let expectedBenefit = EXPECTED_BENEFITS.TOKEN_SAVINGS(metrics.savedTokens);

package/src/tools/smart-search.js

@@ -475,17 +475,13 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
 
   await persistMetrics(metrics);
   
-  // Record usage for feedback
   recordToolUsage({
     tool: 'smart_search',
     savedTokens: metrics.savedTokens,
     target: query,
   });
-  
-  // Record devctx operation for missed opportunity detection
   recordDevctxOperation();
-  
-  // Record decision explanation
+
   let reason = DECISION_REASONS.MULTIPLE_FILES;
   if (validIntent) {
     reason = DECISION_REASONS.INTENT_AWARE;

package/src/tools/smart-shell.js

@@ -176,6 +176,52 @@ const validateCommand = (command, tokens) => {
   return null;
 };
 
+const DIFF_FILE_HEADER = /^diff --git a\/.+ b\/.+/;
+const DIFF_HUNK_HEADER = /^@@ /;
+const MAX_DIFF_FILES = 8;
+const MAX_LINES_PER_FILE = 60;
+const DIFF_TOTAL_LIMIT = 4000;
+
+const splitDiffByFile = (text) => {
+  const files = [];
+  let current = null;
+
+  for (const line of text.split('\n')) {
+    if (DIFF_FILE_HEADER.test(line)) {
+      if (current) files.push(current);
+      current = { header: line, lines: [] };
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  if (current) files.push(current);
+  return files;
+};
+
+const compressDiff = (text) => {
+  if (!DIFF_FILE_HEADER.test(text)) return text;
+
+  const files = splitDiffByFile(text);
+  if (files.length === 0) return text;
+
+  const shown = files.slice(0, MAX_DIFF_FILES);
+  const skipped = files.length - shown.length;
+
+  const parts = shown.map(({ header, lines }) => {
+    const truncatedLines = lines.slice(0, MAX_LINES_PER_FILE);
+    const skippedLines = lines.length - truncatedLines.length;
+    const hunkCount = lines.filter((l) => DIFF_HUNK_HEADER.test(l)).length;
+    const suffix = skippedLines > 0 ? [`... (${skippedLines} more lines — use smart_read(symbol) for full body)`] : [];
+    return [header, `# ${hunkCount} hunk(s)`, ...truncatedLines, ...suffix].join('\n');
+  });
+
+  const footer = skipped > 0
+    ? `\n# ${skipped} more file(s) not shown — run git show -- <file> for each`
+    : '';
+
+  return truncate(parts.join('\n\n'), DIFF_TOTAL_LIMIT) + footer;
+};
+
 const buildBlockedResult = async (command, message) => {
   const metrics = buildMetrics({
     tool: 'smart_shell',
@@ -254,7 +300,7 @@ export const smartShell = async ({ command }) => {
   ]);
   const shouldPrioritizeRelevant = execution.code !== 0 || execution.timedOut;
   const compressedSource = shouldPrioritizeRelevant && relevant ? relevant : rawText;
-  const compressedText = truncate(uniqueLines(compressedSource), 5000);
+  const compressedText = truncate(compressDiff(uniqueLines(compressedSource)), 5000);
   const metrics = buildMetrics({
     tool: 'smart_shell',
     target: command,
@@ -264,17 +310,12 @@ export const smartShell = async ({ command }) => {
 
   await persistMetrics(metrics);
   
-  // Record usage for feedback
   recordToolUsage({
     tool: 'smart_shell',
     savedTokens: metrics.savedTokens,
     target: command,
   });
-  
-  // Record devctx operation for missed opportunity detection
   recordDevctxOperation();
-  
-  // Record decision explanation
   const outputLines = rawText.split('\n').length;
   let reason = DECISION_REASONS.COMMAND_OUTPUT;
   if (shouldPrioritizeRelevant && relevant) {

package/src/usage-feedback.js

@@ -60,7 +60,6 @@ export const formatUsageFeedback = () => {
   lines.push('');
   lines.push('📊 **devctx usage this session:**');
   
-  // Sort by count descending
   const sorted = usage.tools.sort((a, b) => b.count - a.count);
   
   for (const { tool, count, savedTokens, targets } of sorted) {

package/src/workflow-tracker.js

@@ -183,7 +183,6 @@ export const endWorkflow = (workflowId) => {
         return null;
       }
 
-    // Get workflow start time and session
     const workflow = db
       .prepare(
         `
@@ -203,7 +202,6 @@ export const endWorkflow = (workflowId) => {
     const endTime = new Date(now);
     const durationMs = endTime - startTime;
 
-    // Get all metrics for this session since workflow start
     const metrics = db
       .prepare(
         `
@@ -215,7 +213,6 @@ export const endWorkflow = (workflowId) => {
       )
       .all(workflow.session_id, workflow.start_time);
 
-    // Calculate totals
     const rawTokens = metrics.reduce((sum, m) => sum + (m.raw_tokens || 0), 0);
     const compressedTokens = metrics.reduce((sum, m) => sum + (m.compressed_tokens || 0), 0);
     const savedTokens = metrics.reduce((sum, m) => sum + (m.saved_tokens || 0), 0);
@@ -231,7 +228,6 @@ export const endWorkflow = (workflowId) => {
     const savingsPct = rawTokens > 0 ? ((savedTokens / rawTokens) * 100).toFixed(2) : 0;
     const netSavingsPct = rawTokens > 0 ? ((netSavedTokens / rawTokens) * 100).toFixed(2) : 0;
 
-    // Calculate vs baseline
     const baselineTokens = workflow.baseline_tokens || 0;
     const vsBaselinePct = baselineTokens > 0 ? (((baselineTokens - compressedTokens) / baselineTokens) * 100).toFixed(2) : 0;
     const vsBaselineNetPct = baselineTokens > 0 ? (((baselineTokens - (compressedTokens + overheadTokens)) / baselineTokens) * 100).toFixed(2) : 0;
@@ -247,10 +243,7 @@ export const endWorkflow = (workflowId) => {
       },
     };
 
-    // Get unique tools used
     const toolsUsed = [...new Set(metrics.map((m) => m.tool))];
-
-    // Update workflow
     const stmt = db.prepare(`
       UPDATE workflow_metrics
       SET end_time = ?,
@@ -584,7 +577,6 @@ export const autoTrackWorkflow = (sessionId, sessionGoal) => {
         return null;
       }
 
-    // Check if workflow already tracked for this session
     const existing = db
       .prepare(
         `
@@ -601,7 +593,6 @@ export const autoTrackWorkflow = (sessionId, sessionGoal) => {
       return existing.workflow_id;
     }
 
-    // Get tools used so far in this session
     const metrics = db
       .prepare(
         `
@@ -621,7 +612,6 @@ export const autoTrackWorkflow = (sessionId, sessionGoal) => {
       return null;
     }
 
-      // Start tracking
       return startWorkflow(workflowType, sessionId, { autoDetected: true, goal: sessionGoal });
     });
   } catch {