project-graph-mcp 1.0.0

package/src/mcp-server.js

@@ -0,0 +1,375 @@
+/**
+ * Core MCP Server Logic
+ * 
+ * Implements bidirectional JSON-RPC 2.0 over stdio:
+ * - Handles client→server requests (tools/list, tools/call)
+ * - Sends server→client requests (roots/list) to get workspace info
+ */
+
+import { TOOLS } from './tool-defs.js';
+import { getSkeleton, getFocusZone, expand, deps, usages, invalidateCache } from './tools.js';
+import { getPendingTests, markTestPassed, markTestFailed, getTestSummary, resetTestState } from './test-annotations.js';
+import { getFilters, setFilters, addExcludes, removeExcludes, resetFilters } from './filters.js';
+import { getInstructions } from './instructions.js';
+import { getUndocumentedSummary } from './undocumented.js';
+import { getDeadCode } from './dead-code.js';
+import { generateJSDoc, generateJSDocFor } from './jsdoc-generator.js';
+import { getSimilarFunctions } from './similar-functions.js';
+import { getComplexity } from './complexity.js';
+import { getLargeFiles } from './large-files.js';
+import { getOutdatedPatterns } from './outdated-patterns.js';
+import { getFullAnalysis } from './full-analysis.js';
+import { getCustomRules, setCustomRule, checkCustomRules } from './custom-rules.js';
+import { getFrameworkReference } from './framework-references.js';
+import { setRoots, resolvePath } from './workspace.js';
+
+/**
+ * Tool handlers registry
+ * Maps tool names to their handler functions
+ */
+const TOOL_HANDLERS = {
+  // Graph Tools
+  get_skeleton: (args) => getSkeleton(resolvePath(args.path)),
+  get_focus_zone: (args) => getFocusZone({ ...args, path: resolvePath(args.path) }),
+  expand: (args) => expand(args.symbol),
+  deps: (args) => deps(args.symbol),
+  usages: (args) => usages(args.symbol),
+  invalidate_cache: () => { invalidateCache(); return { success: true }; },
+
+  // Test Checklist Tools
+  get_pending_tests: (args) => getPendingTests(resolvePath(args.path)),
+  mark_test_passed: (args) => markTestPassed(args.testId),
+  mark_test_failed: (args) => markTestFailed(args.testId, args.reason),
+  get_test_summary: (args) => getTestSummary(resolvePath(args.path)),
+  reset_test_state: () => resetTestState(),
+
+  // Filter Tools
+  get_filters: () => getFilters(),
+  set_filters: (args) => setFilters(args),
+  add_excludes: (args) => addExcludes(args.dirs),
+  remove_excludes: (args) => removeExcludes(args.dirs),
+  reset_filters: () => resetFilters(),
+
+  // Guidelines
+  get_agent_instructions: () => getInstructions(),
+
+  // Documentation
+  get_undocumented: (args) => getUndocumentedSummary(resolvePath(args.path), args.level || 'tests'),
+
+  // Code Quality
+  get_dead_code: (args) => getDeadCode(resolvePath(args.path)),
+  generate_jsdoc: (args) => args.name
+    ? generateJSDocFor(resolvePath(args.path), args.name)
+    : generateJSDoc(resolvePath(args.path)),
+  get_similar_functions: (args) => getSimilarFunctions(resolvePath(args.path), { threshold: args.threshold }),
+  get_complexity: (args) => getComplexity(resolvePath(args.path), {
+    minComplexity: args.minComplexity,
+    onlyProblematic: args.onlyProblematic,
+  }),
+  get_large_files: (args) => getLargeFiles(resolvePath(args.path), { onlyProblematic: args.onlyProblematic }),
+  get_outdated_patterns: (args) => getOutdatedPatterns(resolvePath(args.path), {
+    codeOnly: args.codeOnly,
+    depsOnly: args.depsOnly,
+  }),
+  get_full_analysis: (args) => getFullAnalysis(resolvePath(args.path), { includeItems: args.includeItems }),
+
+  // Custom Rules
+  get_custom_rules: () => getCustomRules(),
+  set_custom_rule: (args) => setCustomRule(args.ruleSet, args.rule),
+  check_custom_rules: (args) => checkCustomRules(resolvePath(args.path), {
+    ruleSet: args.ruleSet,
+    severity: args.severity,
+  }),
+
+  // Framework References
+  get_framework_reference: (args) => getFrameworkReference({
+    framework: args.framework,
+    path: args.path ? resolvePath(args.path) : undefined,
+  }),
+};
+
+/**
+ * Response hints — contextual coaching tips appended to tool responses.
+ * Maps tool names to hint generators. Each receives the result and returns
+ * an array of hint strings (or empty array for no hints).
+ *
+ * @type {Record<string, (result: any) => string[]>}
+ */
+const RESPONSE_HINTS = {
+  get_skeleton: () => [
+    '💡 Use expand("SYMBOL") to see code for a specific class.',
+    '💡 Use deps("SYMBOL") to see architecture dependencies.',
+    '💡 After code changes, run invalidate_cache() to refresh the graph.',
+  ],
+
+  expand: (result) => {
+    const hints = [];
+    if (result.methods?.length > 10) {
+      hints.push('💡 Large class detected. Run get_complexity() to find refactoring targets.');
+    }
+    hints.push('💡 Use deps() to see what depends on this symbol.');
+    return hints;
+  },
+
+  deps: () => [
+    '💡 Use usages() for cross-project reference search.',
+  ],
+
+  invalidate_cache: () => [
+    '✅ Cache cleared. Run get_skeleton() to rebuild the project graph.',
+  ],
+
+  get_dead_code: (result) => {
+    const hints = ['💡 Review each item before removing — some may be used dynamically.'];
+    if (result.unusedExports?.length > 20) {
+      hints.push('💡 Consider delegating cleanup to agent-pool: delegate_task({ prompt: "Remove dead code..." })');
+    }
+    return hints;
+  },
+
+  get_full_analysis: () => [
+    '💡 Focus on items with "critical" severity first.',
+    '💡 Run individual tools (get_complexity, get_dead_code) for detailed breakdowns.',
+  ],
+
+  get_complexity: () => [
+    '💡 Functions with complexity >10 are candidates for refactoring.',
+    '💡 Use expand() to read the function code before refactoring.',
+  ],
+
+  get_undocumented: () => [
+    '💡 Use generate_jsdoc() to auto-generate documentation templates.',
+  ],
+
+  get_similar_functions: () => [
+    '💡 Consider extracting duplicated logic into a shared utility.',
+  ],
+
+  get_pending_tests: () => [
+    '💡 Use mark_test_passed(testId) or mark_test_failed(testId, reason) to track progress.',
+  ],
+};
+
+/**
+ * Create MCP server instance
+ * @param {Function} sendToClient - Function to send JSON-RPC messages to client
+ * @returns {Object}
+ */
+export function createServer(sendToClient) {
+  let nextRequestId = 1;
+
+  /** @type {Map<number, {resolve: Function, reject: Function}>} */
+  const pendingRequests = new Map();
+
+  /** @type {boolean} */
+  let clientSupportsRoots = false;
+
+  return {
+    pendingRequests,
+
+    /**
+     * Handle incoming JSON-RPC message (request, response, or notification)
+     * @param {Object} message
+     * @returns {Promise<Object|null>}
+     */
+    async handleMessage(message) {
+      // Check if this is a response to our server→client request
+      if (message.result !== undefined || message.error !== undefined) {
+        const pending = pendingRequests.get(message.id);
+        if (pending) {
+          pendingRequests.delete(message.id);
+          if (message.error) {
+            pending.reject(new Error(message.error.message));
+          } else {
+            pending.resolve(message.result);
+          }
+        }
+        return null;
+      }
+
+      const { method, params, id } = message;
+
+      // Notification (no id) — handle but don't respond
+      if (id === undefined) {
+        await this.handleNotification(method, params);
+        return null;
+      }
+
+      // Request — handle and respond
+      try {
+        switch (method) {
+          case 'initialize':
+            // Track client capabilities
+            if (params?.capabilities?.roots) {
+              clientSupportsRoots = true;
+            }
+            // Also check for inline roots
+            if (params?.roots) {
+              setRoots(params.roots);
+            }
+            return {
+              jsonrpc: '2.0',
+              id,
+              result: {
+                protocolVersion: '2024-11-05',
+                capabilities: { tools: {} },
+                serverInfo: { name: 'project-graph', version: '1.1.0' },
+              },
+            };
+
+          case 'tools/list':
+            return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+
+          case 'tools/call': {
+            const result = await this.executeTool(params.name, params.arguments);
+            const content = [{ type: 'text', text: JSON.stringify(result, null, 2) }];
+
+            // Inject contextual hints
+            const hintFn = RESPONSE_HINTS[params.name];
+            if (hintFn) {
+              const hints = hintFn(result);
+              if (hints.length > 0) {
+                content.push({ type: 'text', text: '\n' + hints.join('\n') });
+              }
+            }
+
+            return {
+              jsonrpc: '2.0',
+              id,
+              result: { content },
+            };
+          }
+
+          default:
+            return {
+              jsonrpc: '2.0',
+              id,
+              error: { code: -32601, message: `Method not found: ${method}` },
+            };
+        }
+      } catch (error) {
+        return { jsonrpc: '2.0', id, error: { code: -32000, message: error.message } };
+      }
+    },
+
+    /**
+     * Handle MCP notifications
+     * @param {string} method
+     * @param {Object} params
+     */
+    async handleNotification(method, params) {
+      switch (method) {
+        case 'notifications/initialized':
+          // Client is ready — request workspace roots if supported
+          if (clientSupportsRoots) {
+            try {
+              const roots = await this.requestRoots();
+              if (roots && roots.length > 0) {
+                setRoots(roots);
+              }
+            } catch (e) {
+              console.error(`[project-graph] Failed to get roots: ${e.message}`);
+            }
+          }
+          break;
+
+        case 'notifications/roots/list_changed':
+          // Workspace roots changed — re-request
+          if (clientSupportsRoots) {
+            try {
+              const roots = await this.requestRoots();
+              if (roots && roots.length > 0) {
+                setRoots(roots);
+                invalidateCache();
+              }
+            } catch (e) {
+              console.error(`[project-graph] Failed to refresh roots: ${e.message}`);
+            }
+          }
+          break;
+      }
+    },
+
+    /**
+     * Send roots/list request to client
+     * @returns {Promise<Array<{uri: string, name?: string}>>}
+     */
+    requestRoots() {
+      return new Promise((resolve, reject) => {
+        const id = nextRequestId++;
+        const timeout = setTimeout(() => {
+          pendingRequests.delete(id);
+          reject(new Error('roots/list request timed out'));
+        }, 5000);
+
+        pendingRequests.set(id, {
+          resolve: (result) => {
+            clearTimeout(timeout);
+            resolve(result.roots || []);
+          },
+          reject: (err) => {
+            clearTimeout(timeout);
+            reject(err);
+          },
+        });
+
+        sendToClient({
+          jsonrpc: '2.0',
+          id,
+          method: 'roots/list',
+        });
+      });
+    },
+
+    /**
+     * Execute a tool by name
+     * @param {string} name
+     * @param {Object} args
+     * @returns {Promise<any>}
+     */
+    async executeTool(name, args) {
+      const handler = TOOL_HANDLERS[name];
+      if (!handler) {
+        throw new Error(`Unknown tool: ${name}`);
+      }
+      return await handler(args);
+    },
+  };
+}
+
+/**
+ * Start server with stdio transport
+ */
+export async function startStdioServer() {
+  /**
+   * Send JSON-RPC message to client via stdout
+   * @param {Object} message
+   */
+  const sendToClient = (message) => {
+    console.log(JSON.stringify(message));
+  };
+
+  const server = createServer(sendToClient);
+  const readline = await import('readline');
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  });
+
+  rl.on('line', async (line) => {
+    try {
+      const message = JSON.parse(line);
+      const response = await server.handleMessage(message);
+      if (response !== null) {
+        sendToClient(response);
+      }
+    } catch (e) {
+      sendToClient({
+        jsonrpc: '2.0',
+        error: { code: -32700, message: 'Parse error' },
+      });
+    }
+  });
+}

