@optave/codegraph 2.5.1 → 3.0.0

package/src/mcp.js

@@ -6,10 +6,11 @@
  */
 
 import { createRequire } from 'node:module';
+import { AST_NODE_KINDS } from './ast.js';
 import { findCycles } from './cycles.js';
 import { findDbPath } from './db.js';
 import { MCP_DEFAULTS, MCP_MAX_LIMIT } from './paginate.js';
-import { ALL_SYMBOL_KINDS, diffImpactMermaid, VALID_ROLES } from './queries.js';
+import { diffImpactMermaid, EVERY_EDGE_KIND, EVERY_SYMBOL_KIND, VALID_ROLES } from './queries.js';
 
 const REPO_PROP = {
   repo: {
@@ -25,23 +26,71 @@ const PAGINATION_PROPS = {
 
 const BASE_TOOLS = [
   {
-    name: 'query_function',
-    description: 'Find callers and callees of a function by name',
+    name: 'query',
+    description:
+      'Query the call graph: find callers/callees with transitive chain, or find shortest path between two symbols',
     inputSchema: {
       type: 'object',
       properties: {
-        name: { type: 'string', description: 'Function name to query (supports partial match)' },
+        name: { type: 'string', description: 'Function/method/class name (partial match)' },
+        mode: {
+          type: 'string',
+          enum: ['deps', 'path'],
+          description: 'deps (default): dependency chain. path: shortest path to target',
+        },
         depth: {
           type: 'number',
-          description: 'Traversal depth for transitive callers',
-          default: 2,
+          description: 'Transitive depth (deps default: 3, path default: 10)',
+        },
+        file: {
+          type: 'string',
+          description: 'Scope search to functions in this file (partial match)',
+        },
+        kind: {
+          type: 'string',
+          enum: EVERY_SYMBOL_KIND,
+          description: 'Filter by symbol kind',
+        },
+        to: { type: 'string', description: 'Target symbol for path mode (required in path mode)' },
+        edge_kinds: {
+          type: 'array',
+          items: { type: 'string', enum: EVERY_EDGE_KIND },
+          description: 'Edge kinds to follow in path mode (default: ["calls"])',
+        },
+        reverse: {
+          type: 'boolean',
+          description: 'Follow edges backward in path mode',
+          default: false,
         },
+        from_file: { type: 'string', description: 'Disambiguate source by file in path mode' },
+        to_file: { type: 'string', description: 'Disambiguate target by file in path mode' },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
         ...PAGINATION_PROPS,
       },
       required: ['name'],
     },
   },
+  {
+    name: 'path',
+    description: 'Find shortest path between two symbols in the dependency graph',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from: { type: 'string', description: 'Source symbol name' },
+        to: { type: 'string', description: 'Target symbol name' },
+        depth: { type: 'number', description: 'Max traversal depth (default: 10)' },
+        edge_kinds: {
+          type: 'array',
+          items: { type: 'string', enum: EVERY_EDGE_KIND },
+          description: 'Edge kinds to follow (default: ["calls"])',
+        },
+        from_file: { type: 'string', description: 'Disambiguate source by file' },
+        to_file: { type: 'string', description: 'Disambiguate target by file' },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+      },
+      required: ['from', 'to'],
+    },
+  },
   {
     name: 'file_deps',
     description: 'Show what a file imports and what imports it',
@@ -50,6 +99,21 @@ const BASE_TOOLS = [
       properties: {
         file: { type: 'string', description: 'File path (partial match supported)' },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
+      },
+      required: ['file'],
+    },
+  },
+  {
+    name: 'file_exports',
+    description:
+      'Show exported symbols of a file with per-symbol consumers — who calls each export and from where',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'File path (partial match supported)' },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
       },
       required: ['file'],
     },
@@ -62,6 +126,7 @@ const BASE_TOOLS = [
       properties: {
         file: { type: 'string', description: 'File path to analyze' },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
       },
       required: ['file'],
     },
@@ -85,28 +150,6 @@ const BASE_TOOLS = [
       },
     },
   },
-  {
-    name: 'fn_deps',
-    description: 'Show function-level dependency chain: what a function calls and what calls it',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        name: { type: 'string', description: 'Function/method/class name (partial match)' },
-        depth: { type: 'number', description: 'Transitive caller depth', default: 3 },
-        file: {
-          type: 'string',
-          description: 'Scope search to functions in this file (partial match)',
-        },
-        kind: {
-          type: 'string',
-          enum: ALL_SYMBOL_KINDS,
-          description: 'Filter to a specific symbol kind',
-        },
-        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
-      },
-      required: ['name'],
-    },
-  },
   {
     name: 'fn_impact',
     description:
@@ -122,41 +165,15 @@ const BASE_TOOLS = [
         },
         kind: {
           type: 'string',
-          enum: ALL_SYMBOL_KINDS,
+          enum: EVERY_SYMBOL_KIND,
           description: 'Filter to a specific symbol kind',
         },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
       },
       required: ['name'],
     },
   },
