@grafema/mcp 0.2.0-beta → 0.2.5-beta

package/src/handlers.ts

@@ -2,11 +2,14 @@
  * MCP Tool Handlers
  */
 
-import { join } from 'path';
 import { ensureAnalyzed } from './analysis.js';
 import { getProjectPath, getAnalysisStatus, getOrCreateBackend, getGuaranteeManager, getGuaranteeAPI, isAnalysisRunning } from './state.js';
-import { CoverageAnalyzer, findCallsInFunction, findContainingFunction } from '@grafema/core';
+import { CoverageAnalyzer, findCallsInFunction, findContainingFunction, validateServices, validatePatterns, validateWorkspace, getOnboardingInstruction } from '@grafema/core';
 import type { CallInfo, CallerInfo } from '@grafema/core';
+import { existsSync, readdirSync, statSync, writeFileSync, mkdirSync } from 'fs';
+import type { Dirent } from 'fs';
+import { join, basename } from 'path';
+import { stringify as stringifyYAML } from 'yaml';
 import {
   normalizeLimit,
   formatPaginationInfo,
@@ -34,8 +37,12 @@ import type {
   FindGuardsArgs,
   GuardInfo,
   GetFunctionDetailsArgs,
-  GraphBackend,
   GraphNode,
+  DatalogBinding,
+  CallResult,
+  ReportIssueArgs,
+  ReadProjectStructureArgs,
+  WriteConfigArgs,
 } from './types.js';
 import { isGuaranteeType } from '@grafema/core';
 
@@ -43,8 +50,7 @@ import { isGuaranteeType } from '@grafema/core';
 
 export async function handleQueryGraph(args: QueryGraphArgs): Promise<ToolResult> {
   const db = await ensureAnalyzed();
-  const { query, limit: requestedLimit, offset: requestedOffset, format } = args;
-  const explain = (args as any).explain;
+  const { query, limit: requestedLimit, offset: requestedOffset, format: _format, explain: _explain } = args;
 
   const limit = normalizeLimit(requestedLimit);
   const offset = Math.max(0, requestedOffset || 0);
@@ -87,7 +93,7 @@ export async function handleQueryGraph(args: QueryGraphArgs): Promise<ToolResult
 
     const enrichedResults: unknown[] = [];
     for (const result of paginatedResults) {
-      const nodeId = result.bindings?.find((b: any) => b.name === 'X')?.value;
+      const nodeId = result.bindings?.find((b: DatalogBinding) => b.name === 'X')?.value;
       if (nodeId) {
         const node = await db.getNode(nodeId);
         if (node) {
@@ -117,25 +123,25 @@ export async function handleQueryGraph(args: QueryGraphArgs): Promise<ToolResult
 
     return textResult(guardResponseSize(responseText));
   } catch (error) {
-    return errorResult((error as Error).message);
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(message);
   }
 }
 
 export async function handleFindCalls(args: FindCallsArgs): Promise<ToolResult> {
   const db = await ensureAnalyzed();
-  const { target: name, limit: requestedLimit, offset: requestedOffset } = args;
-  const className = (args as any).className;
+  const { target: name, limit: requestedLimit, offset: requestedOffset, className } = args;
 
   const limit = normalizeLimit(requestedLimit);
   const offset = Math.max(0, requestedOffset || 0);
 
-  const calls: unknown[] = [];
+  const calls: CallResult[] = [];
   let skipped = 0;
   let totalMatched = 0;
 
   for await (const node of db.queryNodes({ type: 'CALL' })) {
-    if ((node as any).name !== name && (node as any).method !== name) continue;
-    if (className && (node as any).object !== className) continue;
+    if (node.name !== name && node['method'] !== name) continue;
+    if (className && node['object'] !== className) continue;
 
     totalMatched++;
 
@@ -155,7 +161,7 @@ export async function handleFindCalls(args: FindCallsArgs): Promise<ToolResult>
       target = targetNode
         ? {
             type: targetNode.type,
-            name: targetNode.name,
+            name: targetNode.name ?? '',
             file: targetNode.file,
             line: targetNode.line,
           }
@@ -164,8 +170,8 @@ export async function handleFindCalls(args: FindCallsArgs): Promise<ToolResult>
 
     calls.push({
       id: node.id,
-      name: (node as any).name,
-      object: (node as any).object,
+      name: node.name,
+      object: node['object'] as string | undefined,
       file: node.file,
       line: node.line,
       resolved: isResolved,
@@ -177,7 +183,7 @@ export async function handleFindCalls(args: FindCallsArgs): Promise<ToolResult>
     return textResult(`No calls found for "${className ? className + '.' : ''}${name}"`);
   }
 
-  const resolved = calls.filter((c: any) => c.resolved).length;
+  const resolved = calls.filter(c => c.resolved).length;
   const unresolved = calls.length - resolved;
   const hasMore = offset + calls.length < totalMatched;
 
@@ -254,7 +260,7 @@ export async function handleFindNodes(args: FindNodesArgs): Promise<ToolResult>
 export async function handleTraceAlias(args: TraceAliasArgs): Promise<ToolResult> {
   const db = await ensureAnalyzed();
   const { variableName, file } = args;
-  const projectPath = getProjectPath();
+  const _projectPath = getProjectPath();
 
   let varNode: GraphNode | null = null;
 
@@ -419,7 +425,8 @@ export async function handleCheckInvariant(args: CheckInvariantArgs): Promise<To
       )}${total > 20 ? `\n\n... and ${total - 20} more` : ''}`
     );
   } catch (error) {
-    return errorResult((error as Error).message);
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(message);
   }
 }
 
@@ -451,7 +458,8 @@ export async function handleAnalyzeProject(args: AnalyzeProjectArgs): Promise<To
         `- Total time: ${status.timings.total || 'N/A'}s`
     );
   } catch (error) {
-    return errorResult((error as Error).message);
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(message);
   }
 }
 
@@ -576,7 +584,8 @@ export async function handleCreateGuarantee(args: CreateGuaranteeArgs): Promise<
       );
     }
   } catch (error) {
-    return errorResult(`Failed to create guarantee: ${(error as Error).message}`);
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to create guarantee: ${message}`);
   }
 }
 
@@ -622,7 +631,8 @@ export async function handleListGuarantees(): Promise<ToolResult> {
 
     return textResult(results.join('\n'));
   } catch (error) {
-    return errorResult(`Failed to list guarantees: ${(error as Error).message}`);
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to list guarantees: ${message}`);
   }
 }
 
@@ -731,7 +741,8 @@ export async function handleCheckGuarantees(args: CheckGuaranteesArgs): Promise<
     const summary = `\n---\nTotal: ${totalPassed + totalFailed} | ✅ Passed: ${totalPassed} | ❌ Failed: ${totalFailed}`;
     return textResult(results.join('\n') + summary);
   } catch (error) {
-    return errorResult(`Failed to check guarantees: ${(error as Error).message}`);
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to check guarantees: ${message}`);
   }
 }
 
