@grafema/mcp 0.1.0-alpha.1

package/dist/utils.js

@@ -0,0 +1,180 @@
+/**
+ * MCP Server Utilities
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, unlinkSync, statSync } from 'fs';
+import { join } from 'path';
+// === CONSTANTS ===
+export const DEFAULT_LIMIT = 10;
+export const MAX_LIMIT = 500;
+export const DEFAULT_RESPONSE_SIZE_LIMIT = 100_000;
+// === LOGGING ===
+let logsDir = null;
+const MAX_LOG_FILES = 7; // Keep logs for 7 days
+function getLogFilePath() {
+    const date = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+    const dir = logsDir || '/tmp';
+    return join(dir, `mcp-${date}.log`);
+}
+function cleanupOldLogs() {
+    if (!logsDir || !existsSync(logsDir))
+        return;
+    try {
+        const files = readdirSync(logsDir)
+            .filter(f => f.startsWith('mcp-') && f.endsWith('.log'))
+            .map(f => ({
+            name: f,
+            path: join(logsDir, f),
+            mtime: statSync(join(logsDir, f)).mtime.getTime()
+        }))
+            .sort((a, b) => b.mtime - a.mtime); // newest first
+        // Remove files beyond MAX_LOG_FILES
+        for (const file of files.slice(MAX_LOG_FILES)) {
+            unlinkSync(file.path);
+        }
+    }
+    catch {
+        // Ignore cleanup errors
+    }
+}
+export function initLogger(grafemaDir) {
+    logsDir = join(grafemaDir, 'logs');
+    if (!existsSync(logsDir)) {
+        mkdirSync(logsDir, { recursive: true });
+    }
+    cleanupOldLogs();
+    log(`[Grafema MCP] Logging initialized: ${logsDir}`);
+}
+export function getLogsDir() {
+    return logsDir;
+}
+export function log(msg) {
+    const timestamp = new Date().toISOString();
+    const line = `[${timestamp}] ${msg}\n`;
+    try {
+        appendFileSync(getLogFilePath(), line);
+    }
+    catch {
+        // Fallback to /tmp if logs dir not initialized
+        appendFileSync('/tmp/grafema-mcp.log', line);
+    }
+}
+// === PAGINATION ===
+export function guardResponseSize(text, maxSize = DEFAULT_RESPONSE_SIZE_LIMIT) {
+    if (text.length > maxSize) {
+        const truncated = text.slice(0, maxSize);
+        const remaining = text.length - maxSize;
+        return truncated + `\n\n... [TRUNCATED: ${remaining.toLocaleString()} chars remaining. Use limit/offset for pagination]`;
+    }
+    return text;
+}
+export function normalizeLimit(limit) {
+    if (limit === undefined || limit === null)
+        return DEFAULT_LIMIT;
+    return Math.min(Math.max(1, Math.floor(limit)), MAX_LIMIT);
+}
+export function formatPaginationInfo(params) {
+    const { limit, offset, returned, total, hasMore } = params;
+    let info = `\n📄 Pagination: showing ${returned}`;
+    if (total !== undefined) {
+        info += ` of ${total}`;
+    }
+    if (offset > 0) {
+        info += ` (offset: ${offset})`;
+    }
+    if (hasMore) {
+        info += ` — use offset=${offset + returned} to get more`;
+    }
+    return info;
+}
+// === TYPE HELPERS ===
+export function findSimilarTypes(queriedType, availableTypes, maxDistance = 2) {
+    const queriedLower = queriedType.toLowerCase();
+    const similar = [];
+    for (const type of availableTypes) {
+        const dist = levenshtein(queriedLower, type.toLowerCase());
+        if (dist > 0 && dist <= maxDistance) {
+            similar.push(type);
+        }
+    }
+    return similar;
+}
+// Levenshtein distance implementation
+export function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const dp = Array(m + 1).fill(null).map(() => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[m][n];
+}
+// === SERIALIZATION ===
+export function serializeBigInt(obj) {
+    if (obj === null || obj === undefined)
+        return obj;
+    if (typeof obj === 'bigint')
+        return obj.toString();
+    if (Array.isArray(obj))
+        return obj.map(serializeBigInt);
+    if (typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            result[key] = serializeBigInt(value);
+        }
+        return result;
+    }
+    return obj;
+}
+// === TOOL RESULT HELPERS ===
+export function textResult(text) {
+    return {
+        content: [{ type: 'text', text }],
+    };
+}
+export function errorResult(message) {
+    return {
+        content: [{ type: 'text', text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+export function jsonResult(data, pretty = true) {
+    const text = pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+    return textResult(text);
+}
+// === PROCESS HELPERS ===
+export function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// === FORMATTING ===
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    return `${(ms / 60000).toFixed(1)}m`;
+}
+export function formatNumber(n) {
+    return n.toLocaleString();
+}
+export function truncate(s, maxLen) {
+    if (s.length <= maxLen)
+        return s;
+    return s.slice(0, maxLen - 3) + '...';
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@grafema/mcp",
+  "version": "0.1.0-alpha.1",
+  "description": "MCP server for Grafema code analysis toolkit",
+  "type": "module",
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "bin": {
+    "grafema-mcp": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./handlers": {
+      "types": "./dist/handlers.d.ts",
+      "import": "./dist/handlers.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "start": "node dist/server.js"
+  },
+  "keywords": [
+    "grafema",
+    "mcp",
+    "model-context-protocol",
+    "code-analysis"
+  ],
+  "license": "Apache-2.0",
+  "author": "Vadim Reshetnikov",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Disentinel/grafema.git",
+    "directory": "packages/mcp"
+  },
+  "dependencies": {
+    "@grafema/core": "workspace:*",
+    "@grafema/types": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "ajv": "^8.17.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "typescript": "^5.9.3"
+  }
+}

package/src/.rfguard/current-session.txt

@@ -0,0 +1 @@
+118083cf-1249-4311-b452-79bb704fcf13

package/src/analysis-worker.ts

@@ -0,0 +1,286 @@
+/**
+ * Analysis Worker - runs in separate process to avoid blocking MCP server
+ *
+ * Usage: node analysis-worker.js <projectPath> [serviceName]
+ *
+ * Sends progress updates via IPC to parent process
+ */
+
+import { join } from 'path';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { pathToFileURL } from 'url';
+
+import {
+  Orchestrator,
+  RFDBServerBackend,
+  Plugin,
+  // Indexing
+  JSModuleIndexer,
+  // Analysis
+  JSASTAnalyzer,
+  ExpressRouteAnalyzer,
+  SocketIOAnalyzer,
+  DatabaseAnalyzer,
+  FetchAnalyzer,
+  ServiceLayerAnalyzer,
+  ReactAnalyzer,
+  // Enrichment
+  MethodCallResolver,
+  AliasTracker,
+  ValueDomainAnalyzer,
+  MountPointResolver,
+  PrefixEvaluator,
+  HTTPConnectionEnricher,
+  // Validation
+  CallResolverValidator,
+  EvalBanValidator,
+  SQLInjectionValidator,
+  ShadowingDetector,
+  GraphConnectivityValidator,
+  DataFlowValidator,
+} from '@grafema/core';
+import type { ParallelConfig } from '@grafema/core';
+
+/**
+ * Config structure
+ */
+interface WorkerConfig {
+  plugins?: Record<string, string[]>;
+  analysis?: {
+    parallel?: ParallelConfig & { workers?: number; socketPath?: string };
+  };
+}
+
+/**
+ * Progress message
+ */
+interface ProgressMessage {
+  type: 'progress';
+  phase?: string;
+  message?: string;
+  servicesDiscovered?: number;
+  servicesAnalyzed?: number;
+}
+
+/**
+ * Complete message
+ */
+interface CompleteMessage {
+  type: 'complete';
+  nodeCount: number;
+  edgeCount: number;
+  totalTime: string;
+}
+
+/**
+ * Error message
+ */
+interface ErrorMessage {
+  type: 'error';
+  message: string;
+  stack?: string;
+}
+
+type WorkerMessage = ProgressMessage | CompleteMessage | ErrorMessage;
+
+const projectPath = process.argv[2];
+const serviceName = process.argv[3] && process.argv[3] !== '' ? process.argv[3] : null;
+const indexOnly = process.argv[4] === 'indexOnly';
+
+if (!projectPath) {
+  console.error('Usage: node analysis-worker.js <projectPath> [serviceName] [indexOnly]');
+  process.exit(1);
+}
+
+function sendProgress(data: Omit<ProgressMessage, 'type'>): void {
+  if (process.send) {
+    process.send({ type: 'progress', ...data } as ProgressMessage);
+  }
+}
+
+function sendComplete(data: Omit<CompleteMessage, 'type'>): void {
+  if (process.send) {
+    process.send({ type: 'complete', ...data } as CompleteMessage);
+  }
+}
+
+function sendError(error: Error): void {
+  if (process.send) {
+    process.send({ type: 'error', message: error.message, stack: error.stack } as ErrorMessage);
+  }
+}
+
+async function loadConfig(): Promise<WorkerConfig> {
+  const configPath = join(projectPath, '.grafema', 'config.json');
+  if (existsSync(configPath)) {
+    return JSON.parse(readFileSync(configPath, 'utf8')) as WorkerConfig;
+  }
+  return { plugins: {} };
+}
+
+async function loadCustomPlugins(): Promise<Record<string, new () => Plugin>> {
+  const pluginsDir = join(projectPath, '.grafema', 'plugins');
+  const customPlugins: Record<string, new () => Plugin> = {};
+
+  if (!existsSync(pluginsDir)) {
+    return customPlugins;
+  }
+
+  const files = readdirSync(pluginsDir).filter(f => f.endsWith('.mjs') || f.endsWith('.js'));
+  for (const file of files) {
+    try {
+      const module = await import(pathToFileURL(join(pluginsDir, file)).href);
+      const PluginClass = module.default as new () => Plugin;
+      if (PluginClass) {
+        customPlugins[PluginClass.name] = PluginClass;
+      }
+    } catch (err) {
+      console.error(`Failed to load plugin ${file}:`, (err as Error).message);
+    }
+  }
+
+  return customPlugins;
+}
+
+async function run(): Promise<void> {
+  const startTime = Date.now();
+  let db: RFDBServerBackend | null = null;
+
+  try {
+    sendProgress({ phase: 'starting', message: 'Loading configuration...' });
+
+    const config = await loadConfig();
+    const customPlugins = await loadCustomPlugins();
+
+    // Built-in plugins map
+    const builtinPlugins: Record<string, () => Plugin> = {
+      JSModuleIndexer: () => new JSModuleIndexer(),
+      JSASTAnalyzer: () => new JSASTAnalyzer(),
+      ExpressRouteAnalyzer: () => new ExpressRouteAnalyzer(),
+      SocketIOAnalyzer: () => new SocketIOAnalyzer(),
+      DatabaseAnalyzer: () => new DatabaseAnalyzer(),
+      FetchAnalyzer: () => new FetchAnalyzer(),
+      ServiceLayerAnalyzer: () => new ServiceLayerAnalyzer(),
+      ReactAnalyzer: () => new ReactAnalyzer(),
+      MethodCallResolver: () => new MethodCallResolver(),
+      AliasTracker: () => new AliasTracker(),
+      ValueDomainAnalyzer: () => new ValueDomainAnalyzer(),
+      MountPointResolver: () => new MountPointResolver(),
+      PrefixEvaluator: () => new PrefixEvaluator(),
+      HTTPConnectionEnricher: () => new HTTPConnectionEnricher(),
+      CallResolverValidator: () => new CallResolverValidator(),
+      EvalBanValidator: () => new EvalBanValidator(),
+      SQLInjectionValidator: () => new SQLInjectionValidator(),
+      ShadowingDetector: () => new ShadowingDetector(),
+      GraphConnectivityValidator: () => new GraphConnectivityValidator(),
+      DataFlowValidator: () => new DataFlowValidator(),
+    };
+
+    // Add custom plugins
+    for (const [name, PluginClass] of Object.entries(customPlugins)) {
+      builtinPlugins[name] = () => new PluginClass();
+    }
+
+    // Build plugins array from config
+    const plugins: Plugin[] = [];
+    for (const [phase, pluginNames] of Object.entries(config.plugins || {})) {
+      for (const name of pluginNames) {
+        if (builtinPlugins[name]) {
+          plugins.push(builtinPlugins[name]());
+        } else if (customPlugins[name]) {
+          plugins.push(new customPlugins[name]());
+          console.log(`[Worker] Loaded custom plugin: ${name}`);
+        } else {
+          console.warn(`[Worker] Plugin not found: ${name}`);
+        }
+      }
+    }
+
+    console.log(`[Worker] Loaded ${plugins.length} plugins:`, plugins.map(p => p.metadata?.name || p.constructor?.name || 'unknown'));
+    sendProgress({ phase: 'starting', message: `Loaded ${plugins.length} plugins` });
+
+    // Get parallel analysis config
+    const parallelConfig = config.analysis?.parallel;
+    if (parallelConfig?.enabled) {
+      console.log(`[Worker] Queue-based parallel mode enabled: workers=${parallelConfig.workers}`);
+    }
+
+    // Connect to RFDB server (shared with MCP server)
+    // The MCP server starts the RFDB server if not running
+    const dbPath = join(projectPath, '.grafema', 'graph.rfdb');
+    const socketPath = config.analysis?.parallel?.socketPath || '/tmp/rfdb.sock';
+
+    console.log(`[Worker] Connecting to RFDB server: socket=${socketPath}, db=${dbPath}`);
+    db = new RFDBServerBackend({ socketPath, dbPath });
+    await db.connect();
+    await db.clear();
+
+    sendProgress({ phase: 'discovery', message: 'Starting analysis...' });
+
+    // Create orchestrator
+    const orchestrator = new Orchestrator({
+      graph: db,
+      plugins,
+      parallel: parallelConfig as ParallelConfig | undefined, // Pass parallel config for queue-based analysis
+      serviceFilter: serviceName,
+      indexOnly: indexOnly,
+      onProgress: (progress) => {
+        sendProgress({
+          phase: progress.phase,
+          message: progress.message,
+          servicesAnalyzed: progress.servicesAnalyzed
+        });
+      }
+    });
+
+    // Run analysis
+    await orchestrator.run(projectPath);
+
+    // Get final stats
+    let nodeCount = 0;
+    let edgeCount = 0;
+
+    // Use async methods for RFDBServerBackend
+    const allEdges = await db.getAllEdgesAsync();
+    edgeCount = allEdges.length;
+
+    for await (const _ of db.queryNodes({})) {
+      nodeCount++;
+    }
+
+    // Flush to disk using proper async method
+    console.log('[Worker] Flushing database to disk...');
+    await db.flush();
+    console.log('[Worker] Database flushed successfully');
+
+    const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+
+    sendComplete({
+      nodeCount,
+      edgeCount,
+      totalTime
+    });
+
+    // Close database properly before exit
+    await db.close();
+    console.log('[Worker] Database closed');
+
+    process.exit(0);
+  } finally {
+    // Ensure database connection is closed even on error
+    if (db && db.connected) {
+      try {
+        await db.close();
+        console.log('[Worker] Database connection closed in cleanup');
+      } catch (closeErr) {
+        console.error('[Worker] Error closing database connection:', (closeErr as Error).message);
+      }
+    }
+  }
+}
+
+run().catch(err => {
+  sendError(err as Error);
+  console.error('Analysis failed:', err);
+  process.exit(1);
+});