-  {
-    name: 'symbol_path',
-    description: 'Find the shortest path between two symbols in the call graph (A calls...calls B)',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        from: { type: 'string', description: 'Source symbol name (partial match)' },
-        to: { type: 'string', description: 'Target symbol name (partial match)' },
-        max_depth: { type: 'number', description: 'Maximum BFS depth', default: 10 },
-        edge_kinds: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Edge kinds to follow (default: ["calls"])',
-        },
-        reverse: { type: 'boolean', description: 'Follow edges backward', default: false },
-        from_file: { type: 'string', description: 'Disambiguate source by file (partial match)' },
-        to_file: { type: 'string', description: 'Disambiguate target by file (partial match)' },
-        kind: {
-          type: 'string',
-          enum: ALL_SYMBOL_KINDS,
-          description: 'Filter both symbols by kind',
-        },
-        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
-      },
-      required: ['from', 'to'],
-    },
-  },
   {
     name: 'context',
     description:
@@ -176,7 +193,7 @@ const BASE_TOOLS = [
         },
         kind: {
           type: 'string',
-          enum: ALL_SYMBOL_KINDS,
+          enum: EVERY_SYMBOL_KIND,
           description: 'Filter to a specific symbol kind',
         },
         no_source: {
@@ -190,21 +207,25 @@ const BASE_TOOLS = [
           description: 'Include test file source code',
           default: false,
         },
+        ...PAGINATION_PROPS,
       },
       required: ['name'],
     },
   },
   {
-    name: 'explain',
+    name: 'symbol_children',
     description:
-      'Structural summary of a file or function: public/internal API, data flow, dependencies. No LLM needed.',
+      'List sub-declaration children of a symbol: parameters, properties, constants. Answers "what fields does this class have?" without reading source.',
     inputSchema: {
       type: 'object',
       properties: {
-        target: { type: 'string', description: 'File path or function name' },
+        name: { type: 'string', description: 'Function/method/class name (partial match)' },
+        file: { type: 'string', description: 'Scope to file (partial match)' },
+        kind: { type: 'string', enum: EVERY_SYMBOL_KIND, description: 'Filter by symbol kind' },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
       },
-      required: ['target'],
+      required: ['name'],
     },
   },
   {
@@ -241,32 +262,41 @@ const BASE_TOOLS = [
           enum: ['json', 'mermaid'],
           description: 'Output format (default: json)',
         },
+        ...PAGINATION_PROPS,
       },
     },
   },
   {
     name: 'semantic_search',
     description:
-      'Search code symbols by meaning using embeddings (requires prior `codegraph embed`)',
+      'Search code symbols by meaning using embeddings and/or keyword matching (requires prior `codegraph embed`). Default hybrid mode combines BM25 keyword + semantic search for best results.',
     inputSchema: {
       type: 'object',
       properties: {
         query: { type: 'string', description: 'Natural language search query' },
         limit: { type: 'number', description: 'Max results to return', default: 15 },
         min_score: { type: 'number', description: 'Minimum similarity score (0-1)', default: 0.2 },
+        mode: {
+          type: 'string',
+          enum: ['hybrid', 'semantic', 'keyword'],
+          description:
+            'Search mode: hybrid (BM25 + semantic, default), semantic (embeddings only), keyword (BM25 only)',
+        },
+        ...PAGINATION_PROPS,
       },
       required: ['query'],
     },
   },
   {
     name: 'export_graph',
-    description: 'Export the dependency graph in DOT (Graphviz), Mermaid, or JSON format',
+    description:
+      'Export the dependency graph in DOT, Mermaid, JSON, GraphML, GraphSON, or Neo4j CSV format',
     inputSchema: {
       type: 'object',
       properties: {
         format: {
           type: 'string',
-          enum: ['dot', 'mermaid', 'json'],
+          enum: ['dot', 'mermaid', 'json', 'graphml', 'graphson', 'neo4j'],
           description: 'Export format',
         },
         file_level: {
@@ -312,6 +342,7 @@ const BASE_TOOLS = [
           description: 'Return all files without limit',
           default: false,
         },
+        ...PAGINATION_PROPS,
       },
     },
   },
@@ -333,28 +364,6 @@ const BASE_TOOLS = [
       },
     },
   },