@@ -766,7 +777,8 @@ export async function handleDeleteGuarantee(args: DeleteGuaranteeArgs): Promise<
 
     return errorResult(`Guarantee not found: ${name}`);
   } catch (error) {
-    return errorResult(`Failed to delete guarantee: ${(error as Error).message}`);
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to delete guarantee: ${message}`);
   }
 }
 
@@ -807,7 +819,8 @@ export async function handleGetCoverage(args: GetCoverageArgs): Promise<ToolResu
 
     return textResult(output);
   } catch (error) {
-    return errorResult(`Failed to calculate coverage: ${(error as Error).message}`);
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to calculate coverage: ${message}`);
   }
 }
 
@@ -815,6 +828,7 @@ export async function handleGetDocumentation(args: GetDocumentationArgs): Promis
   const { topic = 'overview' } = args;
 
   const docs: Record<string, string> = {
+    onboarding: getOnboardingInstruction(),
     overview: `
 # Grafema Code Analysis
 
@@ -855,7 +869,7 @@ Find unresolved calls:
 
 ## Core Node Types
 - MODULE, FUNCTION, CLASS, METHOD, VARIABLE
-- CALL, IMPORT, EXPORT, PARAMETER
+- CALL, PROPERTY_ACCESS, IMPORT, EXPORT, PARAMETER
 
 ## HTTP/Network
 - http:route, http:request, db:query
@@ -1111,7 +1125,7 @@ function formatCallsForDisplay(calls: CallInfo[]): string[] {
 
 // === BUG REPORTING ===
 
-export async function handleReportIssue(args: import('./types.js').ReportIssueArgs): Promise<ToolResult> {
+export async function handleReportIssue(args: ReportIssueArgs): Promise<ToolResult> {
   const { title, description, context, labels = ['bug'] } = args;
   // Use user's token if provided, otherwise fall back to project's issue-only token
   const GRAFEMA_ISSUE_TOKEN = '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';
@@ -1178,3 +1192,182 @@ ${context ? `## Context\n\`\`\`\n${context}\n\`\`\`\n` : ''}
     `---\n**Title:** ${title}\n\n${body}\n---`
   );
 }
