@grafema/mcp 0.1.0-alpha.1

package/src/server.ts

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * Grafema MCP Server
+ *
+ * Provides code analysis tools via Model Context Protocol.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.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 {
+  handleQueryGraph,
+  handleFindCalls,
+  handleFindNodes,
+  handleTraceAlias,
+  handleTraceDataFlow,
+  handleCheckInvariant,
+  handleAnalyzeProject,
+  handleGetAnalysisStatus,
+  handleGetStats,
+  handleGetSchema,
+  handleCreateGuarantee,
+  handleListGuarantees,
+  handleCheckGuarantees,
+  handleDeleteGuarantee,
+  handleGetCoverage,
+  handleGetDocumentation,
+  handleReportIssue,
+} from './handlers.js';
+import type { ToolResult, ReportIssueArgs, GetDocumentationArgs } from './types.js';
+
+// Initialize from command line args
+initializeFromArgs();
+setupLogging();
+
+const projectPath = getProjectPath();
+log(`[Grafema MCP] Starting server for project: ${projectPath}`);
+
+// Create MCP server
+const server = new Server(
+  {
+    name: 'grafema-mcp',
+    version: '0.1.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async (_request, _extra) => {
+  return { tools: TOOLS };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+  void extra; // suppress unused warning
+  const { name, arguments: args } = request.params;
+
+  const startTime = Date.now();
+  const argsPreview = args ? JSON.stringify(args).slice(0, 200) : '{}';
+  log(`[Grafema MCP] ▶ ${name} args=${argsPreview}`);
+
+  try {
+    let result: ToolResult;
+
+    switch (name) {
+      case 'query_graph':
+        result = await handleQueryGraph(args as any);
+        break;
+
+      case 'find_calls':
+        result = await handleFindCalls(args as any);
+        break;
+
+      case 'find_nodes':
+        result = await handleFindNodes(args as any);
+        break;
+
+      case 'trace_alias':
+        result = await handleTraceAlias(args as any);
+        break;
+
+      case 'trace_dataflow':
+        result = await handleTraceDataFlow(args as any);
+        break;
+
+      case 'check_invariant':
+        result = await handleCheckInvariant(args as any);
+        break;
+
+      case 'discover_services':
+        const services = await discoverServices();
+        result = textResult(`Found ${services.length} service(s):\n${JSON.stringify(services, null, 2)}`);
+        break;
+
+      case 'analyze_project':
+        result = await handleAnalyzeProject(args as any);
+        break;
+
+      case 'get_analysis_status':
+        result = await handleGetAnalysisStatus();
+        break;
+
+      case 'get_stats':
+        result = await handleGetStats();
+        break;
+
+      case 'get_schema':
+        result = await handleGetSchema(args as any);
+        break;
+
+      case 'create_guarantee':
+        result = await handleCreateGuarantee(args as any);
+        break;
+
+      case 'list_guarantees':
+        result = await handleListGuarantees();
+        break;
+
+      case 'check_guarantees':
+        result = await handleCheckGuarantees(args as any);
+        break;
+
+      case 'delete_guarantee':
+        result = await handleDeleteGuarantee(args as any);
+        break;
+
+      case 'get_coverage':
+        result = await handleGetCoverage(args as any);
+        break;
+
+      case 'get_documentation':
+        result = await handleGetDocumentation(args as GetDocumentationArgs);
+        break;
+
+      case 'report_issue':
+        result = await handleReportIssue(args as unknown as ReportIssueArgs);
+        break;
+
+      default:
+        result = errorResult(`Unknown tool: ${name}`);
+    }
+
+    const duration = Date.now() - startTime;
+    const resultSize = JSON.stringify(result).length;
+    const status = result.isError ? '✗' : '✓';
+    log(`[Grafema MCP] ${status} ${name} completed in ${duration}ms (${resultSize} bytes)`);
+
+    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);
+  }
+});
+
+// Main entry point
+async function main(): Promise<void> {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log('[Grafema MCP] Server connected via stdio');
+}
+
+main().catch((error) => {
+  log(`[Grafema MCP] Fatal error: ${error.message}`);
+  process.exit(1);
+});

