@softerist/heuristic-mcp 3.0.14 → 3.0.16

package/features/resources.js

@@ -0,0 +1,156 @@
+/**
+ * MCP Resources Feature
+ *
+ * Exposes workspace files as MCP resources for discovery and reading.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { fdir } from 'fdir';
+import { getMimeType } from '../lib/constants.js';
+
+/**
+ * Convert a file path to a file:// URI.
+ * @param {string} filePath - Absolute file path
+ * @returns {string}
+ */
+function pathToUri(filePath) {
+  // Normalize path separators and encode for URI
+  const normalized = filePath.replace(/\\/g, '/');
+  // On Windows, paths start with drive letter like C:/
+  if (/^[a-zA-Z]:/.test(normalized)) {
+    return `file:///${normalized}`;
+  }
+  return `file://${normalized}`;
+}
+
+/**
+ * Convert a file:// URI back to a file path.
+ * @param {string} uri
+ * @returns {string}
+ */
+function uriToPath(uri) {
+  if (!uri.startsWith('file://')) {
+    throw new Error(`Invalid file URI: ${uri}`);
+  }
+  let filePath = uri.slice(7); // Remove 'file://'
+  // Handle Windows paths (file:///C:/...)
+  if (/^\/[a-zA-Z]:/.test(filePath)) {
+    filePath = filePath.slice(1); // Remove leading /
+  }
+  // Decode URI components
+  filePath = decodeURIComponent(filePath);
+  // Normalize to OS path separators
+  if (process.platform === 'win32') {
+    filePath = filePath.replace(/\//g, '\\');
+  }
+  return filePath;
+}
+
+/**
+ * Check if a path is within the workspace directory.
+ * @param {string} filePath - Absolute file path
+ * @param {string} workspaceDir - Workspace directory
+ * @returns {boolean}
+ */
+function isWithinWorkspace(filePath, workspaceDir) {
+  const resolvedPath = path.resolve(filePath);
+  const resolvedWorkspace = path.resolve(workspaceDir);
+  const relativePath = path.relative(resolvedWorkspace, resolvedPath);
+  return !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
+}
+
+/**
+ * List resources handler for MCP.
+ * @param {object} config - Server configuration
+ * @returns {Promise<{resources: Array}>}
+ */
+export async function handleListResources(config) {
+  const workspaceDir = config.searchDirectory;
+  const maxResults = 500; // Limit to avoid overwhelming clients
+
+  // Build set of allowed extensions from config
+  const allowedExtensions = new Set(
+    (config.fileExtensions || []).map(ext => `.${ext.toLowerCase()}`)
+  );
+
+  // Extract directory names from exclude patterns (e.g., '**/node_modules/**' -> 'node_modules')
+  const excludedDirs = new Set();
+  for (const pattern of config.excludePatterns || []) {
+    // Match patterns like '**/dirname/**' or 'dirname/**'
+    const match = pattern.match(/(?:\*\*\/)?([^/*]+)(?:\/\*\*)?$/);
+    if (match && match[1] && !match[1].includes('*')) {
+      excludedDirs.add(match[1]);
+    }
+  }
+
+  try {
+    // Use fdir to scan workspace
+    const crawler = new fdir()
+      .withBasePath()
+      .withMaxDepth(10)
+      .exclude((dirName) => {
+        return excludedDirs.has(dirName);
+      })
+      .filter((filePath) => {
+        const ext = path.extname(filePath).toLowerCase();
+        return allowedExtensions.has(ext);
+      })
+      .crawl(workspaceDir);
+
+    const files = await crawler.withPromise();
+    const limitedFiles = files.slice(0, maxResults);
+
+    const resources = limitedFiles.map((filePath) => {
+      const relativePath = path.relative(workspaceDir, filePath);
+      return {
+        uri: pathToUri(filePath),
+        name: relativePath.replace(/\\/g, '/'),
+        mimeType: getMimeType(path.extname(filePath)),
+      };
+    });
+
+    return { resources };
+  } catch (error) {
+    console.error(`[Resources] Error listing resources: ${error.message}`);
+    return { resources: [] };
+  }
+}
+
+/**
+ * Read resource handler for MCP.
+ * @param {string} uri - Resource URI
+ * @param {object} config - Server configuration
+ * @returns {Promise<{contents: Array}>}
+ */
+export async function handleReadResource(uri, config) {
+  const workspaceDir = config.searchDirectory;
+
+  try {
+    const filePath = uriToPath(uri);
+
+    // Security check: ensure path is within workspace
+    if (!isWithinWorkspace(filePath, workspaceDir)) {
+      throw new Error(`Access denied: ${uri} is outside workspace`);
+    }
+
+    // Check file exists
+    await fs.access(filePath);
+
+    // Read file content
+    const content = await fs.readFile(filePath, 'utf-8');
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: getMimeType(path.extname(filePath)),
+          text: content,
+        },
+      ],
+    };
+  } catch (error) {
+    console.error(`[Resources] Error reading resource ${uri}: ${error.message}`);
+    throw error;
+  }
+}

package/features/set-workspace.js

@@ -0,0 +1,265 @@
+/**
+ * Runtime Workspace Switching Tool
+ *
+ * Changes the workspace path at runtime, reinitializing the cache
+ * and optionally triggering reindexing.
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+import crypto from 'crypto';
+import { acquireWorkspaceLock, releaseWorkspaceLock } from '../lib/server-lifecycle.js';
+
+/**
+ * Generate a workspace-specific cache directory path
+ */
+function getWorkspaceCacheDir(workspacePath, globalCacheDir) {
+  const normalized = path.resolve(workspacePath);
+  const hash = crypto.createHash('md5').update(normalized).digest('hex').slice(0, 12);
+  return path.join(globalCacheDir, 'heuristic-mcp', hash);
+}
+
+// MCP Tool definition
+export function getToolDefinition() {
+  return {
+    name: 'f_set_workspace',
+    description:
+      'Changes the current workspace path at runtime. This updates the search directory and cache, and optionally triggers a full reindex. Useful for multi-project workflows.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        workspacePath: {
+          type: 'string',
+          description: 'Absolute path to the new workspace directory',
+        },
+        reindex: {
+          type: 'boolean',
+          description: 'Whether to trigger a full reindex after switching (default: true)',
+          default: true,
+        },
+      },
+      required: ['workspacePath'],
+    },
+    annotations: {
+      title: 'Set Workspace',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  };
+}
+
+/**
+ * Create the SetWorkspace feature class
+ * This needs access to shared state (config, cache, indexer) to actually perform the switch
+ */
+export class SetWorkspaceFeature {
+  constructor(config, cache, indexer, getGlobalCacheDir) {
+    this.config = config;
+    this.cache = cache;
+    this.indexer = indexer;
+    this.getGlobalCacheDir = getGlobalCacheDir;
+  }
+
+  async execute({ workspacePath, reindex = true }) {
+    // Validate workspace path
+    if (!workspacePath || typeof workspacePath !== 'string') {
+      return {
+        success: false,
+        error: 'workspacePath is required and must be a string',
+      };
+    }
+
+    const normalizedPath = path.resolve(workspacePath);
+
+    // Check if directory exists
+    try {
+      const stat = await fs.stat(normalizedPath);
+      if (!stat.isDirectory()) {
+        return {
+          success: false,
+          error: `Path is not a directory: ${normalizedPath}`,
+        };
+      }
+    } catch (err) {
+      return {
+        success: false,
+        error: `Cannot access directory: ${normalizedPath} (${err.message})`,
+      };
+    }
+
+    const previousWorkspace = this.config.searchDirectory;
+    const previousCache = this.config.cacheDirectory;
+
+    // Update config
+    this.config.searchDirectory = normalizedPath;
+
+    // Calculate new cache directory (match config.js behavior)
+    const globalCacheDir = this.getGlobalCacheDir();
+    let newCacheDir = getWorkspaceCacheDir(normalizedPath, globalCacheDir);
+
+    // Prefer legacy local cache if present
+    const legacyPath = path.join(normalizedPath, '.smart-coding-cache');
+    try {
+      const legacyStats = await fs.stat(legacyPath);
+      if (legacyStats.isDirectory()) {
+        newCacheDir = legacyPath;
+      }
+    } catch {
+      // ignore missing legacy cache
+    }
+    this.config.cacheDirectory = newCacheDir;
+
+    // Create cache directory if needed
+    try {
+      await fs.mkdir(newCacheDir, { recursive: true });
+    } catch (err) {
+      // Revert config on failure
+      this.config.searchDirectory = previousWorkspace;
+      this.config.cacheDirectory = previousCache;
+      return {
+        success: false,
+        error: `Failed to create cache directory: ${err.message}`,
+      };
+    }
+
+    // Acquire new workspace lock before proceeding
+    const lock = await acquireWorkspaceLock({
+      cacheDirectory: newCacheDir,
+      workspaceDir: normalizedPath,
+    });
+    if (!lock.acquired) {
+      // Revert config on failure
+      this.config.searchDirectory = previousWorkspace;
+      this.config.cacheDirectory = previousCache;
+      return {
+        success: false,
+        error: `Workspace is already locked by another server (pid ${lock.ownerPid ?? 'unknown'})`,
+      };
+    }
+    let indexerUpdateError = null;
+
+    // Update indexer's workspace root and related state
+    if (this.indexer) {
+      if (typeof this.indexer.terminateWorkers === 'function') {
+        try {
+          await this.indexer.terminateWorkers();
+        } catch (err) {
+          console.warn(`[SetWorkspace] Failed to terminate workers: ${err.message}`);
+        }
+      }
+      try {
+        if (typeof this.indexer.updateWorkspaceState === 'function') {
+          await this.indexer.updateWorkspaceState({ restartWatcher: true });
+        } else {
+          this.indexer.workspaceRoot = normalizedPath;
+          this.indexer.workspaceRootReal = null; // Reset cached realpath
+          if (this.config.watchFiles && typeof this.indexer.setupFileWatcher === 'function') {
+            await this.indexer.setupFileWatcher();
+          }
+        }
+      } catch (err) {
+        indexerUpdateError = err;
+      }
+    }
+
+    if (indexerUpdateError) {
+      // Roll back config + lock on failure to avoid partial switch
+      this.config.searchDirectory = previousWorkspace;
+      this.config.cacheDirectory = previousCache;
+      await releaseWorkspaceLock({ cacheDirectory: newCacheDir });
+      if (this.indexer) {
+        try {
+          if (typeof this.indexer.updateWorkspaceState === 'function') {
+            await this.indexer.updateWorkspaceState({ restartWatcher: true });
+          } else {
+            this.indexer.workspaceRoot = previousWorkspace;
+            this.indexer.workspaceRootReal = null;
+            if (this.config.watchFiles && typeof this.indexer.setupFileWatcher === 'function') {
+              await this.indexer.setupFileWatcher();
+            }
+          }
+        } catch (rollbackErr) {
+          console.warn(
+            `[SetWorkspace] Failed to rollback indexer state: ${rollbackErr.message}`
+          );
+        }
+      }
+      return {
+        success: false,
+        error: `Failed to update workspace state: ${indexerUpdateError.message}`,
+      };
+    }
+
+    // Release old workspace lock after successful indexer update
+    if (previousCache) {
+      await releaseWorkspaceLock({ cacheDirectory: previousCache });
+    }
+
+    // Re-initialize cache for new workspace if cache has a load method
+    if (this.cache && typeof this.cache.load === 'function') {
+      try {
+        await this.cache.load();
+      } catch (err) {
+        console.warn(`[SetWorkspace] Failed to load cache: ${err.message}`);
+      }
+    }
+
+    // Optionally trigger reindex
+    let reindexStatus = null;
+    if (reindex && this.indexer && typeof this.indexer.indexAll === 'function') {
+      try {
+        // Start indexing asynchronously
+        this.indexer.indexAll().catch((err) => {
+          console.warn(`[SetWorkspace] Reindex failed: ${err.message}`);
+        });
+        reindexStatus = 'started';
+      } catch (err) {
+        reindexStatus = `failed: ${err.message}`;
+      }
+    } else if (!reindex) {
+      reindexStatus = 'skipped';
+    }
+
+    return {
+      success: true,
+      previousWorkspace,
+      newWorkspace: normalizedPath,
+      cacheDirectory: newCacheDir,
+      reindexStatus,
+    };
+  }
+}
+
+// Tool handler (needs instance context, so this is a factory)
+export function createHandleToolCall(featureInstance) {
+  return async (request) => {
+    const args = request.params?.arguments || {};
+    const { workspacePath, reindex } = args;
+
+    const result = await featureInstance.execute({
+      workspacePath,
+      reindex: reindex !== false, // Default to true
+    });
+
+    if (result.success) {
+      let message = `✓ Workspace switched to: **${result.newWorkspace}**\n`;
+      message += `\n- Previous: \`${result.previousWorkspace || '(none)'}\``;
+      message += `\n- Cache: \`${result.cacheDirectory}\``;
+      if (result.reindexStatus) {
+        message += `\n- Reindex: ${result.reindexStatus}`;
+      }
+      return {
+        content: [{ type: 'text', text: message }],
+      };
+    } else {
+      return {
+        content: [{ type: 'text', text: `Error: ${result.error}` }],
+      };
+    }
+  };
+}
+
+// Export for use in registration
+export { getWorkspaceCacheDir };

package/index.js

@@ -52,12 +52,13 @@ import * as AnnConfigFeature from './features/ann-config.js';
 import * as PackageVersionFeature from './features/package-version.js';
 import * as SetWorkspaceFeature from './features/set-workspace.js';
 import { handleListResources, handleReadResource } from './features/resources.js';
+import { getWorkspaceEnvKeys } from './lib/workspace-env.js';
 
-import {
-  MEMORY_LOG_INTERVAL_MS,
-  ONNX_THREAD_LIMIT,
-  BACKGROUND_INDEX_DELAY_MS,
-} from './lib/constants.js';
+import {
+  MEMORY_LOG_INTERVAL_MS,
+  ONNX_THREAD_LIMIT,
+  BACKGROUND_INDEX_DELAY_MS,
+} from './lib/constants.js';
 const PID_FILE_NAME = '.heuristic-mcp.pid';
 
 async function readLogTail(logPath, maxLines = 2000) {
@@ -124,6 +125,69 @@ let cache = null;
 let indexer = null;
 let hybridSearch = null;
 let config = null;
+let setWorkspaceFeatureInstance = null;
+let autoWorkspaceSwitchPromise = null;
+
+async function resolveWorkspaceFromEnvValue(rawValue) {
+  if (!rawValue || rawValue.includes('${')) return null;
+  const resolved = path.resolve(rawValue);
+  try {
+    const stats = await fs.stat(resolved);
+    if (!stats.isDirectory()) return null;
+    return resolved;
+  } catch {
+    return null;
+  }
+}
+
+async function detectRuntimeWorkspaceFromEnv() {
+  for (const key of getWorkspaceEnvKeys()) {
+    const workspacePath = await resolveWorkspaceFromEnvValue(process.env[key]);
+    if (workspacePath) {
+      return { workspacePath, envKey: key };
+    }
+  }
+
+  return null;
+}
+
+async function maybeAutoSwitchWorkspace(request) {
+  if (process.env.VITEST === 'true' || process.env.NODE_ENV === 'test') return;
+  if (!setWorkspaceFeatureInstance || !config?.searchDirectory) return;
+  if (request?.params?.name === 'f_set_workspace') return;
+
+  const detected = await detectRuntimeWorkspaceFromEnv();
+  if (!detected) return;
+
+  const currentWorkspace = path.resolve(config.searchDirectory);
+  if (detected.workspacePath === currentWorkspace) return;
+
+  if (autoWorkspaceSwitchPromise) {
+    await autoWorkspaceSwitchPromise;
+    return;
+  }
+
+  autoWorkspaceSwitchPromise = (async () => {
+    console.info(
+      `[Server] Auto-switching workspace from ${currentWorkspace} to ${detected.workspacePath} (env ${detected.envKey})`
+    );
+    const result = await setWorkspaceFeatureInstance.execute({
+      workspacePath: detected.workspacePath,
+      reindex: false,
+    });
+    if (!result.success) {
+      console.warn(
+        `[Server] Auto workspace switch failed (env ${detected.envKey}): ${result.error}`
+      );
+    }
+  })();
+
+  try {
+    await autoWorkspaceSwitchPromise;
+  } finally {
+    autoWorkspaceSwitchPromise = null;
+  }
+}
 
 // Feature registry - ordered by priority (semantic_search first as primary tool)
 const features = [
@@ -181,46 +245,46 @@ async function initialize(workspaceDir) {
     }
   }
   
-  // Skip gc check during tests (VITEST env is set)
-  const isTest = Boolean(process.env.VITEST || process.env.VITEST_WORKER_ID);
-  if (config.enableExplicitGc && typeof global.gc !== 'function' && !isTest) {
-    console.warn(
-      '[Server] enableExplicitGc=true but this process was not started with --expose-gc; continuing with explicit GC disabled.'
-    );
-    console.warn(
-      '[Server] Tip: start with "npm start" or add --expose-gc to enable explicit GC again.'
-    );
-    config.enableExplicitGc = false;
-  }
+  // Skip gc check during tests (VITEST env is set)
+  const isTest = Boolean(process.env.VITEST || process.env.VITEST_WORKER_ID);
+  if (config.enableExplicitGc && typeof global.gc !== 'function' && !isTest) {
+    console.warn(
+      '[Server] enableExplicitGc=true but this process was not started with --expose-gc; continuing with explicit GC disabled.'
+    );
+    console.warn(
+      '[Server] Tip: start with "npm start" or add --expose-gc to enable explicit GC again.'
+    );
+    config.enableExplicitGc = false;
+  }
 
   let mainBackendConfigured = false;
   let nativeOnnxAvailable = null;
-  const ensureMainOnnxBackend = () => {
-    if (mainBackendConfigured) return;
-    nativeOnnxAvailable = configureNativeOnnxBackend({
-      log: config.verbose ? console.info : null,
-      label: '[Server]',
-      threads: {
+  const ensureMainOnnxBackend = () => {
+    if (mainBackendConfigured) return;
+    nativeOnnxAvailable = configureNativeOnnxBackend({
+      log: config.verbose ? console.info : null,
+      label: '[Server]',
+      threads: {
         intraOpNumThreads: ONNX_THREAD_LIMIT,
         interOpNumThreads: 1,
       },
     });
-    mainBackendConfigured = true;
-  };
-
-  ensureMainOnnxBackend();
-  if (nativeOnnxAvailable === false) {
-    try {
-      const { env } = await getTransformers();
-      if (env?.backends?.onnx?.wasm) {
-        env.backends.onnx.wasm.numThreads = ONNX_THREAD_LIMIT;
-      }
-    } catch {
-      // ignore: fallback tuning is best effort
-    }
-    const status = getNativeOnnxStatus();
-    const reason = status?.message || 'onnxruntime-node not available';
-    console.warn(`[Server] Native ONNX backend unavailable (${reason}); using WASM backend.`);
+    mainBackendConfigured = true;
+  };
+
+  ensureMainOnnxBackend();
+  if (nativeOnnxAvailable === false) {
+    try {
+      const { env } = await getTransformers();
+      if (env?.backends?.onnx?.wasm) {
+        env.backends.onnx.wasm.numThreads = ONNX_THREAD_LIMIT;
+      }
+    } catch {
+      // ignore: fallback tuning is best effort
+    }
+    const status = getNativeOnnxStatus();
+    const reason = status?.message || 'onnxruntime-node not available';
+    console.warn(`[Server] Native ONNX backend unavailable (${reason}); using WASM backend.`);
     console.warn(
       '[Server] Auto-safety: disabling workers and forcing embeddingProcessPerBatch for memory isolation.'
     );
@@ -252,12 +316,12 @@ async function initialize(workspaceDir) {
   }
 
   // Log effective configuration for debugging
-  console.info(
-    `[Server] Config: workerThreads=${config.workerThreads}, embeddingProcessPerBatch=${config.embeddingProcessPerBatch}`
-  );
-  console.info(
-    `[Server] Config: vectorStoreLoadMode=${config.vectorStoreLoadMode}, vectorCacheEntries=${config.vectorCacheEntries}`
-  );
+  console.info(
+    `[Server] Config: workerThreads=${config.workerThreads}, embeddingProcessPerBatch=${config.embeddingProcessPerBatch}`
+  );
+  console.info(
+    `[Server] Config: vectorStoreLoadMode=${config.vectorStoreLoadMode}, vectorCacheEntries=${config.vectorCacheEntries}`
+  );
 
   if (pidPath) {
     console.info(`[Server] PID file: ${pidPath}`);
@@ -342,22 +406,22 @@ async function initialize(workspaceDir) {
       cachedEmbedderPromise = null;
       return false;
     }
-  };
-  
-  embedder = lazyEmbedder;
-  unloadMainEmbedder = unloader; // Store in module scope for tool handler access
-  const preloadEmbeddingModel = async () => {
-    if (config.preloadEmbeddingModel === false) return;
-    try {
-      console.info('[Server] Preloading embedding model (background)...');
-      await embedder(' ');
-    } catch (err) {
-      console.warn(`[Server] Embedding model preload failed: ${err.message}`);
-    }
-  };
-
-  // NOTE: We no longer auto-load in verbose mode when preloadEmbeddingModel=false.
-  // The model will be loaded lazily on first search or by child processes during indexing.
+  };
+  
+  embedder = lazyEmbedder;
+  unloadMainEmbedder = unloader; // Store in module scope for tool handler access
+  const preloadEmbeddingModel = async () => {
+    if (config.preloadEmbeddingModel === false) return;
+    try {
+      console.info('[Server] Preloading embedding model (background)...');
+      await embedder(' ');
+    } catch (err) {
+      console.warn(`[Server] Embedding model preload failed: ${err.message}`);
+    }
+  };
+
+  // NOTE: We no longer auto-load in verbose mode when preloadEmbeddingModel=false.
+  // The model will be loaded lazily on first search or by child processes during indexing.
 
   // Initialize cache (load deferred until after server is ready)
   cache = new EmbeddingsCache(config);
@@ -385,19 +449,20 @@ async function initialize(workspaceDir) {
     indexer,
     getGlobalCacheDir
   );
+  setWorkspaceFeatureInstance = setWorkspaceInstance;
   features[6].instance = setWorkspaceInstance;
   features[6].handler = SetWorkspaceFeature.createHandleToolCall(setWorkspaceInstance);
 
   // Attach hybridSearch to server for cross-feature access (e.g. cache invalidation)
   server.hybridSearch = hybridSearch;
 
-  const startBackgroundTasks = async () => {
-    // Keep startup responsive: do not block server readiness on model preload.
-    void preloadEmbeddingModel();
-
-    try {
-      console.info('[Server] Loading cache (deferred)...');
-      await cache.load();
+  const startBackgroundTasks = async () => {
+    // Keep startup responsive: do not block server readiness on model preload.
+    void preloadEmbeddingModel();
+
+    try {
+      console.info('[Server] Loading cache (deferred)...');
+      await cache.load();
       if (config.verbose) {
         logMemory('[Server] Memory (after cache load)');
       }
@@ -423,8 +488,8 @@ async function initialize(workspaceDir) {
         .catch((err) => {
           console.error('[Server] Background indexing error:', err.message);
         });
-    }, BACKGROUND_INDEX_DELAY_MS);
-  };
+    }, BACKGROUND_INDEX_DELAY_MS);
+  };
 
   return { startBackgroundTasks, config };
 }
@@ -467,6 +532,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 
 // Handle tool calls
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  await maybeAutoSwitchWorkspace(request);
+
   for (const feature of features) {
     const toolDef = feature.module.getToolDefinition(config);