package/src/analysis.ts

@@ -0,0 +1,158 @@
+/**
+ * MCP Analysis Orchestration
+ */
+
+import { Orchestrator, Plugin } from '@grafema/core';
+import {
+  getOrCreateBackend,
+  getProjectPath,
+  getIsAnalyzed,
+  setIsAnalyzed,
+  getAnalysisStatus,
+  setAnalysisStatus,
+} from './state.js';
+import { loadConfig, loadCustomPlugins, BUILTIN_PLUGINS } from './config.js';
+import { log } from './utils.js';
+import type { GraphBackend } from '@grafema/types';
+
+/**
+ * Ensure project is analyzed, optionally filtering to a single service
+ */
+export async function ensureAnalyzed(serviceName: string | null = null): Promise<GraphBackend> {
+  const db = await getOrCreateBackend();
+  const projectPath = getProjectPath();
+  const isAnalyzed = getIsAnalyzed();
+
+  if (!isAnalyzed || serviceName) {
+    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: 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`);
+        }
+      }
+    }
+
+    log(`[Grafema MCP] Total plugins: ${plugins.length}`);
+
+    // Check for parallel analysis config
+    const parallelConfig = (config as any).analysis?.parallel;
+    log(`[Grafema MCP] Config analysis section: ${JSON.stringify((config as any).analysis)}`);
+
+    if (parallelConfig?.enabled) {
+      log(
+        `[Grafema MCP] Parallel analysis enabled: maxWorkers=${parallelConfig.maxWorkers || 'auto'}, socket=${parallelConfig.socketPath || '/tmp/rfdb.sock'}`
+      );
+    }
+
+    const analysisStatus = getAnalysisStatus();
+    const startTime = Date.now();
+
+    const orchestrator = new Orchestrator({
+      graph: db,
+      plugins: plugins as Plugin[],
+      parallel: parallelConfig,
+      serviceFilter: serviceName,
+      onProgress: (progress: any) => {
+        log(`[Grafema MCP] ${progress.phase}: ${progress.message}`);
+
+        setAnalysisStatus({
+          phase: progress.phase,
+          message: progress.message,
+          servicesDiscovered: progress.servicesDiscovered || analysisStatus.servicesDiscovered,
+          servicesAnalyzed: progress.servicesAnalyzed || analysisStatus.servicesAnalyzed,
+        });
+      },
+    });
+
+    await orchestrator.run(projectPath);
+
+    // Flush if available
+    if ('flush' in db && typeof db.flush === 'function') {
+      await (db as any).flush();
+    }
+
+    setIsAnalyzed(true);
+
+    const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+    setAnalysisStatus({
+      timings: {
+        ...analysisStatus.timings,
+        total: parseFloat(totalTime),
+      },
+    });
+
+    log(`[Grafema MCP] ✅ Analysis complete in ${totalTime}s`);
+  }
+
+  return db;
+}
+
+/**
+ * Discover services without running full analysis
+ */
+export async function discoverServices(): Promise<unknown[]> {
+  const db = await getOrCreateBackend();
+  const projectPath = getProjectPath();
+
+  log(`[Grafema MCP] Discovering services in: ${projectPath}`);
+
+  const config = loadConfig(projectPath);
+  const { pluginMap: customPluginMap } = await loadCustomPlugins(projectPath);
+
+  const availablePlugins: Record<string, () => unknown> = {
+    ...Object.fromEntries(
+      Object.entries(customPluginMap).map(([name, PluginClass]) => [
+        name,
+        () => new PluginClass(),
+      ])
+    ),
+  };
+
+  const plugins: unknown[] = [];
+  const discoveryPluginNames = (config.plugins as any)?.discovery || [];
+
+  for (const name of discoveryPluginNames) {
+    const factory = availablePlugins[name];
+    if (factory) {
+      plugins.push(factory());
+      log(`[Grafema MCP] Enabled discovery plugin: ${name}`);
+    } else {
+      log(`[Grafema MCP] Warning: Unknown discovery plugin ${name}`);
+    }
+  }
+
+  const orchestrator = new Orchestrator({
+    graph: db,
+    plugins: plugins as Plugin[],
+  });
+
+  const manifest = await orchestrator.discover(projectPath);
+
+  log(`[Grafema MCP] Discovery complete: found ${manifest.services?.length || 0} services`);
+
+  return manifest.services || [];
+}