@grafema/mcp 0.2.1-beta → 0.2.6-beta

package/src/definitions.ts

@@ -6,9 +6,11 @@ import { DEFAULT_LIMIT, MAX_LIMIT } from './utils.js';
 
 interface SchemaProperty {
   type: string;
-  description: string;
+  description?: string;
   enum?: string[];
-  items?: { type: string };
+  items?: SchemaProperty;
+  properties?: Record<string, SchemaProperty>;
+  required?: string[];
 }
 
 export interface ToolDefinition {
@@ -33,7 +35,7 @@ Available predicates:
 
 NODE TYPES:
 - MODULE, FUNCTION, METHOD, CLASS, VARIABLE, PARAMETER
-- CALL, METHOD_CALL, CALL_SITE
+- CALL, PROPERTY_ACCESS, METHOD_CALL, CALL_SITE
 - http:route, http:request, db:query, socketio:emit, socketio:on
 
 EDGE TYPES:
@@ -101,7 +103,7 @@ Returns call sites with file locations and whether they're resolved.`,
       properties: {
         type: {
           type: 'string',
-          description: 'Node type (e.g., FUNCTION, CLASS, MODULE)',
+          description: 'Node type (e.g., FUNCTION, CLASS, MODULE, PROPERTY_ACCESS)',
         },
         name: {
           type: 'string',
@@ -390,7 +392,7 @@ Examples:
       properties: {
         topic: {
           type: 'string',
-          description: 'Topic: queries, types, guarantees, or overview',
+          description: 'Topic: queries, types, guarantees, onboarding, or overview',
         },
       },
     },
@@ -505,4 +507,159 @@ Max transitive depth is 5 to prevent explosion.`,
       required: ['name'],
     },
   },
+  {
+    name: 'get_context',
+    description: `Get deep context for a graph node: source code + full graph neighborhood.
+
+Shows ALL incoming and outgoing edges grouped by type, with source code
+at each connected node's location. Works for ANY node type.
+
+Use this after find_nodes or query_graph to deep-dive into a specific node.
+
+Output includes:
+- Node info (type, name, semantic ID, location)
+- Source code at the node's location
+- All outgoing edges (what this node connects to)
+- All incoming edges (what connects to this node)
+- Code context at each connected node's location
+
+Primary edges (CALLS, ASSIGNED_FROM, DEPENDS_ON, etc.) include code context.
+Structural edges (CONTAINS, HAS_SCOPE, etc.) are shown in compact form.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        semanticId: {
+          type: 'string',
+          description: 'Exact semantic ID of the node (from find_nodes or query_graph)',
+        },
+        contextLines: {
+          type: 'number',
+          description: 'Lines of code context around each reference (default: 3)',
+        },
+        edgeType: {
+          type: 'string',
+          description: 'Filter by edge type (comma-separated, e.g., "CALLS,ASSIGNED_FROM")',
+        },
+      },
+      required: ['semanticId'],
+    },
+  },
+  {
+    name: 'get_file_overview',
+    description: `Get a structured overview of all entities in a file with their relationships.
+
+Shows imports, exports, classes, functions, and variables with key edges
+(CALLS, EXTENDS, ASSIGNED_FROM). Use this for file-level understanding
+before diving into specific nodes with get_context.
+
+Output includes:
+- Imports: module sources and imported names
+- Exports: named and default exports
+- Classes: with methods and their call targets
+- Functions: with call targets
+- Variables: with assignment sources
+
+This is the recommended first step when exploring a file.
+After using this, use get_context with specific node IDs for details.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: {
+          type: 'string',
+          description: 'File path (relative to project root or absolute)',
+        },
+        include_edges: {
+          type: 'boolean',
+          description:
+            'Include relationship edges like CALLS, EXTENDS (default: true). Set false for faster results.',
+        },
+      },
+      required: ['file'],
+    },
+  },
+  {
+    name: 'read_project_structure',
+    description: `Get the directory structure of the project.
+Returns a tree of files and directories, useful for understanding
+project layout during onboarding.
+
+Excludes: node_modules, .git, dist, build, .grafema, coverage, .next, .nuxt
+
+Use this tool when studying a new project to identify services,
+packages, and entry points.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Subdirectory to scan (relative to project root). Default: project root.',
+        },
+        depth: {
+          type: 'number',
+          description: 'Maximum directory depth (default: 3, max: 5)',
+        },
+        include_files: {
+          type: 'boolean',
+          description: 'Include files in output, not just directories (default: true)',
+        },
+      },
+    },
+  },
+  {
+    name: 'write_config',
+    description: `Write or update the Grafema configuration file (.grafema/config.yaml).
+Validates all inputs before writing. Creates .grafema/ directory if needed.
+
+Use this tool after studying the project to save the discovered configuration.
+Only include fields you want to override — defaults are used for omitted fields.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        services: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', description: 'Service name (e.g., "backend")' },
+              path: { type: 'string', description: 'Path relative to project root (e.g., "apps/backend")' },
+              entryPoint: { type: 'string', description: 'Entry point file relative to service path (e.g., "src/index.ts")' },
+            },
+            required: ['name', 'path'],
+          },
+          description: 'Service definitions (leave empty to use auto-discovery)',
+        },
+        plugins: {
+          type: 'object',
+          properties: {
+            indexing: { type: 'array', items: { type: 'string' }, description: 'Indexing plugins' },
+            analysis: { type: 'array', items: { type: 'string' }, description: 'Analysis plugins' },
+            enrichment: { type: 'array', items: { type: 'string' }, description: 'Enrichment plugins' },
+            validation: { type: 'array', items: { type: 'string' }, description: 'Validation plugins' },
+          },
+          description: 'Plugin configuration (omit to use defaults)',
+        },
+        include: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Glob patterns for files to include (e.g., ["src/**/*.ts"])',
+        },
+        exclude: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Glob patterns for files to exclude (e.g., ["**/*.test.ts"])',
+        },
+        workspace: {
+          type: 'object',
+          properties: {
+            roots: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Root directories for multi-root workspace',
+            },
+          },
+          description: 'Multi-root workspace config (only for workspaces)',
+        },
+      },
+    },
+  },
 ];

package/src/handlers/analysis-handlers.ts

@@ -0,0 +1,105 @@
+/**
+ * MCP Analysis Handlers
+ */
+
+import { ensureAnalyzed } from '../analysis.js';
+import { getAnalysisStatus, getOrCreateBackend, isAnalysisRunning } from '../state.js';
+import {
+  textResult,
+  errorResult,
+} from '../utils.js';
+import type {
+  ToolResult,
+  AnalyzeProjectArgs,
+  GetSchemaArgs,
+} from '../types.js';
+
+// === ANALYSIS HANDLERS ===
+
+export async function handleAnalyzeProject(args: AnalyzeProjectArgs): Promise<ToolResult> {
+  const { service, force } = args;
+
+  // 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, force || false);
+    const status = getAnalysisStatus();
+
+    return textResult(
+      `Analysis complete!\n` +
+        `- Services discovered: ${status.servicesDiscovered}\n` +
+        `- Services analyzed: ${status.servicesAnalyzed}\n` +
+        `- Total time: ${status.timings.total || 'N/A'}s`
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(message);
+  }
+}
+
+export async function handleGetAnalysisStatus(): Promise<ToolResult> {
+  const status = getAnalysisStatus();
+
+  return textResult(
+    `Analysis Status:\n` +
+      `- Running: ${status.running}\n` +
+      `- Phase: ${status.phase || 'N/A'}\n` +
+      `- Message: ${status.message || 'N/A'}\n` +
+      `- Services discovered: ${status.servicesDiscovered}\n` +
+      `- Services analyzed: ${status.servicesAnalyzed}\n` +
+      (status.error ? `- Error: ${status.error}\n` : '')
+  );
+}
+
+export async function handleGetStats(): Promise<ToolResult> {
+  const db = await getOrCreateBackend();
+
+  const nodeCount = await db.nodeCount();
+  const edgeCount = await db.edgeCount();
+  const nodesByType = await db.countNodesByType();
+  const edgesByType = await db.countEdgesByType();
+
+  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)}`
+  );
+}
+
+export async function handleGetSchema(args: GetSchemaArgs): Promise<ToolResult> {
+  const db = await getOrCreateBackend();
+  const { type = 'all' } = args;
+
+  const nodesByType = await db.countNodesByType();
+  const edgesByType = await db.countEdgesByType();
+
+  let output = '';
+
+  if (type === 'nodes' || type === 'all') {
+    output += `Node Types (${Object.keys(nodesByType).length}):\n`;
+    for (const [t, count] of Object.entries(nodesByType)) {
+      output += `  - ${t}: ${count}\n`;
+    }
+  }
+
+  if (type === 'edges' || type === 'all') {
+    output += `\nEdge Types (${Object.keys(edgesByType).length}):\n`;
+    for (const [t, count] of Object.entries(edgesByType)) {
+      output += `  - ${t}: ${count}\n`;
+    }
+  }
+
+  return textResult(output);
+}