smart-context-mcp 1.3.0 → 1.4.0

package/README.md

@@ -42,6 +42,62 @@ npx smart-context-init --target .
 ```
 Restart your AI client. Done.
 
+---
+
+## 🚀 How to Invoke the MCP
+
+The MCP doesn't intercept prompts automatically. **You need to tell the agent to use it.**
+
+### Option 1: Use MCP Prompts (Easiest)
+
+In Cursor, type in the chat:
+
+```
+/prompt use-devctx
+
+[Your task here]
+```
+
+**Available prompts:**
+- `/prompt use-devctx` - Force devctx tools for current task
+- `/prompt devctx-workflow` - Full workflow (start → context → work → end)
+- `/prompt devctx-preflight` - Preflight only (build_index + smart_turn start)
+
+### Option 2: Explicit Instruction
+
+Just tell the agent directly:
+
+```
+Use smart_turn(start) to recover context, then [your task]
+```
+
+Or:
+
+```
+Use the MCP to review this code
+```
+
+### Option 3: Automatic (via Rules)
+
+The agent *should* use devctx automatically for complex tasks because:
+- ✅ `.cursorrules` is active in Cursor
+- ✅ `CLAUDE.md` is active in Claude Desktop (if you created it)
+- ✅ `AGENTS.md` is active in other clients (if you created it)
+
+**But it's not guaranteed** - the agent decides based on task complexity.
+
+### ⚡ Quick Reference
+
+| Scenario | Command |
+|----------|---------|
+| Start new task | `/prompt devctx-workflow` |
+| Continue previous task | `smart_turn(start) and continue` |
+| Force MCP usage | `/prompt use-devctx` |
+| First time in project | `/prompt devctx-preflight` |
+| Trust automatic rules | Just describe your task normally |
+
+---
+
 ## How it Works in Practice
 
 **The reality:** This MCP does not intercept prompts automatically. Here's the actual flow:
@@ -62,7 +118,7 @@ Restart your AI client. Done.
 - ✅ Token savings: 85-90% on complex tasks
 
 Check actual usage:
-- **Real-time feedback** - See usage immediately (enable with `export DEVCTX_SHOW_USAGE=true`)
+- **Real-time feedback** - Enabled by default (disable with `export DEVCTX_SHOW_USAGE=false`)
 - `npm run report:metrics` - Tool-level savings + adoption analysis
 - `npm run report:workflows` - Workflow-level savings (requires `DEVCTX_WORKFLOW_TRACKING=true`)
 
@@ -105,16 +161,11 @@ Production usage: **14.5M tokens → 1.6M tokens** (89.87% reduction)
 
 ## Verify It's Working
 
-### Real-Time Feedback (Auto-enabled for First 10 Calls)
-
-Feedback is **automatically enabled** for your first 10 tool calls (onboarding mode), then auto-disables.
+### Real-Time Feedback (Enabled by Default)
 
-**To keep it enabled permanently:**
-```bash
-export DEVCTX_SHOW_USAGE=true
-```
+Feedback is **enabled by default** and shows after every devctx tool call.
 
-**To disable immediately:**
+**To disable:**
 ```bash
 export DEVCTX_SHOW_USAGE=false
 ```
@@ -130,7 +181,7 @@ You'll see at the end of agent responses:
 
 **Total saved:** ~57.0K tokens
 
-*Onboarding mode: showing for 3 more tool calls. To keep: `export DEVCTX_SHOW_USAGE=true`*
+*To disable this message: `export DEVCTX_SHOW_USAGE=false`*
 ```
 
 **Why this is useful:**
@@ -203,12 +254,12 @@ You'll see warnings like:
 - Low adoption (<30%)
 - Usage dropped mid-session
 
-**Combine all features:**
+**All features enabled by default.** To disable:
 
 ```bash
-export DEVCTX_SHOW_USAGE=true    # See what's used
-export DEVCTX_EXPLAIN=true       # Understand why
-export DEVCTX_DETECT_MISSED=true # Detect gaps
+export DEVCTX_SHOW_USAGE=false
+export DEVCTX_EXPLAIN=false
+export DEVCTX_DETECT_MISSED=false
 ```
 
 ## MCP Prompts
