@grafema/mcp 0.2.5-beta → 0.2.7

package/src/handlers/issue-handlers.ts

@@ -0,0 +1,81 @@
+/**
+ * MCP Issue Handlers
+ */
+
+import {
+  textResult,
+} from '../utils.js';
+import type {
+  ToolResult,
+  ReportIssueArgs,
+} from '../types.js';
+
+// === BUG REPORTING ===
+
+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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';
+  const githubToken = process.env.GITHUB_TOKEN || GRAFEMA_ISSUE_TOKEN;
+  const repo = 'Disentinel/grafema';
+
+  // Build issue body
+  const body = `## Description
+${description}
+
+${context ? `## Context\n\`\`\`\n${context}\n\`\`\`\n` : ''}
+## Environment
+- Grafema version: 0.1.0-alpha.1
+- Reported via: MCP tool
+
+---
+*This issue was automatically created via Grafema MCP server.*`;
+
+  // Try GitHub API if token is available
+  if (githubToken) {
+    try {
+      const response = await fetch(`https://api.github.com/repos/${repo}/issues`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `token ${githubToken}`,
+          'Content-Type': 'application/json',
+          'Accept': 'application/vnd.github.v3+json',
+        },
+        body: JSON.stringify({
+          title,
+          body,
+          labels: labels.filter(l => ['bug', 'enhancement', 'documentation', 'question'].includes(l)),
+        }),
+      });
+
+      if (response.ok) {
+        const issue = await response.json() as { html_url: string; number: number };
+        return textResult(
+          `✅ Issue created successfully!\n\n` +
+          `**Issue #${issue.number}**: ${issue.html_url}\n\n` +
+          `Thank you for reporting this issue.`
+        );
+      } else {
+        const error = await response.text();
+        throw new Error(`GitHub API error: ${response.status} - ${error}`);
+      }
+    } catch (error) {
+      // Fall through to manual template if API fails
+      console.error('[report_issue] GitHub API failed:', error);
+    }
+  }
+
+  // Fallback: return template for manual submission
+  const issueUrl = `https://github.com/${repo}/issues/new`;
+  const encodedTitle = encodeURIComponent(title);
+  const encodedBody = encodeURIComponent(body);
+  const encodedLabels = encodeURIComponent(labels.join(','));
+  const directUrl = `${issueUrl}?title=${encodedTitle}&body=${encodedBody}&labels=${encodedLabels}`;
+
+  return textResult(
+    `⚠️ Failed to create issue automatically. Please create it manually:\n\n` +
+    `**Quick link** (may truncate long descriptions):\n${directUrl}\n\n` +
+    `**Or copy this template to** ${issueUrl}:\n\n` +
+    `---\n**Title:** ${title}\n\n${body}\n---`
+  );
+}

package/src/handlers/project-handlers.ts

@@ -0,0 +1,200 @@
+/**
+ * MCP Project Handlers
+ */
+
+import { getProjectPath } from '../state.js';
+import { validateServices, validatePatterns, validateWorkspace, GRAFEMA_VERSION, getSchemaVersion } 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 {
+  textResult,
+  errorResult,
+} from '../utils.js';
+import type {
+  ToolResult,
+  ReadProjectStructureArgs,
+  WriteConfigArgs,
+} from '../types.js';
+
+// === 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> = {
+      version: getSchemaVersion(GRAFEMA_VERSION),
+    };
+
+    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/handlers/query-handlers.ts

