@optave/codegraph 3.1.5 → 3.2.0

package/src/mcp/server.js

@@ -21,45 +21,84 @@ import { TOOL_HANDLERS } from './tools/index.js';
  * @param {boolean} [options.multiRepo] - Enable multi-repo access (default: false)
  * @param {string[]} [options.allowedRepos] - Restrict access to these repo names only
  */
-export async function startMCPServer(customDbPath, options = {}) {
-  const { allowedRepos } = options;
-  const multiRepo = options.multiRepo || !!allowedRepos;
-  let Server, StdioServerTransport, ListToolsRequestSchema, CallToolRequestSchema;
+async function loadMCPSdk() {
   try {
     const sdk = await import('@modelcontextprotocol/sdk/server/index.js');
-    Server = sdk.Server;
     const transport = await import('@modelcontextprotocol/sdk/server/stdio.js');
-    StdioServerTransport = transport.StdioServerTransport;
     const types = await import('@modelcontextprotocol/sdk/types.js');
-    ListToolsRequestSchema = types.ListToolsRequestSchema;
-    CallToolRequestSchema = types.CallToolRequestSchema;
+    return {
+      Server: sdk.Server,
+      StdioServerTransport: transport.StdioServerTransport,
+      ListToolsRequestSchema: types.ListToolsRequestSchema,
+      CallToolRequestSchema: types.CallToolRequestSchema,
+    };
   } catch {
     throw new ConfigError(
       'MCP server requires @modelcontextprotocol/sdk.\nInstall it with: npm install @modelcontextprotocol/sdk',
     );
   }
+}
 
-  // Connect transport FIRST so the server can receive the client's
-  // `initialize` request while heavy modules (queries, better-sqlite3)
-  // are still loading.  These are lazy-loaded on the first tool call
-  // and cached for subsequent calls.
+function createLazyLoaders() {
   let _queries;
   let _Database;
+  return {
+    async getQueries() {
+      if (!_queries) _queries = await import('../domain/queries.js');
+      return _queries;
+    },
+    getDatabase() {
+      if (!_Database) {
+        const require = createRequire(import.meta.url);
+        _Database = require('better-sqlite3');
+      }
+      return _Database;
+    },
+  };
+}
 
-  async function getQueries() {
-    if (!_queries) {
-      _queries = await import('../domain/queries.js');
+async function resolveDbPath(customDbPath, args, allowedRepos) {
+  let dbPath = customDbPath || undefined;
+  if (args.repo) {
+    if (allowedRepos && !allowedRepos.includes(args.repo)) {
+      throw new ConfigError(`Repository "${args.repo}" is not in the allowed repos list.`);
     }
-    return _queries;
+    const { resolveRepoDbPath } = await import('../infrastructure/registry.js');
+    const resolved = resolveRepoDbPath(args.repo);
+    if (!resolved)
+      throw new ConfigError(
+        `Repository "${args.repo}" not found in registry or its database is missing.`,
+      );
+    dbPath = resolved;
   }
+  return dbPath;
+}
 
-  function getDatabase() {
-    if (!_Database) {
-      const require = createRequire(import.meta.url);
-      _Database = require('better-sqlite3');
-    }
-    return _Database;
+function validateMultiRepoAccess(multiRepo, name, args) {
+  if (!multiRepo && args.repo) {
+    throw new ConfigError(
+      'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to access other repositories.',
+    );
+  }
+  if (!multiRepo && name === 'list_repos') {
+    throw new ConfigError(
+      'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to list repositories.',
+    );
   }
+}
+
+export async function startMCPServer(customDbPath, options = {}) {
+  const { allowedRepos } = options;
+  const multiRepo = options.multiRepo || !!allowedRepos;
+
+  const { Server, StdioServerTransport, ListToolsRequestSchema, CallToolRequestSchema } =
+    await loadMCPSdk();
+
+  // Connect transport FIRST so the server can receive the client's
+  // `initialize` request while heavy modules (queries, better-sqlite3)
+  // are still loading.  These are lazy-loaded on the first tool call
+  // and cached for subsequent calls.
+  const { getQueries, getDatabase } = createLazyLoaders();
 
   const server = new Server(
     { name: 'codegraph', version: '1.0.0' },
@@ -73,47 +112,17 @@ export async function startMCPServer(customDbPath, options = {}) {
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
-      if (!multiRepo && args.repo) {
-        throw new ConfigError(
-          'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to access other repositories.',
-        );
-      }
-      if (!multiRepo && name === 'list_repos') {
-        throw new ConfigError(
-          'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to list repositories.',
-        );
-      }
-
-      let dbPath = customDbPath || undefined;
-      if (args.repo) {
-        if (allowedRepos && !allowedRepos.includes(args.repo)) {
-          throw new ConfigError(`Repository "${args.repo}" is not in the allowed repos list.`);
-        }
-        const { resolveRepoDbPath } = await import('../infrastructure/registry.js');
-        const resolved = resolveRepoDbPath(args.repo);
-        if (!resolved)
-          throw new ConfigError(
-            `Repository "${args.repo}" not found in registry or its database is missing.`,
-          );
-        dbPath = resolved;
-      }
+      validateMultiRepoAccess(multiRepo, name, args);
+      const dbPath = await resolveDbPath(customDbPath, args, allowedRepos);
 
       const toolEntry = TOOL_HANDLERS.get(name);
       if (!toolEntry) {
         return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
       }
 
-      const ctx = {
-        dbPath,
-        getQueries,
-        getDatabase,
-        findDbPath,
-        allowedRepos,
-        MCP_MAX_LIMIT,
-      };
-
+      const ctx = { dbPath, getQueries, getDatabase, findDbPath, allowedRepos, MCP_MAX_LIMIT };
       const result = await toolEntry.handler(args, ctx);
-      if (result?.content) return result; // pass-through MCP responses
+      if (result?.content) return result;
       return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     } catch (err) {
       const code = err instanceof CodegraphError ? err.code : 'UNKNOWN_ERROR';

package/src/mcp/tool-registry.js

@@ -99,6 +99,19 @@ const BASE_TOOLS = [
       required: ['file'],
     },
   },
+  {
+    name: 'brief',
+    description:
+      'Token-efficient file summary: symbols with roles and transitive caller counts, importer counts, and file risk tier (high/medium/low). Designed for context injection.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'File path (partial match supported)' },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+      },
+      required: ['file'],
+    },
+  },
   {
     name: 'file_exports',
     description:

package/src/mcp/tools/brief.js

@@ -0,0 +1,8 @@
+export const name = 'brief';
+
+export async function handler(args, ctx) {
+  const { briefData } = await ctx.getQueries();
+  return briefData(args.file, ctx.dbPath, {
+    noTests: args.no_tests,
+  });
+}

package/src/mcp/tools/index.js

@@ -6,6 +6,7 @@ import * as astQuery from './ast-query.js';
 import * as audit from './audit.js';
 import * as batchQuery from './batch-query.js';
 import * as branchCompare from './branch-compare.js';
+import * as brief from './brief.js';
 import * as cfg from './cfg.js';
 import * as check from './check.js';
 import * as coChanges from './co-changes.js';
@@ -67,5 +68,6 @@ export const TOOL_HANDLERS = new Map([
   [dataflow.name, dataflow],
   [check.name, check],
   [astQuery.name, astQuery],
+  [brief.name, brief],
   [listRepos.name, listRepos],
 ]);

package/src/presentation/brief.js

@@ -0,0 +1,51 @@
+import { briefData } from '../domain/analysis/brief.js';
+import { outputResult } from './result-formatter.js';
+
+/**
+ * Format a compact brief for hook context injection.
+ * Single-block, token-efficient output.
+ *
+ * Example:
+ *   src/domain/graph/builder.js [HIGH RISK]
+ *   Symbols: buildGraph [core, 12 callers], collectFiles [leaf, 2 callers]
+ *   Imports: src/db/index.js, src/domain/parser.js
+ *   Imported by: src/cli/commands/build.js (+8 transitive)
+ */
+export function brief(file, customDbPath, opts = {}) {
+  const data = briefData(file, customDbPath, opts);
+  if (outputResult(data, 'results', opts)) return;
+
+  if (data.results.length === 0) {
+    console.log(`No file matching "${file}" in graph`);
+    return;
+  }
+
+  for (const r of data.results) {
+    console.log(`${r.file} [${r.risk.toUpperCase()} RISK]`);
+
+    // Symbols line
+    if (r.symbols.length > 0) {
+      const parts = r.symbols.map((s) => {
+        const tags = [];
+        if (s.role) tags.push(s.role);
+        tags.push(`${s.callerCount} caller${s.callerCount !== 1 ? 's' : ''}`);
+        return `${s.name} [${tags.join(', ')}]`;
+      });
+      console.log(`  Symbols: ${parts.join(', ')}`);
+    }
+
+    // Imports line
+    if (r.imports.length > 0) {
+      console.log(`  Imports: ${r.imports.join(', ')}`);
+    }
+
+    // Imported by line with transitive count
+    if (r.importedBy.length > 0) {
+      const transitive = r.totalImporterCount - r.importedBy.length;
+      const suffix = transitive > 0 ? ` (+${transitive} transitive)` : '';
+      console.log(`  Imported by: ${r.importedBy.join(', ')}${suffix}`);
+    } else if (r.totalImporterCount > 0) {
+      console.log(`  Imported by: ${r.totalImporterCount} transitive importers`);
+    }
+  }
+}

package/src/presentation/queries-cli/exports.js

@@ -1,19 +1,7 @@
 import { exportsData, kindIcon } from '../../domain/queries.js';
 import { outputResult } from '../../infrastructure/result-formatter.js';
 
-export function fileExports(file, customDbPath, opts = {}) {
-  const data = exportsData(file, customDbPath, opts);
-  if (outputResult(data, 'results', opts)) return;
-
-  if (data.results.length === 0) {
-    if (opts.unused) {
-      console.log(`No unused exports found for "${file}".`);
-    } else {
-      console.log(`No exported symbols found for "${file}". Run "codegraph build" first.`);
-    }
-    return;
-  }
-
+function printExportHeader(data, opts) {
   if (opts.unused) {
     console.log(
       `\n# ${data.file} — ${data.totalUnused} unused export${data.totalUnused !== 1 ? 's' : ''} (of ${data.totalExported} exported)\n`,
@@ -24,8 +12,10 @@ export function fileExports(file, customDbPath, opts = {}) {
       `\n# ${data.file} — ${data.totalExported} exported${unusedNote}, ${data.totalInternal} internal\n`,
     );
   }
+}
 
-  for (const sym of data.results) {
+function printExportSymbols(results) {
+  for (const sym of results) {
     const icon = kindIcon(sym.kind);
     const sig = sym.signature?.params ? `(${sym.signature.params})` : '';
     const role = sym.role ? ` [${sym.role}]` : '';
@@ -38,6 +28,23 @@ export function fileExports(file, customDbPath, opts = {}) {
       }
     }
   }
+}
+
+export function fileExports(file, customDbPath, opts = {}) {
+  const data = exportsData(file, customDbPath, opts);
+  if (outputResult(data, 'results', opts)) return;
+
+  if (data.results.length === 0) {
+    if (opts.unused) {
+      console.log(`No unused exports found for "${file}".`);
+    } else {
+      console.log(`No exported symbols found for "${file}". Run "codegraph build" first.`);
+    }
+    return;
+  }
+
+  printExportHeader(data, opts);
+  printExportSymbols(data.results);
 
   if (data.reexports.length > 0) {
     console.log(`\n  Re-exports: ${data.reexports.map((r) => r.file).join(', ')}`);

package/src/presentation/queries-cli/impact.js

@@ -132,6 +132,56 @@ export function fnImpact(name, customDbPath, opts = {}) {
   }
 }
 
+function printDiffFunctions(data) {
+  console.log(`\ndiff-impact: ${data.changedFiles} files changed\n`);
+  console.log(`  ${data.affectedFunctions.length} functions changed:\n`);
+  for (const fn of data.affectedFunctions) {
+    console.log(`  ${kindIcon(fn.kind)} ${fn.name} -- ${fn.file}:${fn.line}`);
+    if (fn.transitiveCallers > 0) console.log(`    ^ ${fn.transitiveCallers} transitive callers`);
+  }
+}
+
+function printDiffCoupled(data) {
+  if (!data.historicallyCoupled?.length) return;
+  console.log('\n  Historically coupled (not in static graph):\n');
+  for (const c of data.historicallyCoupled) {
+    const pct = `${(c.jaccard * 100).toFixed(0)}%`;
+    console.log(
+      `    ${c.file}  <- coupled with ${c.coupledWith} (${pct}, ${c.commitCount} commits)`,
+    );
+  }
+}
+
+function printDiffOwnership(data) {
+  if (!data.ownership) return;
+  console.log(`\n  Affected owners: ${data.ownership.affectedOwners.join(', ')}`);
+  console.log(`  Suggested reviewers: ${data.ownership.suggestedReviewers.join(', ')}`);
+}
+
+function printDiffBoundaries(data) {
+  if (!data.boundaryViolations?.length) return;
+  console.log(`\n  Boundary violations (${data.boundaryViolationCount}):\n`);
+  for (const v of data.boundaryViolations) {
+    console.log(`    [${v.name}] ${v.file} -> ${v.targetFile}`);
+    if (v.message) console.log(`      ${v.message}`);
+  }
+}
+
+function printDiffSummary(summary) {
+  if (!summary) return;
+  let line = `\n  Summary: ${summary.functionsChanged} functions changed -> ${summary.callersAffected} callers affected across ${summary.filesAffected} files`;
+  if (summary.historicallyCoupledCount > 0) {
+    line += `, ${summary.historicallyCoupledCount} historically coupled`;
+  }
+  if (summary.ownersAffected > 0) {
+    line += `, ${summary.ownersAffected} owners affected`;
+  }
+  if (summary.boundaryViolationCount > 0) {
+    line += `, ${summary.boundaryViolationCount} boundary violations`;
+  }
+  console.log(`${line}\n`);
+}
+
 export function diffImpact(customDbPath, opts = {}) {
   if (opts.format === 'mermaid') {
     console.log(diffImpactMermaid(customDbPath, opts));
@@ -156,43 +206,9 @@ export function diffImpact(customDbPath, opts = {}) {
     return;
   }
 
-  console.log(`\ndiff-impact: ${data.changedFiles} files changed\n`);
-  console.log(`  ${data.affectedFunctions.length} functions changed:\n`);
-  for (const fn of data.affectedFunctions) {
-    console.log(`  ${kindIcon(fn.kind)} ${fn.name} -- ${fn.file}:${fn.line}`);
-    if (fn.transitiveCallers > 0) console.log(`    ^ ${fn.transitiveCallers} transitive callers`);
-  }
-  if (data.historicallyCoupled && data.historicallyCoupled.length > 0) {
-    console.log('\n  Historically coupled (not in static graph):\n');
-    for (const c of data.historicallyCoupled) {
-      const pct = `${(c.jaccard * 100).toFixed(0)}%`;
-      console.log(
-        `    ${c.file}  <- coupled with ${c.coupledWith} (${pct}, ${c.commitCount} commits)`,
-      );
-    }
-  }
-  if (data.ownership) {
-    console.log(`\n  Affected owners: ${data.ownership.affectedOwners.join(', ')}`);
-    console.log(`  Suggested reviewers: ${data.ownership.suggestedReviewers.join(', ')}`);
-  }
-  if (data.boundaryViolations && data.boundaryViolations.length > 0) {
-    console.log(`\n  Boundary violations (${data.boundaryViolationCount}):\n`);
-    for (const v of data.boundaryViolations) {
-      console.log(`    [${v.name}] ${v.file} -> ${v.targetFile}`);
-      if (v.message) console.log(`      ${v.message}`);
-    }
-  }
-  if (data.summary) {
-    let summaryLine = `\n  Summary: ${data.summary.functionsChanged} functions changed -> ${data.summary.callersAffected} callers affected across ${data.summary.filesAffected} files`;
-    if (data.summary.historicallyCoupledCount > 0) {
-      summaryLine += `, ${data.summary.historicallyCoupledCount} historically coupled`;
-    }
-    if (data.summary.ownersAffected > 0) {
-      summaryLine += `, ${data.summary.ownersAffected} owners affected`;
-    }
-    if (data.summary.boundaryViolationCount > 0) {
-      summaryLine += `, ${data.summary.boundaryViolationCount} boundary violations`;
-    }
-    console.log(`${summaryLine}\n`);
-  }
+  printDiffFunctions(data);
+  printDiffCoupled(data);
+  printDiffOwnership(data);
+  printDiffBoundaries(data);
+  printDiffSummary(data.summary);
 }