-  {
-    name: 'hotspots',
-    description:
-      'Find structural hotspots: files or directories with extreme fan-in, fan-out, or symbol density',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        metric: {
-          type: 'string',
-          enum: ['fan-in', 'fan-out', 'density', 'coupling'],
-          description: 'Metric to rank by',
-        },
-        level: {
-          type: 'string',
-          enum: ['file', 'directory'],
-          description: 'Rank files or directories',
-        },
-        limit: { type: 'number', description: 'Number of results to return', default: 10 },
-        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
-      },
-    },
-  },
   {
     name: 'co_changes',
     description:
@@ -373,20 +382,26 @@ const BASE_TOOLS = [
           default: 0.3,
         },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        offset: { type: 'number', description: 'Skip this many results (pagination, default: 0)' },
       },
     },
   },
   {
     name: 'execution_flow',
     description:
-      'Trace execution flow forward from an entry point (route, command, event) through callees to leaf functions. Answers "what happens when X is called?"',
+      'Trace execution flow forward from an entry point through callees to leaves, or list all entry points with list=true',
     inputSchema: {
       type: 'object',
       properties: {
         name: {
           type: 'string',
           description:
-            'Entry point or function name (e.g. "POST /login", "build"). Supports prefix-stripped matching.',
+            'Entry point or function name (required unless list=true). Supports prefix-stripped matching.',
+        },
+        list: {
+          type: 'boolean',
+          description: 'List all entry points grouped by type',
+          default: false,
         },
         depth: { type: 'number', description: 'Max forward traversal depth', default: 10 },
         file: {
@@ -395,22 +410,10 @@ const BASE_TOOLS = [
         },
         kind: {
           type: 'string',
-          enum: ALL_SYMBOL_KINDS,
+          enum: EVERY_SYMBOL_KIND,
           description: 'Filter to a specific symbol kind',
         },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
-      },
-      required: ['name'],
-    },
-  },
-  {
-    name: 'list_entry_points',
-    description:
-      'List all framework entry points (routes, commands, events) in the codebase, grouped by type',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
         ...PAGINATION_PROPS,
       },
     },
@@ -446,48 +449,284 @@ const BASE_TOOLS = [
           type: 'string',
           description: 'Filter by symbol kind (function, method, class, etc.)',
         },
