@softerist/heuristic-mcp 3.0.15 → 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

@@ -50,18 +50,18 @@ import * as ClearCacheFeature from './features/clear-cache.js';
 import * as FindSimilarCodeFeature from './features/find-similar-code.js';
 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';
-const PID_FILE_NAME = '.heuristic-mcp.pid';
-
-async function readLogTail(logPath, maxLines = 2000) {
+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';
+const PID_FILE_NAME = '.heuristic-mcp.pid';
+
+async function readLogTail(logPath, maxLines = 2000) {
   const data = await fs.readFile(logPath, 'utf-8');
   if (!data) return [];
   const lines = data.split(/\r?\n/).filter(Boolean);
@@ -119,75 +119,75 @@ async function printMemorySnapshot(workspaceDir) {
 // Arguments parsed in main()
 
 // Global state
-let embedder = null;
-let unloadMainEmbedder = null; // Function to unload the embedding model
-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;
-  }
-}
+let embedder = null;
+let unloadMainEmbedder = null; // Function to unload the embedding model
+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 = [
@@ -443,15 +443,15 @@ async function initialize(workspaceDir) {
   // Features 5 (PackageVersion) doesn't need instance
 
   // Initialize SetWorkspace feature with shared state
-  const setWorkspaceInstance = new SetWorkspaceFeature.SetWorkspaceFeature(
-    config,
-    cache,
-    indexer,
-    getGlobalCacheDir
-  );
-  setWorkspaceFeatureInstance = setWorkspaceInstance;
-  features[6].instance = setWorkspaceInstance;
-  features[6].handler = SetWorkspaceFeature.createHandleToolCall(setWorkspaceInstance);
+  const setWorkspaceInstance = new SetWorkspaceFeature.SetWorkspaceFeature(
+    config,
+    cache,
+    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;
@@ -530,12 +530,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools };
 });
 
-// Handle tool calls
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  await maybeAutoSwitchWorkspace(request);
-
-  for (const feature of features) {
-    const toolDef = feature.module.getToolDefinition(config);
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  await maybeAutoSwitchWorkspace(request);
+
+  for (const feature of features) {
+    const toolDef = feature.module.getToolDefinition(config);
 
     if (request.params.name === toolDef.name) {
       // Safety check: handler may be null if initialization is incomplete

package/lib/cache-ops.js

@@ -1,22 +1,22 @@
-import fs from 'fs/promises';
-import { loadConfig } from './config.js';
-import { clearStaleCaches } from './cache-utils.js';
-
-export async function clearCache(workspaceDir) {
-  const effectiveWorkspace = workspaceDir || process.cwd();
-  const activeConfig = await loadConfig(effectiveWorkspace);
-
-  if (!activeConfig.enableCache) {
-    console.info('[Cache] Cache disabled (enableCache=false); nothing to clear.');
-    return;
-  }
-
-  try {
-    await fs.rm(activeConfig.cacheDirectory, { recursive: true, force: true });
-    console.info(`[Cache] Cleared cache directory: ${activeConfig.cacheDirectory}`);
-    await clearStaleCaches();
-  } catch (err) {
-    console.error(`[Cache] Failed to clear cache: ${err.message}`);
-    process.exit(1);
-  }
-}
+import fs from 'fs/promises';
+import { loadConfig } from './config.js';
+import { clearStaleCaches } from './cache-utils.js';
+
+export async function clearCache(workspaceDir) {
+  const effectiveWorkspace = workspaceDir || process.cwd();
+  const activeConfig = await loadConfig(effectiveWorkspace);
+
+  if (!activeConfig.enableCache) {
+    console.info('[Cache] Cache disabled (enableCache=false); nothing to clear.');
+    return;
+  }
+
+  try {
+    await fs.rm(activeConfig.cacheDirectory, { recursive: true, force: true });
+    console.info(`[Cache] Cleared cache directory: ${activeConfig.cacheDirectory}`);
+    await clearStaleCaches();
+  } catch (err) {
+    console.error(`[Cache] Failed to clear cache: ${err.message}`);
+    process.exit(1);
+  }
+}