package/src/state.ts

@@ -0,0 +1,169 @@
+/**
+ * MCP Server State Management
+ */
+
+import { join } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+import { RFDBServerBackend, GuaranteeManager, GuaranteeAPI } from '@grafema/core';
+import type { GuaranteeGraphBackend, GuaranteeGraph } from '@grafema/core';
+import { loadConfig } from './config.js';
+import { log, initLogger } from './utils.js';
+import type { AnalysisStatus } from './types.js';
+import type { GraphBackend } from '@grafema/types';
+
+// === GLOBAL STATE ===
+let projectPath: string = process.cwd();
+let backend: GraphBackend | null = null;
+let isAnalyzed: boolean = false;
+let backgroundPid: number | null = null;
+
+// Guarantee managers
+let guaranteeManager: GuaranteeManager | null = null;
+let guaranteeAPI: GuaranteeAPI | null = null;
+
+let analysisStatus: AnalysisStatus = {
+  running: false,
+  phase: null,
+  message: null,
+  servicesDiscovered: 0,
+  servicesAnalyzed: 0,
+  startTime: null,
+  endTime: null,
+  error: null,
+  timings: {
+    discovery: null,
+    indexing: null,
+    analysis: null,
+    enrichment: null,
+    validation: null,
+    total: null,
+  },
+};
+
+// === GETTERS ===
+export function getProjectPath(): string {
+  return projectPath;
+}
+
+export function getIsAnalyzed(): boolean {
+  return isAnalyzed;
+}
+
+export function getAnalysisStatus(): AnalysisStatus {
+  return analysisStatus;
+}
+
+export function getBackgroundPid(): number | null {
+  return backgroundPid;
+}
+
+export function getGuaranteeManager(): GuaranteeManager | null {
+  return guaranteeManager;
+}
+
+export function getGuaranteeAPI(): GuaranteeAPI | null {
+  return guaranteeAPI;
+}
+
+// === SETTERS ===
+export function setProjectPath(path: string): void {
+  projectPath = path;
+}
+
+export function setIsAnalyzed(value: boolean): void {
+  isAnalyzed = value;
+}
+
+export function setAnalysisStatus(status: Partial<AnalysisStatus>): void {
+  analysisStatus = { ...analysisStatus, ...status };
+}
+
+export function setBackgroundPid(pid: number | null): void {
+  backgroundPid = pid;
+}
+
+export function updateAnalysisTimings(timings: Partial<AnalysisStatus['timings']>): void {
+  analysisStatus.timings = { ...analysisStatus.timings, ...timings };
+}
+
+// === BACKEND ===
+export async function getOrCreateBackend(): Promise<GraphBackend> {
+  if (backend) return backend;
+
+  const grafemaDir = join(projectPath, '.grafema');
+  const dbPath = join(grafemaDir, 'graph.rfdb');
+
+  if (!existsSync(grafemaDir)) {
+    mkdirSync(grafemaDir, { recursive: true });
+  }
+
+  const config = loadConfig(projectPath);
+  // Socket path from config, or let RFDBServerBackend derive it from dbPath
+  const socketPath = (config as any).analysis?.parallel?.socketPath;
+
+  log(`[Grafema MCP] Using RFDB server backend: socket=${socketPath || 'auto'}, db=${dbPath}`);
+
+  const rfdbBackend = new RFDBServerBackend({ socketPath, dbPath });
+  await rfdbBackend.connect();
+  backend = rfdbBackend as unknown as GraphBackend;
+
+  const nodeCount = await backend.nodeCount();
+  if (nodeCount > 0) {
+    isAnalyzed = true;
+    log(`[Grafema MCP] Connected to existing database: ${nodeCount} nodes`);
+  } else {
+    log(`[Grafema MCP] Empty database, analysis needed`);
+  }
+
+  // Initialize guarantee managers
+  initializeGuaranteeManagers(rfdbBackend);
+
+  return backend;
+}
+
+/**
+ * Initialize GuaranteeManager (Datalog-based) and GuaranteeAPI (contract-based)
+ */
+function initializeGuaranteeManagers(rfdbBackend: RFDBServerBackend): void {
+  // GuaranteeManager for Datalog-based guarantees
+  // Cast to GuaranteeGraph interface expected by GuaranteeManager
+  const guaranteeGraph = rfdbBackend as unknown as GuaranteeGraph;
+  guaranteeManager = new GuaranteeManager(guaranteeGraph, projectPath);
+  log(`[Grafema MCP] GuaranteeManager initialized`);
+
+  // GuaranteeAPI for contract-based guarantees
+  const guaranteeGraphBackend = rfdbBackend as unknown as GuaranteeGraphBackend;
+  guaranteeAPI = new GuaranteeAPI(guaranteeGraphBackend);
+  log(`[Grafema MCP] GuaranteeAPI initialized`);
+}
+
+export function getBackendIfExists(): GraphBackend | null {
+  return backend;
+}
+
+// === LOGGING SETUP ===
+export function setupLogging(): void {
+  const grafemaDir = join(projectPath, '.grafema');
+  if (!existsSync(grafemaDir)) {
+    mkdirSync(grafemaDir, { recursive: true });
+  }
+  initLogger(grafemaDir);
+}
+
+// === INITIALIZATION ===
+export function initializeFromArgs(): void {
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--project' && args[i + 1]) {
+      projectPath = args[i + 1];
+      i++;
+    }
+  }
+}
+
+// === CLEANUP ===
+export async function cleanup(): Promise<void> {
+  if (backend && 'close' in backend && typeof backend.close === 'function') {
+    await backend.close();
+  }
+}

