@grafema/mcp 0.2.12-beta → 0.3.0-beta

package/src/dev-proxy.ts

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+/**
+ * Grafema MCP Dev Proxy
+ *
+ * A thin stdio proxy that sits between Claude Code and the real MCP server.
+ * It transparently forwards all JSON-RPC messages, with two exceptions:
+ *
+ * 1. Intercepts `tools/call` with `name: "reload"` — kills and respawns the
+ *    child server process so it picks up new code from dist/ after `pnpm build`.
+ *
+ * 2. Injects a `reload` tool definition into `tools/list` responses from the
+ *    real server.
+ *
+ * Architecture:
+ *   Claude Code  <--stdio-->  dev-proxy  <--stdio-->  real server.js
+ *
+ * Usage in .claude/mcp.json:
+ *   {
+ *     "grafema-dev": {
+ *       "command": "node",
+ *       "args": ["packages/mcp/dist/dev-proxy.js", "--project", "/path/to/project"]
+ *     }
+ *   }
+ *
+ * The MCP SDK uses newline-delimited JSON framing (each message is a single
+ * JSON object followed by '\n'). No Content-Length headers.
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ── Constants ──────────────────────────────────────────────────────────
+
+const RELOAD_TOOL_DEFINITION = {
+  name: 'reload',
+  description:
+    'Hot-reload the MCP server (restarts the process to pick up new dist/ code after pnpm build)',
+  inputSchema: { type: 'object' as const, properties: {} },
+};
+
+/** Path to the real MCP server entry point (co-located in dist/) */
+const SERVER_SCRIPT = join(__dirname, 'server.js');
+
+/** All CLI args passed to this proxy are forwarded to the child server */
+const CHILD_ARGS = process.argv.slice(2);
+
+// ── Logging (stderr only — stdout is the JSON-RPC channel) ────────────
+
+function log(msg: string): void {
+  process.stderr.write(`[dev-proxy] ${msg}\n`);
+}
+
+// ── Child Process Management ───────────────────────────────────────────
+
+let child: ChildProcess | null = null;
+let childReady = false;
+/** Messages buffered while child is (re)starting */
+let pendingMessages: string[] = [];
+/** Track in-flight requests so we can send error responses on crash */
+const inflightRequests = new Map<string | number, boolean>();
+
+/**
+ * Spawn the real MCP server as a child process.
+ * stdin/stdout are piped for JSON-RPC; stderr is inherited for debug logs.
+ */
+function spawnChild(): void {
+  log(`Spawning child: node ${SERVER_SCRIPT} ${CHILD_ARGS.join(' ')}`);
+
+  child = spawn('node', [SERVER_SCRIPT, ...CHILD_ARGS], {
+    stdio: ['pipe', 'pipe', 'inherit'],
+  });
+
+  childReady = true;
+
+  // ── Child stdout → proxy stdout (with tools/list injection) ──
+  let childBuffer = '';
+
+  child.stdout!.on('data', (chunk: Buffer) => {
+    childBuffer += chunk.toString('utf8');
+
+    // Process complete newline-delimited messages
+    let newlineIdx: number;
+    while ((newlineIdx = childBuffer.indexOf('\n')) !== -1) {
+      const line = childBuffer.slice(0, newlineIdx);
+      childBuffer = childBuffer.slice(newlineIdx + 1);
+
+      if (line.trim().length === 0) continue;
+
+      try {
+        const msg = JSON.parse(line);
+
+        // Remove from in-flight tracking if this is a response
+        if ('id' in msg && msg.id !== undefined) {
+          inflightRequests.delete(msg.id);
+        }
+
+        // Inject reload tool into tools/list responses
+        if (isToolsListResponse(msg)) {
+          msg.result.tools.push(RELOAD_TOOL_DEFINITION);
+        }
+
+        process.stdout.write(JSON.stringify(msg) + '\n');
+      } catch {
+        // If we can't parse it, forward raw (shouldn't happen with well-formed server)
+        process.stdout.write(line + '\n');
+      }
+    }
+  });
+
+  // ── Child exit handling ──
+  child.on('exit', (code, signal) => {
+    log(`Child exited: code=${code}, signal=${signal}`);
+    childReady = false;
+
+    // Send error responses for any in-flight requests
+    for (const [id] of inflightRequests) {
+      sendErrorResponse(id, -32000, 'MCP server process crashed');
+    }
+    inflightRequests.clear();
+
+    child = null;
+
+    // Auto-restart unless we're shutting down
+    if (!shuttingDown) {
+      log('Auto-restarting child in 500ms...');
+      setTimeout(() => {
+        spawnChild();
+        flushPendingMessages();
+      }, 500);
+    }
+  });
+
+  child.on('error', (err) => {
+    log(`Child spawn error: ${err.message}`);
+    childReady = false;
+    child = null;
+  });
+
+  // Flush any messages that arrived while child was restarting
+  flushPendingMessages();
+}
+
+function flushPendingMessages(): void {
+  if (!child || !childReady || pendingMessages.length === 0) return;
+  log(`Flushing ${pendingMessages.length} pending message(s)`);
+  for (const msg of pendingMessages) {
+    child.stdin!.write(msg + '\n');
+  }
+  pendingMessages = [];
+}
+
+function killChild(): Promise<void> {
+  return new Promise((resolve) => {
+    if (!child) {
+      resolve();
+      return;
+    }
+
+    const c = child;
+    // Prevent auto-restart during intentional reload
+    const onExit = () => {
+      child = null;
+      childReady = false;
+      resolve();
+    };
+
+    c.once('exit', onExit);
+    c.kill('SIGTERM');
+
+    // Force kill after 3 seconds
+    setTimeout(() => {
+      if (c.exitCode === null && c.signalCode === null) {
+        log('Child did not exit after SIGTERM, sending SIGKILL');
+        c.kill('SIGKILL');
+      }
+    }, 3000);
+  });
+}
+
+// ── JSON-RPC Helpers ───────────────────────────────────────────────────
+
+interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id?: string | number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: string | number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+function isToolsCallReload(msg: JsonRpcRequest): boolean {
+  return (
+    msg.method === 'tools/call' &&
+    msg.params != null &&
+    (msg.params as Record<string, unknown>).name === 'reload'
+  );
+}
+
+function isToolsListResponse(msg: unknown): msg is JsonRpcResponse & {
+  result: { tools: Array<{ name: string }> };
+} {
+  const m = msg as Record<string, unknown>;
+  if (!m || typeof m !== 'object') return false;
+  if (!('result' in m) || !m.result) return false;
+  const result = m.result as Record<string, unknown>;
+  return Array.isArray(result.tools);
+}
+
+function sendSuccessResponse(id: string | number, result: unknown): void {
+  const response: JsonRpcResponse = {
+    jsonrpc: '2.0',
+    id,
+    result,
+  };
+  process.stdout.write(JSON.stringify(response) + '\n');
+}
+
+function sendErrorResponse(
+  id: string | number,
+  code: number,
+  message: string
+): void {
+  const response: JsonRpcResponse = {
+    jsonrpc: '2.0',
+    id,
+    error: { code, message },
+  };
+  process.stdout.write(JSON.stringify(response) + '\n');
+}
+
+// ── Reload Handler ─────────────────────────────────────────────────────
+
+async function handleReload(requestId: string | number): Promise<void> {
+  log('Reload requested — restarting child process...');
+
+  try {
+    // Suppress auto-restart during intentional kill
+    shuttingDown = true;
+    await killChild();
+    shuttingDown = false;
+
+    spawnChild();
+
+    sendSuccessResponse(requestId, {
+      content: [
+        {
+          type: 'text',
+          text: 'MCP server reloaded successfully. New dist/ code is now active.',
+        },
+      ],
+    });
+  } catch (err) {
+    shuttingDown = false;
+    const message = err instanceof Error ? err.message : String(err);
+    log(`Reload failed: ${message}`);
+    sendErrorResponse(requestId, -32000, `Reload failed: ${message}`);
+  }
+}
+
+// ── Main: stdin → child (with reload interception) ─────────────────────
+
+let shuttingDown = false;
+let stdinBuffer = '';
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk: string) => {
+  stdinBuffer += chunk;
+
+  let newlineIdx: number;
+  while ((newlineIdx = stdinBuffer.indexOf('\n')) !== -1) {
+    const line = stdinBuffer.slice(0, newlineIdx);
+    stdinBuffer = stdinBuffer.slice(newlineIdx + 1);
+
+    if (line.trim().length === 0) continue;
+
+    try {
+      const msg = JSON.parse(line) as JsonRpcRequest;
+
+      // Intercept reload tool call
+      if (msg.method === 'tools/call' && isToolsCallReload(msg)) {
+        if (msg.id !== undefined) {
+          void handleReload(msg.id);
+        }
+        continue;
+      }
+
+      // Track request IDs for crash error responses
+      if ('id' in msg && msg.id !== undefined && 'method' in msg) {
+        inflightRequests.set(msg.id, true);
+      }
+
+      // Forward to child
+      if (child && childReady) {
+        child.stdin!.write(line + '\n');
+      } else {
+        pendingMessages.push(line);
+      }
+    } catch {
+      // Not valid JSON — forward raw (shouldn't happen with well-formed client)
+      if (child && childReady) {
+        child.stdin!.write(line + '\n');
+      } else {
+        pendingMessages.push(line);
+      }
+    }
+  }
+});
+
+// ── Graceful Shutdown ──────────────────────────────────────────────────
+
+async function shutdown(): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  log('Shutting down...');
+
+  await killChild();
+  process.exit(0);
+}
+
+process.on('SIGINT', () => void shutdown());
+process.on('SIGTERM', () => void shutdown());
+process.stdin.on('end', () => void shutdown());
+
+// ── Start ──────────────────────────────────────────────────────────────
+
+log('Dev proxy starting');
+spawnChild();