@@ -0,0 +1,232 @@
+/**
+ * MCP Query Handlers
+ */
+
+import { ensureAnalyzed } from '../analysis.js';
+import {
+  normalizeLimit,
+  formatPaginationInfo,
+  guardResponseSize,
+  serializeBigInt,
+  findSimilarTypes,
+  textResult,
+  errorResult,
+} from '../utils.js';
+import type {
+  ToolResult,
+  QueryGraphArgs,
+  FindCallsArgs,
+  FindNodesArgs,
+  GraphNode,
+  DatalogBinding,
+  CallResult,
+} from '../types.js';
+
+// === QUERY HANDLERS ===
+
+export async function handleQueryGraph(args: QueryGraphArgs): Promise<ToolResult> {
+  const db = await ensureAnalyzed();
+  const { query, limit: requestedLimit, offset: requestedOffset, format: _format, explain: _explain } = args;
+
+  const limit = normalizeLimit(requestedLimit);
+  const offset = Math.max(0, requestedOffset || 0);
+
+  try {
+    // Check if backend supports Datalog queries
+    if (!('checkGuarantee' in db)) {
+      return errorResult('Backend does not support Datalog queries');
+    }
+
+    const checkFn = (db as unknown as { checkGuarantee: (q: string) => Promise<Array<{ bindings: Array<{ name: string; value: string }> }>> }).checkGuarantee;
+    const results = await checkFn(query);
+    const total = results.length;
+
+    if (total === 0) {
+      const nodeCounts = await db.countNodesByType();
+      const totalNodes = Object.values(nodeCounts).reduce((a, b) => a + b, 0);
+
+      const typeMatch = query.match(/node\([^,]+,\s*"([^"]+)"\)/);
+      const queriedType = typeMatch ? typeMatch[1] : null;
+
+      let hint = '';
+      if (queriedType && !nodeCounts[queriedType]) {
+        const availableTypes = Object.keys(nodeCounts);
+        const similar = findSimilarTypes(queriedType, availableTypes);
+        if (similar.length > 0) {
+          hint = `\n💡 Did you mean: ${similar.join(', ')}?`;
+        } else {
+          hint = `\n💡 Available types: ${availableTypes.slice(0, 10).join(', ')}${availableTypes.length > 10 ? '...' : ''}`;
+        }
+      }
+
+      return textResult(
+        `Query returned no results.${hint}\n📊 Graph: ${totalNodes.toLocaleString()} nodes`
+      );
+    }
+
+    const paginatedResults = results.slice(offset, offset + limit);
+    const hasMore = offset + limit < total;
+
+    const enrichedResults: unknown[] = [];
+    for (const result of paginatedResults) {
+      const nodeId = result.bindings?.find((b: DatalogBinding) => b.name === 'X')?.value;
+      if (nodeId) {
+        const node = await db.getNode(nodeId);
+        if (node) {
+          enrichedResults.push({
+            ...node,
+            id: nodeId,
+            file: node.file,
+            line: node.line,
+          });
+        }
+      }
+    }
+
+    const paginationInfo = formatPaginationInfo({
+      limit,
+      offset,
+      returned: enrichedResults.length,
+      total,
+      hasMore,
+    });
+
+    const responseText = `Found ${total} result(s):${paginationInfo}\n\n${JSON.stringify(
+      serializeBigInt(enrichedResults),
+      null,
+      2
+    )}`;
+
+    return textResult(guardResponseSize(responseText));
+  } catch (error) {
+    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, className } = args;
+
+  const limit = normalizeLimit(requestedLimit);
+  const offset = Math.max(0, requestedOffset || 0);
+
+  const calls: CallResult[] = [];
+  let skipped = 0;
+  let totalMatched = 0;
+
+  for await (const node of db.queryNodes({ type: 'CALL' })) {
+    if (node.name !== name && node['method'] !== name) continue;
+    if (className && node['object'] !== className) continue;
+
+    totalMatched++;
+
+    if (skipped < offset) {
+      skipped++;
+      continue;
+    }
+
+    if (calls.length >= limit) continue;
+
+    const callsEdges = await db.getOutgoingEdges(node.id, ['CALLS']);
+    const isResolved = callsEdges.length > 0;
+
+    let target = null;
+    if (isResolved) {
+      const targetNode = await db.getNode(callsEdges[0].dst);
+      target = targetNode
+        ? {
+            type: targetNode.type,
+            name: targetNode.name ?? '',
+            file: targetNode.file,
+            line: targetNode.line,
+          }
+        : null;
+    }
+
+    calls.push({
+      id: node.id,
+      name: node.name,
+      object: node['object'] as string | undefined,
+      file: node.file,
+      line: node.line,
+      resolved: isResolved,
+      target,
+    });
+  }
+
+  if (totalMatched === 0) {
+    return textResult(`No calls found for "${className ? className + '.' : ''}${name}"`);
+  }
+
+  const resolved = calls.filter(c => c.resolved).length;
+  const unresolved = calls.length - resolved;
+  const hasMore = offset + calls.length < totalMatched;
+
+  const paginationInfo = formatPaginationInfo({
+    limit,
+    offset,
+    returned: calls.length,
+    total: totalMatched,
+    hasMore,
+  });
+
+  const responseText =
+    `Found ${totalMatched} call(s) to "${className ? className + '.' : ''}${name}":${paginationInfo}\n` +
+    `- Resolved: ${resolved}\n` +
+    `- Unresolved: ${unresolved}\n\n` +
+    JSON.stringify(serializeBigInt(calls), null, 2);
+
+  return textResult(guardResponseSize(responseText));
+}
+
+export async function handleFindNodes(args: FindNodesArgs): Promise<ToolResult> {
+  const db = await ensureAnalyzed();
+  const { type, name, file, limit: requestedLimit, offset: requestedOffset } = args;
+
+  const limit = normalizeLimit(requestedLimit);
+  const offset = Math.max(0, requestedOffset || 0);
+
+  const filter: Record<string, unknown> = {};
+  if (type) filter.type = type;
+  if (name) filter.name = name;
+  if (file) filter.file = file;
+
+  const nodes: GraphNode[] = [];
+  let skipped = 0;
+  let totalMatched = 0;
+
+  for await (const node of db.queryNodes(filter)) {
+    totalMatched++;
+
+    if (skipped < offset) {
+      skipped++;
+      continue;
+    }
+
+    if (nodes.length < limit) {
+      nodes.push(node);
+    }
+  }
+
+  if (totalMatched === 0) {
+    return textResult('No nodes found matching criteria');
+  }
+
+  const hasMore = offset + nodes.length < totalMatched;
+  const paginationInfo = formatPaginationInfo({
+    limit,
+    offset,
+    returned: nodes.length,
+    total: totalMatched,
+    hasMore,
+  });
+
+  return textResult(
+    `Found ${totalMatched} node(s):${paginationInfo}\n\n${JSON.stringify(
+      serializeBigInt(nodes),
+      null,
+      2
+    )}`
+  );
+}