package/src/outdated-patterns.js

@@ -0,0 +1,295 @@
+/**
+ * Outdated Patterns Detector
+ * Finds legacy code patterns and redundant npm dependencies
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'fs';
+import { join, relative, resolve } from 'path';
+import { parse } from '../vendor/acorn.mjs';
+import * as walk from '../vendor/walk.mjs';
+import { shouldExcludeDir, shouldExcludeFile, parseGitignore } from './filters.js';
+
+/**
+ * Redundant npm packages that are now built into Node.js 18+
+ */
+const REDUNDANT_DEPS = {
+  'node-fetch': { replacement: 'fetch()', since: 'Node 18' },
+  'cross-fetch': { replacement: 'fetch()', since: 'Node 18' },
+  'isomorphic-fetch': { replacement: 'fetch()', since: 'Node 18' },
+  'uuid': { replacement: 'crypto.randomUUID()', since: 'Node 19' },
+  'deep-clone': { replacement: 'structuredClone()', since: 'Node 17' },
+  'lodash.clonedeep': { replacement: 'structuredClone()', since: 'Node 17' },
+  'abort-controller': { replacement: 'AbortController (global)', since: 'Node 15' },
+  'form-data': { replacement: 'FormData (global)', since: 'Node 18' },
+  'web-streams-polyfill': { replacement: 'ReadableStream (global)', since: 'Node 18' },
+  'url-parse': { replacement: 'URL (global)', since: 'Node 10' },
+  'querystring': { replacement: 'URLSearchParams', since: 'Node 10' },
+  'rimraf': { replacement: 'fs.rm({ recursive: true })', since: 'Node 14' },
+  'mkdirp': { replacement: 'fs.mkdir({ recursive: true })', since: 'Node 10' },
+  'recursive-readdir': { replacement: 'fs.readdir({ recursive: true })', since: 'Node 20' },
+  'glob': { replacement: 'fs.glob()', since: 'Node 22' },
+};
+
+/**
+ * Legacy code patterns to detect
+ */
+const CODE_PATTERNS = [
+  {
+    name: 'var-usage',
+    description: 'Use const/let instead of var',
+    check: (node) => node.type === 'VariableDeclaration' && node.kind === 'var',
+    severity: 'warning',
+    replacement: 'const/let',
+  },
+  {
+    name: 'require-usage',
+    description: 'Use ESM import instead of require()',
+    check: (node) => node.type === 'CallExpression' &&
+      node.callee.type === 'Identifier' && node.callee.name === 'require',
+    severity: 'info',
+    replacement: 'import ... from',
+  },
+  {
+    name: 'module-exports',
+    description: 'Use ESM export instead of module.exports',
+    check: (node) => node.type === 'AssignmentExpression' &&
+      node.left.type === 'MemberExpression' &&
+      node.left.object.type === 'Identifier' && node.left.object.name === 'module' &&
+      node.left.property.type === 'Identifier' && node.left.property.name === 'exports',
+    severity: 'info',
+    replacement: 'export default/export',
+  },
+  {
+    name: 'buffer-constructor',
+    description: 'new Buffer() is deprecated',
+    check: (node) => node.type === 'NewExpression' &&
+      node.callee.type === 'Identifier' && node.callee.name === 'Buffer',
+    severity: 'error',
+    replacement: 'Buffer.from() / Buffer.alloc()',
+  },
+  {
+    name: 'arguments-usage',
+    description: 'Use rest parameters instead of arguments',
+    check: (node) => node.type === 'Identifier' && node.name === 'arguments',
+    severity: 'warning',
+    replacement: '...args',
+  },
+  {
+    name: 'promisify-usage',
+    description: 'Use fs/promises instead of util.promisify',
+    check: (node) => node.type === 'CallExpression' &&
+      node.callee.type === 'MemberExpression' &&
+      node.callee.object.type === 'Identifier' && node.callee.object.name === 'util' &&
+      node.callee.property.type === 'Identifier' && node.callee.property.name === 'promisify',
+    severity: 'info',
+    replacement: 'fs/promises module',
+  },
+  {
+    name: 'sync-in-async',
+    description: 'Avoid sync methods in async context (readFileSync, etc.)',
+    check: (node, context) => {
+      if (node.type !== 'CallExpression') return false;
+      const callee = node.callee;
+      if (callee.type === 'MemberExpression' && callee.property.type === 'Identifier') {
+        const name = callee.property.name;
+        return name.endsWith('Sync') && context.inAsync;
+      }
+      return false;
+    },
+    severity: 'warning',
+    replacement: 'async fs/promises methods',
+  },
+];
+
+/**
+ * @typedef {Object} PatternMatch
+ * @property {string} pattern
+ * @property {string} description
+ * @property {string} file
+ * @property {number} line
+ * @property {string} severity
+ * @property {string} replacement
+ */
+
+/**
+ * @typedef {Object} RedundantDep
+ * @property {string} name
+ * @property {string} replacement
+ * @property {string} since
+ */
+
+/**
+ * Find all JS files
+ * @param {string} dir 
+ * @param {string} rootDir 
+ * @returns {string[]}
+ */
+function findJSFiles(dir, rootDir = dir) {
+  if (dir === rootDir) parseGitignore(rootDir);
+  const files = [];
+
+  try {
+    for (const entry of readdirSync(dir)) {
+      const fullPath = join(dir, entry);
+      const relativePath = relative(rootDir, fullPath);
+      const stat = statSync(fullPath);
+
+      if (stat.isDirectory()) {
+        if (!shouldExcludeDir(entry, relativePath)) {
+          files.push(...findJSFiles(fullPath, rootDir));
+        }
+      } else if (entry.endsWith('.js') && !entry.endsWith('.css.js') && !entry.endsWith('.tpl.js')) {
+        if (!shouldExcludeFile(entry, relativePath)) {
+          files.push(fullPath);
+        }
+      }
+    }
+  } catch (e) { }
+
+  return files;
+}
+
+/**
+ * Analyze file for outdated patterns
+ * @param {string} filePath 
+ * @returns {PatternMatch[]}
+ */
+function analyzeFilePatterns(filePath, rootDir) {
+  const code = readFileSync(filePath, 'utf-8');
+  const relPath = relative(rootDir, filePath);
+  const matches = [];
+
+  let ast;
+  try {
+    ast = parse(code, { ecmaVersion: 'latest', sourceType: 'module', locations: true });
+  } catch (e) {
+    return matches;
+  }
+
+  // Track async context
+  const context = { inAsync: false };
+
+  walk.simple(ast, {
+    FunctionDeclaration(node) {
+      context.inAsync = node.async;
+    },
+    ArrowFunctionExpression(node) {
+      context.inAsync = node.async;
+    },
+  });
+
+  // Reset and check patterns
+  context.inAsync = false;
+
+  walk.ancestor(ast, {
+    '*'(node, ancestors) {
+      // Update async context
+      for (const anc of ancestors) {
+        if ((anc.type === 'FunctionDeclaration' || anc.type === 'ArrowFunctionExpression' ||
+          anc.type === 'FunctionExpression') && anc.async) {
+          context.inAsync = true;
+          break;
+        }
+      }
+
+      for (const pattern of CODE_PATTERNS) {
+        if (pattern.check(node, context)) {
+          matches.push({
+            pattern: pattern.name,
+            description: pattern.description,
+            file: relPath,
+            line: node.loc?.start?.line || 0,
+            severity: pattern.severity,
+            replacement: pattern.replacement,
+          });
+        }
+      }
+    },
+  });
+
+  return matches;
+}
+
+/**
+ * Analyze package.json for redundant dependencies
+ * @param {string} dir 
+ * @returns {RedundantDep[]}
+ */
+function analyzePackageJson(dir) {
+  const pkgPath = join(dir, 'package.json');
+  const redundant = [];
+
+  if (!existsSync(pkgPath)) return redundant;
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    const allDeps = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+    };
+
+    for (const depName of Object.keys(allDeps)) {
+      if (REDUNDANT_DEPS[depName]) {
+        redundant.push({
+          name: depName,
+          ...REDUNDANT_DEPS[depName],
+        });
+      }
+    }
+  } catch (e) { }
+
+  return redundant;
+}
+
+/**
+ * Get outdated patterns analysis
+ * @param {string} dir 
+ * @param {Object} [options]
+ * @param {boolean} [options.codeOnly=false] - Only check code patterns
+ * @param {boolean} [options.depsOnly=false] - Only check dependencies
+ * @returns {Promise<{codePatterns: PatternMatch[], redundantDeps: RedundantDep[], stats: Object}>}
+ */
+export async function getOutdatedPatterns(dir, options = {}) {
+  const codeOnly = options.codeOnly || false;
+  const depsOnly = options.depsOnly || false;
+  const resolvedDir = resolve(dir);
+
+  let codePatterns = [];
+  let redundantDeps = [];
+
+  if (!depsOnly) {
+    const files = findJSFiles(dir);
+    for (const file of files) {
+      codePatterns.push(...analyzeFilePatterns(file, resolvedDir));
+    }
+    // Sort by severity
+    const severityOrder = { error: 0, warning: 1, info: 2 };
+    codePatterns.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+  }
+
+  if (!codeOnly) {
+    redundantDeps = analyzePackageJson(dir);
+  }
+
+  const stats = {
+    totalPatterns: codePatterns.length,
+    byPattern: {},
+    bySeverity: {
+      error: codePatterns.filter(p => p.severity === 'error').length,
+      warning: codePatterns.filter(p => p.severity === 'warning').length,
+      info: codePatterns.filter(p => p.severity === 'info').length,
+    },
+    redundantDeps: redundantDeps.length,
+  };
+
+  // Group by pattern name
+  for (const p of codePatterns) {
+    stats.byPattern[p.pattern] = (stats.byPattern[p.pattern] || 0) + 1;
+  }
+
+  return {
+    codePatterns: codePatterns.slice(0, 50),
+    redundantDeps,
+    stats,
+  };
+}