@grafema/mcp 0.1.0-alpha.5 → 0.1.1-alpha

package/dist/analysis-worker.js

@@ -131,7 +131,11 @@ async function run() {
         console.log(`[Worker] Connecting to RFDB server: socket=${socketPath}, db=${dbPath}`);
         db = new RFDBServerBackend({ socketPath, dbPath });
         await db.connect();
-        await db.clear();
+        // NOTE: db.clear() is NOT called here.
+        // MCP server clears DB INSIDE the analysis lock BEFORE spawning this worker.
+        // This prevents race conditions where concurrent analysis calls could both
+        // clear the database. Worker assumes DB is already clean.
+        // See: REG-159 implementation, Phase 2.5 (Worker Clear Coordination)
         sendProgress({ phase: 'discovery', message: 'Starting analysis...' });
         // Create orchestrator
         const orchestrator = new Orchestrator({

package/dist/analysis.d.ts

@@ -3,9 +3,19 @@
  */
 import type { GraphBackend } from '@grafema/types';
 /**
- * Ensure project is analyzed, optionally filtering to a single service
+ * Ensure project is analyzed, optionally filtering to a single service.
+ *
+ * CONCURRENCY: This function is protected by a global mutex.
+ * - Only one analysis can run at a time
+ * - Concurrent calls wait for the current analysis to complete
+ * - force=true while analysis is running returns an error immediately
+ *
+ * @param serviceName - Optional service to analyze (null = all)
+ * @param force - If true, clear DB and re-analyze even if already analyzed.
+ *                ERROR if another analysis is already running.
+ * @throws Error if force=true and analysis is already running
  */
-export declare function ensureAnalyzed(serviceName?: string | null): Promise<GraphBackend>;
+export declare function ensureAnalyzed(serviceName?: string | null, force?: boolean): Promise<GraphBackend>;
 /**
  * Discover services without running full analysis
  */

package/dist/analysis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analysis.d.ts","sourceRoot":"","sources":["../src/analysis.ts"],"names":[],"mappings":"AAAA;;GAEG;AAaH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;GAEG;AACH,wBAAsB,cAAc,CAAC,WAAW,GAAE,MAAM,GAAG,IAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CA2F7F;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAyC3D"}
+{"version":3,"file":"analysis.d.ts","sourceRoot":"","sources":["../src/analysis.ts"],"names":[],"mappings":"AAAA;;GAEG;AAeH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,WAAW,GAAE,MAAM,GAAG,IAAW,EACjC,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,YAAY,CAAC,CAwGvB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAyC3D"}

package/dist/analysis.js

@@ -2,42 +2,57 @@
  * MCP Analysis Orchestration
  */
 import { Orchestrator } from '@grafema/core';
-import { getOrCreateBackend, getProjectPath, getIsAnalyzed, setIsAnalyzed, getAnalysisStatus, setAnalysisStatus, } from './state.js';
-import { loadConfig, loadCustomPlugins, BUILTIN_PLUGINS } from './config.js';
+import { getOrCreateBackend, getProjectPath, getIsAnalyzed, setIsAnalyzed, getAnalysisStatus, setAnalysisStatus, isAnalysisRunning, acquireAnalysisLock, } from './state.js';
+import { loadConfig, loadCustomPlugins, createPlugins } from './config.js';
 import { log } from './utils.js';
 /**
- * Ensure project is analyzed, optionally filtering to a single service
+ * Ensure project is analyzed, optionally filtering to a single service.
+ *
+ * CONCURRENCY: This function is protected by a global mutex.
+ * - Only one analysis can run at a time
+ * - Concurrent calls wait for the current analysis to complete
+ * - force=true while analysis is running returns an error immediately
+ *
+ * @param serviceName - Optional service to analyze (null = all)
+ * @param force - If true, clear DB and re-analyze even if already analyzed.
+ *                ERROR if another analysis is already running.
+ * @throws Error if force=true and analysis is already running
  */
-export async function ensureAnalyzed(serviceName = null) {
+export async function ensureAnalyzed(serviceName = null, force = false) {
     const db = await getOrCreateBackend();
     const projectPath = getProjectPath();
-    const isAnalyzed = getIsAnalyzed();
-    if (!isAnalyzed || serviceName) {
+    // CONCURRENCY CHECK: If force=true and analysis is running, error immediately
+    // This check is BEFORE acquiring lock to fail fast
+    if (force && isAnalysisRunning()) {
+        throw new Error('Analysis is already in progress. Cannot force re-analysis while another analysis is running. ' +
+            'Wait for the current analysis to complete or check status with get_analysis_status.');
+    }
+    // Skip if already analyzed (and not forcing, and no service filter)
+    if (getIsAnalyzed() && !serviceName && !force) {
+        return db;
+    }
+    // Acquire lock (waits if another analysis is running)
+    const releaseLock = await acquireAnalysisLock();
+    try {
+        // Double-check after acquiring lock (another call might have completed analysis while we waited)
+        if (getIsAnalyzed() && !serviceName && !force) {
+            return db;
+        }
+        // Clear DB inside lock, BEFORE running analysis
+        // This is critical for worker coordination: MCP server clears DB here,
+        // worker does NOT call db.clear() (see analysis-worker.ts)
+        if (force || !getIsAnalyzed()) {
+            log('[Grafema MCP] Clearing database before analysis...');
+            if (db.clear) {
+                await db.clear();
+            }
+            setIsAnalyzed(false);
+        }
         log(`[Grafema MCP] Analyzing project: ${projectPath}${serviceName ? ` (service: ${serviceName})` : ''}`);
         const config = loadConfig(projectPath);
         const { pluginMap: customPluginMap } = await loadCustomPlugins(projectPath);
-        // Merge builtin and custom plugins
-        const availablePlugins = {
-            ...BUILTIN_PLUGINS,
-            ...Object.fromEntries(Object.entries(customPluginMap).map(([name, PluginClass]) => [
-                name,
-                () => new PluginClass(),
-            ])),
-        };
-        // Build plugin list from config
-        const plugins = [];
-        for (const [phase, pluginNames] of Object.entries(config.plugins || {})) {
-            for (const name of pluginNames) {
-                const factory = availablePlugins[name];
-                if (factory) {
-                    plugins.push(factory());
-                    log(`[Grafema MCP] Enabled plugin: ${name} (${phase})`);
-                }
-                else {
-                    log(`[Grafema MCP] Warning: Unknown plugin ${name} in config`);
-                }
-            }
-        }
+        // Create plugins from config
+        const plugins = createPlugins(config.plugins, customPluginMap);
         log(`[Grafema MCP] Total plugins: ${plugins.length}`);
         // Check for parallel analysis config
         const parallelConfig = config.analysis?.parallel;
@@ -75,9 +90,13 @@ export async function ensureAnalyzed(serviceName = null) {
                 total: parseFloat(totalTime),
             },
         });
-        log(`[Grafema MCP] ✅ Analysis complete in ${totalTime}s`);
+        log(`[Grafema MCP] Analysis complete in ${totalTime}s`);
+        return db;
+    }
+    finally {
+        // ALWAYS release the lock, even on error
+        releaseLock();
     }
-    return db;
 }
 /**
  * Discover services without running full analysis
@@ -95,7 +114,7 @@ export async function discoverServices() {
         ])),
     };
     const plugins = [];
-    const discoveryPluginNames = config.plugins?.discovery || [];
+    const discoveryPluginNames = config.plugins.discovery ?? [];
     for (const name of discoveryPluginNames) {
         const factory = availablePlugins[name];
         if (factory) {

package/dist/config.d.ts

@@ -1,16 +1,12 @@
 /**
  * MCP Server Configuration
  */
-export interface PluginConfig {
-    indexing: string[];
-    analysis: string[];
-    enrichment: string[];
-    validation: string[];
-    discovery?: string[];
-}
-export interface ProjectConfig {
-    plugins: PluginConfig;
-    discovery: {
+import { type GrafemaConfig } from '@grafema/core';
+/**
+ * MCP-specific configuration extends GrafemaConfig with additional fields.
+ */
+export interface MCPConfig extends GrafemaConfig {
+    discovery?: {
         enabled: boolean;
         customOnly: boolean;
     };
@@ -20,15 +16,18 @@ export interface ProjectConfig {
     backend?: 'local' | 'rfdb';
     rfdb_socket?: string;
 }
-export declare const DEFAULT_CONFIG: ProjectConfig;
 type PluginFactory = () => unknown;
 export declare const BUILTIN_PLUGINS: Record<string, PluginFactory>;
-export declare function loadConfig(projectPath: string): ProjectConfig;
+/**
+ * Load MCP configuration (extends base GrafemaConfig).
+ * Uses shared ConfigLoader but adds MCP-specific defaults.
+ */
+export declare function loadConfig(projectPath: string): MCPConfig;
 export interface CustomPluginResult {
     plugins: unknown[];
     pluginMap: Record<string, new () => unknown>;
 }
 export declare function loadCustomPlugins(projectPath: string): Promise<CustomPluginResult>;
-export declare function createPlugins(pluginNames: string[], customPluginMap?: Record<string, new () => unknown>): unknown[];
+export declare function createPlugins(config: GrafemaConfig['plugins'], customPluginMap?: Record<string, new () => unknown>): unknown[];
 export {};
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AA0CH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE;QACT,OAAO,EAAE,OAAO,CAAC;QACjB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,cAAc,EAAE,aAiC5B,CAAC;AAGF,KAAK,aAAa,GAAG,MAAM,OAAO,CAAC;AAEnC,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAiCzD,CAAC;AAGF,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CA2B7D;AAGD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,OAAO,CAAC,CAAC;CAC9C;AAED,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAoCxF;AAGD,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EAAE,EACrB,eAAe,GAAE,MAAM,CAAC,MAAM,EAAE,UAAU,OAAO,CAAM,GACtD,OAAO,EAAE,CAuBX"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAoCrF;;GAEG;AACH,MAAM,WAAW,SAAU,SAAQ,aAAa;IAC9C,SAAS,CAAC,EAAE;QACV,OAAO,EAAE,OAAO,CAAC;QACjB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAUD,KAAK,aAAa,GAAG,MAAM,OAAO,CAAC;AAEnC,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAiCzD,CAAC;AAGF;;;GAGG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAWzD;AAGD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,OAAO,CAAC,CAAC;CAC9C;AAED,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAoCxF;AAGD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,EAChC,eAAe,GAAE,MAAM,CAAC,MAAM,EAAE,UAAU,OAAO,CAAM,GACtD,OAAO,EAAE,CA8BX"}

package/dist/config.js

@@ -2,9 +2,10 @@
  * MCP Server Configuration
  */
 import { join } from 'path';
-import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { existsSync, readdirSync } from 'fs';
 import { pathToFileURL } from 'url';
 import { log } from './utils.js';
+import { loadConfig as loadConfigFromCore } from '@grafema/core';
 // === PLUGIN IMPORTS ===
 import { 
 // Indexing
@@ -15,35 +16,7 @@ JSASTAnalyzer, ExpressRouteAnalyzer, SocketIOAnalyzer, DatabaseAnalyzer, FetchAn
 MethodCallResolver, AliasTracker, ValueDomainAnalyzer, MountPointResolver, PrefixEvaluator, InstanceOfResolver, HTTPConnectionEnricher, RustFFIEnricher, 
 // Validation
 CallResolverValidator, EvalBanValidator, SQLInjectionValidator, ShadowingDetector, GraphConnectivityValidator, DataFlowValidator, TypeScriptDeadCodeValidator, } from '@grafema/core';
-export const DEFAULT_CONFIG = {
-    plugins: {
-        indexing: ['JSModuleIndexer'],
-        analysis: [
-            'JSASTAnalyzer',
-            'ExpressRouteAnalyzer',
-            'SocketIOAnalyzer',
-            'DatabaseAnalyzer',
-            'FetchAnalyzer',
-            'ServiceLayerAnalyzer',
-        ],
-        enrichment: [
-            'MethodCallResolver',
-            'AliasTracker',
-            'ValueDomainAnalyzer',
-            'MountPointResolver',
-            'PrefixEvaluator',
-            'HTTPConnectionEnricher',
-        ],
-        validation: [
-            'CallResolverValidator',
-            'EvalBanValidator',
-            'SQLInjectionValidator',
-            'ShadowingDetector',
-            'GraphConnectivityValidator',
-            'DataFlowValidator',
-            'TypeScriptDeadCodeValidator',
-        ],
-    },
+const MCP_DEFAULTS = {
     discovery: {
         enabled: true,
         customOnly: false,
@@ -81,33 +54,20 @@ export const BUILTIN_PLUGINS = {
     TypeScriptDeadCodeValidator: () => new TypeScriptDeadCodeValidator(),
 };
 // === CONFIG LOADING ===
+/**
+ * Load MCP configuration (extends base GrafemaConfig).
+ * Uses shared ConfigLoader but adds MCP-specific defaults.
+ */
 export function loadConfig(projectPath) {
-    const configPath = join(projectPath, '.grafema', 'config.json');
-    if (!existsSync(configPath)) {
-        try {
-            const grafemaDir = join(projectPath, '.grafema');
-            if (!existsSync(grafemaDir)) {
-                const { mkdirSync } = require('fs');
-                mkdirSync(grafemaDir, { recursive: true });
-            }
-            writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2));
-            log(`[Grafema MCP] Created default config: ${configPath}`);
-        }
-        catch (err) {
-            log(`[Grafema MCP] Failed to create config: ${err.message}`);
-        }
-        return DEFAULT_CONFIG;
-    }
-    try {
-        const configContent = readFileSync(configPath, 'utf-8');
-        const config = JSON.parse(configContent);
-        log(`[Grafema MCP] Loaded config from ${configPath}`);
-        return { ...DEFAULT_CONFIG, ...config };
-    }
-    catch (err) {
-        log(`[Grafema MCP] Failed to load config: ${err.message}, using defaults`);
-        return DEFAULT_CONFIG;
-    }
+    // Use shared loader (handles YAML/JSON, deprecation warnings)
+    const baseConfig = loadConfigFromCore(projectPath, {
+        warn: (msg) => log(`[Grafema MCP] ${msg}`),
+    });
+    // Add MCP-specific defaults
+    return {
+        ...baseConfig,
+        ...MCP_DEFAULTS,
+    };
 }
 export async function loadCustomPlugins(projectPath) {
     const pluginsDir = join(projectPath, '.grafema', 'plugins');
@@ -142,7 +102,13 @@ export async function loadCustomPlugins(projectPath) {
     return { plugins: customPlugins, pluginMap };
 }
 // === PLUGIN INSTANTIATION ===
-export function createPlugins(pluginNames, customPluginMap = {}) {
+export function createPlugins(config, customPluginMap = {}) {
+    const pluginNames = [
+        ...config.indexing,
+        ...config.analysis,
+        ...config.enrichment,
+        ...config.validation,
+    ];
     const plugins = [];
     const availablePlugins = {
         ...BUILTIN_PLUGINS,

package/dist/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAcH,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,EAGrB,MAAM,YAAY,CAAC;AAKpB,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CA8EhF;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CA2E9E;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAiD9E;AAID,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CA2DhF;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CA+DtF;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CA4CxF;AAID,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CAoBxF;AAED,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,UAAU,CAAC,CAYnE;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,UAAU,CAAC,CAe1D;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAwB9E;AAID;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CA6D1F;AAED;;GAEG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,UAAU,CAAC,CAyChE;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAwG1F;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CA8B1F;AAID,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAalF;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CAwE5F;AAID,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,OAAO,YAAY,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAkEvG"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAeH,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,EAGrB,MAAM,YAAY,CAAC;AAKpB,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CA8EhF;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CA2E9E;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAiD9E;AAID,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CA2DhF;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CA+DtF;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CA4CxF;AAID,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CA4BxF;AAED,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,UAAU,CAAC,CAYnE;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,UAAU,CAAC,CAe1D;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAwB9E;AAID;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CA6D1F;AAED;;GAEG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,UAAU,CAAC,CAyChE;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAwG1F;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CA8B1F;AAID,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAqClF;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CAwE5F;AAID,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,OAAO,YAAY,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAkEvG"}

package/dist/handlers.js

@@ -2,7 +2,8 @@
  * MCP Tool Handlers
  */
 import { ensureAnalyzed } from './analysis.js';
-import { getProjectPath, getAnalysisStatus, setIsAnalyzed, getOrCreateBackend, getGuaranteeManager, getGuaranteeAPI } from './state.js';
+import { getProjectPath, getAnalysisStatus, getOrCreateBackend, getGuaranteeManager, getGuaranteeAPI, isAnalysisRunning } from './state.js';
+import { CoverageAnalyzer } from '@grafema/core';
 import { normalizeLimit, formatPaginationInfo, guardResponseSize, serializeBigInt, findSimilarTypes, textResult, errorResult, } from './utils.js';
 import { isGuaranteeType } from '@grafema/core';
 // === QUERY HANDLERS ===
@@ -174,7 +175,7 @@ export async function handleFindNodes(args) {
 // === TRACE HANDLERS ===
 export async function handleTraceAlias(args) {
     const db = await ensureAnalyzed();
-    const { identifier: variableName, file } = args;
+    const { variableName, file } = args;
     const projectPath = getProjectPath();
     let varNode = null;
     for await (const node of db.queryNodes({ type: 'VARIABLE' })) {
@@ -306,13 +307,18 @@ export async function handleCheckInvariant(args) {
 // === ANALYSIS HANDLERS ===
 export async function handleAnalyzeProject(args) {
     const { service, force } = args;
-    if (force) {
-        setIsAnalyzed(false);
+    // Early check: return error for force=true if analysis is already running
+    // This provides immediate feedback instead of waiting or causing corruption
+    if (force && isAnalysisRunning()) {
+        return errorResult('Cannot force re-analysis: analysis is already in progress. ' +
+            'Use get_analysis_status to check current status, or wait for completion.');
     }
+    // Note: setIsAnalyzed(false) is now handled inside ensureAnalyzed() within the lock
+    // to prevent race conditions where multiple calls could both clear the database
     try {
-        await ensureAnalyzed(service || null);
+        await ensureAnalyzed(service || null, force || false);
         const status = getAnalysisStatus();
-        return textResult(`✅ Analysis complete!\n` +
+        return textResult(`Analysis complete!\n` +
             `- Services discovered: ${status.servicesDiscovered}\n` +
             `- Services analyzed: ${status.servicesAnalyzed}\n` +
             `- Total time: ${status.timings.total || 'N/A'}s`);
@@ -608,11 +614,34 @@ export async function handleGetCoverage(args) {
     const db = await getOrCreateBackend();
     const projectPath = getProjectPath();
     const { path: targetPath = projectPath } = args;
-    const nodeCount = await db.nodeCount();
-    const moduleNodes = db.findByType ? await db.findByType('MODULE') : [];
-    return textResult(`Coverage for ${targetPath}:\n` +
-        `- Analyzed files: ${moduleNodes.length}\n` +
-        `- Total nodes: ${nodeCount}\n`);
+    try {
+        const analyzer = new CoverageAnalyzer(db, targetPath);
+        const result = await analyzer.analyze();
+        // Format output for AI agents
+        let output = `Analysis Coverage for ${targetPath}\n`;
+        output += `==============================\n\n`;
+        output += `File breakdown:\n`;
+        output += `  Total files:     ${result.total}\n`;
+        output += `  Analyzed:        ${result.analyzed.count} (${result.percentages.analyzed}%) - in graph\n`;
+        output += `  Unsupported:     ${result.unsupported.count} (${result.percentages.unsupported}%) - no indexer available\n`;
+        output += `  Unreachable:     ${result.unreachable.count} (${result.percentages.unreachable}%) - not imported from entrypoints\n`;
+        if (result.unsupported.count > 0) {
+            output += `\nUnsupported files by extension:\n`;
+            for (const [ext, files] of Object.entries(result.unsupported.byExtension)) {
+                output += `  ${ext}: ${files.length} files\n`;
+            }
+        }
+        if (result.unreachable.count > 0) {
+            output += `\nUnreachable source files:\n`;
+            for (const [ext, files] of Object.entries(result.unreachable.byExtension)) {
+                output += `  ${ext}: ${files.length} files\n`;
+            }
+        }
+        return textResult(output);
+    }
+    catch (error) {
+        return errorResult(`Failed to calculate coverage: ${error.message}`);
+    }
 }
 export async function handleGetDocumentation(args) {
     const { topic = 'overview' } = args;

package/dist/state.d.ts

@@ -15,6 +15,45 @@ export declare function setIsAnalyzed(value: boolean): void;
 export declare function setAnalysisStatus(status: Partial<AnalysisStatus>): void;
 export declare function setBackgroundPid(pid: number | null): void;
 export declare function updateAnalysisTimings(timings: Partial<AnalysisStatus['timings']>): void;
+/**
+ * Check if analysis is currently running.
+ *
+ * Use this to check status before attempting operations that conflict
+ * with analysis (e.g., force re-analysis while analysis is in progress).
+ *
+ * @returns true if analysis is in progress, false otherwise
+ */
+export declare function isAnalysisRunning(): boolean;
+/**
+ * Acquire the analysis lock.
+ *
+ * This function implements a Promise-based mutex for serializing analysis operations.
+ * Only one analysis can run at a time. If another analysis is running, this function
+ * waits for it to complete (up to LOCK_TIMEOUT_MS).
+ *
+ * Usage:
+ * ```typescript
+ * const releaseLock = await acquireAnalysisLock();
+ * try {
+ *   // ... perform analysis ...
+ * } finally {
+ *   releaseLock();
+ * }
+ * ```
+ *
+ * @returns A release function to call when analysis is complete
+ * @throws Error if timeout (10 minutes) expires while waiting for existing analysis
+ */
+export declare function acquireAnalysisLock(): Promise<() => void>;
+/**
+ * Wait for any running analysis to complete without acquiring the lock.
+ *
+ * Use this when you need to wait for analysis completion but don't need
+ * to start a new analysis yourself.
+ *
+ * @returns Promise that resolves when no analysis is running
+ */
+export declare function waitForAnalysis(): Promise<void>;
 export declare function getOrCreateBackend(): Promise<GraphBackend>;
 export declare function getBackendIfExists(): GraphBackend | null;
 export declare function setupLogging(): void;

package/dist/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAqB,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAIlF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAgCnD,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,IAAI,CAE7D;AAED,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAErD;AAGD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAElD;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CAEvE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEzD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAEvF;AAGD,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CAgChE;AAkBD,wBAAgB,kBAAkB,IAAI,YAAY,GAAG,IAAI,CAExD;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAMnC;AAGD,wBAAgB,kBAAkB,IAAI,IAAI,CAQzC;AAGD,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAI7C"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAqB,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAIlF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA+EnD,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,IAAI,CAE7D;AAED,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAErD;AAGD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAElD;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CAEvE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEzD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAEvF;AAID;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,CA8B/D;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAIrD;AAGD,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CAgChE;AAkBD,wBAAgB,kBAAkB,IAAI,YAAY,GAAG,IAAI,CAExD;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAMnC;AAGD,wBAAgB,kBAAkB,IAAI,IAAI,CAQzC;AAGD,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAI7C"}

package/dist/state.js

@@ -32,6 +32,51 @@ let analysisStatus = {
         total: null,
     },
 };
+// === ANALYSIS LOCK ===
+//
+// Promise-based mutex for analysis serialization.
+//
+// Why not a simple boolean flag?
+// - Boolean can indicate "analysis is running" but cannot make callers wait
+// - Promise allows awaiting until analysis completes
+//
+// Pattern:
+// - null = no analysis running, lock available
+// - Promise = analysis running, await it to wait for completion
+//
+// Behavior on force=true during analysis:
+// - Returns error immediately (does NOT wait)
+// - Rationale: force=true implies "clear DB and re-analyze"
+// - Clearing DB while another analysis writes = corruption
+// - Better UX: immediate feedback vs mysterious wait
+//
+// Scope: Global Lock (not per-service) because:
+// - Single RFDB backend instance
+// - db.clear() affects entire database
+// - Simpler reasoning about state
+//
+// Process Death Behavior:
+// - Lock is in-memory - next process starts with fresh state (no deadlock)
+// - RFDB may have partial data from incomplete analysis
+// - isAnalyzed resets to false - next call will re-analyze
+// - RFDB is append-only - partial data won't corrupt existing data
+//
+// Worker Process Coordination:
+// - Worker is SEPARATE process from MCP server
+// - MCP server calls db.clear() INSIDE the lock, BEFORE spawning worker
+// - Worker assumes DB is already clean and does NOT call clear()
+//
+// Timeout:
+// - Lock acquisition times out after 10 minutes
+// - Matches project's execution guard policy (see CLAUDE.md)
+//
+let analysisLock = null;
+let analysisLockResolve = null;
+/**
+ * Lock timeout in milliseconds (10 minutes).
+ * Matches project's execution guard policy - max 10 minutes for any operation.
+ */
+const LOCK_TIMEOUT_MS = 10 * 60 * 1000;
 // === GETTERS ===
 export function getProjectPath() {
     return projectPath;
@@ -67,6 +112,76 @@ export function setBackgroundPid(pid) {
 export function updateAnalysisTimings(timings) {
     analysisStatus.timings = { ...analysisStatus.timings, ...timings };
 }
+// === ANALYSIS LOCK FUNCTIONS ===
+/**
+ * Check if analysis is currently running.
+ *
+ * Use this to check status before attempting operations that conflict
+ * with analysis (e.g., force re-analysis while analysis is in progress).
+ *
+ * @returns true if analysis is in progress, false otherwise
+ */
+export function isAnalysisRunning() {
+    return analysisLock !== null;
+}
+/**
+ * Acquire the analysis lock.
+ *
+ * This function implements a Promise-based mutex for serializing analysis operations.
+ * Only one analysis can run at a time. If another analysis is running, this function
+ * waits for it to complete (up to LOCK_TIMEOUT_MS).
+ *
+ * Usage:
+ * ```typescript
+ * const releaseLock = await acquireAnalysisLock();
+ * try {
+ *   // ... perform analysis ...
+ * } finally {
+ *   releaseLock();
+ * }
+ * ```
+ *
+ * @returns A release function to call when analysis is complete
+ * @throws Error if timeout (10 minutes) expires while waiting for existing analysis
+ */
+export async function acquireAnalysisLock() {
+    const start = Date.now();
+    // Wait for any existing analysis to complete (with timeout)
+    while (analysisLock !== null) {
+        if (Date.now() - start > LOCK_TIMEOUT_MS) {
+            throw new Error('Analysis lock timeout (10 minutes). Previous analysis may have failed. ' +
+                'Check .grafema/mcp.log for errors or restart MCP server.');
+        }
+        await analysisLock;
+    }
+    // Create new lock - a Promise that will be resolved when analysis completes
+    analysisLock = new Promise((resolve) => {
+        analysisLockResolve = resolve;
+    });
+    // Update status to reflect that analysis is running
+    setAnalysisStatus({ running: true });
+    // Return release function
+    return () => {
+        setAnalysisStatus({ running: false });
+        const resolve = analysisLockResolve;
+        analysisLock = null;
+        analysisLockResolve = null;
+        resolve?.();
+    };
+}
+/**
+ * Wait for any running analysis to complete without acquiring the lock.
+ *
+ * Use this when you need to wait for analysis completion but don't need
+ * to start a new analysis yourself.
+ *
+ * @returns Promise that resolves when no analysis is running
+ */
+export async function waitForAnalysis() {
+    if (analysisLock) {
+        await analysisLock;
+    }
+}
 // === BACKEND ===
 export async function getOrCreateBackend() {
     if (backend)

package/dist/types.d.ts

@@ -28,13 +28,8 @@ export interface PaginationParams {
     total?: number;
     hasMore: boolean;
 }
-export interface GrafemaConfig {
-    project_path?: string;
-    backend?: 'local' | 'rfdb';
-    rfdb_socket?: string;
-    plugins?: string[];
-    ignore_patterns?: string[];
-}
+export type { GrafemaConfig } from '@grafema/core';
+export type { MCPConfig } from './config.js';
 export interface QueryGraphArgs {
     query: string;
     limit?: number;
@@ -48,7 +43,7 @@ export interface FindCallsArgs {
     include_indirect?: boolean;
 }
 export interface TraceAliasArgs {
-    identifier: string;
+    variableName: string;
     file?: string;
     max_depth?: number;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafema/mcp",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.1-alpha",
   "description": "MCP server for Grafema code analysis toolkit",
   "type": "module",
   "main": "./dist/server.js",
@@ -38,16 +38,19 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
     "ajv": "^8.17.1",
-    "@grafema/core": "0.1.0-alpha.5",
-    "@grafema/types": "0.1.0-alpha.5"
+    "@grafema/types": "0.1.1-alpha",
+    "@grafema/core": "0.1.1-alpha"
   },
   "devDependencies": {
     "@types/node": "^25.0.8",
+    "tsx": "^4.19.2",
     "typescript": "^5.9.3"
   },
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
-    "start": "node dist/server.js"
+    "start": "node dist/server.js",
+    "test": "node --import tsx --test test/*.test.ts",
+    "test:watch": "node --import tsx --test --watch test/*.test.ts"
   }
 }

package/src/analysis-worker.ts

@@ -213,7 +213,12 @@ async function run(): Promise<void> {
     console.log(`[Worker] Connecting to RFDB server: socket=${socketPath}, db=${dbPath}`);
     db = new RFDBServerBackend({ socketPath, dbPath });
     await db.connect();
-    await db.clear();
+
+    // NOTE: db.clear() is NOT called here.
+    // MCP server clears DB INSIDE the analysis lock BEFORE spawning this worker.
+    // This prevents race conditions where concurrent analysis calls could both
+    // clear the database. Worker assumes DB is already clean.
+    // See: REG-159 implementation, Phase 2.5 (Worker Clear Coordination)
 
     sendProgress({ phase: 'discovery', message: 'Starting analysis...' });
 

package/src/analysis.ts

@@ -10,20 +10,67 @@ import {
   setIsAnalyzed,
   getAnalysisStatus,
   setAnalysisStatus,
+  isAnalysisRunning,
+  acquireAnalysisLock,
 } from './state.js';
-import { loadConfig, loadCustomPlugins, BUILTIN_PLUGINS } from './config.js';
+import { loadConfig, loadCustomPlugins, createPlugins } from './config.js';
 import { log } from './utils.js';
 import type { GraphBackend } from '@grafema/types';
 
 /**
- * Ensure project is analyzed, optionally filtering to a single service
+ * Ensure project is analyzed, optionally filtering to a single service.
+ *
+ * CONCURRENCY: This function is protected by a global mutex.
+ * - Only one analysis can run at a time
+ * - Concurrent calls wait for the current analysis to complete
+ * - force=true while analysis is running returns an error immediately
+ *
+ * @param serviceName - Optional service to analyze (null = all)
+ * @param force - If true, clear DB and re-analyze even if already analyzed.
+ *                ERROR if another analysis is already running.
+ * @throws Error if force=true and analysis is already running
  */
-export async function ensureAnalyzed(serviceName: string | null = null): Promise<GraphBackend> {
+export async function ensureAnalyzed(
+  serviceName: string | null = null,
+  force: boolean = false
+): Promise<GraphBackend> {
   const db = await getOrCreateBackend();
   const projectPath = getProjectPath();
-  const isAnalyzed = getIsAnalyzed();
 
-  if (!isAnalyzed || serviceName) {
+  // CONCURRENCY CHECK: If force=true and analysis is running, error immediately
+  // This check is BEFORE acquiring lock to fail fast
+  if (force && isAnalysisRunning()) {
+    throw new Error(
+      'Analysis is already in progress. Cannot force re-analysis while another analysis is running. ' +
+        'Wait for the current analysis to complete or check status with get_analysis_status.'
+    );
+  }
+
+  // Skip if already analyzed (and not forcing, and no service filter)
+  if (getIsAnalyzed() && !serviceName && !force) {
+    return db;
+  }
+
+  // Acquire lock (waits if another analysis is running)
+  const releaseLock = await acquireAnalysisLock();
+
+  try {
+    // Double-check after acquiring lock (another call might have completed analysis while we waited)
+    if (getIsAnalyzed() && !serviceName && !force) {
+      return db;
+    }
+
+    // Clear DB inside lock, BEFORE running analysis
+    // This is critical for worker coordination: MCP server clears DB here,
+    // worker does NOT call db.clear() (see analysis-worker.ts)
+    if (force || !getIsAnalyzed()) {
+      log('[Grafema MCP] Clearing database before analysis...');
+      if (db.clear) {
+        await db.clear();
+      }
+      setIsAnalyzed(false);
+    }
+
     log(
       `[Grafema MCP] Analyzing project: ${projectPath}${serviceName ? ` (service: ${serviceName})` : ''}`
     );
@@ -31,30 +78,8 @@ export async function ensureAnalyzed(serviceName: string | null = null): Promise
     const config = loadConfig(projectPath);
     const { pluginMap: customPluginMap } = await loadCustomPlugins(projectPath);
 
-    // Merge builtin and custom plugins
-    const availablePlugins: Record<string, () => unknown> = {
-      ...BUILTIN_PLUGINS,
-      ...Object.fromEntries(
-        Object.entries(customPluginMap).map(([name, PluginClass]) => [
-          name,
-          () => new PluginClass(),
-        ])
-      ),
-    };
-
-    // Build plugin list from config
-    const plugins: unknown[] = [];
-    for (const [phase, pluginNames] of Object.entries(config.plugins || {})) {
-      for (const name of pluginNames as string[]) {
-        const factory = availablePlugins[name];
-        if (factory) {
-          plugins.push(factory());
-          log(`[Grafema MCP] Enabled plugin: ${name} (${phase})`);
-        } else {
-          log(`[Grafema MCP] Warning: Unknown plugin ${name} in config`);
-        }
-      }
-    }
+    // Create plugins from config
+    const plugins = createPlugins(config.plugins, customPluginMap);
 
     log(`[Grafema MCP] Total plugins: ${plugins.length}`);
 
@@ -105,10 +130,13 @@ export async function ensureAnalyzed(serviceName: string | null = null): Promise
       },
     });
 
-    log(`[Grafema MCP] ✅ Analysis complete in ${totalTime}s`);
-  }
+    log(`[Grafema MCP] Analysis complete in ${totalTime}s`);
 
-  return db;
+    return db;
+  } finally {
+    // ALWAYS release the lock, even on error
+    releaseLock();
+  }
 }
 
 /**
@@ -133,7 +161,7 @@ export async function discoverServices(): Promise<unknown[]> {
   };
 
   const plugins: unknown[] = [];
-  const discoveryPluginNames = (config.plugins as any)?.discovery || [];
+  const discoveryPluginNames = config.plugins.discovery ?? [];
 
   for (const name of discoveryPluginNames) {
     const factory = availablePlugins[name];

package/src/config.ts

@@ -3,10 +3,10 @@
  */
 
 import { join } from 'path';
-import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { existsSync, readdirSync } from 'fs';
 import { pathToFileURL } from 'url';
 import { log } from './utils.js';
-import type { GrafemaConfig } from './types.js';
+import { loadConfig as loadConfigFromCore, type GrafemaConfig } from '@grafema/core';
 
 // === PLUGIN IMPORTS ===
 import {
@@ -41,18 +41,12 @@ import {
   TypeScriptDeadCodeValidator,
 } from '@grafema/core';
 
-// === DEFAULT CONFIG ===
-export interface PluginConfig {
-  indexing: string[];
-  analysis: string[];
-  enrichment: string[];
-  validation: string[];
-  discovery?: string[];
-}
-
-export interface ProjectConfig {
-  plugins: PluginConfig;
-  discovery: {
+// === MCP-SPECIFIC CONFIG ===
+/**
+ * MCP-specific configuration extends GrafemaConfig with additional fields.
+ */
+export interface MCPConfig extends GrafemaConfig {
+  discovery?: {
     enabled: boolean;
     customOnly: boolean;
   };
@@ -63,35 +57,7 @@ export interface ProjectConfig {
   rfdb_socket?: string;
 }
 
-export const DEFAULT_CONFIG: ProjectConfig = {
-  plugins: {
-    indexing: ['JSModuleIndexer'],
-    analysis: [
-      'JSASTAnalyzer',
-      'ExpressRouteAnalyzer',
-      'SocketIOAnalyzer',
-      'DatabaseAnalyzer',
-      'FetchAnalyzer',
-      'ServiceLayerAnalyzer',
-    ],
-    enrichment: [
-      'MethodCallResolver',
-      'AliasTracker',
-      'ValueDomainAnalyzer',
-      'MountPointResolver',
-      'PrefixEvaluator',
-      'HTTPConnectionEnricher',
-    ],
-    validation: [
-      'CallResolverValidator',
-      'EvalBanValidator',
-      'SQLInjectionValidator',
-      'ShadowingDetector',
-      'GraphConnectivityValidator',
-      'DataFlowValidator',
-      'TypeScriptDeadCodeValidator',
-    ],
-  },
+const MCP_DEFAULTS: Pick<MCPConfig, 'discovery'> = {
   discovery: {
     enabled: true,
     customOnly: false,
@@ -137,33 +103,21 @@ export const BUILTIN_PLUGINS: Record<string, PluginFactory> = {
 };
 
 // === CONFIG LOADING ===
-export function loadConfig(projectPath: string): ProjectConfig {
-  const configPath = join(projectPath, '.grafema', 'config.json');
-
-  if (!existsSync(configPath)) {
-    try {
-      const grafemaDir = join(projectPath, '.grafema');
-      if (!existsSync(grafemaDir)) {
-        const { mkdirSync } = require('fs');
-        mkdirSync(grafemaDir, { recursive: true });
-      }
-      writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2));
-      log(`[Grafema MCP] Created default config: ${configPath}`);
-    } catch (err) {
-      log(`[Grafema MCP] Failed to create config: ${(err as Error).message}`);
-    }
-    return DEFAULT_CONFIG;
-  }
-
-  try {
-    const configContent = readFileSync(configPath, 'utf-8');
-    const config = JSON.parse(configContent) as Partial<ProjectConfig>;
-    log(`[Grafema MCP] Loaded config from ${configPath}`);
-    return { ...DEFAULT_CONFIG, ...config };
-  } catch (err) {
-    log(`[Grafema MCP] Failed to load config: ${(err as Error).message}, using defaults`);
-    return DEFAULT_CONFIG;
-  }
+/**
+ * Load MCP configuration (extends base GrafemaConfig).
+ * Uses shared ConfigLoader but adds MCP-specific defaults.
+ */
+export function loadConfig(projectPath: string): MCPConfig {
+  // Use shared loader (handles YAML/JSON, deprecation warnings)
+  const baseConfig = loadConfigFromCore(projectPath, {
+    warn: (msg) => log(`[Grafema MCP] ${msg}`),
+  });
+
+  // Add MCP-specific defaults
+  return {
+    ...baseConfig,
+    ...MCP_DEFAULTS,
+  };
 }
 
 // === CUSTOM PLUGINS ===
@@ -212,9 +166,16 @@ export async function loadCustomPlugins(projectPath: string): Promise<CustomPlug
 
 // === PLUGIN INSTANTIATION ===
 export function createPlugins(
-  pluginNames: string[],
+  config: GrafemaConfig['plugins'],
   customPluginMap: Record<string, new () => unknown> = {}
 ): unknown[] {
+  const pluginNames = [
+    ...config.indexing,
+    ...config.analysis,
+    ...config.enrichment,
+    ...config.validation,
+  ];
+
   const plugins: unknown[] = [];
   const availablePlugins: Record<string, PluginFactory> = {
     ...BUILTIN_PLUGINS,

package/src/handlers.ts

@@ -4,7 +4,8 @@
 
 import { join } from 'path';
 import { ensureAnalyzed } from './analysis.js';
-import { getProjectPath, getAnalysisStatus, setIsAnalyzed, getOrCreateBackend, getGuaranteeManager, getGuaranteeAPI } from './state.js';
+import { getProjectPath, getAnalysisStatus, getOrCreateBackend, getGuaranteeManager, getGuaranteeAPI, isAnalysisRunning } from './state.js';
+import { CoverageAnalyzer } from '@grafema/core';
 import {
   normalizeLimit,
   formatPaginationInfo,
@@ -248,7 +249,7 @@ export async function handleFindNodes(args: FindNodesArgs): Promise<ToolResult>
 
 export async function handleTraceAlias(args: TraceAliasArgs): Promise<ToolResult> {
   const db = await ensureAnalyzed();
-  const { identifier: variableName, file } = args;
+  const { variableName, file } = args;
   const projectPath = getProjectPath();
 
   let varNode: GraphNode | null = null;
@@ -423,16 +424,24 @@ export async function handleCheckInvariant(args: CheckInvariantArgs): Promise<To
 export async function handleAnalyzeProject(args: AnalyzeProjectArgs): Promise<ToolResult> {
   const { service, force } = args;
 
-  if (force) {
-    setIsAnalyzed(false);
+  // Early check: return error for force=true if analysis is already running
+  // This provides immediate feedback instead of waiting or causing corruption
+  if (force && isAnalysisRunning()) {
+    return errorResult(
+      'Cannot force re-analysis: analysis is already in progress. ' +
+        'Use get_analysis_status to check current status, or wait for completion.'
+    );
   }
 
+  // Note: setIsAnalyzed(false) is now handled inside ensureAnalyzed() within the lock
+  // to prevent race conditions where multiple calls could both clear the database
+
   try {
-    await ensureAnalyzed(service || null);
+    await ensureAnalyzed(service || null, force || false);
     const status = getAnalysisStatus();
 
     return textResult(
-      `✅ Analysis complete!\n` +
+      `Analysis complete!\n` +
         `- Services discovered: ${status.servicesDiscovered}\n` +
         `- Services analyzed: ${status.servicesAnalyzed}\n` +
         `- Total time: ${status.timings.total || 'N/A'}s`
@@ -764,14 +773,38 @@ export async function handleGetCoverage(args: GetCoverageArgs): Promise<ToolResu
   const projectPath = getProjectPath();
   const { path: targetPath = projectPath } = args;
 
-  const nodeCount = await db.nodeCount();
-  const moduleNodes = db.findByType ? await db.findByType('MODULE') : [];
+  try {
+    const analyzer = new CoverageAnalyzer(db, targetPath);
+    const result = await analyzer.analyze();
+
+    // Format output for AI agents
+    let output = `Analysis Coverage for ${targetPath}\n`;
+    output += `==============================\n\n`;
+
+    output += `File breakdown:\n`;
+    output += `  Total files:     ${result.total}\n`;
+    output += `  Analyzed:        ${result.analyzed.count} (${result.percentages.analyzed}%) - in graph\n`;
+    output += `  Unsupported:     ${result.unsupported.count} (${result.percentages.unsupported}%) - no indexer available\n`;
+    output += `  Unreachable:     ${result.unreachable.count} (${result.percentages.unreachable}%) - not imported from entrypoints\n`;
+
+    if (result.unsupported.count > 0) {
+      output += `\nUnsupported files by extension:\n`;
+      for (const [ext, files] of Object.entries(result.unsupported.byExtension)) {
+        output += `  ${ext}: ${files.length} files\n`;
+      }
+    }
 
-  return textResult(
-    `Coverage for ${targetPath}:\n` +
-      `- Analyzed files: ${moduleNodes.length}\n` +
-      `- Total nodes: ${nodeCount}\n`
-  );
+    if (result.unreachable.count > 0) {
+      output += `\nUnreachable source files:\n`;
+      for (const [ext, files] of Object.entries(result.unreachable.byExtension)) {
+        output += `  ${ext}: ${files.length} files\n`;
+      }
+    }
+
+    return textResult(output);
+  } catch (error) {
+    return errorResult(`Failed to calculate coverage: ${(error as Error).message}`);
+  }
 }
 
 export async function handleGetDocumentation(args: GetDocumentationArgs): Promise<ToolResult> {

package/src/state.ts

@@ -40,6 +40,53 @@ let analysisStatus: AnalysisStatus = {
   },
 };
 
+// === ANALYSIS LOCK ===
+//
+// Promise-based mutex for analysis serialization.
+//
+// Why not a simple boolean flag?
+// - Boolean can indicate "analysis is running" but cannot make callers wait
+// - Promise allows awaiting until analysis completes
+//
+// Pattern:
+// - null = no analysis running, lock available
+// - Promise = analysis running, await it to wait for completion
+//
+// Behavior on force=true during analysis:
+// - Returns error immediately (does NOT wait)
+// - Rationale: force=true implies "clear DB and re-analyze"
+// - Clearing DB while another analysis writes = corruption
+// - Better UX: immediate feedback vs mysterious wait
+//
+// Scope: Global Lock (not per-service) because:
+// - Single RFDB backend instance
+// - db.clear() affects entire database
+// - Simpler reasoning about state
+//
+// Process Death Behavior:
+// - Lock is in-memory - next process starts with fresh state (no deadlock)
+// - RFDB may have partial data from incomplete analysis
+// - isAnalyzed resets to false - next call will re-analyze
+// - RFDB is append-only - partial data won't corrupt existing data
+//
+// Worker Process Coordination:
+// - Worker is SEPARATE process from MCP server
+// - MCP server calls db.clear() INSIDE the lock, BEFORE spawning worker
+// - Worker assumes DB is already clean and does NOT call clear()
+//
+// Timeout:
+// - Lock acquisition times out after 10 minutes
+// - Matches project's execution guard policy (see CLAUDE.md)
+//
+let analysisLock: Promise<void> | null = null;
+let analysisLockResolve: (() => void) | null = null;
+
+/**
+ * Lock timeout in milliseconds (10 minutes).
+ * Matches project's execution guard policy - max 10 minutes for any operation.
+ */
+const LOCK_TIMEOUT_MS = 10 * 60 * 1000;
+
 // === GETTERS ===
 export function getProjectPath(): string {
   return projectPath;
@@ -86,6 +133,86 @@ export function updateAnalysisTimings(timings: Partial<AnalysisStatus['timings']
   analysisStatus.timings = { ...analysisStatus.timings, ...timings };
 }
 
+// === ANALYSIS LOCK FUNCTIONS ===
+
+/**
+ * Check if analysis is currently running.
+ *
+ * Use this to check status before attempting operations that conflict
+ * with analysis (e.g., force re-analysis while analysis is in progress).
+ *
+ * @returns true if analysis is in progress, false otherwise
+ */
+export function isAnalysisRunning(): boolean {
+  return analysisLock !== null;
+}
+
+/**
+ * Acquire the analysis lock.
+ *
+ * This function implements a Promise-based mutex for serializing analysis operations.
+ * Only one analysis can run at a time. If another analysis is running, this function
+ * waits for it to complete (up to LOCK_TIMEOUT_MS).
+ *
+ * Usage:
+ * ```typescript
+ * const releaseLock = await acquireAnalysisLock();
+ * try {
+ *   // ... perform analysis ...
+ * } finally {
+ *   releaseLock();
+ * }
+ * ```
+ *
+ * @returns A release function to call when analysis is complete
+ * @throws Error if timeout (10 minutes) expires while waiting for existing analysis
+ */
+export async function acquireAnalysisLock(): Promise<() => void> {
+  const start = Date.now();
+
+  // Wait for any existing analysis to complete (with timeout)
+  while (analysisLock !== null) {
+    if (Date.now() - start > LOCK_TIMEOUT_MS) {
+      throw new Error(
+        'Analysis lock timeout (10 minutes). Previous analysis may have failed. ' +
+          'Check .grafema/mcp.log for errors or restart MCP server.'
+      );
+    }
+    await analysisLock;
+  }
+
+  // Create new lock - a Promise that will be resolved when analysis completes
+  analysisLock = new Promise<void>((resolve) => {
+    analysisLockResolve = resolve;
+  });
+
+  // Update status to reflect that analysis is running
+  setAnalysisStatus({ running: true });
+
+  // Return release function
+  return () => {
+    setAnalysisStatus({ running: false });
+    const resolve = analysisLockResolve;
+    analysisLock = null;
+    analysisLockResolve = null;
+    resolve?.();
+  };
+}
+
+/**
+ * Wait for any running analysis to complete without acquiring the lock.
+ *
+ * Use this when you need to wait for analysis completion but don't need
+ * to start a new analysis yourself.
+ *
+ * @returns Promise that resolves when no analysis is running
+ */
+export async function waitForAnalysis(): Promise<void> {
+  if (analysisLock) {
+    await analysisLock;
+  }
+}
+
 // === BACKEND ===
 export async function getOrCreateBackend(): Promise<GraphBackend> {
   if (backend) return backend;

package/src/types.ts

@@ -36,13 +36,8 @@ export interface PaginationParams {
 }
 
 // === CONFIG ===
-export interface GrafemaConfig {
-  project_path?: string;
-  backend?: 'local' | 'rfdb';
-  rfdb_socket?: string;
-  plugins?: string[];
-  ignore_patterns?: string[];
-}
+export type { GrafemaConfig } from '@grafema/core';
+export type { MCPConfig } from './config.js';
 
 // === TOOL ARGUMENTS ===
 export interface QueryGraphArgs {
@@ -60,7 +55,7 @@ export interface FindCallsArgs {
 }
 
 export interface TraceAliasArgs {
-  identifier: string;
+  variableName: string;
   file?: string;
   max_depth?: number;
 }