package/src/handlers/analysis-handlers.ts

@@ -3,7 +3,7 @@
  */
 
 import { ensureAnalyzed } from '../analysis.js';
-import { getAnalysisStatus, getOrCreateBackend, isAnalysisRunning } from '../state.js';
+import { getAnalysisStatus, isAnalysisRunning } from '../state.js';
 import {
   textResult,
   errorResult,
@@ -13,6 +13,7 @@ import type {
   AnalyzeProjectArgs,
   GetSchemaArgs,
 } from '../types.js';
+import type { ServerStats } from '@grafema/types';
 
 // === ANALYSIS HANDLERS ===
 
@@ -62,24 +63,54 @@ export async function handleGetAnalysisStatus(): Promise<ToolResult> {
 }
 
 export async function handleGetStats(): Promise<ToolResult> {
-  const db = await getOrCreateBackend();
+  const db = await ensureAnalyzed();
 
   const nodeCount = await db.nodeCount();
   const edgeCount = await db.edgeCount();
   const nodesByType = await db.countNodesByType();
   const edgesByType = await db.countEdgesByType();
 
+  let shardSection = '';
+  if ('getServerStats' in db && typeof (db as Record<string, unknown>).getServerStats === 'function') {
+    try {
+      const stats = await (db as { getServerStats(): Promise<ServerStats> }).getServerStats();
+      if (stats.shardDiagnostics?.length > 0) {
+        shardSection = `\nShard Diagnostics (${stats.shardDiagnostics.length} shards):\n`;
+        for (const s of stats.shardDiagnostics) {
+          const parts = [
+            `nodes=${s.nodeCount}`,
+            `edges=${s.edgeCount}`,
+            `wb=${s.writeBufferNodes}/${s.writeBufferEdges}`,
+            s.compacted ? `compacted (L1: ${s.l1NodeRecords}n/${s.l1EdgeRecords}e)` : `L0: ${s.l0NodeSegmentCount}n/${s.l0EdgeSegmentCount}e segs`,
+          ];
+          if (s.tombstoneNodeCount > 0 || s.tombstoneEdgeCount > 0) {
+            parts.push(`tombstones=${s.tombstoneNodeCount}n/${s.tombstoneEdgeCount}e`);
+          }
+          const indexes = [s.hasL1ByType && 'type', s.hasL1ByFile && 'file', s.hasL1ByName && 'name'].filter(Boolean);
+          if (indexes.length > 0) {
+            parts.push(`indexes=[${indexes.join(',')}]`);
+          }
+          shardSection += `  shard ${s.shardId}: ${parts.join(', ')}\n`;
+        }
+        shardSection += `\nServer: uptime=${stats.uptimeSecs}s, queries=${stats.queryCount}, memory=${stats.memoryPercent.toFixed(1)}%`;
+      }
+    } catch {
+      // Server may not support getStats yet — skip diagnostics
+    }
+  }
+
   return textResult(
     `Graph Statistics:\n\n` +
       `Total nodes: ${nodeCount.toLocaleString()}\n` +
       `Total edges: ${edgeCount.toLocaleString()}\n\n` +
       `Nodes by type:\n${JSON.stringify(nodesByType, null, 2)}\n\n` +
-      `Edges by type:\n${JSON.stringify(edgesByType, null, 2)}`
+      `Edges by type:\n${JSON.stringify(edgesByType, null, 2)}` +
+      shardSection
   );
 }
 
 export async function handleGetSchema(args: GetSchemaArgs): Promise<ToolResult> {
-  const db = await getOrCreateBackend();
+  const db = await ensureAnalyzed();
   const { type = 'all' } = args;
 
   const nodesByType = await db.countNodesByType();

package/src/handlers/context-handlers.ts

@@ -4,8 +4,8 @@
 
 import { ensureAnalyzed } from '../analysis.js';
 import { getProjectPath } from '../state.js';
-import { findCallsInFunction, findContainingFunction, FileOverview, buildNodeContext, getNodeDisplayName, formatEdgeMetadata, STRUCTURAL_EDGE_TYPES } from '@grafema/core';
-import type { CallInfo, CallerInfo, NodeContext } from '@grafema/core';
+import { findCallsInFunction, findContainingFunction, FileOverview, buildNodeContext, getNodeDisplayName, formatEdgeMetadata, STRUCTURAL_EDGE_TYPES, isGrafemaUri, toCompactSemanticId } from '@grafema/util';
+import type { CallInfo, CallerInfo, NodeContext } from '@grafema/util';
 import { existsSync, readFileSync, realpathSync } from 'fs';
 import { isAbsolute, join, relative } from 'path';
 import {
@@ -26,12 +26,11 @@ import type {
 /**
  * Get comprehensive function details including calls made and callers.
  *
- * Graph structure:
- * ```
- * FUNCTION -[HAS_SCOPE]-> SCOPE -[CONTAINS]-> CALL/METHOD_CALL
- *                         SCOPE -[CONTAINS]-> SCOPE (nested blocks)
- * CALL -[CALLS]-> FUNCTION (target)
- * ```
+ * Supports two graph layouts (see findCallsInFunction for details):
+ * - Layout A: FUNCTION -> HAS_SCOPE -> SCOPE -> CONTAINS -> CALL (legacy)
+ * - Layout B: FUNCTION -> AWAITS|RETURNS|THROWS -> CALL (Rust orchestrator)
+ *
+ * In both layouts: CALL -[CALLS]-> FUNCTION (target)
  *
  * This is the core tool for understanding function behavior.
  * Use transitive=true to follow call chains (A -> B -> C).
@@ -42,12 +41,14 @@ export async function handleGetFunctionDetails(
   const db = await ensureAnalyzed();
   const { name, file, transitive = false } = args;
 
-  // Step 1: Find the function
+  // Step 1: Find the function (search both FUNCTION and METHOD nodes)
   const candidates: GraphNode[] = [];
-  for await (const node of db.queryNodes({ type: 'FUNCTION' })) {
-    if (node.name !== name) continue;
-    if (file && !node.file?.includes(file)) continue;
-    candidates.push(node);
+  for (const nodeType of ['FUNCTION', 'METHOD']) {
+    for await (const node of db.queryNodes({ type: nodeType })) {
+      if (node.name !== name) continue;
+      if (file && !node.file?.includes(file)) continue;
+      candidates.push(node);
+    }
   }
 
   if (candidates.length === 0) {
@@ -168,11 +169,14 @@ export async function handleGetContext(
   const db = await ensureAnalyzed();
   const { semanticId, contextLines: ctxLines = 3, edgeType } = args;
 
+  // Accept both grafema:// URI and compact format
+  const displayId = isGrafemaUri(semanticId) ? toCompactSemanticId(semanticId) : semanticId;
+
   // 1. Look up node
   const node = await db.getNode(semanticId);
   if (!node) {
     return errorResult(
-      `Node not found: "${semanticId}"\n` +
+      `Node not found: "${displayId}"\n` +
       `Use find_nodes or query_graph to find the correct semantic ID.`
     );
   }
@@ -324,7 +328,7 @@ export async function handleGetFileOverview(
 
   try {
     const overview = new FileOverview(db);
-    const result = await overview.getOverview(absolutePath, {
+    const result = await overview.getOverview(relativePath, {
       includeEdges,
     });
 

package/src/handlers/coverage-handlers.ts

@@ -3,7 +3,7 @@
  */
 
 import { getOrCreateBackend, getProjectPath } from '../state.js';
-import { CoverageAnalyzer } from '@grafema/core';
+import { CoverageAnalyzer } from '@grafema/util';
 import {
   textResult,
   errorResult,