+
+// === PROJECT STRUCTURE (REG-173) ===
+
+export async function handleReadProjectStructure(
+  args: ReadProjectStructureArgs
+): Promise<ToolResult> {
+  const projectPath = getProjectPath();
+  const subPath = args.path || '.';
+  const maxDepth = Math.min(Math.max(1, args.depth || 3), 5);
+  const includeFiles = args.include_files !== false;
+
+  const targetPath = join(projectPath, subPath);
+
+  if (!existsSync(targetPath)) {
+    return errorResult(`Path does not exist: ${subPath}`);
+  }
+
+  if (!statSync(targetPath).isDirectory()) {
+    return errorResult(`Path is not a directory: ${subPath}`);
+  }
+
+  const EXCLUDED = new Set([
+    'node_modules', '.git', 'dist', 'build', '.grafema',
+    'coverage', '.next', '.nuxt', '.cache', '.output',
+    '__pycache__', '.tox', 'target',
+  ]);
+
+  const lines: string[] = [];
+
+  function walk(dir: string, prefix: string, depth: number): void {
+    if (depth > maxDepth) return;
+
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    const dirs: string[] = [];
+    const files: string[] = [];
+
+    for (const entry of entries) {
+      if (EXCLUDED.has(entry.name)) continue;
+
+      if (entry.isDirectory()) {
+        dirs.push(entry.name);
+      } else if (includeFiles) {
+        files.push(entry.name);
+      }
+    }
+
+    dirs.sort();
+    files.sort();
+
+    const allEntries = [
+      ...dirs.map(d => ({ name: d, isDir: true })),
+      ...files.map(f => ({ name: f, isDir: false })),
+    ];
+
+    for (let i = 0; i < allEntries.length; i++) {
+      const entry = allEntries[i];
+      const isLast = i === allEntries.length - 1;
+      const connector = isLast ? '└── ' : '├── ';
+      const childPrefix = isLast ? '    ' : '│   ';
+
+      if (entry.isDir) {
+        lines.push(`${prefix}${connector}${entry.name}/`);
+        walk(join(dir, entry.name), prefix + childPrefix, depth + 1);
+      } else {
+        lines.push(`${prefix}${connector}${entry.name}`);
+      }
+    }
+  }
+
+  lines.push(subPath === '.' ? basename(projectPath) + '/' : subPath + '/');
+  walk(targetPath, '', 1);
+
+  if (lines.length === 1) {
+    return textResult(`Directory is empty or contains only excluded entries: ${subPath}`);
+  }
+
+  return textResult(lines.join('\n'));
+}
+
+// === WRITE CONFIG (REG-173) ===
+
+export async function handleWriteConfig(
+  args: WriteConfigArgs
+): Promise<ToolResult> {
+  const projectPath = getProjectPath();
+  const grafemaDir = join(projectPath, '.grafema');
+  const configPath = join(grafemaDir, 'config.yaml');
+
+  try {
+    if (args.services) {
+      validateServices(args.services, projectPath);
+    }
+
+    if (args.include !== undefined || args.exclude !== undefined) {
+      const warnings: string[] = [];
+      validatePatterns(args.include, args.exclude, {
+        warn: (msg: string) => warnings.push(msg),
+      });
+    }
+
+    if (args.workspace) {
+      validateWorkspace(args.workspace, projectPath);
+    }
+
+    const config: Record<string, unknown> = {};
+
+    if (args.services && args.services.length > 0) {
+      config.services = args.services;
+    }
+
+    if (args.plugins) {
+      config.plugins = args.plugins;
+    }
+
+    if (args.include) {
+      config.include = args.include;
+    }
+
+    if (args.exclude) {
+      config.exclude = args.exclude;
+    }
+
+    if (args.workspace) {
+      config.workspace = args.workspace;
+    }
+
+    const yaml = stringifyYAML(config, { lineWidth: 0 });
+    const content =
+      '# Grafema Configuration\n' +
+      '# Generated by Grafema onboarding\n' +
+      '# Documentation: https://github.com/grafema/grafema#configuration\n\n' +
+      yaml;
+
+    if (!existsSync(grafemaDir)) {
+      mkdirSync(grafemaDir, { recursive: true });
+    }
+
+    writeFileSync(configPath, content);
+
+    const summary: string[] = ['Configuration written to .grafema/config.yaml'];
+
+    if (args.services && args.services.length > 0) {
+      summary.push(`Services: ${args.services.map(s => s.name).join(', ')}`);
+    } else {
+      summary.push('Services: using auto-discovery (none explicitly configured)');
+    }
+
+    if (args.plugins) {
+      summary.push('Plugins: custom configuration');
+    } else {
+      summary.push('Plugins: using defaults');
+    }
+
+    if (args.include) {
+      summary.push(`Include patterns: ${args.include.join(', ')}`);
+    }
+
+    if (args.exclude) {
+      summary.push(`Exclude patterns: ${args.exclude.join(', ')}`);
+    }
+
+    if (args.workspace?.roots) {
+      summary.push(`Workspace roots: ${args.workspace.roots.join(', ')}`);
+    }
+
+    summary.push('\nNext step: run analyze_project to build the graph.');
+
+    return textResult(summary.join('\n'));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to write config: ${message}`);
+  }
+}

package/src/prompts.ts

@@ -0,0 +1,56 @@
+/**
+ * MCP Prompts handler logic.
+ * Extracted for testability — server.ts is a thin wrapper.
+ */
+import { getOnboardingInstruction } from '@grafema/core';
+
+export interface PromptDefinition {
+  name: string;
+  description: string;
+  arguments: Array<{ name: string; description: string; required?: boolean }>;
+}
+
+export interface PromptMessage {
+  role: 'user' | 'assistant';
+  content: { type: 'text'; text: string };
+}
+
+export interface PromptResult {
+  [x: string]: unknown;
+  description: string;
+  messages: PromptMessage[];
+  _meta?: Record<string, unknown>;
+}
+
+export const PROMPTS: PromptDefinition[] = [
+  {
+    name: 'onboard_project',
+    description:
+      'Step-by-step instructions for studying a new project and ' +
+      'configuring Grafema for analysis. Use this when setting up ' +
+      'Grafema for the first time on a project.',
+    arguments: [],
+  },
+];
+
+export function getPrompt(name: string): PromptResult {
+  if (name === 'onboard_project') {
+    const instruction = getOnboardingInstruction();
+    return {
+      description: PROMPTS[0].description,
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: instruction,
+          },
+        },
+      ],
+    };
+  }
+
+  throw new Error(
+    `Unknown prompt: ${name}. Available prompts: ${PROMPTS.map(p => p.name).join(', ')}`
+  );
+}

package/src/server.ts

@@ -10,12 +10,15 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
+import { PROMPTS, getPrompt } from './prompts.js';
 
 import { TOOLS } from './definitions.js';
 import { initializeFromArgs, setupLogging, getProjectPath } from './state.js';
 import { textResult, errorResult, log } from './utils.js';
-import { ensureAnalyzed, discoverServices } from './analysis.js';
+import { discoverServices } from './analysis.js';
 import {
   handleQueryGraph,
   handleFindCalls,
@@ -36,8 +39,39 @@ import {
   handleFindGuards,
   handleReportIssue,
   handleGetFunctionDetails,
+  handleReadProjectStructure,
+  handleWriteConfig,
 } from './handlers.js';
-import type { ToolResult, ReportIssueArgs, GetDocumentationArgs, GetFunctionDetailsArgs } from './types.js';
+import type {
+  ToolResult,
+  ReportIssueArgs,
+  GetDocumentationArgs,
+  GetFunctionDetailsArgs,
+  QueryGraphArgs,
+  FindCallsArgs,
+  FindNodesArgs,
+  TraceAliasArgs,
+  TraceDataFlowArgs,
+  CheckInvariantArgs,
+  AnalyzeProjectArgs,
+  GetSchemaArgs,
+  CreateGuaranteeArgs,
+  CheckGuaranteesArgs,
+  DeleteGuaranteeArgs,
+  GetCoverageArgs,
+  FindGuardsArgs,
+  ReadProjectStructureArgs,
+  WriteConfigArgs,
+} from './types.js';
+
+/**
+ * Type-safe argument casting helper.
+ * MCP SDK provides args as Record<string, unknown>, this helper
+ * casts them to the expected handler argument type.
+ */
+function asArgs<T>(args: Record<string, unknown> | undefined): T {
+  return (args ?? {}) as T;
+}
 
 // Initialize from command line args
 initializeFromArgs();
@@ -55,6 +89,7 @@ const server = new Server(
   {
     capabilities: {
       tools: {},
+      prompts: {},
     },
   }
 );
@@ -64,6 +99,16 @@ server.setRequestHandler(ListToolsRequestSchema, async (_request, _extra) => {
   return { tools: TOOLS };
 });
 
+// List available prompts
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  return { prompts: PROMPTS };
+});
+
+// Get prompt by name
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  return getPrompt(request.params.name);
+});
+
 // Handle tool calls
 server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
   void extra; // suppress unused warning
@@ -78,27 +123,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
 
     switch (name) {
       case 'query_graph':
-        result = await handleQueryGraph(args as any);
+        result = await handleQueryGraph(asArgs<QueryGraphArgs>(args));
         break;
 
       case 'find_calls':
-        result = await handleFindCalls(args as any);
+        result = await handleFindCalls(asArgs<FindCallsArgs>(args));
         break;
 
       case 'find_nodes':
-        result = await handleFindNodes(args as any);
+        result = await handleFindNodes(asArgs<FindNodesArgs>(args));
         break;
 
       case 'trace_alias':
-        result = await handleTraceAlias(args as any);
+        result = await handleTraceAlias(asArgs<TraceAliasArgs>(args));
         break;
 
       case 'trace_dataflow':
-        result = await handleTraceDataFlow(args as any);
+        result = await handleTraceDataFlow(asArgs<TraceDataFlowArgs>(args));
         break;
 
       case 'check_invariant':
-        result = await handleCheckInvariant(args as any);
+        result = await handleCheckInvariant(asArgs<CheckInvariantArgs>(args));
         break;
 
       case 'discover_services':
@@ -107,7 +152,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         break;
 
       case 'analyze_project':
-        result = await handleAnalyzeProject(args as any);
+        result = await handleAnalyzeProject(asArgs<AnalyzeProjectArgs>(args));
         break;
 
       case 'get_analysis_status':
@@ -119,11 +164,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         break;
 
       case 'get_schema':
-        result = await handleGetSchema(args as any);
+        result = await handleGetSchema(asArgs<GetSchemaArgs>(args));
         break;
 
       case 'create_guarantee':
-        result = await handleCreateGuarantee(args as any);
+        result = await handleCreateGuarantee(asArgs<CreateGuaranteeArgs>(args));
         break;
 
       case 'list_guarantees':
@@ -131,31 +176,39 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         break;
 
       case 'check_guarantees':
-        result = await handleCheckGuarantees(args as any);
+        result = await handleCheckGuarantees(asArgs<CheckGuaranteesArgs>(args));
         break;
 
       case 'delete_guarantee':
-        result = await handleDeleteGuarantee(args as any);
+        result = await handleDeleteGuarantee(asArgs<DeleteGuaranteeArgs>(args));
         break;
 
       case 'get_coverage':
-        result = await handleGetCoverage(args as any);
+        result = await handleGetCoverage(asArgs<GetCoverageArgs>(args));
         break;
 
       case 'get_documentation':
-        result = await handleGetDocumentation(args as GetDocumentationArgs);
+        result = await handleGetDocumentation(asArgs<GetDocumentationArgs>(args));
         break;
 
       case 'find_guards':
-        result = await handleFindGuards(args as any);
+        result = await handleFindGuards(asArgs<FindGuardsArgs>(args));
         break;
 
       case 'report_issue':
-        result = await handleReportIssue(args as unknown as ReportIssueArgs);
+        result = await handleReportIssue(asArgs<ReportIssueArgs>(args));
         break;
 
       case 'get_function_details':
-        result = await handleGetFunctionDetails(args as unknown as GetFunctionDetailsArgs);
+        result = await handleGetFunctionDetails(asArgs<GetFunctionDetailsArgs>(args));
+        break;
+
+      case 'read_project_structure':
+        result = await handleReadProjectStructure(asArgs<ReadProjectStructureArgs>(args));
+        break;
+
+      case 'write_config':
+        result = await handleWriteConfig(asArgs<WriteConfigArgs>(args));
         break;
 
       default:
@@ -170,8 +223,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     return result;
   } catch (error) {
     const duration = Date.now() - startTime;
-    log(`[Grafema MCP] ✗ ${name} FAILED after ${duration}ms: ${(error as Error).message}`);
-    return errorResult((error as Error).message);
+    const message = error instanceof Error ? error.message : String(error);
+    log(`[Grafema MCP] ✗ ${name} FAILED after ${duration}ms: ${message}`);
+    return errorResult(message);
   }
 });