+        offset: { type: 'number', description: 'Skip this many results (pagination, default: 0)' },
       },
     },
   },
   {
-    name: 'manifesto',
+    name: 'communities',
     description:
-      'Evaluate manifesto rules and return pass/fail verdicts for code health. Checks function complexity, file metrics, and cycle rules against configured thresholds.',
+      'Detect natural module boundaries using Louvain community detection. Compares discovered communities against directory structure and surfaces architectural drift.',
     inputSchema: {
       type: 'object',
       properties: {
-        file: { type: 'string', description: 'Scope to file (partial match)' },
+        functions: {
+          type: 'boolean',
+          description: 'Function-level instead of file-level',
+          default: false,
+        },
+        resolution: {
+          type: 'number',
+          description: 'Louvain resolution parameter (higher = more communities)',
+          default: 1.0,
+        },
+        drift: {
+          type: 'boolean',
+          description: 'Show only drift analysis (omit community member lists)',
+          default: false,
+        },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
+      },
+    },
+  },
+  {
+    name: 'code_owners',
+    description:
+      'Show CODEOWNERS mapping for files and functions. Shows ownership coverage, per-owner breakdown, and cross-owner boundary edges.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'Scope to a specific file (partial match)' },
+        owner: { type: 'string', description: 'Filter to a specific owner (e.g. @team-name)' },
+        boundary: {
+          type: 'boolean',
+          description: 'Show cross-owner boundary edges',
+          default: false,
+        },
         kind: {
           type: 'string',
           description: 'Filter by symbol kind (function, method, class, etc.)',
         },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
       },
     },
   },
   {
-    name: 'communities',
+    name: 'audit',
     description:
-      'Detect natural module boundaries using Louvain community detection. Compares discovered communities against directory structure and surfaces architectural drift.',
+      'Composite report combining explain, fn-impact, and health metrics for a file or function. Returns structure, blast radius, complexity, and threshold breaches in one call.',
     inputSchema: {
       type: 'object',
       properties: {
-        functions: {
+        target: { type: 'string', description: 'File path or function name' },
+        quick: {
           type: 'boolean',
-          description: 'Function-level instead of file-level',
+          description: 'Structural summary only (skip impact + health)',
           default: false,
         },
-        resolution: {
+        depth: { type: 'number', description: 'Impact analysis depth (default: 3)', default: 3 },
+        file: { type: 'string', description: 'Scope to file (partial match)' },
+        kind: {
+          type: 'string',
+          description: 'Filter by symbol kind (function, method, class, etc.)',
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
+      },
+      required: ['target'],
+    },
+  },
+  {
+    name: 'batch_query',
+    description:
+      'Run a query command against multiple targets in one call. Returns all results in a single JSON payload — ideal for multi-agent dispatch.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          enum: [
+            'fn-impact',
+            'context',
+            'explain',
+            'where',
+            'query',
+            'impact',
+            'deps',
+            'flow',
+            'dataflow',
+            'complexity',
+          ],
+          description: 'The query command to run for each target',
+        },
+        targets: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'List of target names (symbol names or file paths depending on command)',
+        },
+        depth: {
           type: 'number',
-          description: 'Louvain resolution parameter (higher = more communities)',
-          default: 1.0,
+          description: 'Traversal depth (for fn-impact, context, fn, flow)',
         },
-        drift: {
+        file: {
+          type: 'string',
+          description: 'Scope to file (partial match)',
+        },
+        kind: {
+          type: 'string',
+          enum: EVERY_SYMBOL_KIND,
+          description: 'Filter symbol kind',
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+      },
+      required: ['command', 'targets'],
+    },
+  },
+  {
+    name: 'triage',
+    description:
+      'Ranked audit queue by composite risk score. Merges connectivity (fan-in), complexity (cognitive), churn (commit count), role classification, and maintainability index into a single weighted score.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        level: {
+          type: 'string',
+          enum: ['function', 'file', 'directory'],
+          description:
+            'Granularity: function (default) | file | directory. File/directory shows hotspots',
+        },
+        sort: {
+          type: 'string',
+          enum: ['risk', 'complexity', 'churn', 'fan-in', 'mi'],
+          description: 'Sort metric (default: risk)',
+        },
+        min_score: {
+          type: 'number',
+          description: 'Only return symbols with risk score >= this threshold (0-1)',
+        },
+        role: {
+          type: 'string',
+          enum: VALID_ROLES,
+          description: 'Filter by role classification',
+        },
+        file: { type: 'string', description: 'Scope to file (partial match)' },
+        kind: {
+          type: 'string',
+          enum: ['function', 'method', 'class'],
+          description: 'Filter by symbol kind',
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        weights: {
+          type: 'object',
+          description:
+            'Custom scoring weights (e.g. {"fanIn":1,"complexity":0,"churn":0,"role":0,"mi":0})',
+        },
+        ...PAGINATION_PROPS,
+      },
+    },
+  },
+  {
+    name: 'branch_compare',
+    description:
+      'Compare code structure between two git refs (branches, tags, commits). Shows added/removed/changed symbols and transitive caller impact using temporary git worktrees.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        base: { type: 'string', description: 'Base git ref (branch, tag, or commit SHA)' },
+        target: { type: 'string', description: 'Target git ref to compare against base' },
+        depth: { type: 'number', description: 'Max transitive caller depth', default: 3 },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        format: {
+          type: 'string',
+          enum: ['json', 'mermaid'],
+          description: 'Output format (default: json)',
+        },
+      },
+      required: ['base', 'target'],
+    },
+  },
+  {
+    name: 'cfg',
+    description: 'Show intraprocedural control flow graph for a function. Requires build --cfg.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Function/method name (partial match)' },
+        format: {
+          type: 'string',
+          enum: ['json', 'dot', 'mermaid'],
+          description: 'Output format (default: json)',
+        },
+        file: { type: 'string', description: 'Scope to file (partial match)' },
+        kind: { type: 'string', enum: EVERY_SYMBOL_KIND, description: 'Filter by symbol kind' },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'dataflow',
+    description: 'Show data flow edges or data-dependent blast radius. Requires build --dataflow.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Function/method name (partial match)' },
+        mode: {
+          type: 'string',
+          enum: ['edges', 'impact'],
+          description: 'edges (default) or impact',
+        },
+        depth: { type: 'number', description: 'Max depth for impact mode', default: 5 },
+        file: { type: 'string', description: 'Scope to file (partial match)' },
+        kind: { type: 'string', enum: EVERY_SYMBOL_KIND, description: 'Filter by symbol kind' },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'check',
+    description:
+      'CI gate: run manifesto rules (no args), diff predicates (with ref/staged), or both (with rules flag). Returns pass/fail verdicts.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ref: { type: 'string', description: 'Git ref to diff against (default: HEAD)' },
+        staged: { type: 'boolean', description: 'Analyze staged changes instead of unstaged' },
+        rules: {
           type: 'boolean',
-          description: 'Show only drift analysis (omit community member lists)',
-          default: false,
+          description: 'Also run manifesto rules alongside diff predicates',
+        },
+        cycles: { type: 'boolean', description: 'Enable cycles predicate (default: true)' },
+        blast_radius: {
+          type: 'number',
+          description: 'Max transitive callers threshold (null = disabled)',
+        },
+        signatures: { type: 'boolean', description: 'Enable signatures predicate (default: true)' },
+        boundaries: { type: 'boolean', description: 'Enable boundaries predicate (default: true)' },
+        depth: { type: 'number', description: 'Max BFS depth for blast radius (default: 3)' },
+        file: { type: 'string', description: 'Scope to file (partial match, manifesto mode)' },
+        kind: {
+          type: 'string',
+          description: 'Filter by symbol kind (manifesto mode)',
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
+      },
+    },
+  },
+  {
+    name: 'ast_query',
+    description:
+      'Search stored AST nodes (calls, literals, new, throw, await) by pattern. Requires a prior build.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pattern: {
+          type: 'string',
+          description: 'GLOB pattern for node name (auto-wrapped in *..* for substring match)',
         },
