@softerist/heuristic-mcp 3.0.13 → 3.0.15

package/README.md

@@ -76,14 +76,20 @@ heuristic-mcp --version
 ### Start/Stop
 
 ```bash
-heuristic-mcp --start
-heuristic-mcp --start antigravity
-heuristic-mcp --start cursor
-heuristic-mcp --start "Claude Desktop"
-heuristic-mcp --stop
-```
-
-`--start` registers (if needed) and enables the MCP server entry. `--stop` disables it so the IDE won't immediately respawn it. Restart/reload the IDE after `--start` to launch.
+heuristic-mcp --start
+heuristic-mcp --start antigravity
+heuristic-mcp --start codex
+heuristic-mcp --start cursor
+heuristic-mcp --start vscode
+heuristic-mcp --start windsurf
+heuristic-mcp --start warp
+heuristic-mcp --start "Claude Desktop"
+heuristic-mcp --stop
+```
+
+`--start` registers (if needed) and enables the MCP server entry. `--stop` disables it so the IDE won't immediately respawn it. Restart/reload the IDE after `--start` to launch.
+
+Warp note: this package now targets `~/.warp/mcp_settings.json` (and `%APPDATA%\\Warp\\mcp_settings.json` on Windows when present). If no local Warp MCP config is writable yet, use Warp MCP settings/UI once to initialize it, then re-run `--start warp`.
 
 ### Clear Cache
 
@@ -97,33 +103,50 @@ Clears the cache for the current working directory (or `--workspace` if provided
 
 ## Configuration (`config.jsonc`)
 
-Configuration is loaded from your workspace root when the server runs with `--workspace` (this is how IDEs launch it). In server mode, it falls back to the package `config.jsonc` (or `config.json`) and then your current working directory.
-
-Example `config.jsonc`:
-
-```json
-{
-  "excludePatterns": ["**/legacy-code/**", "**/*.test.ts"],
-  "fileNames": ["Dockerfile", ".env.example", "Makefile"],
-  "smartIndexing": true,
-  "embeddingModel": "jinaai/jina-embeddings-v2-base-code",
-  "workerThreads": 0,
-  "embeddingBatchSize": null,
-  "embeddingProcessNumThreads": 8,
-  "enableExplicitGc": false,
-  "recencyBoost": 0.1,
-  "recencyDecayDays": 30,
-  "callGraphEnabled": true,
-  "callGraphBoost": 0.15,
-  "annEnabled": true,
-  "vectorStoreFormat": "binary",
-  "vectorStoreContentMode": "external",
-  "vectorStoreLoadMode": "disk",
-  "contentCacheEntries": 256,
-  "vectorCacheEntries": 64,
-  "clearCacheAfterIndex": true
-}
-```
+Configuration is loaded from your workspace root when the server runs with `--workspace`. If not provided by the IDE, the server auto-detects workspace via environment variables and current working directory. In server mode, it falls back to the package `config.jsonc` (or `config.json`) and then your current working directory.
+
+Example `config.jsonc`:
+
+```json
+{
+  "excludePatterns": ["**/legacy-code/**", "**/*.test.ts"],
+  "fileNames": ["Dockerfile", ".env.example", "Makefile"],
+  "indexing": {
+    "smartIndexing": true
+  },
+  "worker": {
+    "workerThreads": 0
+  },
+  "embedding": {
+    "embeddingModel": "jinaai/jina-embeddings-v2-base-code",
+    "embeddingBatchSize": null,
+    "embeddingProcessNumThreads": 8
+  },
+  "search": {
+    "recencyBoost": 0.1,
+    "recencyDecayDays": 30
+  },
+  "callGraph": {
+    "callGraphEnabled": true,
+    "callGraphBoost": 0.15
+  },
+  "ann": {
+    "annEnabled": true
+  },
+  "vectorStore": {
+    "vectorStoreFormat": "binary",
+    "vectorStoreContentMode": "external",
+    "vectorStoreLoadMode": "disk",
+    "contentCacheEntries": 256,
+    "vectorCacheEntries": 64
+  },
+  "memoryCleanup": {
+    "clearCacheAfterIndex": true
+  }
+}
+```
+
+Preferred style is namespaced keys (shown above). Legacy top-level keys are still supported for backward compatibility.
 
 ### Embedding Model & Dimension Options
 
@@ -133,12 +156,14 @@ Example `config.jsonc`:
 
 For faster search with smaller embeddings, switch to an MRL-compatible model:
 
-```json
-{
-  "embeddingModel": "nomic-ai/nomic-embed-text-v1.5",
-  "embeddingDimension": 128
-}
-```
+```json
+{
+  "embedding": {
+    "embeddingModel": "nomic-ai/nomic-embed-text-v1.5",
+    "embeddingDimension": 128
+  }
+}
+```
 
 **MRL-compatible models:**
 - `nomic-ai/nomic-embed-text-v1.5` — recommended for 128d/256d
@@ -153,7 +178,9 @@ Cache location:
 
 ### Environment Variables
 
-Selected overrides (prefix `SMART_CODING_`):
+Selected overrides (prefix `SMART_CODING_`):
+
+Environment overrides target runtime keys and are synced back into namespaces by `lib/config.js`.
 
 - `SMART_CODING_VERBOSE=true|false` — enable detailed logging.
 - `SMART_CODING_WORKER_THREADS=auto|N` — worker thread count.
@@ -179,35 +206,37 @@ Selected overrides (prefix `SMART_CODING_`):
 
 See `lib/config.js` for the full list.
 
-### Binary Vector Store
-
-Set `vectorStoreFormat` to `binary` to use the on-disk binary cache. This keeps vectors and content out of JS heap
-and reads on demand. Recommended for large repos.
-
-- `vectorStoreContentMode=external` keeps content in the binary file and only loads for top-N results.
-- `contentCacheEntries` controls the small in-memory LRU for decoded content strings.
-- `vectorStoreLoadMode=disk` streams vectors from disk to reduce memory usage.
-- `vectorCacheEntries` controls the small in-memory LRU for vectors when using disk mode.
-- `clearCacheAfterIndex=true` drops in-memory vectors after indexing and reloads lazily on next query.
-- `unloadModelAfterIndex=true` (default) unloads the embedding model after indexing to free ~500MB-1GB of RAM; the model will reload on the next search query.
-- Note: `annEnabled=true` with `vectorStoreLoadMode=disk` can increase disk reads during ANN rebuilds on large indexes.
+### Binary Vector Store
+
+Set `vectorStore.vectorStoreFormat` to `binary` to use the on-disk binary cache. This keeps vectors and content out of JS heap
+and reads on demand. Recommended for large repos.
+
+- `vectorStore.vectorStoreContentMode=external` keeps content in the binary file and only loads for top-N results.
+- `vectorStore.contentCacheEntries` controls the small in-memory LRU for decoded content strings.
+- `vectorStore.vectorStoreLoadMode=disk` streams vectors from disk to reduce memory usage.
+- `vectorStore.vectorCacheEntries` controls the small in-memory LRU for vectors when using disk mode.
+- `memoryCleanup.clearCacheAfterIndex=true` drops in-memory vectors after indexing and reloads lazily on next query.
+- `memoryCleanup.unloadModelAfterIndex=true` (default) unloads the embedding model after indexing to free ~500MB-1GB of RAM; the model will reload on the next search query.
+- Note: `ann.annEnabled=true` with `vectorStore.vectorStoreLoadMode=disk` can increase disk reads during ANN rebuilds on large indexes.
 
 ### SQLite Vector Store
 
-Set `vectorStoreFormat` to `sqlite` to use SQLite for persistence. This provides:
+Set `vectorStore.vectorStoreFormat` to `sqlite` to use SQLite for persistence. This provides:
 
 - ACID transactions for reliable writes
 - Simpler concurrent access
 - Standard database format for inspection
 
-```json
-{
-  "vectorStoreFormat": "sqlite"
-}
-```
-
-The vectors and content are stored in `vectors.sqlite` in your cache directory. You can inspect it with any SQLite browser.
-`vectorStoreContentMode` and `vectorStoreLoadMode` are respected for SQLite (use `vectorStoreLoadMode=disk` to avoid loading vectors into memory).
+```json
+{
+  "vectorStore": {
+    "vectorStoreFormat": "sqlite"
+  }
+}
+```
+
+The vectors and content are stored in `vectors.sqlite` in your cache directory. You can inspect it with any SQLite browser.
+`vectorStore.vectorStoreContentMode` and `vectorStore.vectorStoreLoadMode` are respected for SQLite (use `vectorStore.vectorStoreLoadMode=disk` to avoid loading vectors into memory).
 
 **Tradeoffs vs Binary:**
 - Slightly higher read overhead (SQL queries vs direct memory access)
@@ -230,7 +259,7 @@ SMART_CODING_VECTOR_STORE_LOAD_MODE=disk node tools/scripts/benchmark-search.js
 SMART_CODING_VECTOR_STORE_FORMAT=binary SMART_CODING_VECTOR_STORE_LOAD_MODE=disk node tools/scripts/benchmark-search.js --runs 10
 ```
 