package/src/server.ts

@@ -39,14 +39,17 @@ import {
   handleFindGuards,
   handleReportIssue,
   handleGetFunctionDetails,
+  handleGetContext,
   handleReadProjectStructure,
   handleWriteConfig,
-} from './handlers.js';
+  handleGetFileOverview,
+} from './handlers/index.js';
 import type {
   ToolResult,
   ReportIssueArgs,
   GetDocumentationArgs,
   GetFunctionDetailsArgs,
+  GetContextArgs,
   QueryGraphArgs,
   FindCallsArgs,
   FindNodesArgs,
@@ -62,6 +65,7 @@ import type {
   FindGuardsArgs,
   ReadProjectStructureArgs,
   WriteConfigArgs,
+  GetFileOverviewArgs,
 } from './types.js';
 
 /**
@@ -203,6 +207,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         result = await handleGetFunctionDetails(asArgs<GetFunctionDetailsArgs>(args));
         break;
 
+      case 'get_context':
+        result = await handleGetContext(asArgs<GetContextArgs>(args));
+        break;
+
+      case 'get_file_overview':
+        result = await handleGetFileOverview(asArgs<GetFileOverviewArgs>(args));
+        break;
+
       case 'read_project_structure':
         result = await handleReadProjectStructure(asArgs<ReadProjectStructureArgs>(args));
         break;

package/src/types.ts

@@ -300,6 +300,21 @@ export interface GuardInfo {
   line: number;
 }
 
+// === NODE CONTEXT (REG-406) ===
+
+export interface GetContextArgs {
+  semanticId: string;
+  contextLines?: number;
+  edgeType?: string;
+}
+
+// === FILE OVERVIEW (REG-412) ===
+
+export interface GetFileOverviewArgs {
+  file: string;
+  include_edges?: boolean;
+}
+
 // === PROJECT STRUCTURE (REG-173) ===
 
 export interface ReadProjectStructureArgs {