@@ -272,19 +323,50 @@ Get everything for a task in one call:
 
 Returns: relevant files + compressed content + symbol details + graph relationships
 
+**Smart pattern detection:** Automatically detects literal patterns (TODO, FIXME, /**, console.log, debugger) and prioritizes them in search.
+
 ### smart_summary
 
 Maintain task checkpoint:
 
 ```javascript
-// Save checkpoint
+// Save checkpoint (flat API - recommended)
+{ action: 'update', goal: 'Implement OAuth', status: 'in_progress', nextStep: '...' }
+
+// Or nested format (backward compatible)
 { action: 'update', update: { goal: 'Implement OAuth', status: 'in_progress', nextStep: '...' }}
 
 // Resume task
 { action: 'get' }
 ```
 
-Stores compressed task state (~100 tokens: goal, status, decisions, blockers), not full conversation.
+Stores compressed task state (~100 tokens: goal, status, decisions, blockers), not full conversation. Supports both flat and nested parameter formats.
+
+### smart_status
+
+Display current session context:
+
+```javascript
+{ format: 'detailed' }  // Full output with progress stats
+{ format: 'compact' }   // Minimal JSON
+```
+
+Shows goal, status, recent decisions, touched files, and progress. Updates automatically with each MCP operation.
+
+### smart_edit
+
+Batch edit multiple files:
+
+```javascript
+{
+  pattern: 'console.log',
+  replacement: 'logger.info',
+  files: ['src/a.js', 'src/b.js'],
+  mode: 'literal'  // or 'regex'
+}
+```
+
+Use `dryRun: true` for preview. Max 50 files per call.
 
 ## New Features
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-context-mcp",
-  "version": "1.3.0",
+  "version": "1.4.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/src/config/ignored-paths.js

@@ -0,0 +1,21 @@
+export const IGNORED_DIRS = [
+  'node_modules',
+  '.git',
+  '.next',
+  'dist',
+  'build',
+  'coverage',
+  '.venv',
+  'venv',
+  '__pycache__',
+  '.terraform',
+  '.devctx',
+];
+
+export const IGNORED_FILE_NAMES = [
+  'pnpm-lock.yaml',
+  'package-lock.json',
+  'yarn.lock',
+  'bun.lockb',
+  'npm-shrinkwrap.json',
+];

package/src/cross-project.js

@@ -1,24 +1,12 @@
-/**
- * Cross-project context for monorepos and related projects.
- * 
- * Enables context sharing across multiple related codebases.
- */
-
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadIndex } from './index.js';
 import { smartSearch } from './tools/smart-search.js';
 import { smartRead } from './tools/smart-read.js';
-import { projectRoot, setProjectRoot } from './utils/paths.js';
+import { projectRoot } from './utils/paths.js';
 
 const CROSS_PROJECT_CONFIG_FILE = '.devctx-projects.json';
 
-/**
- * Load cross-project configuration.
- * 
- * @param {string} root - Project root
- * @returns {object|null} Configuration or null if not found
- */
 export const loadCrossProjectConfig = (root = projectRoot) => {
   const configPath = path.join(root, CROSS_PROJECT_CONFIG_FILE);
   
@@ -34,12 +22,6 @@ export const loadCrossProjectConfig = (root = projectRoot) => {
   }
 };
 
