@optave/codegraph 3.1.5 → 3.3.0

package/src/graph/classifiers/roles.js

@@ -1,11 +1,59 @@
 /**
  * Node role classification — pure logic, no DB.
  *
- * Roles: entry, core, utility, adapter, leaf, dead
+ * Roles: entry, core, utility, adapter, leaf, dead-*, test-only
+ *
+ * Dead sub-categories refine the coarse "dead" bucket:
+ *   dead-leaf       — parameters, properties, constants (leaf nodes by definition)
+ *   dead-entry      — framework dispatch: CLI commands, MCP tools, event handlers
+ *   dead-ffi        — cross-language FFI boundaries (e.g. Rust napi-rs bindings)
+ *   dead-unresolved — genuinely unreferenced callables (the real dead code)
  */
 
 export const FRAMEWORK_ENTRY_PREFIXES = ['route:', 'event:', 'command:'];
 
+// ── Dead sub-classification helpers ────────────────────────────────
+
+const LEAF_KINDS = new Set(['parameter', 'property', 'constant']);
+
+const FFI_EXTENSIONS = new Set(['.rs', '.c', '.cpp', '.h', '.go', '.java', '.cs']);
+
+/** Path patterns indicating framework-dispatched entry points. */
+const ENTRY_PATH_PATTERNS = [
+  /cli[/\\]commands[/\\]/,
+  /mcp[/\\]/,
+  /routes?[/\\]/,
+  /handlers?[/\\]/,
+  /middleware[/\\]/,
+];
+
+/**
+ * Refine a "dead" classification into a sub-category.
+ *
+ * @param {{ kind?: string, file?: string }} node
+ * @returns {'dead-leaf'|'dead-entry'|'dead-ffi'|'dead-unresolved'}
+ */
+function classifyDeadSubRole(node) {
+  // Leaf kinds are dead by definition — they can't have callers
+  if (node.kind && LEAF_KINDS.has(node.kind)) return 'dead-leaf';
+
+  if (node.file) {
+    // Cross-language FFI: compiled-language files in a JS/TS project
+    // Priority: dead-ffi is checked before dead-entry deliberately — an FFI
+    // boundary is a more fundamental classification than a path-based hint.
+    // A .so/.dll in a routes/ directory is still FFI, not an entry point.
+    const dotIdx = node.file.lastIndexOf('.');
+    if (dotIdx !== -1 && FFI_EXTENSIONS.has(node.file.slice(dotIdx))) return 'dead-ffi';
+
+    // Framework-dispatched entry points (CLI commands, MCP tools, routes)
+    if (ENTRY_PATH_PATTERNS.some((p) => p.test(node.file))) return 'dead-entry';
+  }
+
+  return 'dead-unresolved';
+}
+
+// ── Helpers ────────────────────────────────────────────────────────
+
 function median(sorted) {
   if (sorted.length === 0) return 0;
   const mid = Math.floor(sorted.length / 2);
@@ -15,7 +63,7 @@ function median(sorted) {
 /**
  * Classify nodes into architectural roles based on fan-in/fan-out metrics.
  *
- * @param {{ id: string, name: string, fanIn: number, fanOut: number, isExported: boolean }[]} nodes
+ * @param {{ id: string, name: string, kind?: string, file?: string, fanIn: number, fanOut: number, isExported: boolean, testOnlyFanIn?: number }[]} nodes
  * @returns {Map<string, string>} nodeId → role
  */
 export function classifyRoles(nodes) {
@@ -38,15 +86,18 @@ export function classifyRoles(nodes) {
   for (const node of nodes) {
     const highIn = node.fanIn >= medFanIn && node.fanIn > 0;
     const highOut = node.fanOut >= medFanOut && node.fanOut > 0;
+    const hasProdFanIn = typeof node.productionFanIn === 'number';
 
     let role;
     const isFrameworkEntry = FRAMEWORK_ENTRY_PREFIXES.some((p) => node.name.startsWith(p));
     if (isFrameworkEntry) {
       role = 'entry';
     } else if (node.fanIn === 0 && !node.isExported) {
-      role = 'dead';
+      role = node.testOnlyFanIn > 0 ? 'test-only' : classifyDeadSubRole(node);
     } else if (node.fanIn === 0 && node.isExported) {
       role = 'entry';
+    } else if (hasProdFanIn && node.fanIn > 0 && node.productionFanIn === 0) {
+      role = 'test-only';
     } else if (highIn && !highOut) {
       role = 'core';
     } else if (highIn && highOut) {

package/src/index.js

@@ -12,6 +12,7 @@
 export { buildGraph } from './domain/graph/builder.js';
 export { findCycles } from './domain/graph/cycles.js';
 export {
+  briefData,
   childrenData,
   contextData,
   diffImpactData,

package/src/infrastructure/config.js

@@ -23,7 +23,7 @@ export const DEFAULTS = {
   },
   embeddings: { model: 'nomic-v1.5', llmProvider: null },
   llm: { provider: null, model: null, baseUrl: null, apiKey: null, apiKeyCommand: null },
-  search: { defaultMinScore: 0.2, rrfK: 60, topK: 15 },
+  search: { defaultMinScore: 0.2, rrfK: 60, topK: 15, similarityWarnThreshold: 0.85 },
   ci: { failOnCycles: false, impactThreshold: null },
   manifesto: {
     rules: {
@@ -54,6 +54,80 @@ export const DEFAULTS = {
     minJaccard: 0.3,
     maxFilesPerCommit: 50,
   },
+  analysis: {
+    impactDepth: 3,
+    fnImpactDepth: 5,
+    auditDepth: 3,
+    sequenceDepth: 10,
+    falsePositiveCallers: 20,
+    briefCallerDepth: 5,
+    briefImporterDepth: 5,
+    briefHighRiskCallers: 10,
+    briefMediumRiskCallers: 3,
+  },
+  community: {
+    resolution: 1.0,
+  },
+  structure: {
+    cohesionThreshold: 0.3,
+  },
+  risk: {
+    weights: {
+      fanIn: 0.25,
+      complexity: 0.3,
+      churn: 0.2,
+      role: 0.15,
+      mi: 0.1,
+    },
+    roleWeights: {
+      core: 1.0,
+      utility: 0.9,
+      entry: 0.8,
+      adapter: 0.5,
+      leaf: 0.2,
+      'test-only': 0.1,
+      dead: 0.1,
+      'dead-leaf': 0.0,
+      'dead-entry': 0.3,
+      'dead-ffi': 0.05,
+      'dead-unresolved': 0.15,
+    },
+    defaultRoleWeight: 0.5,
+  },
+  display: {
+    maxColWidth: 40,
+    excerptLines: 50,
+    summaryMaxChars: 100,
+    jsdocEndScanLines: 10,
+    jsdocOpenScanLines: 20,
+    signatureGatherLines: 5,
+  },
+  mcp: {
+    defaults: {
+      list_functions: 100,
+      query: 10,
+      where: 50,
+      node_roles: 100,
+      export_graph: 500,
+      fn_impact: 5,
+      context: 5,
+      explain: 10,
+      file_deps: 20,
+      file_exports: 20,
+      diff_impact: 30,
+      impact_analysis: 20,
+      semantic_search: 20,
+      execution_flow: 50,
+      hotspots: 20,
+      co_changes: 20,
+      complexity: 30,
+      manifesto: 50,
+      communities: 20,
+      structure: 30,
+      triage: 20,
+      ast_query: 50,
+    },
+  },
 };
 
 /**
@@ -120,7 +194,183 @@ export function resolveSecrets(config) {
   return config;
 }
 
-function mergeConfig(defaults, overrides) {
+// ── Monorepo workspace detection ─────────────────────────────────────
+
+/**
+ * Expand a workspace glob pattern into matching directories.
+ * Supports trailing `/*` or `/**` patterns (e.g. "packages/*").
+ * Does not depend on an external glob library — uses fs.readdirSync.
+ */
+function expandWorkspaceGlob(pattern, rootDir) {
+  // Strip trailing /*, /**, or just *
+  const clean = pattern.replace(/\/?\*\*?$/, '');
+  const baseDir = path.resolve(rootDir, clean);
+  if (!fs.existsSync(baseDir)) return [];
+  try {
+    const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isDirectory())
+      .map((e) => path.join(baseDir, e.name))
+      .filter((d) => fs.existsSync(path.join(d, 'package.json')));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read a package.json and return its name field, or null.
+ */
+function readPackageName(pkgDir) {
+  try {
+    const raw = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw);
+    return pkg.name || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the entry-point source file for a workspace package.
+ * Checks exports → main → index file fallback.
+ */
+function resolveWorkspaceEntry(pkgDir) {
+  try {
+    const raw = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw);
+
+    // Try "source" field first (common in monorepos for pre-built packages)
+    if (pkg.source) {
+      const s = path.resolve(pkgDir, pkg.source);
+      if (fs.existsSync(s)) return s;
+    }
+
+    // Try "main" field
+    if (pkg.main) {
+      const m = path.resolve(pkgDir, pkg.main);
+      if (fs.existsSync(m)) return m;
+    }
+
+    // Index file fallback
+    for (const idx of [
+      'index.ts',
+      'index.tsx',
+      'index.js',
+      'index.mjs',
+      'src/index.ts',
+      'src/index.tsx',
+      'src/index.js',
+    ]) {
+      const candidate = path.resolve(pkgDir, idx);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+/**
+ * Detect monorepo workspace packages from workspace configuration files.
+ *
+ * Checks (in order):
+ *   1. pnpm-workspace.yaml — `packages:` array
+ *   2. package.json — `workspaces` field (npm/yarn)
+ *   3. lerna.json — `packages` array
+ *
+ * @param {string} rootDir - Project root directory
+ * @returns {Map<string, { dir: string, entry: string|null }>}
+ *   Map of package name → { absolute dir, resolved entry file }
+ */
+export function detectWorkspaces(rootDir) {
+  const workspaces = new Map();
+  const patterns = [];
+
+  // 1. pnpm-workspace.yaml
+  const pnpmPath = path.join(rootDir, 'pnpm-workspace.yaml');
+  if (fs.existsSync(pnpmPath)) {
+    try {
+      const raw = fs.readFileSync(pnpmPath, 'utf-8');
+      // Simple YAML parse for `packages:` array — no dependency needed
+      const packagesMatch = raw.match(/^packages:\s*\n((?:\s+-\s+.+\n?)*)/m);
+      if (packagesMatch) {
+        const lines = packagesMatch[1].match(/^\s+-\s+['"]?([^'"#\n]+)['"]?\s*$/gm);
+        if (lines) {
+          for (const line of lines) {
+            const m = line.match(/^\s+-\s+['"]?([^'"#\n]+?)['"]?\s*$/);
+            if (m) patterns.push(m[1].trim());
+          }
+        }
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
+  // 2. package.json workspaces (npm/yarn)
+  if (patterns.length === 0) {
+    const rootPkgPath = path.join(rootDir, 'package.json');
+    if (fs.existsSync(rootPkgPath)) {
+      try {
+        const raw = fs.readFileSync(rootPkgPath, 'utf-8');
+        const pkg = JSON.parse(raw);
+        const ws = pkg.workspaces;
+        if (Array.isArray(ws)) {
+          patterns.push(...ws);
+        } else if (ws && Array.isArray(ws.packages)) {
+          // Yarn classic format: { packages: [...], nohoist: [...] }
+          patterns.push(...ws.packages);
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  // 3. lerna.json
+  if (patterns.length === 0) {
+    const lernaPath = path.join(rootDir, 'lerna.json');
+    if (fs.existsSync(lernaPath)) {
+      try {
+        const raw = fs.readFileSync(lernaPath, 'utf-8');
+        const lerna = JSON.parse(raw);
+        if (Array.isArray(lerna.packages)) {
+          patterns.push(...lerna.packages);
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  if (patterns.length === 0) return workspaces;
+
+  // Expand glob patterns and collect packages
+  for (const pattern of patterns) {
+    // Check if pattern is a direct path (no glob) or a glob
+    if (pattern.includes('*')) {
+      for (const dir of expandWorkspaceGlob(pattern, rootDir)) {
+        const name = readPackageName(dir);
+        if (name) workspaces.set(name, { dir, entry: resolveWorkspaceEntry(dir) });
+      }
+    } else {
+      // Direct path like "packages/core"
+      const dir = path.resolve(rootDir, pattern);
+      if (fs.existsSync(path.join(dir, 'package.json'))) {
+        const name = readPackageName(dir);
+        if (name) workspaces.set(name, { dir, entry: resolveWorkspaceEntry(dir) });
+      }
+    }
+  }
+
+  if (workspaces.size > 0) {
+    debug(`Detected ${workspaces.size} workspace packages: ${[...workspaces.keys()].join(', ')}`);
+  }
+
+  return workspaces;
+}
+
+export function mergeConfig(defaults, overrides) {
   const result = { ...defaults };
   for (const [key, value] of Object.entries(overrides)) {
     if (
@@ -128,9 +378,10 @@ function mergeConfig(defaults, overrides) {
       typeof value === 'object' &&
       !Array.isArray(value) &&
       defaults[key] &&
-      typeof defaults[key] === 'object'
+      typeof defaults[key] === 'object' &&
+      !Array.isArray(defaults[key])
     ) {
-      result[key] = { ...defaults[key], ...value };
+      result[key] = mergeConfig(defaults[key], value);
     } else {
       result[key] = value;
     }

package/src/mcp/middleware.js

@@ -2,10 +2,28 @@
  * MCP middleware helpers — pagination defaults and limits.
  */
 
-import { MCP_DEFAULTS, MCP_MAX_LIMIT } from '../shared/paginate.js';
+import { getMcpDefaults, MCP_DEFAULTS, MCP_MAX_LIMIT } from '../shared/paginate.js';
 
 export { MCP_DEFAULTS, MCP_MAX_LIMIT };
 
+/** Resolved MCP defaults (may include config overrides). Set via initMcpDefaults(). */
+let resolvedDefaults = MCP_DEFAULTS;
+
+/**
+ * Initialize MCP defaults from config. Call once at server startup.
+ * @param {object} [configMcpDefaults] - config.mcp.defaults overrides
+ */
+export function initMcpDefaults(configMcpDefaults) {
+  resolvedDefaults = getMcpDefaults(configMcpDefaults);
+}
+
+/**
+ * Reset MCP defaults back to the base defaults. Useful for test isolation.
+ */
+export function resetMcpDefaults() {
+  resolvedDefaults = MCP_DEFAULTS;
+}
+
 /**
  * Resolve effective limit for a tool call.
  * @param {object} args - Tool arguments
@@ -13,7 +31,7 @@ export { MCP_DEFAULTS, MCP_MAX_LIMIT };
  * @returns {number}
  */
 export function effectiveLimit(args, toolName) {
-  return Math.min(args.limit ?? MCP_DEFAULTS[toolName] ?? 100, MCP_MAX_LIMIT);
+  return Math.min(args.limit ?? resolvedDefaults[toolName] ?? 100, MCP_MAX_LIMIT);
 }
 
 /**

package/src/mcp/server.js

@@ -7,8 +7,10 @@
 
 import { createRequire } from 'node:module';
 import { findDbPath } from '../db/index.js';
+import { loadConfig } from '../infrastructure/config.js';
 import { CodegraphError, ConfigError } from '../shared/errors.js';
 import { MCP_MAX_LIMIT } from '../shared/paginate.js';
+import { initMcpDefaults } from './middleware.js';
 import { buildToolList } from './tool-registry.js';
 import { TOOL_HANDLERS } from './tools/index.js';
 
@@ -21,45 +23,88 @@ 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;
+
+  // Apply config-based MCP page-size overrides
+  const config = options.config || loadConfig();
+  initMcpDefaults(config.mcp?.defaults);
+
+  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 +118,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:
@@ -349,7 +362,7 @@ const BASE_TOOLS = [
   {
     name: 'node_roles',
     description:
-      'Show node role classification (entry, core, utility, adapter, dead, leaf) based on connectivity patterns',
+      'Show node role classification (entry, core, utility, adapter, dead [dead-leaf, dead-entry, dead-ffi, dead-unresolved], leaf) based on connectivity patterns',
     inputSchema: {
       type: 'object',
       properties: {
@@ -745,6 +758,45 @@ const BASE_TOOLS = [
       },
     },
   },
+  {
+    name: 'implementations',
+    description:
+      'List all concrete types (classes, structs, records) that implement a given interface or trait',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Interface/trait 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: ['name'],
+    },
+  },
+  {
+    name: 'interfaces',
+    description: 'List all interfaces and traits that a given class, struct, or record implements',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Class/struct 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: ['name'],
+    },
+  },
   {
     name: 'ast_query',
     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,
+  });
+}