+        kind: {
+          type: 'string',
+          enum: AST_NODE_KINDS,
+          description: 'Filter by AST node kind',
+        },
+        file: { type: 'string', description: 'Scope to file (partial match)' },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
       },
     },
   },
@@ -557,14 +796,15 @@ export async function startMCPServer(customDbPath, options = {}) {
 
   // Lazy import query functions to avoid circular deps at module load
   const {
-    queryNameData,
     impactAnalysisData,
     moduleMapData,
     fileDepsData,
+    exportsData,
     fnDepsData,
     fnImpactData,
     pathData,
     contextData,
+    childrenData,
     explainData,
     whereData,
     diffImpactData,
@@ -615,18 +855,63 @@ export async function startMCPServer(customDbPath, options = {}) {
 
       let result;
       switch (name) {
-        case 'query_function':
-          result = queryNameData(args.name, dbPath, {
+        case 'query': {
+          const qMode = args.mode || 'deps';
+          if (qMode === 'path') {
+            if (!args.to) {
+              result = { error: 'path mode requires a "to" argument' };
+              break;
+            }
+            result = pathData(args.name, args.to, dbPath, {
+              maxDepth: args.depth ?? 10,
+              edgeKinds: args.edge_kinds,
+              reverse: args.reverse,
+              fromFile: args.from_file,
+              toFile: args.to_file,
+              kind: args.kind,
+              noTests: args.no_tests,
+            });
+          } else {
+            result = fnDepsData(args.name, dbPath, {
+              depth: args.depth,
+              file: args.file,
+              kind: args.kind,
+              noTests: args.no_tests,
+              limit: Math.min(args.limit ?? MCP_DEFAULTS.query, MCP_MAX_LIMIT),
+              offset: args.offset ?? 0,
+            });
+          }
+          break;
+        }
+        case 'path':
+          result = pathData(args.from, args.to, dbPath, {
+            maxDepth: args.depth ?? 10,
+            edgeKinds: args.edge_kinds,
+            fromFile: args.from_file,
+            toFile: args.to_file,
             noTests: args.no_tests,
-            limit: Math.min(args.limit ?? MCP_DEFAULTS.query_function, MCP_MAX_LIMIT),
-            offset: args.offset ?? 0,
           });
           break;
         case 'file_deps':
-          result = fileDepsData(args.file, dbPath, { noTests: args.no_tests });
+          result = fileDepsData(args.file, dbPath, {
+            noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.file_deps, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
+          });
+          break;
+        case 'file_exports':
+          result = exportsData(args.file, dbPath, {
+            noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.file_exports, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
+          });
           break;
         case 'impact_analysis':
-          result = impactAnalysisData(args.file, dbPath, { noTests: args.no_tests });
+          result = impactAnalysisData(args.file, dbPath, {
+            noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.impact_analysis, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
+          });
           break;
         case 'find_cycles': {
           const db = new Database(findDbPath(dbPath), { readonly: true });
@@ -638,31 +923,14 @@ export async function startMCPServer(customDbPath, options = {}) {
         case 'module_map':
           result = moduleMapData(dbPath, args.limit || 20, { noTests: args.no_tests });
           break;
-        case 'fn_deps':
-          result = fnDepsData(args.name, dbPath, {
-            depth: args.depth,
-            file: args.file,
-            kind: args.kind,
-            noTests: args.no_tests,
-          });
-          break;
         case 'fn_impact':
           result = fnImpactData(args.name, dbPath, {
             depth: args.depth,
             file: args.file,
             kind: args.kind,
             noTests: args.no_tests,
-          });
-          break;
-        case 'symbol_path':
-          result = pathData(args.from, args.to, dbPath, {
-            maxDepth: args.max_depth,
-            edgeKinds: args.edge_kinds,
-            reverse: args.reverse,
-            fromFile: args.from_file,
-            toFile: args.to_file,
-            kind: args.kind,
-            noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.fn_impact, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
           });
           break;
         case 'context':
@@ -673,10 +941,18 @@ export async function startMCPServer(customDbPath, options = {}) {
             noSource: args.no_source,
             noTests: args.no_tests,
             includeTests: args.include_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.context, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
           });
           break;
-        case 'explain':
-          result = explainData(args.target, dbPath, { noTests: args.no_tests });
+        case 'symbol_children':
+          result = childrenData(args.name, dbPath, {
+            file: args.file,
+            kind: args.kind,
+            noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.context, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
+          });
           break;
         case 'where':
           result = whereData(args.target, dbPath, {
@@ -700,27 +976,77 @@ export async function startMCPServer(customDbPath, options = {}) {
               ref: args.ref,
               depth: args.depth,
               noTests: args.no_tests,
+              limit: Math.min(args.limit ?? MCP_DEFAULTS.diff_impact, MCP_MAX_LIMIT),
+              offset: args.offset ?? 0,
             });
           }
           break;
         case 'semantic_search': {
-          const { searchData } = await import('./embedder.js');
-          result = await searchData(args.query, dbPath, {
-            limit: args.limit,
+          const mode = args.mode || 'hybrid';
+          const searchOpts = {
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.semantic_search, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
             minScore: args.min_score,
-          });
-          if (result === null) {
-            return {
-              content: [
-                { type: 'text', text: 'Semantic search unavailable. Run `codegraph embed` first.' },
-              ],
-              isError: true,
-            };
+          };
+
+          if (mode === 'keyword') {
+            const { ftsSearchData } = await import('./embedder.js');
+            result = ftsSearchData(args.query, dbPath, searchOpts);
+            if (result === null) {
+              return {
+                content: [
+                  {
+                    type: 'text',
+                    text: 'No FTS5 index found. Run `codegraph embed` to build the keyword index.',
+                  },
+                ],
+                isError: true,
+              };
+            }
+          } else if (mode === 'semantic') {
+            const { searchData } = await import('./embedder.js');
+            result = await searchData(args.query, dbPath, searchOpts);
+            if (result === null) {
+              return {
+                content: [
+                  {
+                    type: 'text',
+                    text: 'Semantic search unavailable. Run `codegraph embed` first.',
+                  },
+                ],
+                isError: true,
+              };
+            }
+          } else {
+            // hybrid (default) — falls back to semantic if no FTS5
+            const { hybridSearchData, searchData } = await import('./embedder.js');
+            result = await hybridSearchData(args.query, dbPath, searchOpts);
+            if (result === null) {
+              result = await searchData(args.query, dbPath, searchOpts);
+              if (result === null) {
+                return {
+                  content: [
+                    {
+                      type: 'text',
+                      text: 'Semantic search unavailable. Run `codegraph embed` first.',
+                    },
+                  ],
+                  isError: true,
+                };
+              }
+            }
           }
           break;
         }
         case 'export_graph': {
-          const { exportDOT, exportMermaid, exportJSON } = await import('./export.js');
+          const {
+            exportDOT,
+            exportGraphML,
+            exportGraphSON,
+            exportJSON,
+            exportMermaid,
+            exportNeo4jCSV,
+          } = await import('./export.js');
           const db = new Database(findDbPath(dbPath), { readonly: true });
           const fileLevel = args.file_level !== false;
           const exportLimit = args.limit
@@ -739,13 +1065,26 @@ export async function startMCPServer(customDbPath, options = {}) {
                 offset: args.offset ?? 0,
               });
               break;
+            case 'graphml':
+              result = exportGraphML(db, { fileLevel, limit: exportLimit });
+              break;
+            case 'graphson':
+              result = exportGraphSON(db, {
+                fileLevel,
+                limit: exportLimit,
+                offset: args.offset ?? 0,
+              });
+              break;
+            case 'neo4j':
+              result = exportNeo4jCSV(db, { fileLevel, limit: exportLimit });
+              break;
             default:
               db.close();
               return {
                 content: [
                   {
                     type: 'text',
-                    text: `Unknown format: ${args.format}. Use dot, mermaid, or json.`,
+                    text: `Unknown format: ${args.format}. Use dot, mermaid, json, graphml, graphson, or neo4j.`,
                   },
                 ],
                 isError: true,
@@ -779,16 +1118,8 @@ export async function startMCPServer(customDbPath, options = {}) {
             depth: args.depth,
             sort: args.sort,
             full: args.full,
-          });
-          break;
-        }
-        case 'hotspots': {
-          const { hotspotsData } = await import('./structure.js');
-          result = hotspotsData(dbPath, {
-            metric: args.metric,
-            level: args.level,
-            limit: args.limit,
-            noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.structure, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
           });
           break;
         }
@@ -796,34 +1127,42 @@ export async function startMCPServer(customDbPath, options = {}) {
           const { coChangeData, coChangeTopData } = await import('./cochange.js');
           result = args.file
             ? coChangeData(args.file, dbPath, {
-                limit: args.limit,
+                limit: Math.min(args.limit ?? MCP_DEFAULTS.co_changes, MCP_MAX_LIMIT),
+                offset: args.offset ?? 0,
                 minJaccard: args.min_jaccard,
                 noTests: args.no_tests,
               })
             : coChangeTopData(dbPath, {
-                limit: args.limit,
+                limit: Math.min(args.limit ?? MCP_DEFAULTS.co_changes, MCP_MAX_LIMIT),
+                offset: args.offset ?? 0,
                 minJaccard: args.min_jaccard,
                 noTests: args.no_tests,
               });
           break;
         }
         case 'execution_flow': {
-          const { flowData } = await import('./flow.js');
-          result = flowData(args.name, dbPath, {
-            depth: args.depth,
-            file: args.file,
-            kind: args.kind,
-            noTests: args.no_tests,
-          });
-          break;
-        }
-        case 'list_entry_points': {
-          const { listEntryPointsData } = await import('./flow.js');
-          result = listEntryPointsData(dbPath, {
-            noTests: args.no_tests,
-            limit: Math.min(args.limit ?? MCP_DEFAULTS.list_entry_points, MCP_MAX_LIMIT),
-            offset: args.offset ?? 0,
-          });
+          if (args.list) {
+            const { listEntryPointsData } = await import('./flow.js');
+            result = listEntryPointsData(dbPath, {
+              noTests: args.no_tests,
+              limit: Math.min(args.limit ?? MCP_DEFAULTS.execution_flow, MCP_MAX_LIMIT),
+              offset: args.offset ?? 0,
+            });
+          } else {
+            if (!args.name) {
+              result = { error: 'Provide a name or set list=true' };
+              break;
+            }
+            const { flowData } = await import('./flow.js');
+            result = flowData(args.name, dbPath, {
+              depth: args.depth,
+              file: args.file,
+              kind: args.kind,
+              noTests: args.no_tests,
+              limit: Math.min(args.limit ?? MCP_DEFAULTS.execution_flow, MCP_MAX_LIMIT),
+              offset: args.offset ?? 0,
+            });
+          }
           break;
         }
         case 'complexity': {
@@ -831,7 +1170,8 @@ export async function startMCPServer(customDbPath, options = {}) {
           result = complexityData(dbPath, {
             target: args.name,
             file: args.file,
-            limit: args.limit,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.complexity, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
             sort: args.sort,
             aboveThreshold: args.above_threshold,
             health: args.health,
@@ -840,15 +1180,6 @@ export async function startMCPServer(customDbPath, options = {}) {
           });
           break;
         }
-        case 'manifesto': {
-          const { manifestoData } = await import('./manifesto.js');
-          result = manifestoData(dbPath, {
-            file: args.file,
-            noTests: args.no_tests,
-            kind: args.kind,
-          });
-          break;
-        }
         case 'communities': {
           const { communitiesData } = await import('./communities.js');
           result = communitiesData(dbPath, {
@@ -856,6 +1187,184 @@ export async function startMCPServer(customDbPath, options = {}) {
             resolution: args.resolution,
             drift: args.drift,
             noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.communities, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
+          });
+          break;
+        }
+        case 'code_owners': {
+          const { ownersData } = await import('./owners.js');
+          result = ownersData(dbPath, {
+            file: args.file,
+            owner: args.owner,
+            boundary: args.boundary,
+            kind: args.kind,
+            noTests: args.no_tests,
+          });
+          break;
+        }
+        case 'audit': {
+          if (args.quick) {
+            result = explainData(args.target, dbPath, {
+              noTests: args.no_tests,
+              limit: Math.min(args.limit ?? MCP_DEFAULTS.explain, MCP_MAX_LIMIT),
+              offset: args.offset ?? 0,
+            });
+          } else {
+            const { auditData } = await import('./audit.js');
+            result = auditData(args.target, dbPath, {
+              depth: args.depth,
+              file: args.file,
+              kind: args.kind,
+              noTests: args.no_tests,
+            });
+          }
+          break;
+        }
+        case 'batch_query': {
+          const { batchData } = await import('./batch.js');
+          result = batchData(args.command, args.targets, dbPath, {
+            depth: args.depth,
+            file: args.file,
+            kind: args.kind,
+            noTests: args.no_tests,
+          });
+          break;
+        }
+        case 'triage': {
+          if (args.level === 'file' || args.level === 'directory') {
+            const { hotspotsData } = await import('./structure.js');
+            const TRIAGE_TO_HOTSPOT = {
+              risk: 'fan-in',
+              complexity: 'density',
+              churn: 'coupling',
+              mi: 'fan-in',
+            };
+            const metric = TRIAGE_TO_HOTSPOT[args.sort] ?? args.sort;
+            result = hotspotsData(dbPath, {
+              metric,
+              level: args.level,
+              limit: Math.min(args.limit ?? MCP_DEFAULTS.hotspots, MCP_MAX_LIMIT),
+              offset: args.offset ?? 0,
+              noTests: args.no_tests,
+            });
+          } else {
+            const { triageData } = await import('./triage.js');
+            result = triageData(dbPath, {
+              sort: args.sort,
+              minScore: args.min_score,
+              role: args.role,
+              file: args.file,
+              kind: args.kind,
+              noTests: args.no_tests,
+              weights: args.weights,
+              limit: Math.min(args.limit ?? MCP_DEFAULTS.triage, MCP_MAX_LIMIT),
+              offset: args.offset ?? 0,
+            });
+          }
+          break;
+        }
+        case 'branch_compare': {
+          const { branchCompareData, branchCompareMermaid } = await import('./branch-compare.js');
+          const bcData = await branchCompareData(args.base, args.target, {
+            depth: args.depth,
+            noTests: args.no_tests,
+          });
+          result = args.format === 'mermaid' ? branchCompareMermaid(bcData) : bcData;
+          break;
+        }
+        case 'cfg': {
+          const { cfgData, cfgToDOT, cfgToMermaid } = await import('./cfg.js');
+          const cfgResult = cfgData(args.name, dbPath, {
+            file: args.file,
+            kind: args.kind,
+            noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.query, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
+          });
+          if (args.format === 'dot') {
+            result = { text: cfgToDOT(cfgResult) };
+          } else if (args.format === 'mermaid') {
+            result = { text: cfgToMermaid(cfgResult) };
+          } else {
+            result = cfgResult;
+          }
+          break;
+        }
+        case 'dataflow': {
+          const dfMode = args.mode || 'edges';
+          if (dfMode === 'impact') {
+            const { dataflowImpactData } = await import('./dataflow.js');
+            result = dataflowImpactData(args.name, dbPath, {
+              depth: args.depth,
+              file: args.file,
+              kind: args.kind,
+              noTests: args.no_tests,
+              limit: Math.min(args.limit ?? MCP_DEFAULTS.fn_impact, MCP_MAX_LIMIT),
+              offset: args.offset ?? 0,
+            });
+          } else {
+            const { dataflowData } = await import('./dataflow.js');
+            result = dataflowData(args.name, dbPath, {
+              file: args.file,
+              kind: args.kind,
+              noTests: args.no_tests,
+              limit: Math.min(args.limit ?? MCP_DEFAULTS.query, MCP_MAX_LIMIT),
+              offset: args.offset ?? 0,
+            });
+          }
+          break;
+        }
+        case 'check': {
+          const isDiffMode = args.ref || args.staged;
+
+          if (!isDiffMode && !args.rules) {
+            // No ref, no staged → run manifesto rules on whole codebase
+            const { manifestoData } = await import('./manifesto.js');
+            result = manifestoData(dbPath, {
+              file: args.file,
+              noTests: args.no_tests,
+              kind: args.kind,
+              limit: Math.min(args.limit ?? MCP_DEFAULTS.manifesto, MCP_MAX_LIMIT),
+              offset: args.offset ?? 0,
+            });
+          } else {
+            const { checkData } = await import('./check.js');
+            const checkResult = checkData(dbPath, {
+              ref: args.ref,
+              staged: args.staged,
+              cycles: args.cycles,
+              blastRadius: args.blast_radius,
+              signatures: args.signatures,
+              boundaries: args.boundaries,
+              depth: args.depth,
+              noTests: args.no_tests,
+            });
+
+            if (args.rules) {
+              const { manifestoData } = await import('./manifesto.js');
+              const manifestoResult = manifestoData(dbPath, {
+                file: args.file,
+                noTests: args.no_tests,
+                kind: args.kind,
+                limit: Math.min(args.limit ?? MCP_DEFAULTS.manifesto, MCP_MAX_LIMIT),
+                offset: args.offset ?? 0,
+              });
+              result = { check: checkResult, manifesto: manifestoResult };
+            } else {
+              result = checkResult;
+            }
+          }
+          break;
+        }
+        case 'ast_query': {
+          const { astQueryData } = await import('./ast.js');
+          result = astQueryData(args.pattern, dbPath, {
+            kind: args.kind,
+            file: args.file,
+            noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.ast_query, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
           });
           break;
         }