@optave/codegraph 3.3.1 → 3.4.0

package/src/infrastructure/{registry.js → registry.ts}

@@ -3,22 +3,33 @@ import os from 'node:os';
 import path from 'node:path';
 import { debug, warn } from './logger.js';
 
-export const REGISTRY_PATH =
-  process.env.CODEGRAPH_REGISTRY_PATH || path.join(os.homedir(), '.codegraph', 'registry.json');
+export const REGISTRY_PATH: string =
+  process.env['CODEGRAPH_REGISTRY_PATH'] || path.join(os.homedir(), '.codegraph', 'registry.json');
 
 /** Default TTL: entries not accessed within 30 days are pruned. */
 export const DEFAULT_TTL_DAYS = 30;
 
+interface RegistryEntry {
+  path: string;
+  dbPath: string;
+  addedAt: string;
+  lastAccessedAt?: string;
+}
+
+interface Registry {
+  repos: Record<string, RegistryEntry>;
+}
+
 /**
  * Load the registry from disk.
  * Returns `{ repos: {} }` on missing or corrupt file.
  */
-export function loadRegistry(registryPath = REGISTRY_PATH) {
+export function loadRegistry(registryPath: string = REGISTRY_PATH): Registry {
   try {
     const raw = fs.readFileSync(registryPath, 'utf-8');
     const data = JSON.parse(raw);
     if (!data || typeof data.repos !== 'object') return { repos: {} };
-    return data;
+    return data as Registry;
   } catch {
     return { repos: {} };
   }
@@ -28,7 +39,7 @@ export function loadRegistry(registryPath = REGISTRY_PATH) {
  * Persist the registry to disk (atomic write via temp + rename).
  * Creates the parent directory if needed.
  */
-export function saveRegistry(registry, registryPath = REGISTRY_PATH) {
+export function saveRegistry(registry: Registry, registryPath: string = REGISTRY_PATH): void {
   const dir = path.dirname(registryPath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 
@@ -45,7 +56,11 @@ export function saveRegistry(registry, registryPath = REGISTRY_PATH) {
  * pointing to a different path, auto-suffixes (`api` → `api-2`, `api-3`, …).
  * Re-registering the same path updates in place. Explicit names always overwrite.
  */
-export function registerRepo(rootDir, name, registryPath = REGISTRY_PATH) {
+export function registerRepo(
+  rootDir: string,
+  name?: string,
+  registryPath: string = REGISTRY_PATH,
+): { name: string; entry: RegistryEntry } {
   const absRoot = path.resolve(rootDir);
   const baseName = name || path.basename(absRoot);
   const registry = loadRegistry(registryPath);
@@ -59,7 +74,7 @@ export function registerRepo(rootDir, name, registryPath = REGISTRY_PATH) {
       // Basename collision with a different path — find next available suffix
       let suffix = 2;
       while (registry.repos[`${baseName}-${suffix}`]) {
-        const entry = registry.repos[`${baseName}-${suffix}`];
+        const entry = registry.repos[`${baseName}-${suffix}`]!;
         if (path.resolve(entry.path) === absRoot) {
           // Already registered under this suffixed name — update in place
           repoName = `${baseName}-${suffix}`;
@@ -83,13 +98,13 @@ export function registerRepo(rootDir, name, registryPath = REGISTRY_PATH) {
 
   saveRegistry(registry, registryPath);
   debug(`Registered repo "${repoName}" at ${absRoot}`);
-  return { name: repoName, entry: registry.repos[repoName] };
+  return { name: repoName, entry: registry.repos[repoName]! };
 }
 
 /**
  * Remove a repo from the registry. Returns false if not found.
  */
-export function unregisterRepo(name, registryPath = REGISTRY_PATH) {
+export function unregisterRepo(name: string, registryPath: string = REGISTRY_PATH): boolean {
   const registry = loadRegistry(registryPath);
   if (!registry.repos[name]) return false;
   delete registry.repos[name];
@@ -97,10 +112,18 @@ export function unregisterRepo(name, registryPath = REGISTRY_PATH) {
   return true;
 }
 
+export interface RepoListEntry {
+  name: string;
+  path: string;
+  dbPath: string;
+  addedAt: string;
+  lastAccessedAt: string;
+}
+
 /**
  * List all registered repos, sorted by name.
  */
-export function listRepos(registryPath = REGISTRY_PATH) {
+export function listRepos(registryPath: string = REGISTRY_PATH): RepoListEntry[] {
   const registry = loadRegistry(registryPath);
   return Object.entries(registry.repos)
     .map(([name, entry]) => ({
@@ -117,7 +140,10 @@ export function listRepos(registryPath = REGISTRY_PATH) {
  * Resolve a repo name to its database path.
  * Returns undefined if the repo is not found or its DB file is missing.
  */
-export function resolveRepoDbPath(name, registryPath = REGISTRY_PATH) {
+export function resolveRepoDbPath(
+  name: string,
+  registryPath: string = REGISTRY_PATH,
+): string | undefined {
   const registry = loadRegistry(registryPath);
   const entry = registry.repos[name];
   if (!entry) return undefined;
@@ -131,6 +157,12 @@ export function resolveRepoDbPath(name, registryPath = REGISTRY_PATH) {
   return entry.dbPath;
 }
 
+interface PrunedEntry {
+  name: string;
+  path: string;
+  reason: 'missing' | 'expired';
+}
+
 /**
  * Remove registry entries whose repo directory no longer exists on disk,
  * or that haven't been accessed within `ttlDays` days.
@@ -139,13 +171,13 @@ export function resolveRepoDbPath(name, registryPath = REGISTRY_PATH) {
  * When `dryRun` is true, entries are identified but not removed from disk.
  */
 export function pruneRegistry(
-  registryPath = REGISTRY_PATH,
-  ttlDays = DEFAULT_TTL_DAYS,
-  excludeNames = [],
+  registryPath: string = REGISTRY_PATH,
+  ttlDays: number = DEFAULT_TTL_DAYS,
+  excludeNames: string[] = [],
   dryRun = false,
-) {
+): PrunedEntry[] {
   const registry = loadRegistry(registryPath);
-  const pruned = [];
+  const pruned: PrunedEntry[] = [];
   const cutoff = Date.now() - ttlDays * 24 * 60 * 60 * 1000;
   const excludeSet = new Set(
     excludeNames.filter((n) => typeof n === 'string' && n.trim().length > 0),

package/src/infrastructure/{test-filter.js → test-filter.ts}

@@ -2,6 +2,6 @@
 export const TEST_PATTERN = /\.(test|spec)\.|__test__|__tests__|\.stories\./;
 
 /** Check whether a file path looks like a test file. */
-export function isTestFile(filePath) {
+export function isTestFile(filePath: string): boolean {
   return TEST_PATTERN.test(filePath);
 }

package/src/infrastructure/{update-check.js → update-check.ts}

@@ -3,19 +3,24 @@ import https from 'node:https';
 import os from 'node:os';
 import path from 'node:path';
 
-const CACHE_PATH =
-  process.env.CODEGRAPH_UPDATE_CACHE_PATH ||
+const CACHE_PATH: string =
+  process.env['CODEGRAPH_UPDATE_CACHE_PATH'] ||
   path.join(os.homedir(), '.codegraph', 'update-check.json');
 
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const FETCH_TIMEOUT_MS = 3000;
 const REGISTRY_URL = 'https://registry.npmjs.org/@optave/codegraph/latest';
 
+interface UpdateCache {
+  lastCheckedAt: number;
+  latestVersion: string;
+}
+
 /**
  * Minimal semver comparison. Returns -1, 0, or 1.
  * Only handles numeric x.y.z (no pre-release tags).
  */
-export function semverCompare(a, b) {
+export function semverCompare(a: string, b: string): -1 | 0 | 1 {
   const pa = a.split('.').map(Number);
   const pb = b.split('.').map(Number);
   for (let i = 0; i < 3; i++) {
@@ -31,14 +36,14 @@ export function semverCompare(a, b) {
  * Load the cached update-check result from disk.
  * Returns null on missing or corrupt file.
  */
-function loadCache(cachePath = CACHE_PATH) {
+function loadCache(cachePath: string = CACHE_PATH): UpdateCache | null {
   try {
     const raw = fs.readFileSync(cachePath, 'utf-8');
     const data = JSON.parse(raw);
     if (!data || typeof data.lastCheckedAt !== 'number' || typeof data.latestVersion !== 'string') {
       return null;
     }
-    return data;
+    return data as UpdateCache;
   } catch {
     return null;
   }
@@ -47,7 +52,7 @@ function loadCache(cachePath = CACHE_PATH) {
 /**
  * Persist the cache to disk (atomic write via temp + rename).
  */
-function saveCache(cache, cachePath = CACHE_PATH) {
+function saveCache(cache: UpdateCache, cachePath: string = CACHE_PATH): void {
   const dir = path.dirname(cachePath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 
@@ -60,7 +65,7 @@ function saveCache(cache, cachePath = CACHE_PATH) {
  * Fetch the latest version string from the npm registry.
  * Returns the version string or null on failure.
  */
-function fetchLatestVersion() {
+function fetchLatestVersion(): Promise<string | null> {
   return new Promise((resolve) => {
     const req = https.get(
       REGISTRY_URL,
@@ -73,7 +78,7 @@ function fetchLatestVersion() {
         }
         let body = '';
         res.setEncoding('utf-8');
-        res.on('data', (chunk) => {
+        res.on('data', (chunk: string) => {
           body += chunk;
         });
         res.on('end', () => {
@@ -94,20 +99,29 @@ function fetchLatestVersion() {
   });
 }
 
+interface UpdateResult {
+  current: string;
+  latest: string;
+}
+
+interface CheckForUpdatesOptions {
+  cachePath?: string;
+  _fetchLatest?: () => Promise<string | null>;
+}
+
 /**
  * Check whether a newer version of codegraph is available.
  *
  * Returns `{ current, latest }` if an update is available, `null` otherwise.
  * Silently returns null on any error — never affects CLI operation.
- *
- * Options:
- *   cachePath — override cache file location (for testing)
- *   _fetchLatest — override the fetch function (for testing)
  */
-export async function checkForUpdates(currentVersion, options = {}) {
+export async function checkForUpdates(
+  currentVersion: string,
+  options: CheckForUpdatesOptions = {},
+): Promise<UpdateResult | null> {
   // Suppress in non-interactive / CI contexts
-  if (process.env.CI) return null;
-  if (process.env.NO_UPDATE_CHECK) return null;
+  if (process.env['CI']) return null;
+  if (process.env['NO_UPDATE_CHECK']) return null;
   if (!process.stderr.isTTY) return null;
   if (currentVersion.includes('-')) return null;
 
@@ -144,7 +158,7 @@ export async function checkForUpdates(currentVersion, options = {}) {
 /**
  * Print a visible update notification box to stderr.
  */
-export function printUpdateNotification(current, latest) {
+export function printUpdateNotification(current: string, latest: string): void {
   const msg1 = `Update available: ${current} → ${latest}`;
   const msg2 = 'Run `npm i -g @optave/codegraph` to update';
   const width = Math.max(msg1.length, msg2.length) + 4;

package/src/mcp/{middleware.js → middleware.ts}

@@ -7,38 +7,32 @@ import { getMcpDefaults, MCP_DEFAULTS, MCP_MAX_LIMIT } from '../shared/paginate.
 export { MCP_DEFAULTS, MCP_MAX_LIMIT };
 
 /** Resolved MCP defaults (may include config overrides). Set via initMcpDefaults(). */
-let resolvedDefaults = MCP_DEFAULTS;
+let resolvedDefaults: Record<string, number> = 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);
+export function initMcpDefaults(configMcpDefaults?: Record<string, number>): void {
+  resolvedDefaults = getMcpDefaults(configMcpDefaults) as Record<string, number>;
 }
 
 /**
  * Reset MCP defaults back to the base defaults. Useful for test isolation.
  */
-export function resetMcpDefaults() {
+export function resetMcpDefaults(): void {
   resolvedDefaults = MCP_DEFAULTS;
 }
 
 /**
  * Resolve effective limit for a tool call.
- * @param {object} args - Tool arguments
- * @param {string} toolName - Tool name (for default lookup)
- * @returns {number}
  */
-export function effectiveLimit(args, toolName) {
+export function effectiveLimit(args: { limit?: number }, toolName: string): number {
   return Math.min(args.limit ?? resolvedDefaults[toolName] ?? 100, MCP_MAX_LIMIT);
 }
 
 /**
  * Resolve effective offset for a tool call.
- * @param {object} args - Tool arguments
- * @returns {number}
  */
-export function effectiveOffset(args) {
+export function effectiveOffset(args: { offset?: number }): number {
   return args.offset ?? 0;
 }

package/src/mcp/server.ts

@@ -0,0 +1,249 @@
+/**
+ * MCP (Model Context Protocol) server for codegraph.
+ * Exposes codegraph queries as tools that AI coding assistants can call.
+ *
+ * Requires: npm install @modelcontextprotocol/sdk
+ */
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require('../../package.json') as { version: string };
+
+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 type { CodegraphConfig, MCPServerOptions } from '../types.js';
+import { initMcpDefaults } from './middleware.js';
+import { buildToolList } from './tool-registry.js';
+import { TOOL_HANDLERS } from './tools/index.js';
+
+/**
+ * Module-level guard to register shutdown handlers only once per process.
+ * Because tests use vi.resetModules(), this module-level variable resets
+ * on each re-import — but the process-level flag on `process` persists.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: MCP SDK server type is lazy-loaded
+let _activeServer: any = null;
+
+export interface McpToolContext {
+  dbPath: string | undefined;
+  // biome-ignore lint/suspicious/noExplicitAny: lazy-loaded queries module
+  getQueries(): Promise<any>;
+  // biome-ignore lint/suspicious/noExplicitAny: lazy-loaded better-sqlite3 constructor
+  getDatabase(): any;
+  findDbPath: typeof findDbPath;
+  allowedRepos: string[] | undefined;
+  MCP_MAX_LIMIT: number;
+}
+
+interface MCPServerOptionsInternal extends MCPServerOptions {
+  config?: CodegraphConfig;
+}
+
+async function loadMCPSdk(): Promise<{
+  Server: unknown;
+  StdioServerTransport: unknown;
+  ListToolsRequestSchema: unknown;
+  CallToolRequestSchema: unknown;
+}> {
+  try {
+    const sdk = await import('@modelcontextprotocol/sdk/server/index.js');
+    const transport = await import('@modelcontextprotocol/sdk/server/stdio.js');
+    const types = await import('@modelcontextprotocol/sdk/types.js');
+    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',
+    );
+  }
+}
+
+function createLazyLoaders(): {
+  getQueries(): Promise<unknown>;
+  getDatabase(): unknown;
+} {
+  let _queries: unknown;
+  let _Database: unknown;
+  return {
+    async getQueries(): Promise<unknown> {
+      if (!_queries) _queries = await import('../domain/queries.js');
+      return _queries;
+    },
+    getDatabase(): unknown {
+      if (!_Database) {
+        const require = createRequire(import.meta.url);
+        _Database = require('better-sqlite3');
+      }
+      return _Database;
+    },
+  };
+}
+
+async function resolveDbPath(
+  customDbPath: string | undefined,
+  args: { repo?: string },
+  allowedRepos?: string[],
+): Promise<string | undefined> {
+  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;
+  }
+  return dbPath;
+}
+
+function validateMultiRepoAccess(multiRepo: boolean, name: string, args: { repo?: string }): void {
+  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?: string,
+  options: MCPServerOptionsInternal = {},
+): Promise<void> {
+  const { allowedRepos } = options;
+  const multiRepo = options.multiRepo || !!allowedRepos;
+
+  // Apply config-based MCP page-size overrides
+  const config = options.config || loadConfig();
+  initMcpDefaults(config.mcp?.defaults ? { ...config.mcp.defaults } : undefined);
+
+  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();
+
+  // biome-ignore lint/suspicious/noExplicitAny: MCP SDK types are lazy-loaded and untyped
+  const server = new (Server as any)(
+    { name: 'codegraph', version: PKG_VERSION },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: buildToolList(multiRepo),
+  }));
+
+  // biome-ignore lint/suspicious/noExplicitAny: MCP SDK request type is dynamic
+  server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
+    const { name, arguments: args } = request.params;
+    try {
+      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: McpToolContext = {
+        dbPath: dbPath,
+        getQueries,
+        getDatabase,
+        findDbPath,
+        allowedRepos,
+        MCP_MAX_LIMIT,
+      };
+      const result: unknown = await toolEntry.handler(args, ctx);
+      if (result && typeof result === 'object' && 'content' in result) {
+        return result as { content: Array<{ type: string; text: string }> };
+      }
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    } catch (err: unknown) {
+      const code = err instanceof CodegraphError ? err.code : 'UNKNOWN_ERROR';
+      const text =
+        err instanceof CodegraphError
+          ? `[${code}] ${err.message}`
+          : `Error: ${(err as Error).message}`;
+      return { content: [{ type: 'text', text }], isError: true };
+    }
+  });
+
+  // biome-ignore lint/suspicious/noExplicitAny: MCP SDK types are lazy-loaded and untyped
+  const transport = new (StdioServerTransport as any)();
+
+  // Graceful shutdown — when the client disconnects (e.g. session clear),
+  // close the server cleanly so the process exits without error.
+  // Track the active server at module level so handlers always reference
+  // the latest instance (matters when tests call startMCPServer repeatedly).
+  _activeServer = server;
+
+  // Register handlers once per process to avoid listener accumulation.
+  // Use a process-level flag so it survives vi.resetModules() in tests.
+  const g = globalThis as Record<string, unknown>;
+  // biome-ignore lint/complexity/useLiteralKeys: bracket notation required by TS noPropertyAccessFromIndexSignature
+  if (!g['__codegraph_shutdown_installed']) {
+    // biome-ignore lint/complexity/useLiteralKeys: bracket notation required by TS noPropertyAccessFromIndexSignature
+    g['__codegraph_shutdown_installed'] = true;
+
+    const shutdown = async () => {
+      try {
+        await _activeServer?.close();
+      } catch {}
+      process.exit(0);
+    };
+    const silentExit = (err: Error & { code?: string }) => {
+      // Only suppress broken-pipe errors from closed stdio transport;
+      // let real bugs surface with a non-zero exit code.
+      if (err.code === 'EPIPE' || err.code === 'ERR_STREAM_DESTROYED') {
+        process.exit(0);
+      }
+      process.stderr.write(`Uncaught exception: ${err.stack ?? err.message}\n`);
+      process.exit(1);
+    };
+    const silentReject = (reason: unknown) => {
+      const err = reason instanceof Error ? reason : new Error(String(reason));
+      const code = (err as Error & { code?: string }).code;
+      if (code === 'EPIPE' || code === 'ERR_STREAM_DESTROYED') {
+        process.exit(0);
+      }
+      process.stderr.write(`Unhandled rejection: ${err.stack ?? err.message}\n`);
+      process.exit(1);
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    process.on('SIGHUP', shutdown);
+    process.on('uncaughtException', silentExit);
+    process.on('unhandledRejection', silentReject);
+  }
+
+  try {
+    await server.connect(transport);
+  } catch (err) {
+    const code = (err as Error & { code?: string }).code;
+    if (code === 'EPIPE' || code === 'ERR_STREAM_DESTROYED') {
+      process.exit(0);
+    }
+    process.stderr.write(
+      `MCP transport connect failed: ${(err as Error).stack ?? (err as Error).message}\n`,
+    );
+    process.exit(1);
+  }
+}

package/src/mcp/{tool-registry.js → tool-registry.ts}

@@ -7,19 +7,29 @@
 import { EVERY_EDGE_KIND, EVERY_SYMBOL_KIND, VALID_ROLES } from '../domain/queries.js';
 import { AST_NODE_KINDS } from '../features/ast.js';
 
-const REPO_PROP = {
+interface ToolSchema {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+const REPO_PROP: Record<string, unknown> = {
   repo: {
     type: 'string',
     description: 'Repository name from the registry (omit for local project)',
   },
 };
 
-const PAGINATION_PROPS = {
+const PAGINATION_PROPS: Record<string, unknown> = {
   limit: { type: 'number', description: 'Max results to return (pagination)' },
   offset: { type: 'number', description: 'Skip this many results (pagination, default: 0)' },
 };
 
-const BASE_TOOLS = [
+const BASE_TOOLS: ToolSchema[] = [
   {
     name: 'query',
     description:
@@ -139,7 +149,6 @@ 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'],
     },
@@ -821,7 +830,7 @@ const BASE_TOOLS = [
   },
 ];
 
-const LIST_REPOS_TOOL = {
+const LIST_REPOS_TOOL: ToolSchema = {
   name: 'list_repos',
   description: 'List all repositories registered in the codegraph registry',
   inputSchema: {
@@ -832,10 +841,8 @@ const LIST_REPOS_TOOL = {
 
 /**
  * Build the tool list based on multi-repo mode.
- * @param {boolean} multiRepo - If true, inject `repo` prop into each tool and append `list_repos`
- * @returns {object[]}
  */
-export function buildToolList(multiRepo) {
+export function buildToolList(multiRepo: boolean): ToolSchema[] {
   if (!multiRepo) return BASE_TOOLS;
   return [
     ...BASE_TOOLS.map((tool) => ({
@@ -850,4 +857,4 @@ export function buildToolList(multiRepo) {
 }
 
 // Backward-compatible export: full multi-repo tool list
-export const TOOLS = buildToolList(true);
+export const TOOLS: ToolSchema[] = buildToolList(true);

package/src/mcp/tools/{ast-query.js → ast-query.ts}

@@ -1,8 +1,19 @@
+import type { ASTNodeKind } from '../../types.js';
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'ast_query';
 
-export async function handler(args, ctx) {
+interface AstQueryArgs {
+  pattern?: string;
+  kind?: ASTNodeKind;
+  file?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: AstQueryArgs, ctx: McpToolContext): Promise<unknown> {
   const { astQueryData } = await import('../../features/ast.js');
   return astQueryData(args.pattern, ctx.dbPath, {
     kind: args.kind,

package/src/mcp/tools/{audit.js → audit.ts}

@@ -1,13 +1,25 @@
 import { effectiveOffset, MCP_DEFAULTS, MCP_MAX_LIMIT } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'audit';
 
-export async function handler(args, ctx) {
+interface AuditArgs {
+  target: string;
+  quick?: boolean;
+  depth?: number;
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: AuditArgs, ctx: McpToolContext): Promise<unknown> {
   if (args.quick) {
     const { explainData } = await ctx.getQueries();
     return explainData(args.target, ctx.dbPath, {
       noTests: args.no_tests,
-      limit: Math.min(args.limit ?? MCP_DEFAULTS.explain, MCP_MAX_LIMIT),
+      limit: Math.min(args.limit ?? MCP_DEFAULTS['explain'] ?? 100, MCP_MAX_LIMIT),
       offset: effectiveOffset(args),
     });
   }