-Note: On small repos, disk mode may be slightly slower and show noisy RSS deltas; benefits are clearer on large indexes with a small `vectorCacheEntries`.
+Note: On small repos, disk mode may be slightly slower and show noisy RSS deltas; benefits are clearer on large indexes with a small `vectorStore.vectorCacheEntries`.
 
 ---
 
@@ -268,12 +297,14 @@ Fetch the latest version of a package from its official registry.
 - **Homebrew**: `brew:node`
 - **Conda**: `conda:numpy`
 
-### `f_set_workspace`
-Change the workspace directory at runtime. Updates search directory, cache location, and optionally triggers reindex.
-
-**Parameters:**
-- `workspacePath` (required): Absolute path to the new workspace
-- `reindex` (optional, default: `true`): Whether to trigger a full reindex
+### `f_set_workspace`
+Change the workspace directory at runtime. Updates search directory, cache location, and optionally triggers reindex.
+
+The server also attempts this automatically before each tool call when it detects a new workspace path from environment variables (for example `CODEX_WORKSPACE`, `CODEX_PROJECT_ROOT`, `WORKSPACE_FOLDER`).
+
+**Parameters:**
+- `workspacePath` (required): Absolute path to the new workspace
+- `reindex` (optional, default: `true`): Whether to trigger a full reindex
 
 ---
 