package/src/types.ts

@@ -0,0 +1,245 @@
+/**
+ * MCP Server Types
+ */
+
+import type { WriteStream } from 'fs';
+
+// === ANALYSIS STATUS ===
+export interface AnalysisTimings {
+  discovery: number | null;
+  indexing: number | null;
+  analysis: number | null;
+  enrichment: number | null;
+  validation: number | null;
+  total: number | null;
+}
+
+export interface AnalysisStatus {
+  running: boolean;
+  phase: string | null;
+  message: string | null;
+  servicesDiscovered: number;
+  servicesAnalyzed: number;
+  startTime: number | null;
+  endTime: number | null;
+  error: string | null;
+  timings: AnalysisTimings;
+}
+
+// === PAGINATION ===
+export interface PaginationParams {
+  limit: number;
+  offset: number;
+  returned: number;
+  total?: number;
+  hasMore: boolean;
+}
+
+// === CONFIG ===
+export interface GrafemaConfig {
+  project_path?: string;
+  backend?: 'local' | 'rfdb';
+  rfdb_socket?: string;
+  plugins?: string[];
+  ignore_patterns?: string[];
+}
+
+// === TOOL ARGUMENTS ===
+export interface QueryGraphArgs {
+  query: string;
+  limit?: number;
+  offset?: number;
+  format?: 'table' | 'json' | 'tree';
+}
+
+export interface FindCallsArgs {
+  target: string;
+  limit?: number;
+  offset?: number;
+  include_indirect?: boolean;
+}
+
+export interface TraceAliasArgs {
+  identifier: string;
+  file?: string;
+  max_depth?: number;
+}
+
+export interface TraceDataFlowArgs {
+  source: string;
+  file?: string;
+  direction?: 'forward' | 'backward' | 'both';
+  max_depth?: number;
+  limit?: number;
+}
+
+export interface CheckInvariantArgs {
+  rule: string;
+  name?: string;
+}
+
+export interface GetSchemaArgs {
+  type?: 'nodes' | 'edges' | 'all';
+}
+
+export interface GetValueSetArgs {
+  node_id: string;
+  property?: string;
+}
+
+export interface FindNodesArgs {
+  type?: string;
+  name?: string;
+  file?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface AnalyzeProjectArgs {
+  service?: string;
+  force?: boolean;
+  index_only?: boolean;
+}
+
+export interface GetCoverageArgs {
+  path?: string;
+  depth?: number;
+}
+
+export interface GetDocumentationArgs {
+  topic?: string;
+}
+
+// === GUARANTEE ARGS ===
+
+// Priority levels for contract-based guarantees
+export type GuaranteePriority = 'critical' | 'important' | 'observed' | 'tracked';
+
+// Lifecycle status for contract-based guarantees
+export type GuaranteeStatus = 'discovered' | 'reviewed' | 'active' | 'changing' | 'deprecated';
+
+export interface CreateGuaranteeArgs {
+  name: string;
+  // Datalog-based guarantee fields (optional for contract-based)
+  rule?: string;
+  description?: string;
+  severity?: 'error' | 'warning' | 'info';
+  // Contract-based guarantee fields
+  type?: 'guarantee:queue' | 'guarantee:api' | 'guarantee:permission';
+  priority?: GuaranteePriority;
+  status?: GuaranteeStatus;
+  owner?: string;
+  schema?: Record<string, unknown>;
+  condition?: string;
+  governs?: string[]; // Node IDs that this guarantee governs
+}
+
+export interface CheckGuaranteesArgs {
+  names?: string[];
+}
+
+export interface DeleteGuaranteeArgs {
+  name: string;
+}
+
+export interface ExportGuaranteesArgs {
+  format?: 'json' | 'yaml';
+}
+
+export interface ImportGuaranteesArgs {
+  guarantees: Array<{
+    name: string;
+    rule: string;
+    description?: string;
+    severity?: string;
+  }>;
+  merge?: boolean;
+}
+
+export interface GuaranteeDriftArgs {
+  baseline?: string;
+}
+
+export interface CheckGuaranteeFeasibilityArgs {
+  rule: string;
+}
+
+// === TOOL RESULT ===
+export interface ToolResult {
+  [x: string]: unknown;
+  content: Array<{
+    type: 'text';
+    text: string;
+  }>;
+  isError?: boolean;
+  _meta?: Record<string, unknown>;
+}
+
+// === BACKEND INTERFACE (minimal) ===
+export interface GraphBackend {
+  nodeCount(): Promise<number>;
+  edgeCount(): Promise<number>;
+  countNodesByType(types?: string[] | null): Promise<Record<string, number>>;
+  countEdgesByType(types?: string[] | null): Promise<Record<string, number>>;
+  getNode(id: string): Promise<GraphNode | null>;
+  findByType(type: string): Promise<string[]>;
+  findByAttr(query: Record<string, unknown>): Promise<string[]>;
+  getOutgoingEdges(id: string, types?: string[] | null): Promise<GraphEdge[]>;
+  getIncomingEdges(id: string, types?: string[] | null): Promise<GraphEdge[]>;
+  queryNodes(filter: Record<string, unknown>): AsyncIterable<GraphNode>;
+  getAllNodes(filter?: Record<string, unknown>): Promise<GraphNode[]>;
+  runDatalogQuery?(query: string): Promise<unknown[]>;
+  close?(): Promise<void>;
+}
+
+export interface GraphNode {
+  id: string;
+  type: string;
+  name: string;
+  file?: string;
+  line?: number;
+  [key: string]: unknown;
+}
+
+export interface GraphEdge {
+  src: string;
+  dst: string;
+  type: string;
+  edgeType?: string;
+  [key: string]: unknown;
+}
+
+// === GLOBAL STATE ===
+export interface MCPState {
+  projectPath: string;
+  backend: GraphBackend | null;
+  isAnalyzed: boolean;
+  analysisStatus: AnalysisStatus;
+  logStream: WriteStream | null;
+  backgroundPid: number | null;
+}
+
+// === FILE CLASSIFICATION ===
+export interface FileClassification {
+  category: 'source' | 'config' | 'test' | 'doc' | 'asset' | 'generated' | 'other';
+  language?: string;
+  framework?: string;
+}
+
+export interface ExtensionGroup {
+  [ext: string]: string[];
+}
+
+export interface AnalyzerSuggestion {
+  name: string;
+  reason: string;
+  priority: number;
+}
+
+// === BUG REPORTING ===
+export interface ReportIssueArgs {
+  title: string;
+  description: string;
+  context?: string;
+  labels?: string[];
+}