-/**
- * Discover related projects from config.
- * 
- * @param {string} root - Project root
- * @returns {Array<object>} Array of { name, path, type, description }
- */
 export const discoverRelatedProjects = (root = projectRoot) => {
   const config = loadCrossProjectConfig(root);
   if (!config?.projects) return [];
@@ -68,13 +50,6 @@ export const discoverRelatedProjects = (root = projectRoot) => {
   return projects;
 };
 
-/**
- * Search across multiple related projects.
- * 
- * @param {string} query - Search query
- * @param {object} options - Search options
- * @returns {Promise<Array>} Results from all projects
- */
 export const searchAcrossProjects = async (query, options = {}) => {
   const {
     root = projectRoot,
@@ -125,18 +100,10 @@ export const searchAcrossProjects = async (query, options = {}) => {
   return results;
 };
 
-/**
- * Read files from multiple projects.
- * 
- * @param {Array<object>} fileRefs - Array of { project, file, mode }
- * @param {string} root - Project root
- * @returns {Promise<Array>} Read results
- */
 export const readAcrossProjects = async (fileRefs, root = projectRoot) => {
   const relatedProjects = discoverRelatedProjects(root);
   const projectMap = new Map(relatedProjects.map(p => [p.name, p]));
 
-  const originalRoot = projectRoot;
   const results = [];
 
   for (const ref of fileRefs) {
@@ -151,11 +118,10 @@ export const readAcrossProjects = async (fileRefs, root = projectRoot) => {
     }
 
     try {
-      setProjectRoot(project.path);
-
       const readResult = await smartRead({
         filePath: ref.file,
         mode: ref.mode || 'outline',
+        cwd: project.path,
       });
 
       results.push({
@@ -175,17 +141,9 @@ export const readAcrossProjects = async (fileRefs, root = projectRoot) => {
     }
   }
 
-  setProjectRoot(originalRoot);
   return results;
 };
 
-/**
- * Find symbol definitions across projects.
- * 
- * @param {string} symbolName - Symbol to find
- * @param {string} root - Project root
- * @returns {Promise<Array>} Symbol locations across projects
- */
 export const findSymbolAcrossProjects = async (symbolName, root = projectRoot) => {
   const relatedProjects = discoverRelatedProjects(root).filter(p => p.hasIndex);
   const results = [];
@@ -223,12 +181,6 @@ export const findSymbolAcrossProjects = async (symbolName, root = projectRoot) =
   return results;
 };
 
-/**
- * Get dependency graph across projects.
- * 
- * @param {string} root - Project root
- * @returns {object} Cross-project dependency graph
- */
 export const getCrossProjectDependencies = (root = projectRoot) => {
   const relatedProjects = discoverRelatedProjects(root).filter(p => p.hasIndex);
   const dependencies = {
@@ -276,12 +228,6 @@ export const getCrossProjectDependencies = (root = projectRoot) => {
   return dependencies;
 };
 
-/**
- * Get statistics about cross-project usage.
- * 
- * @param {string} root - Project root
- * @returns {object} Usage statistics
- */
 export const getCrossProjectStats = (root = projectRoot) => {
   const relatedProjects = discoverRelatedProjects(root);
   const deps = getCrossProjectDependencies(root);
@@ -306,12 +252,6 @@ export const getCrossProjectStats = (root = projectRoot) => {
   return stats;
 };
 
-/**
- * Create a sample cross-project configuration.
- * 
- * @param {string} root - Project root
- * @returns {object} Sample configuration
- */
 export const createSampleConfig = (root = projectRoot) => {
   return {
     version: '1.0',

package/src/decision-explainer.js

@@ -1,32 +1,25 @@
-/**
- * Decision explainer - tracks and explains why devctx tools were used or not used
- * 
- * Enable with environment variable: DEVCTX_EXPLAIN=true
- * 
- * Provides transparency into agent decision-making:
- * - Why was smart_read used instead of Read?
- * - Why was smart_search chosen?
- * - What are the expected benefits?
- */
-
 const sessionDecisions = {
   decisions: [],
-  enabled: false,
+  enabled: true,
 };
 
-/**
- * Check if explanations are enabled
- */
 export const isExplainEnabled = () => {
   const envValue = process.env.DEVCTX_EXPLAIN?.toLowerCase();
-  const enabled = envValue === 'true' || envValue === '1' || envValue === 'yes';
-  sessionDecisions.enabled = enabled;
-  return enabled;
+  
+  if (envValue === 'true' || envValue === '1' || envValue === 'yes') {
+    sessionDecisions.enabled = true;
+    return true;
+  }
+  
+  if (envValue === 'false' || envValue === '0' || envValue === 'no') {
+    sessionDecisions.enabled = false;
+    return false;
+  }
+  
+  sessionDecisions.enabled = true;
+  return true;
 };
 
-/**
- * Record a decision with explanation
- */
 export const recordDecision = ({
   tool,
   action,
@@ -48,16 +41,10 @@ export const recordDecision = ({
   });
 };
 
-/**
- * Get all decisions for current session
- */
 export const getSessionDecisions = () => {
   return sessionDecisions.decisions;
 };
 
-/**
- * Format decisions as markdown for display
- */
 export const formatDecisionExplanations = () => {
   if (!isExplainEnabled()) return '';
   
@@ -95,46 +82,30 @@ export const formatDecisionExplanations = () => {
   return lines.join('\n');
 };
 
-/**
- * Reset session decisions (for testing or manual reset)
- */
 export const resetSessionDecisions = () => {
   sessionDecisions.decisions = [];
+  sessionDecisions.enabled = true;
 };
 
-/**
- * Common decision reasons (for consistency)
- */
 export const DECISION_REASONS = {
-  // smart_read reasons
   LARGE_FILE: 'File is large (>500 lines), outline mode extracts structure only',
   SYMBOL_EXTRACTION: 'Extracting specific symbol, smart_read can locate and extract it efficiently',
   TOKEN_BUDGET: 'Token budget constraint, cascading to more compressed mode',
   MULTIPLE_SYMBOLS: 'Reading multiple symbols, smart_read can batch them',
-  
-  // smart_search reasons
   MULTIPLE_FILES: 'Query spans 50+ files, smart_search ranks by relevance',
   INTENT_AWARE: 'Intent-aware search prioritizes relevant results (debug/implementation/tests)',
   INDEX_BOOST: 'Symbol index available, boosting relevant matches',
   PATTERN_SEARCH: 'Complex pattern search, smart_search handles regex efficiently',
-  
-  // smart_context reasons
   TASK_CONTEXT: 'Building complete context for task, smart_context orchestrates multiple reads',
   RELATED_FILES: 'Need related files (callers, tests, types), smart_context finds them',
   ONE_CALL: 'Single call to get all context, more efficient than multiple reads',
   DIFF_ANALYSIS: 'Analyzing git diff, smart_context expands changed symbols',
-  
-  // smart_shell reasons
   COMMAND_OUTPUT: 'Command output needs compression (git log, npm test, etc.)',
   RELEVANT_LINES: 'Extracting relevant lines from command output',
   SAFE_EXECUTION: 'Using allowlist-validated command execution',
-  
-  // smart_summary reasons
   CHECKPOINT: 'Saving task checkpoint for session recovery',
   RESUME: 'Recovering previous task context',
   PERSISTENCE: 'Maintaining task state across agent restarts',
-  
-  // Native tool reasons
   SIMPLE_TASK: 'Task is simple, native tool is more direct',
   ALREADY_CACHED: 'Content already in context, no need for compression',
   SINGLE_LINE: 'Reading single line, native Read is sufficient',
@@ -142,9 +113,6 @@ export const DECISION_REASONS = {
   NO_INDEX: 'No symbol index available, native search is equivalent',
 };
 
-/**
- * Common expected benefits (for consistency)
- */
 export const EXPECTED_BENEFITS = {
   TOKEN_SAVINGS: (tokens) => `~${formatTokens(tokens)} saved`,
   FASTER_RESPONSE: 'Faster response due to less data to process',
@@ -154,9 +122,6 @@ export const EXPECTED_BENEFITS = {
   FOCUSED_RESULTS: 'Focused on relevant code only',
 };
 
-/**
- * Format token count for display
- */
 const formatTokens = (tokens) => {
   if (tokens >= 1000000) {
     return `${(tokens / 1000000).toFixed(1)}M tokens`;

package/src/index.js

@@ -3,6 +3,7 @@ import fsp from 'node:fs/promises';
 import path from 'node:path';
 import ts from 'typescript';
 import { isBinaryBuffer } from './utils/fs.js';
+import { IGNORED_DIRS } from './config/ignored-paths.js';
 
 const INDEX_VERSION = 4;
 
@@ -61,10 +62,7 @@ const indexableExtensions = new Set([
   '.cs', '.kt', '.php', '.swift',
 ]);
 
-const ignoredDirs = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
-  '.venv', 'venv', '__pycache__', '.terraform', '.devctx',
-]);
+const ignoredDirs = new Set(IGNORED_DIRS);
 
 const scriptKindByExtension = {
   '.js': ts.ScriptKind.JS,

package/src/missed-opportunities.js

@@ -1,25 +1,9 @@
-/**
- * Missed opportunities detector - identifies when devctx should have been used but wasn't
- * 
- * Analyzes session metrics to detect patterns where devctx would have helped.
- * 
- * Enable with environment variable: DEVCTX_DETECT_MISSED=true
- * 
- * Detection heuristics (based on session metrics):
- * - Low devctx adoption in complex sessions (many operations, few devctx calls)
- * - Sessions with 0 devctx usage but high operation count
- * - Inferred complexity vs actual devctx usage
- * 
- * Note: We can't intercept native tool calls in real-time, so we analyze
- * patterns from metrics after the fact.
- */
-
 const sessionActivity = {
   devctxOperations: 0,
-  totalOperations: 0, // Estimated from devctx calls + time-based heuristic
+  totalOperations: 0,
   lastDevctxCall: 0,
   sessionStart: Date.now(),
-  enabled: false,
+  enabled: true,
   warnings: [],
 };
 
@@ -34,19 +18,23 @@ const DEVCTX_TOOLS = new Set([
   'build_index',
 ]);
 
-/**
- * Check if missed opportunity detection is enabled
- */
 export const isMissedDetectionEnabled = () => {
   const envValue = process.env.DEVCTX_DETECT_MISSED?.toLowerCase();
-  const enabled = envValue === 'true' || envValue === '1' || envValue === 'yes';
-  sessionActivity.enabled = enabled;
-  return enabled;
+  
+  if (envValue === 'true' || envValue === '1' || envValue === 'yes') {
+    sessionActivity.enabled = true;
+    return true;
+  }
+  
+  if (envValue === 'false' || envValue === '0' || envValue === 'no') {
+    sessionActivity.enabled = false;
+    return false;
+  }
+  
+  sessionActivity.enabled = true;
+  return true;
 };
 
-/**
- * Record devctx tool usage
- */
 export const recordDevctxOperation = () => {
   if (!isMissedDetectionEnabled()) return;
   
@@ -55,29 +43,19 @@ export const recordDevctxOperation = () => {
   sessionActivity.lastDevctxCall = Date.now();
 };
 
-/**
- * Estimate total operations based on time and activity
- * Heuristic: If no devctx calls for >2 minutes, likely agent is using native tools
- */
 const estimateTotalOperations = () => {
   const now = Date.now();
   const sessionDuration = now - sessionActivity.sessionStart;
   const timeSinceLastDevctx = now - sessionActivity.lastDevctxCall;
   
-  // If session is active (recent devctx calls), estimate conservatively
   if (timeSinceLastDevctx < 2 * 60 * 1000) {
     return sessionActivity.totalOperations;
   }
   
-  // If long gap without devctx, estimate agent is using native tools
-  // Heuristic: ~1 operation per 10 seconds of activity
   const estimatedNativeOps = Math.floor(timeSinceLastDevctx / 10000);
   return sessionActivity.totalOperations + estimatedNativeOps;
 };
 
-/**
- * Analyze session and detect missed opportunities
- */
 export const analyzeMissedOpportunities = () => {
   if (!isMissedDetectionEnabled()) return null;
   
@@ -85,21 +63,18 @@ export const analyzeMissedOpportunities = () => {
   const sessionDuration = now - sessionActivity.sessionStart;
   const timeSinceLastDevctx = now - sessionActivity.lastDevctxCall;
   const estimatedTotal = estimateTotalOperations();
-  
   const opportunities = [];
   
-  // Detection 1: Long session with no devctx usage
   if (sessionDuration > 5 * 60 * 1000 && sessionActivity.devctxOperations === 0) {
     opportunities.push({
       type: 'no_devctx_usage',
       severity: 'high',
       reason: 'Session active for >5 minutes with 0 devctx calls. Agent may not be using devctx.',
       suggestion: 'Use forcing prompt or check if MCP is active',
-      estimatedSavings: estimatedTotal * 10000, // Estimate ~10K tokens per operation
+      estimatedSavings: estimatedTotal * 10000,
     });
   }
   
-  // Detection 2: Low devctx adoption in active session
   const devctxRatio = estimatedTotal > 0 ? sessionActivity.devctxOperations / estimatedTotal : 0;
   if (estimatedTotal >= 10 && devctxRatio < 0.3) {
     opportunities.push({
@@ -111,7 +86,6 @@ export const analyzeMissedOpportunities = () => {
     });
   }
   
-  // Detection 3: Long gap without devctx (agent switched to native tools)
   if (sessionActivity.devctxOperations > 0 && timeSinceLastDevctx > 3 * 60 * 1000) {
     const minutesSince = Math.round(timeSinceLastDevctx / 60000);
     opportunities.push({
@@ -123,7 +97,6 @@ export const analyzeMissedOpportunities = () => {
     });
   }
   
-  // Detection 4: Session too short to analyze
   if (sessionDuration < 60 * 1000 && opportunities.length === 0) {
     return {
       opportunities: [],
@@ -143,17 +116,21 @@ export const analyzeMissedOpportunities = () => {
   };
 };
 
-/**
- * Format missed opportunities as markdown
- */
 export const formatMissedOpportunities = () => {
   if (!isMissedDetectionEnabled()) return '';
   
   const analysis = analyzeMissedOpportunities();
   if (!analysis) return '';
   
-  // Don't show if session is too short or no opportunities
-  if (analysis.message || analysis.opportunities.length === 0) {
+  if (analysis.message) {
+    return '';
+  }
+  
+  if (analysis.opportunities.length === 0 && analysis.devctxOperations > 0) {
+    return `\n\n✅ **devctx adoption: ${analysis.devctxRatio}%** (${analysis.devctxOperations}/${analysis.estimatedTotal} operations)\n`;
+  }
+  
+  if (analysis.opportunities.length === 0) {
     return '';
   }
   
@@ -200,9 +177,6 @@ export const formatMissedOpportunities = () => {
   return lines.join('\n');
 };
 
-/**
- * Get session activity summary
- */
 export const getSessionActivity = () => {
   return {
     devctxOperations: sessionActivity.devctxOperations,
@@ -213,20 +187,15 @@ export const getSessionActivity = () => {
   };
 };
 
-/**
- * Reset session activity (for testing or manual reset)
- */
 export const resetSessionActivity = () => {
   sessionActivity.devctxOperations = 0;
   sessionActivity.totalOperations = 0;
   sessionActivity.lastDevctxCall = 0;
   sessionActivity.sessionStart = Date.now();
   sessionActivity.warnings = [];
+  sessionActivity.enabled = true;
 };
 
-/**
- * Testing helpers - expose internal state for test scenarios
- */
 export const __testing__ = {
   setSessionStart: (timestamp) => {
     sessionActivity.sessionStart = timestamp;
@@ -240,9 +209,6 @@ export const __testing__ = {
   getSessionActivity: () => sessionActivity,
 };
 
-/**
- * Format token count for display
- */
 const formatTokens = (tokens) => {
   if (tokens >= 1000000) {
     return `${(tokens / 1000000).toFixed(1)}M tokens`;