@@ -293,8 +324,8 @@ Native ONNX backend unavailable: The operating system cannot run %1.
 ...onnxruntime_binding.node. Falling back to WASM.
 ```
 
-The server will automatically disable workers and force `embeddingProcessPerBatch` to reduce memory spikes, but you
-should fix the native binding to restore stable memory usage:
+The server will automatically disable workers and force `embedding.embeddingProcessPerBatch` to reduce memory spikes, but you
+should fix the native binding to restore stable memory usage:
 
 - Ensure you are running **64-bit Node.js** (`node -p "process.arch"` should be `x64`).
 - Install **Microsoft Visual C++ 2015–2022 Redistributable (x64)**.
@@ -334,7 +365,7 @@ node tools/scripts/cache-stats.js --workspace <path>
 
 **Stop doesn't stick**
 
-- The IDE will auto-restart the server if it's still enabled in its config. `--stop` now disables the server entry for Antigravity, Cursor, Claude Desktop, and VS Code (when using common MCP settings keys). Restart the IDE after `--start` to re-enable.
+- The IDE will auto-restart the server if it's still enabled in its config. `--stop` now disables the server entry for Antigravity, Cursor (including `~/.cursor/mcp.json`), Windsurf (`~/.codeium/windsurf/mcp_config.json`), Warp (`~/.warp/mcp_settings.json` and `%APPDATA%\\Warp\\mcp_settings.json` when present), Claude Desktop, and VS Code (when using common MCP settings keys). Restart the IDE after `--start` to re-enable.
 
 ---
 

package/index.js

@@ -50,17 +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 * 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 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);
@@ -118,12 +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 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 = [
@@ -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);
@@ -379,25 +443,26 @@ 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
-  );
-  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;
 
-  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 };
 }
@@ -465,10 +530,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools };
 });
 
-// Handle tool calls
-server.setRequestHandler(CallToolRequestSchema, async (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/cli.js

@@ -16,7 +16,7 @@ Options:
   --mem                    Show last memory snapshot from logs (requires verbose logging)
   --tail <lines>           Lines to show with --logs (default: ${defaultTailLines})
   --no-follow              Do not follow log output with --logs
-  --start [ide]            Register + enable in IDE config (antigravity|cursor|"Claude Desktop")
+  --start [ide]            Register + enable in IDE config (antigravity|codex|cursor|vscode|windsurf|warp|"Claude Desktop")
   --stop                   Stop running server instances
   --workspace <path>       Workspace path (used by IDE launch / log viewer)
   --version, -v            Show version

package/lib/config.js

@@ -3,13 +3,14 @@ import path from 'path';
 import os from 'os';
 import crypto from 'crypto';
 import { fileURLToPath } from 'url';
-import { ProjectDetector } from './project-detector.js';
-import { parseJsonc } from './settings-editor.js';
+import { ProjectDetector } from './project-detector.js';
+import { parseJsonc } from './settings-editor.js';
 import {
   EMBEDDING_PROCESS_DEFAULT_GC_MAX_REQUESTS_WITHOUT_COLLECTION,
   EMBEDDING_PROCESS_DEFAULT_GC_MIN_INTERVAL_MS,
   EMBEDDING_PROCESS_DEFAULT_GC_RSS_THRESHOLD_MB,
 } from './constants.js';
+import { getWorkspaceEnvKeys } from './workspace-env.js';
 
 const DEFAULT_MEMORY_CLEANUP_CONFIG = {
   enableExplicitGc: true, // Require --expose-gc for more aggressive memory cleanup
@@ -455,18 +456,7 @@ const DEFAULT_CONFIG = {
   ann: { ...DEFAULT_ANN_CONFIG },
 };
 
-let config = { ...DEFAULT_CONFIG };
-
-const WORKSPACE_ENV_VARS = [
-  'HEURISTIC_MCP_WORKSPACE',
-  'MCP_WORKSPACE',
-  'WORKSPACE_FOLDER',
-  'WORKSPACE_ROOT',
-  'CURSOR_WORKSPACE',
-  'CLAUDE_WORKSPACE',
-  'ANTIGRAVITY_WORKSPACE',
-  'INIT_CWD',
-];
+let config = { ...DEFAULT_CONFIG };
 
 const WORKSPACE_MARKERS = [
   '.git',
@@ -612,7 +602,7 @@ async function readConfigFile(filePath) {
   }
 }
 
-async function findWorkspaceRoot(startDir) {
+async function findWorkspaceRoot(startDir) {
   let current = path.resolve(startDir);
   while (true) {
     for (const marker of WORKSPACE_MARKERS) {
@@ -624,43 +614,113 @@ async function findWorkspaceRoot(startDir) {
     if (parent === current) break;
     current = parent;
   }
-  return path.resolve(startDir);
-}
-
-async function resolveWorkspaceDir(workspaceDir) {
-  if (workspaceDir) return path.resolve(workspaceDir);
-  if (process.env.VITEST === 'true' || process.env.NODE_ENV === 'test') {
-    return path.resolve(process.cwd());
-  }
-
-  for (const key of WORKSPACE_ENV_VARS) {
-    const value = process.env[key];
-    if (!value || value.includes('${')) continue;
-    const candidate = path.resolve(value);
-    if (await pathExists(candidate)) return candidate;
-  }
-
-  return await findWorkspaceRoot(process.cwd());
-}
-
-export async function loadConfig(workspaceDir = null) {
-  try {
+  return path.resolve(startDir);
+}
+
+async function resolveWorkspaceCandidate(rawValue) {
+  if (!rawValue || rawValue.includes('${')) return null;
+  const candidate = path.resolve(rawValue);
+  if (!(await pathExists(candidate))) return null;
+  try {
+    const stats = await fs.stat(candidate);
+    if (!stats.isDirectory()) return null;
+  } catch {
+    return null;
+  }
+  return candidate;
+}
+
+function logWorkspaceResolution(resolution) {
+  if (!resolution || !resolution.path) return;
+
+  if (resolution.source === 'workspace-arg') {
+    console.info(`[Config] Workspace resolution: --workspace -> ${resolution.path}`);
+    return;
+  }
+
+  if (resolution.source === 'env' && resolution.envKey) {
+    console.info(`[Config] Workspace resolution: env ${resolution.envKey} -> ${resolution.path}`);
+    return;
+  }
+
+  if (resolution.source === 'test-cwd') {
+    console.info(`[Config] Workspace resolution: process.cwd() (test mode) -> ${resolution.path}`);
+    return;
+  }
+
+  if (resolution.source === 'cwd-root-search') {
+    const from = resolution.fromPath || process.cwd();
+    console.info(
+      `[Config] Workspace resolution: workspace root from cwd (${from}) -> ${resolution.path}`
+    );
+    return;
+  }
+
+  console.info(`[Config] Workspace resolution: process.cwd() -> ${resolution.path}`);
+}
+
+async function resolveWorkspaceDir(workspaceDir) {
+  if (workspaceDir) {
+    return {
+      path: path.resolve(workspaceDir),
+      source: 'workspace-arg',
+    };
+  }
+  if (process.env.VITEST === 'true' || process.env.NODE_ENV === 'test') {
+    return {
+      path: path.resolve(process.cwd()),
+      source: 'test-cwd',
+    };
+  }
+
+  for (const key of getWorkspaceEnvKeys()) {
+    const candidate = await resolveWorkspaceCandidate(process.env[key]);
+    if (candidate) {
+      return {
+        path: candidate,
+        source: 'env',
+        envKey: key,
+      };
+    }
+  }
+
+  const cwd = path.resolve(process.cwd());
+  const root = await findWorkspaceRoot(cwd);
+  if (root !== cwd) {
+    return {
+      path: root,
+      source: 'cwd-root-search',
+      fromPath: cwd,
+    };
+  }
+  return {
+    path: cwd,
+    source: 'cwd',
+  };
+}
+
+export async function loadConfig(workspaceDir = null) {
+  try {
     // Determine the base directory for configuration
     let baseDir;
     let configPath;
-
-    let serverDir = null;
-    if (workspaceDir) {
-      // Workspace mode: load config from workspace root
-      baseDir = path.resolve(workspaceDir);
-      console.info(`[Config] Workspace mode: ${baseDir}`);
-    } else {
-      // Server mode: load config from server directory for global settings,
-      // but use process.cwd() as base for searching if not specified otherwise
-      const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-      serverDir = path.resolve(scriptDir, '..');
-      baseDir = await resolveWorkspaceDir(null);
-    }
+
+    let serverDir = null;
+    if (workspaceDir) {
+      // Workspace mode: load config from workspace root
+      const workspaceResolution = await resolveWorkspaceDir(workspaceDir);
+      baseDir = workspaceResolution.path;
+      console.info(`[Config] Workspace mode: ${baseDir}`);
+      logWorkspaceResolution(workspaceResolution);
+    } else {
+      // Server mode: load config from server directory for global settings,
+      // but use process.cwd() as base for searching if not specified otherwise
+      const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+      serverDir = path.resolve(scriptDir, '..');
+      const workspaceResolution = await resolveWorkspaceDir(null);
+      baseDir = workspaceResolution.path;
+      logWorkspaceResolution(workspaceResolution);
+    }
 
     let userConfig = {};
     const configNames = ['config.jsonc', 'config.json'];

package/lib/constants.js

@@ -1,11 +1,42 @@
-/**
- * Centralized constants for the heuristic-mcp project.
- * Extracting magic numbers improves maintainability and documents design decisions.
- */
-
-// ================================
-// Chunking Constants
-// ================================
+/**
+ * Centralized constants for the heuristic-mcp project.
+ * Extracting magic numbers improves maintainability and documents design decisions.
+ */
+
+// ================================
+// Workspace Resolution Constants
+// ================================
+
+/**
+ * Environment variables checked for workspace resolution, in precedence order.
+ */
+export const WORKSPACE_ENV_VARS = Object.freeze([
+  'HEURISTIC_MCP_WORKSPACE',
+  'MCP_WORKSPACE',
+  'CODEX_WORKSPACE',
+  'CODEX_PROJECT_ROOT',
+  'CODEX_CWD',
+  'WORKSPACE_FOLDER',
+  'WORKSPACE_ROOT',
+  'CURSOR_WORKSPACE',
+  'CLAUDE_WORKSPACE',
+  'ANTIGRAVITY_WORKSPACE',
+  'INIT_CWD',
+]);
+
+/**
+ * Prefix for dynamic workspace-related env vars (provider-specific).
+ */
+export const DYNAMIC_WORKSPACE_ENV_PREFIX = 'CODEX_';
+
+/**
+ * Pattern used when ranking provider-specific workspace env vars.
+ */
+export const WORKSPACE_ENV_KEY_PATTERN = /(WORKSPACE|PROJECT|ROOT|CWD|DIR)/i;
+
+// ================================
+// Chunking Constants
+// ================================
 
 /**
  * Minimum text length for a chunk to be considered valid.

package/lib/settings-editor.js

@@ -469,14 +469,23 @@ function replaceRange(text, start, end, replacement) {
   return text.slice(0, start) + replacement + text.slice(end);
 }
 
-function resolveContainer(text, rootRange) {
-  const containers = [
+function resolveContainer(text, rootRange, preferredContainerKey = 'mcpServers') {
+  const baseContainers = [
     { type: 'key', key: 'mcpServers' },
+    { type: 'key', key: 'servers' },
     { type: 'key', key: 'cline.mcpServers' },
     { type: 'nested', key: 'cline', child: 'mcpServers' },
   ];
 
-  for (const candidate of containers) {
+  const preferredIndex = baseContainers.findIndex(
+    (candidate) => candidate.type === 'key' && candidate.key === preferredContainerKey
+  );
+  if (preferredIndex > 0) {
+    const [preferred] = baseContainers.splice(preferredIndex, 1);
+    baseContainers.unshift(preferred);
+  }
+
+  for (const candidate of baseContainers) {
     if (candidate.type === 'key') {
       const entry = findPropertyValueRange(text, rootRange, candidate.key);
       if (entry) {
@@ -517,14 +526,19 @@ function resolveContainer(text, rootRange) {
   return null;
 }
 
-export function upsertMcpServerEntryInText(text, serverName, serverConfig) {
+export function upsertMcpServerEntryInText(
+  text,
+  serverName,
+  serverConfig,
+  preferredContainerKey = 'mcpServers'
+) {
   const newline = detectNewline(text);
   const indentUnit = detectIndentUnit(text);
   const trimmed = text.trim();
 
   if (!trimmed) {
     const payload = {
-      mcpServers: {
+      [preferredContainerKey]: {
         [serverName]: serverConfig,
       },
     };
@@ -536,7 +550,7 @@ export function upsertMcpServerEntryInText(text, serverName, serverConfig) {
     return null;
   }
 
-  const container = resolveContainer(text, rootRange);
+  const container = resolveContainer(text, rootRange, preferredContainerKey);
 
   if (!container) {
     const objectIndent = getLineIndent(text, rootRange.start);
@@ -547,7 +561,14 @@ export function upsertMcpServerEntryInText(text, serverName, serverConfig) {
       propertyIndent,
       newline
     );
-    return insertPropertyIntoObject(text, rootRange, 'mcpServers', valueText, indentUnit, newline);
+    return insertPropertyIntoObject(
+      text,
+      rootRange,
+      preferredContainerKey,
+      valueText,
+      indentUnit,
+      newline
+    );
   }
 
   if (container.needsObjectReplace) {
@@ -622,6 +643,9 @@ export function findMcpServerEntry(config, serverName) {
   if (config.mcpServers && config.mcpServers[serverName]) {
     return { containerKey: 'mcpServers', entry: config.mcpServers[serverName] };
   }
+  if (config.servers && config.servers[serverName]) {
+    return { containerKey: 'servers', entry: config.servers[serverName] };
+  }
   if (config['cline.mcpServers'] && config['cline.mcpServers'][serverName]) {
     return {
       containerKey: 'cline.mcpServers',
@@ -636,3 +660,95 @@ export function findMcpServerEntry(config, serverName) {
   }
   return null;
 }
+
+function formatTomlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function formatTomlArray(values) {
+  const list = Array.isArray(values) ? values : [];
+  return `[${list.map((value) => formatTomlString(value)).join(', ')}]`;
+}
+
+function formatTomlMcpSection(serverName, serverConfig, newline) {
+  const lines = [`[mcp_servers.${serverName}]`];
+  if (serverConfig.command !== undefined) {
+    lines.push(`command = ${formatTomlString(serverConfig.command)}`);
+  }
+  if (serverConfig.args !== undefined) {
+    lines.push(`args = ${formatTomlArray(serverConfig.args)}`);
+  }
+  if (serverConfig.disabled !== undefined) {
+    lines.push(`disabled = ${serverConfig.disabled ? 'true' : 'false'}`);
+  }
+  return lines.join(newline);
+}
+
+function findTomlSectionRange(source, sectionName) {
+  const headerRegex = /^\s*\[([^\]\r\n]+)\]\s*$/gm;
+  let start = -1;
+  let end = source.length;
+  let match;
+
+  while ((match = headerRegex.exec(source)) !== null) {
+    const currentSection = String(match[1] || '').trim();
+    if (start === -1) {
+      if (currentSection === sectionName) {
+        start = match.index;
+      }
+      continue;
+    }
+
+    end = match.index;
+    break;
+  }
+
+  if (start === -1) {
+    return null;
+  }
+
+  return { start, end };
+}
+
+export function upsertMcpServerEntryInToml(text, serverName, serverConfig) {
+  const source = String(text || '');
+  const newline = detectNewline(source || '\n');
+  const section = formatTomlMcpSection(serverName, serverConfig, newline);
+  const sectionName = `mcp_servers.${serverName}`;
+  const range = findTomlSectionRange(source, sectionName);
+
+  if (!source.trim()) {
+    return `${section}${newline}`;
+  }
+
+  if (range) {
+    const before = source.slice(0, range.start);
+    const after = source.slice(range.end).replace(/^\s*\r?\n?/, '');
+    const normalizedBefore =
+      before.endsWith('\n') || before.endsWith('\r') || !before ? before : `${before}${newline}`;
+    const between = after ? newline : '';
+    return `${normalizedBefore}${section}${between}${after}`;
+  }
+
+  const withTrailingNewline = source.endsWith('\n') || source.endsWith('\r') ? source : `${source}${newline}`;
+  return `${withTrailingNewline}${newline}${section}${newline}`;
+}
+
+export function setMcpServerDisabledInToml(text, serverName, disabled) {
+  const source = String(text || '');
+  const sectionName = `mcp_servers.${serverName}`;
+  const range = findTomlSectionRange(source, sectionName);
+
+  if (!range) {
+    return source;
+  }
+
+  const sectionBlock = source.slice(range.start, range.end);
+  const newline = detectNewline(sectionBlock || '\n');
+  const disabledLine = `disabled = ${disabled ? 'true' : 'false'}`;
+  const updatedSection = /^\s*disabled\s*=.*$/m.test(sectionBlock)
+    ? sectionBlock.replace(/^\s*disabled\s*=.*$/m, disabledLine)
+    : `${sectionBlock.trimEnd()}${newline}${disabledLine}${newline}`;
+
+  return `${source.slice(0, range.start)}${updatedSection}${source.slice(range.end)}`;
+}

package/lib/workspace-env.js

@@ -0,0 +1,28 @@
+import {
+  DYNAMIC_WORKSPACE_ENV_PREFIX,
+  WORKSPACE_ENV_KEY_PATTERN,
+  WORKSPACE_ENV_VARS,
+} from './constants.js';
+
+export function scoreWorkspaceEnvKey(key) {
+  const upper = String(key || '').toUpperCase();
+  let score = 0;
+  if (upper.includes('WORKSPACE')) score += 8;
+  if (upper.includes('PROJECT')) score += 4;
+  if (upper.includes('ROOT')) score += 3;
+  if (upper.includes('CWD')) score += 2;
+  if (upper.includes('DIR')) score += 1;
+  return score;
+}
+
+export function getDynamicWorkspaceEnvKeys(env = process.env) {
+  return Object.keys(env)
+    .filter((key) => key.startsWith(DYNAMIC_WORKSPACE_ENV_PREFIX))
+    .filter((key) => WORKSPACE_ENV_KEY_PATTERN.test(key))
+    .filter((key) => !WORKSPACE_ENV_VARS.includes(key))
+    .sort((a, b) => scoreWorkspaceEnvKey(b) - scoreWorkspaceEnvKey(a));
+}
+
+export function getWorkspaceEnvKeys(env = process.env) {
+  return [...WORKSPACE_ENV_VARS, ...getDynamicWorkspaceEnvKeys(env)];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softerist/heuristic-mcp",
-  "version": "3.0.13",
+  "version": "3.0.15",
   "description": "An enhanced MCP server providing intelligent semantic code search with find-similar-code, recency ranking, and improved chunking. Fork of smart-coding-mcp.",
   "type": "module",
   "main": "index.js",