code-auditor-mcp 2.6.2 → 3.0.0

package/dist/mcp.js

@@ -1,649 +1,103 @@
 #!/usr/bin/env node
-// MCP servers use stdio: stdout for protocol messages, stderr for logging
-// All log messages must go to stderr to avoid interfering with MCP protocol
+// MUST be first import: sets NAPI_RS_NATIVE_LIBRARY_PATH before @ast-grep/napi loads
+import './native-bootstrap.js';
+// ── Bootstrap: parse --data-dir before any module loads CodeIndexDB ──────────
+import path from 'node:path';
+let autoIndexPath;
+let uiMode = false;
+let stdioMode = false;
+let showHelp = false;
+const argv = process.argv.slice(2);
+for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--data-dir' || a === '--dataDir') {
+        const val = argv[i + 1];
+        if (val && !val.startsWith('-')) {
+            process.env.CODE_AUDITOR_DATA_DIR = path.resolve(val);
+        }
+        else {
+            console.error('[code-auditor] --data-dir requires a directory path (next argv). Using CODE_AUDITOR_DATA_DIR env or default.');
+        }
+    }
+    else if (a === '--auto-index') {
+        const val = argv[i + 1];
+        if (val && !val.startsWith('-')) {
+            autoIndexPath = path.resolve(val);
+        }
+        else {
+            autoIndexPath = process.cwd();
+        }
+    }
+    else if (a === '--ui') {
+        uiMode = true;
+    }
+    else if (a === '--stdio') {
+        stdioMode = true;
+    }
+    else if (a === '--help' || a === '-h') {
+        showHelp = true;
+    }
+}
+if (showHelp) {
+    console.error(`code-auditor-mcp v0.0.0
+Usage: code-auditor-mcp [--stdio] [--ui] [--auto-index <path>] [--data-dir <dir>]
+
+  --stdio        Start MCP stdio server (default mode)
+  --ui           Start the HTTP UI server on port 3001 (or MCP_UI_PORT)
+  --auto-index   Sync the index from <path> and exit
+  --data-dir     Directory for persistent data (index.db, tasks, configs)
+  --help, -h     Show this message
+`);
+    process.exit(0);
+}
+// ── Imports ──────────────────────────────────────────────────────────────────
 import chalk from 'chalk';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, InitializeRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, InitializeRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { createWriteStream } from 'node:fs';
+import fs from 'node:fs/promises';
 import { createAuditRunner } from './auditRunner.js';
 import { searchFunctions, findDefinition, syncFileIndex, getDatabase } from './codeIndexService.js';
 import { CodeMapGenerator } from './services/CodeMapGenerator.js';
 import { analyzeDocumentation } from './analyzers/documentationAnalyzer.js';
 import { ConfigGeneratorFactory } from './generators/ConfigGeneratorFactory.js';
 import { DEFAULT_SERVER_URL, IS_DEV_MODE, PACKAGE_VERSION } from './constants.js';
-import { getAuditJobStatus, getAuditResultsPage, startAuditJob } from './mcpAuditJobs.js';
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { createWriteStream } from 'node:fs';
+import { getAuditJobStatus, getAuditResultsPage, getAuditResultsAsSarif, startAuditJob } from './mcpAuditJobs.js';
 import { CodeIndexDB } from './codeIndexDB.js';
 import { logMcpDebug, logMcpInfo, mcpDebugStderr, mcpTraceStderr } from './mcpDiagnostics.js';
 import { assertAuditPathExists, formatMcpToolErrorPayload } from './mcpToolErrors.js';
-// Set up file logging (only in development mode)
+import { ToolRegistry } from './tool-registry.js';
+import { initParsers } from './languages/index.js';
+// ── Console / logging setup ──────────────────────────────────────────────────
+const originalConsoleError = console.error;
 let logStream = null;
 if (IS_DEV_MODE) {
     const logFilePath = path.join(process.cwd(), 'mcp-server.log');
     logStream = createWriteStream(logFilePath, { flags: 'a' });
     console.error(chalk.blue('[INFO]'), `Development mode: Logging to file: ${logFilePath}`);
 }
-// Save original console.error (log is redirected to stderr; see below)
-const originalConsoleError = console.error;
-// Override console.log — MCP uses stdout only for JSON-RPC; log() must never touch stdout.
 console.log = (...args) => {
     if (logStream) {
-        const message = args.map(arg => typeof arg === 'object' ? JSON.stringify(arg) : String(arg)).join(' ');
+        const message = args
+            .map((arg) => (typeof arg === 'object' ? JSON.stringify(arg) : String(arg)))
+            .join(' ');
         const timestamp = new Date().toISOString();
         logStream.write(`[${timestamp}] [LOG] ${message}\n`);
     }
     originalConsoleError.apply(console, args);
 };
-// Override console.error (with conditional file logging)
 console.error = (...args) => {
     if (logStream) {
-        const message = args.map(arg => typeof arg === 'object' ? JSON.stringify(arg) : String(arg)).join(' ');
+        const message = args
+            .map((arg) => (typeof arg === 'object' ? JSON.stringify(arg) : String(arg)))
+            .join(' ');
         const timestamp = new Date().toISOString();
         logStream.write(`[${timestamp}] [ERROR] ${message}\n`);
     }
     originalConsoleError.apply(console, args);
 };
-const tools = [
-    // Core Audit Tools
-    {
-        name: 'audit',
-        description: 'Fetch paginated results for a completed audit by resultId (or auditId alias). This tool never starts a new audit.',
-        parameters: [
-            {
-                name: 'limit',
-                type: 'number',
-                required: false,
-                description: 'Maximum number of violations to return per page (default: 50, max: 100)',
-                default: 50,
-            },
-            {
-                name: 'offset',
-                type: 'number',
-                required: false,
-                description: 'Violation offset for pagination (default: 0).',
-                default: 0,
-            },
-            {
-                name: 'resultId',
-                type: 'string',
-                required: false,
-                description: 'Result ID returned by audit_status when the background audit job completes.',
-            },
-            {
-                name: 'auditId',
-                type: 'string',
-                required: false,
-                description: 'Backward-compatible alias for resultId.',
-            },
-        ],
-    },
-    {
-        name: 'start_audit',
-        description: 'Start a background audit job. Returns immediately with a jobId. Poll audit_status until completed, then fetch pages with audit or audit_results.',
-        parameters: [
-            {
-                name: 'path',
-                type: 'string',
-                required: false,
-                description: 'File or directory path to audit (defaults to current directory).',
-                default: process.cwd(),
-            },
-            {
-                name: 'analyzers',
-                type: 'array',
-                required: false,
-                description: 'Analyzers to run (default: solid, dry, documentation, react, data-access).',
-                default: ['solid', 'dry', 'documentation', 'react', 'data-access'],
-            },
-            {
-                name: 'minSeverity',
-                type: 'string',
-                required: false,
-                description: 'Minimum severity level to report.',
-                default: 'warning',
-                enum: ['info', 'warning', 'critical'],
-            },
-            {
-                name: 'indexFunctions',
-                type: 'boolean',
-                required: false,
-                description: 'Index functions during audit (default: true).',
-                default: true,
-            },
-            {
-                name: 'analyzerConfigs',
-                type: 'object',
-                required: false,
-                description: 'Analyzer-specific configuration overrides.',
-            },
-            {
-                name: 'analyzerConcurrency',
-                type: 'number',
-                required: false,
-                description: 'Max analyzers to run in parallel (default: 1).',
-                default: 1,
-            },
-            {
-                name: 'partitionStrategy',
-                type: 'string',
-                required: false,
-                description: 'Partition mode: none | auto | top-level. auto shards when large source trees are detected.',
-                default: 'auto',
-                enum: ['none', 'auto', 'top-level'],
-            },
-            {
-                name: 'maxPartitions',
-                type: 'number',
-                required: false,
-                description: 'Maximum number of folder partitions for sharded audits (default: 4).',
-                default: 4,
-            },
-            {
-                name: 'partitionThresholdFiles',
-                type: 'number',
-                required: false,
-                description: 'Minimum discovered files before auto partitioning is enabled (default: 250).',
-                default: 250,
-            },
-            {
-                name: 'workerCount',
-                type: 'number',
-                required: false,
-                description: 'Number of worker processes for shard execution (default: min(4, CPU-1)).',
-            },
-            {
-                name: 'maxRetries',
-                type: 'number',
-                required: false,
-                description: 'Retry attempts per shard for retryable failures (default: 1).',
-                default: 1,
-            },
-            {
-                name: 'shardTimeoutMs',
-                type: 'number',
-                required: false,
-                description: 'Per-shard timeout in milliseconds (default: 180000).',
-                default: 180000,
-            },
-            {
-                name: 'retryBackoffMs',
-                type: 'number',
-                required: false,
-                description: 'Base retry backoff in milliseconds (default: 500).',
-                default: 500,
-            },
-            {
-                name: 'jobTimeoutMs',
-                type: 'number',
-                required: false,
-                description: 'Maximum wall time for the entire audit job (default 30m, env CODE_AUDITOR_JOB_TIMEOUT_MS, cap 4h). Aborts workers cooperatively then tears down.',
-            },
-            {
-                name: 'maxFilesPerRun',
-                type: 'number',
-                required: false,
-                description: 'Per worker chunk: if more files match than this, the worker finishes one chunk and the parent queues the rest on another worker (optional).',
-            },
-            {
-                name: 'shardSoftBudgetMs',
-                type: 'number',
-                required: false,
-                description: 'Per worker soft wall-clock budget; aborts in-process analysis cooperatively via AbortSignal so the parent can assign the next chunk to a fresh worker.',
-            },
-            {
-                name: 'generateCodeMap',
-                type: 'boolean',
-                required: false,
-                description: 'Generate code map artifacts during audit (default: false).',
-                default: false,
-            },
-        ],
-    },
-    {
-        name: 'audit_status',
-        description: 'Get current status for a previously started background audit job. Returns resultId when completed.',
-        parameters: [
-            {
-                name: 'jobId',
-                type: 'string',
-                required: true,
-                description: 'Job ID returned by start_audit.',
-            },
-        ],
-    },
-    {
-        name: 'audit_results',
-        description: 'Fetch paginated violations for a completed audit result by resultId.',
-        parameters: [
-            {
-                name: 'resultId',
-                type: 'string',
-                required: true,
-                description: 'Result ID returned by audit_status when status is completed.',
-            },
-            {
-                name: 'limit',
-                type: 'number',
-                required: false,
-                description: 'Maximum number of violations to return per page (default: 50, max: 100).',
-                default: 50,
-            },
-            {
-                name: 'offset',
-                type: 'number',
-                required: false,
-                description: 'Violation offset for pagination (default: 0).',
-                default: 0,
-            },
-        ],
-    },
-    {
-        name: 'audit_health',
-        description: 'Quick health check of a codebase with key metrics',
-        parameters: [
-            {
-                name: 'path',
-                type: 'string',
-                required: false,
-                description: 'The directory path to check',
-                default: process.cwd(),
-            },
-            {
-                name: 'threshold',
-                type: 'number',
-                required: false,
-                description: 'Health score threshold (0-100) for pass/fail',
-                default: 70,
-            },
-            {
-                name: 'indexFunctions',
-                type: 'boolean',
-                required: false,
-                description: 'Automatically index functions during health check',
-                default: true,
-            },
-            {
-                name: 'analyzerConfigs',
-                type: 'object',
-                required: false,
-                description: 'Analyzer-specific configuration overrides (e.g., SOLID thresholds, DRY settings)',
-            },
-            {
-                name: 'generateCodeMap',
-                type: 'boolean',
-                required: false,
-                description: 'Generate and return a human-readable code map as part of the health check results',
-                default: true,
-            },
-        ],
-    },
-    // Code Index Tools
-    {
-        name: 'search_code',
-        description: 'Search indexed functions and React components with natural language queries. Supports operators: entity:component, component:functional|class|memo|forwardRef, hook:useState|useEffect|etc, prop:propName, dep:packageName, dependency:lodash, uses:express, calls:functionName, calledby:functionName, dependents-of:functionName, used-by:functionName, depends-on:module, imports-from:file, unused-imports, dead-imports, type:fileType, file:path, lang:language, complexity:1-10, jsdoc:true|false',
-        parameters: [
-            {
-                name: 'query',
-                type: 'string',
-                required: true,
-                description: 'Search query with natural language and/or operators. Examples: "Button component:functional", "entity:component hook:useState", "render prop:onClick", "dep:lodash", "calls:validateUser", "unused-imports", "dependents-of:authenticate"',
-            },
-            {
-                name: 'filters',
-                type: 'object',
-                required: false,
-                description: 'Optional filters (language, filePath, dependencies, componentType, entityType, searchMode). Set searchMode to "content" to search within function bodies, "metadata" for names/signatures only, or "both" for combined search',
-            },
-            {
-                name: 'limit',
-                type: 'number',
-                required: false,
-                description: 'Maximum results to return',
-                default: 50,
-            },
-            {
-                name: 'offset',
-                type: 'number',
-                required: false,
-                description: 'Offset for pagination',
-                default: 0,
-            },
-        ],
-    },
-    {
-        name: 'find_definition',
-        description: 'Find the exact definition of a specific function or React component',
-        parameters: [
-            {
-                name: 'name',
-                type: 'string',
-                required: true,
-                description: 'Function or component name to find',
-            },
-            {
-                name: 'filePath',
-                type: 'string',
-                required: false,
-                description: 'Optional file path to narrow search',
-            },
-        ],
-    },
-    {
-        name: 'sync_index',
-        description: 'Synchronize, cleanup, or reset analysis-derived data (indexed functions, FlexSearch, cached audits, code maps, schema overlays). Project tasks, analyzer configs, and whitelist entries are preserved on reset.',
-        parameters: [
-            {
-                name: 'mode',
-                type: 'string',
-                required: false,
-                description: 'sync: update index from files; cleanup: remove index rows for deleted files; reset: clear all analysis-derived data (not tasks/config/whitelist)',
-                default: 'sync',
-                enum: ['sync', 'cleanup', 'reset'],
-            },
-            {
-                name: 'path',
-                type: 'string',
-                required: false,
-                description: 'Optional specific path to sync',
-            },
-        ],
-    },
-    // AI Configuration Tool
-    {
-        name: 'generate_ai_config',
-        description: 'Generate configuration files for AI coding assistants',
-        parameters: [
-            {
-                name: 'tools',
-                type: 'array',
-                required: true,
-                description: 'AI tools to configure (cursor, continue, copilot, claude, zed, windsurf, cody, aider, cline, pearai)',
-            },
-            {
-                name: 'outputDir',
-                type: 'string',
-                required: false,
-                description: 'Output directory for configuration files',
-                default: '.',
-            },
-        ],
-    },
-    // Workflow Guide Tool
-    {
-        name: 'get_workflow_guide',
-        description: 'Get recommended workflows and best practices for using code auditor tools effectively',
-        parameters: [
-            {
-                name: 'scenario',
-                type: 'string',
-                required: false,
-                description: 'Specific scenario: initial-setup, react-development, code-review, find-patterns, maintenance. Leave empty to see all.',
-            },
-        ],
-    },
-    // Analyzer Configuration Tools
-    {
-        name: 'set_analyzer_config',
-        description: 'Set or update analyzer configuration that persists across audit runs',
-        parameters: [
-            {
-                name: 'analyzerName',
-                type: 'string',
-                required: true,
-                description: 'The analyzer to configure (solid, dry, security, etc.)',
-            },
-            {
-                name: 'config',
-                type: 'object',
-                required: true,
-                description: 'Configuration object for the analyzer (e.g., thresholds, rules)',
-            },
-            {
-                name: 'projectPath',
-                type: 'string',
-                required: false,
-                description: 'Optional project path for project-specific config (defaults to global)',
-            },
-        ],
-    },
-    {
-        name: 'get_analyzer_config',
-        description: 'Get current configuration for an analyzer',
-        parameters: [
-            {
-                name: 'analyzerName',
-                type: 'string',
-                required: false,
-                description: 'Specific analyzer name, or omit to get all configs',
-            },
-            {
-                name: 'projectPath',
-                type: 'string',
-                required: false,
-                description: 'Optional project path to get project-specific config',
-            },
-        ],
-    },
-    {
-        name: 'reset_analyzer_config',
-        description: 'Reset analyzer configuration to defaults',
-        parameters: [
-            {
-                name: 'analyzerName',
-                type: 'string',
-                required: false,
-                description: 'Specific analyzer to reset, or omit to reset all',
-            },
-            {
-                name: 'projectPath',
-                type: 'string',
-                required: false,
-                description: 'Optional project path to reset only project-specific config',
-            },
-        ],
-    },
-    {
-        name: 'get_code_map_section',
-        description: 'Retrieve a specific section of a previously generated code map',
-        parameters: [
-            {
-                name: 'mapId',
-                type: 'string',
-                required: true,
-                description: 'The map ID returned from a previous audit with code map generation',
-            },
-            {
-                name: 'sectionType',
-                type: 'string',
-                required: true,
-                description: 'The section type to retrieve (e.g., overview, files, dependencies, documentation)',
-            },
-        ],
-    },
-    {
-        name: 'list_code_map_sections',
-        description: 'List all available sections for a code map',
-        parameters: [
-            {
-                name: 'mapId',
-                type: 'string',
-                required: true,
-                description: 'The map ID returned from a previous audit',
-            },
-        ],
-    },
-    {
-        name: 'project_tasks',
-        description: 'Manage a persistent per-project task queue. Tasks and analyzer configs survive sync_index reset; reset clears function index, cached audits, code maps, and schema overlays (no ghost code references). Use delete to remove a task.',
-        parameters: [
-            {
-                name: 'action',
-                type: 'string',
-                required: true,
-                description: 'list | list_tree | create | get | update | complete_task | delete. list/list_tree/create use projectPath or default to process.cwd(); create needs title; get/update/complete_task/delete need taskId; update needs patch object.',
-                enum: [
-                    'list',
-                    'list_tree',
-                    'create',
-                    'get',
-                    'update',
-                    'complete_task',
-                    'delete'
-                ],
-            },
-            {
-                name: 'projectPath',
-                type: 'string',
-                required: false,
-                description: 'Project root (resolved). Omit to use the MCP server working directory (same default idea as audit path); response includes projectPathDefaulted when omitted.',
-            },
-            {
-                name: 'taskId',
-                type: 'string',
-                required: false,
-                description: 'Stable task id (UUID). Required for get, update, complete_task, delete.',
-            },
-            {
-                name: 'title',
-                type: 'string',
-                required: false,
-                description: 'Task title. Required for create.',
-            },
-            {
-                name: 'description',
-                type: 'string',
-                required: false,
-                description: 'Longer description / notes.',
-            },
-            {
-                name: 'status',
-                type: 'string',
-                required: false,
-                description: 'pending | in_progress | blocked | done | cancelled. Filter for list; initial status for create; can be set via update patch.',
-                enum: ['pending', 'in_progress', 'blocked', 'done', 'cancelled'],
-            },
-            {
-                name: 'priority',
-                type: 'string',
-                required: false,
-                description: 'Optional priority for create/update patch.',
-                enum: ['low', 'medium', 'high'],
-            },
-            {
-                name: 'labels',
-                type: 'array',
-                required: false,
-                description: 'String tags (e.g. ["audit","refactor"]).',
-            },
-            {
-                name: 'metadata',
-                type: 'object',
-                required: false,
-                description: 'Arbitrary JSON object: related file paths, links, audit IDs, etc.',
-            },
-            {
-                name: 'parentTaskId',
-                type: 'string',
-                required: false,
-                description: 'Optional parent task for subtasks.',
-            },
-            {
-                name: 'source',
-                type: 'string',
-                required: false,
-                description: 'manual | audit | mcp. Filter for list; provenance for create; can be set via update patch.',
-                enum: ['manual', 'audit', 'mcp'],
-            },
-            {
-                name: 'blockedBy',
-                type: 'array',
-                required: false,
-                description: 'Task IDs this item is blocked by (waiting-on).',
-            },
-            {
-                name: 'label',
-                type: 'string',
-                required: false,
-                description: 'Filter/search by label value.',
-            },
-            {
-                name: 'blockedByTaskId',
-                type: 'string',
-                required: false,
-                description: 'Filter tasks blocked by this task ID.',
-            },
-            {
-                name: 'query',
-                type: 'string',
-                required: false,
-                description: 'Case-insensitive text search across title/description/labels/files/symbols.',
-            },
-            {
-                name: 'hasChildren',
-                type: 'boolean',
-                required: false,
-                description: 'Filter tasks that do/do not have direct subtasks.',
-            },
-            {
-                name: 'overdueOnly',
-                type: 'boolean',
-                required: false,
-                description: 'Filter tasks with dueAt in the past and not closed.',
-            },
-            {
-                name: 'actionableOnly',
-                type: 'boolean',
-                required: false,
-                description: 'Filter tasks that are open and unblocked by open dependencies.',
-            },
-            {
-                name: 'dueAt',
-                type: 'string',
-                required: false,
-                description: 'ISO 8601 due datetime for create; omit or null in patch to clear.',
-            },
-            {
-                name: 'sortOrder',
-                type: 'number',
-                required: false,
-                description: 'Lower numbers sort first within a project (default 0).',
-            },
-            {
-                name: 'relatedFiles',
-                type: 'array',
-                required: false,
-                description: 'Repo-relative or absolute file paths tied to the task.',
-            },
-            {
-                name: 'relatedSymbols',
-                type: 'array',
-                required: false,
-                description: 'Function, class, or component names for cross-linking.',
-            },
-            {
-                name: 'patch',
-                type: 'object',
-                required: false,
-                description: 'For update: partial fields (title, description, status, priority, labels, metadata, parentTaskId, source, blockedBy, dueAt, sortOrder, relatedFiles, relatedSymbols).',
-            },
-            {
-                name: 'limit',
-                type: 'number',
-                required: false,
-                description: 'Max tasks to return for list (default 500, max 1000).',
-            },
-            {
-                name: 'mode',
-                type: 'string',
-                required: false,
-                description: 'Delete mode: reject (default), detach subtasks, or cascade descendants.',
-                enum: ['reject', 'detach', 'cascade'],
-            },
-        ],
-    },
-];
+// ── Helpers ──────────────────────────────────────────────────────────────────
 class RequestAbortedError extends Error {
     constructor(message = 'MCP request aborted') {
         super(message);
@@ -651,25 +105,21 @@ class RequestAbortedError extends Error {
     }
 }
 function throwIfRequestAborted(signal, phase) {
-    if (!signal?.aborted) {
-        return;
+    if (signal?.aborted) {
+        throw new RequestAbortedError(`Request aborted${phase ? ` during ${phase}` : ''}`);
     }
-    throw new RequestAbortedError(`Request aborted${phase ? ` during ${phase}` : ''}`);
 }
 async function withAbortSignal(signal, phase, op) {
     throwIfRequestAborted(signal, phase);
-    if (!signal) {
+    if (!signal)
         return op();
-    }
-    return await new Promise((resolve, reject) => {
+    return new Promise((resolve, reject) => {
         const onAbort = () => reject(new RequestAbortedError(`Request aborted during ${phase}`));
         signal.addEventListener('abort', onAbort, { once: true });
         void op()
             .then(resolve)
             .catch(reject)
-            .finally(() => {
-            signal.removeEventListener('abort', onAbort);
-        });
+            .finally(() => signal.removeEventListener('abort', onAbort));
     });
 }
 function serializeForMcp(value) {
@@ -679,7 +129,7 @@ function serializeForMcp(value) {
     catch (error) {
         return JSON.stringify({
             success: false,
-            error: `Failed to serialize MCP response: ${error instanceof Error ? error.message : String(error)}`
+            error: `Failed to serialize MCP response: ${error instanceof Error ? error.message : String(error)}`,
         });
     }
 }
@@ -691,6 +141,26 @@ function safeJson(value) {
         return `[unserializable: ${error instanceof Error ? error.message : String(error)}]`;
     }
 }
+function calculateHealthScore(result) {
+    const filesAnalyzed = result.metadata?.filesAnalyzed || 1;
+    const critical = result.summary.criticalIssues || 0;
+    const warnings = result.summary.warnings || 0;
+    const suggestions = result.summary.suggestions || 0;
+    const weights = { critical: 10, warning: 3, suggestion: 0.5 };
+    const weightedViolations = critical * weights.critical + warnings * weights.warning + suggestions * weights.suggestion;
+    const violationsPerFile = weightedViolations / filesAnalyzed;
+    const score = 100 - violationsPerFile * 2;
+    return Math.max(0, Math.round(Math.min(100, score)));
+}
+function getHealthRecommendation(score, result) {
+    if (score >= 90)
+        return 'Excellent code health!';
+    if (score >= 70)
+        return 'Good code health with room for improvement';
+    if (result.summary.criticalIssues > 0)
+        return `Fix ${result.summary.criticalIssues} critical violations first`;
+    return 'Code health needs attention - run detailed audit';
+}
 function registerProcessReliabilityHandlers() {
     const g = globalThis;
     const exitOnFatal = process.env.CODE_AUDITOR_EXIT_ON_FATAL === '1' ||
@@ -700,9 +170,8 @@ function registerProcessReliabilityHandlers() {
             console.error(chalk.red('[ERROR]'), 'Uncaught exception:', error);
             console.error(chalk.red('[ERROR]'), 'Stack:', error.stack);
             console.error(chalk.red('[ERROR]'), 'Error details:', safeJson(error));
-            if (exitOnFatal) {
+            if (exitOnFatal)
                 process.exit(1);
-            }
         });
         g.__codeAuditorUncaughtExceptionHandlerInstalled = true;
     }
@@ -711,285 +180,826 @@ function registerProcessReliabilityHandlers() {
             console.error(chalk.red('[ERROR]'), 'Unhandled rejection at:', promise);
             console.error(chalk.red('[ERROR]'), 'Reason:', reason);
             console.error(chalk.red('[ERROR]'), 'Rejection details:', safeJson(reason));
-            if (exitOnFatal) {
+            if (exitOnFatal)
                 process.exit(1);
-            }
         });
         g.__codeAuditorUnhandledRejectionHandlerInstalled = true;
     }
 }
-async function startMcpServer() {
-    logMcpInfo('startup', `code-auditor-mcp ${PACKAGE_VERSION} (stdio)`, {
-        pid: process.pid,
-        cwd: process.cwd(),
-        dataDir: process.env.CODE_AUDITOR_DATA_DIR ?? '(default)',
-        debug: process.env.CODE_AUDITOR_DEBUG ?? '0',
-        logFile: process.env.CODE_AUDITOR_LOG_FILE ?? '(none)'
-    });
-    mcpDebugStderr(chalk.blue('[DEBUG]'), `Node ${process.version} · cwd ${process.cwd()}`);
-    const server = new Server({
-        name: 'code-auditor',
-        version: PACKAGE_VERSION,
-    }, {
-        capabilities: {
-            tools: {},
-        },
-    });
-    // Add error handler
-    server.onerror = (error) => {
-        console.error(chalk.red('[ERROR]'), 'Server error occurred:', error);
-        console.error(chalk.red('[ERROR]'), 'Error stack:', error.stack);
-    };
-    server.setRequestHandler(ListToolsRequestSchema, async (request) => {
-        mcpTraceStderr(chalk.blue('[DEBUG]'), 'ListTools', JSON.stringify(request, null, 2));
-        const response = {
-            tools: tools.map(tool => ({
-                name: tool.name,
-                description: tool.description,
-                inputSchema: {
+// ── Tool registration ────────────────────────────────────────────────────────
+const DEFAULT_ANALYZERS = ['solid', 'dry', 'documentation', 'react', 'data-access'];
+function registerAllTools(registry) {
+    // ── audit ──────────────────────────────────────────────────────────────────
+    const auditActions = [
+        {
+            name: 'run',
+            description: 'Run a synchronous audit on the specified path. Returns a full audit result with violations.',
+            parameters: [
+                {
+                    name: 'path',
+                    type: 'string',
+                    required: false,
+                    description: 'File or directory path to audit (defaults to current directory).',
+                    default: process.cwd(),
+                },
+                {
+                    name: 'analyzers',
+                    type: 'array',
+                    required: false,
+                    description: `Analyzers to run (default: ${DEFAULT_ANALYZERS.join(', ')}).`,
+                    default: DEFAULT_ANALYZERS,
+                },
+                {
+                    name: 'minSeverity',
+                    type: 'string',
+                    required: false,
+                    description: 'Minimum severity level to report.',
+                    default: 'warning',
+                    enum: ['info', 'warning', 'critical'],
+                },
+                {
+                    name: 'indexFunctions',
+                    type: 'boolean',
+                    required: false,
+                    description: 'Index functions during audit (default: true).',
+                    default: true,
+                },
+                {
+                    name: 'analyzerConfigs',
                     type: 'object',
-                    properties: tool.parameters.reduce((acc, param) => {
-                        acc[param.name] = {
-                            type: param.type,
-                            description: param.description,
-                            ...(param.default !== undefined && { default: param.default }),
-                            ...(param.enum && { enum: param.enum }),
-                        };
-                        return acc;
-                    }, {}),
-                    required: tool.parameters.filter(p => p.required).map(p => p.name),
+                    required: false,
+                    description: 'Analyzer-specific configuration overrides.',
                 },
-            })),
-        };
-        mcpTraceStderr(chalk.blue('[DEBUG]'), `ListTools → ${response.tools.length} tools`);
-        return response;
-    });
-    server.setRequestHandler(InitializeRequestSchema, async (request) => {
-        mcpTraceStderr(chalk.blue('[DEBUG]'), 'initialize', JSON.stringify(request, null, 2));
-        const response = {
-            protocolVersion: '2024-11-05',
-            capabilities: {
-                tools: {},
-            },
-            serverInfo: {
-                name: 'code-auditor',
-                version: PACKAGE_VERSION,
-            },
-        };
-        mcpTraceStderr(chalk.blue('[DEBUG]'), 'initialize response', JSON.stringify(response, null, 2));
-        return response;
-    });
-    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-        const { name, arguments: args } = request.params;
-        mcpTraceStderr(chalk.blue('[DEBUG]'), `CallTool ${name}`, JSON.stringify({
-            argKeys: args && typeof args === 'object' ? Object.keys(args) : [],
-            hasArgs: !!args
-        }));
-        const requestSignal = extra?.signal;
-        const toolStartedAt = Date.now();
-        try {
-            if (name !== 'audit_status') {
-                logMcpDebug('tool', `call ${name}`, {
-                    argKeys: args && typeof args === 'object' ? Object.keys(args) : [],
-                    pathArg: args?.path,
-                    cwd: process.cwd()
-                });
-            }
-            let result;
-            throwIfRequestAborted(requestSignal, `start ${name}`);
-            switch (name) {
-                case 'start_audit': {
-                    result = await withAbortSignal(requestSignal, 'start_audit', () => startAuditJob(args, {
-                        defaultAnalyzers: ['solid', 'dry', 'documentation', 'react', 'data-access'],
-                        defaultMinSeverity: 'warning',
-                        defaultGenerateCodeMap: false,
-                    }));
-                    break;
-                }
-                case 'audit_status': {
-                    const jobId = args.jobId;
-                    if (!jobId) {
-                        throw new Error('audit_status requires jobId');
-                    }
-                    result = getAuditJobStatus(jobId);
-                    break;
-                }
-                case 'audit_results': {
-                    result = await withAbortSignal(requestSignal, 'audit_results', () => getAuditResultsPage(args));
-                    break;
-                }
-                case 'audit': {
-                    result = await withAbortSignal(requestSignal, 'audit', () => getAuditResultsPage(args));
-                    break;
-                }
-                case 'audit_health': {
+                {
+                    name: 'scope',
+                    type: 'string',
+                    required: false,
+                    description: 'Audit scope: "all" (default), "changed" (files differing from index), "git:<ref>" (diff against a git ref), or a comma-separated list of file paths.',
+                    default: 'all',
+                },
+            ],
+            handler: async (args, signal) => {
+                return withAbortSignal(signal, 'audit.run', async () => {
                     const auditPath = path.resolve(args.path || process.cwd());
                     await assertAuditPathExists(auditPath);
-                    const threshold = args.threshold || 70;
-                    const indexFunctions = args.indexFunctions !== false; // Default true
-                    const generateCodeMap = args.generateCodeMap !== false; // Default true
-                    // Get stored analyzer configs from database
+                    const analyzers = args.analyzers ?? DEFAULT_ANALYZERS;
+                    const minSeverity = (args.minSeverity || 'warning');
+                    const indexFunctions = args.indexFunctions !== false;
                     const db = CodeIndexDB.getInstance();
                     await db.initialize();
                     const storedConfigs = await db.getAllAnalyzerConfigs(auditPath);
-                    // Merge stored configs with any provided configs
                     const analyzerConfigs = {
                         ...storedConfigs,
-                        ...(args.analyzerConfigs || {})
+                        ...(args.analyzerConfigs || {}),
                     };
+                    const scope = args.scope || 'all';
                     const runner = createAuditRunner({
                         projectRoot: auditPath,
-                        enabledAnalyzers: ['solid', 'dry', 'documentation', 'react', 'data-access'],
-                        minSeverity: 'warning',
+                        enabledAnalyzers: analyzers,
+                        minSeverity,
                         verbose: false,
-                        indexFunctions, // Pass the flag to the runner
+                        indexFunctions,
+                        scope: scope !== 'all' ? scope : undefined,
                         ...(Object.keys(analyzerConfigs).length > 0 && { analyzerConfigs }),
-                        progressCallback: (p) => {
-                            if (p.phase === 'function-indexing' &&
-                                typeof p.current === 'number' &&
-                                typeof p.total === 'number' &&
-                                p.total > 0 &&
-                                p.current % 50 !== 0 &&
-                                p.current !== p.total) {
-                                return;
-                            }
-                            logMcpDebug('audit_health', p.message ?? p.phase ?? 'progress', {
-                                phase: p.phase,
-                                analyzer: p.analyzer,
-                                current: p.current,
-                                total: p.total
-                            });
-                        }
                     });
                     const auditResult = await runner.run();
-                    const healthScore = calculateHealthScore(auditResult);
-                    // Handle function indexing if enabled and functions were collected
-                    let indexingResult = null;
                     if (indexFunctions && auditResult.metadata.fileToFunctionsMap) {
                         try {
-                            const syncStats = { added: 0, updated: 0, removed: 0 };
-                            // Sync each file's functions to handle additions, updates, and removals
                             for (const [filePath, functions] of Object.entries(auditResult.metadata.fileToFunctionsMap)) {
-                                const fileStats = await syncFileIndex(filePath, functions);
-                                syncStats.added += fileStats.added;
-                                syncStats.updated += fileStats.updated;
-                                syncStats.removed += fileStats.removed;
+                                await syncFileIndex(filePath, functions);
                             }
-                            indexingResult = {
-                                success: true,
-                                registered: syncStats.added + syncStats.updated,
-                                failed: 0,
-                                syncStats
-                            };
-                            mcpDebugStderr(chalk.blue('[INFO]'), `Synced functions: ${syncStats.added} added, ${syncStats.updated} updated, ${syncStats.removed} removed`);
                         }
-                        catch (error) {
-                            console.error(chalk.yellow('[WARN]'), 'Failed to sync functions:', error);
+                        catch {
+                            // indexing is best-effort for sync audit
                         }
                     }
-                    // Generate code map if requested and functions were indexed
-                    let codeMapResult = null;
-                    if (generateCodeMap && indexingResult && indexingResult.success) {
+                    return {
+                        success: true,
+                        summary: auditResult.summary,
+                        violations: auditResult.analyzerResults,
+                        metadata: auditResult.metadata,
+                    };
+                });
+            },
+        },
+        {
+            name: 'start',
+            description: 'Start a background audit job. Returns immediately with a jobId. Poll `audit.status` until completed, then fetch pages with `audit.results`.',
+            parameters: [
+                {
+                    name: 'path',
+                    type: 'string',
+                    required: false,
+                    description: 'File or directory path to audit (defaults to current directory).',
+                    default: process.cwd(),
+                },
+                {
+                    name: 'analyzers',
+                    type: 'array',
+                    required: false,
+                    description: `Analyzers to run (default: ${DEFAULT_ANALYZERS.join(', ')}).`,
+                    default: DEFAULT_ANALYZERS,
+                },
+                {
+                    name: 'minSeverity',
+                    type: 'string',
+                    required: false,
+                    description: 'Minimum severity level to report.',
+                    default: 'warning',
+                    enum: ['info', 'warning', 'critical'],
+                },
+                {
+                    name: 'indexFunctions',
+                    type: 'boolean',
+                    required: false,
+                    description: 'Index functions during audit (default: true).',
+                    default: true,
+                },
+                {
+                    name: 'analyzerConfigs',
+                    type: 'object',
+                    required: false,
+                    description: 'Analyzer-specific configuration overrides.',
+                },
+                {
+                    name: 'scope',
+                    type: 'string',
+                    required: false,
+                    description: 'Audit scope: "all" (default), "changed" (files differing from index), "git:<ref>" (diff against a git ref), or a comma-separated list of file paths.',
+                    default: 'all',
+                },
+                {
+                    name: 'analyzerConcurrency',
+                    type: 'number',
+                    required: false,
+                    description: 'Max analyzers to run in parallel (default: 1).',
+                    default: 1,
+                },
+                {
+                    name: 'partitionStrategy',
+                    type: 'string',
+                    required: false,
+                    description: 'Partition mode: none | auto | top-level.',
+                    default: 'auto',
+                    enum: ['none', 'auto', 'top-level'],
+                },
+                {
+                    name: 'maxPartitions',
+                    type: 'number',
+                    required: false,
+                    description: 'Maximum number of folder partitions (default: 4).',
+                    default: 4,
+                },
+                {
+                    name: 'partitionThresholdFiles',
+                    type: 'number',
+                    required: false,
+                    description: 'Minimum files before auto partitioning (default: 250).',
+                    default: 250,
+                },
+                {
+                    name: 'workerCount',
+                    type: 'number',
+                    required: false,
+                    description: 'Number of worker processes (default: min(4, CPU-1)).',
+                },
+                {
+                    name: 'maxRetries',
+                    type: 'number',
+                    required: false,
+                    description: 'Retry attempts per shard (default: 1).',
+                    default: 1,
+                },
+                {
+                    name: 'shardTimeoutMs',
+                    type: 'number',
+                    required: false,
+                    description: 'Per-shard timeout in ms (default: 180000).',
+                    default: 180000,
+                },
+                {
+                    name: 'retryBackoffMs',
+                    type: 'number',
+                    required: false,
+                    description: 'Base retry backoff in ms (default: 500).',
+                    default: 500,
+                },
+                {
+                    name: 'jobTimeoutMs',
+                    type: 'number',
+                    required: false,
+                    description: 'Max wall time for the audit job (default 30m, cap 4h).',
+                },
+                {
+                    name: 'maxFilesPerRun',
+                    type: 'number',
+                    required: false,
+                    description: 'Per worker chunk size for file processing.',
+                },
+                {
+                    name: 'shardSoftBudgetMs',
+                    type: 'number',
+                    required: false,
+                    description: 'Per worker soft wall-clock budget.',
+                },
+                {
+                    name: 'generateCodeMap',
+                    type: 'boolean',
+                    required: false,
+                    description: 'Generate code map artifacts during audit (default: false).',
+                    default: false,
+                },
+            ],
+            handler: async (args, signal) => {
+                return withAbortSignal(signal, 'audit.start', () => startAuditJob(args, {
+                    defaultAnalyzers: DEFAULT_ANALYZERS,
+                    defaultMinSeverity: 'warning',
+                    defaultGenerateCodeMap: false,
+                }));
+            },
+        },
+        {
+            name: 'status',
+            description: 'Get current status for a previously started background audit job.',
+            parameters: [
+                {
+                    name: 'jobId',
+                    type: 'string',
+                    required: true,
+                    description: 'Job ID returned by `audit start`.',
+                },
+            ],
+            handler: async (args) => {
+                const jobId = args.jobId;
+                if (!jobId)
+                    throw new Error('audit.status requires jobId');
+                return getAuditJobStatus(jobId);
+            },
+        },
+        {
+            name: 'results',
+            description: 'Fetch paginated violations for a completed audit result by resultId.',
+            parameters: [
+                {
+                    name: 'resultId',
+                    type: 'string',
+                    required: false,
+                    description: 'Result ID returned by `audit status` when completed. Also accepts legacy `auditId`.',
+                },
+                {
+                    name: 'auditId',
+                    type: 'string',
+                    required: false,
+                    description: 'Backward-compatible alias for resultId.',
+                },
+                {
+                    name: 'limit',
+                    type: 'number',
+                    required: false,
+                    description: 'Maximum violations per page (default: 50, max: 100).',
+                    default: 50,
+                },
+                {
+                    name: 'offset',
+                    type: 'number',
+                    required: false,
+                    description: 'Violation offset for pagination (default: 0).',
+                    default: 0,
+                },
+                {
+                    name: 'format',
+                    type: 'string',
+                    required: false,
+                    description: 'Output format. "json" (default, structured data) or "sarif" (SARIF 2.1.0 JSON string).',
+                },
+            ],
+            handler: async (args, signal) => {
+                const format = args.format || 'json';
+                if (format === 'sarif') {
+                    return withAbortSignal(signal, 'audit.results', () => getAuditResultsAsSarif(args));
+                }
+                return withAbortSignal(signal, 'audit.results', () => getAuditResultsPage(args));
+            },
+        },
+        {
+            name: 'health',
+            description: 'Quick health check of a codebase with key metrics and optional code map generation.',
+            parameters: [
+                {
+                    name: 'path',
+                    type: 'string',
+                    required: false,
+                    description: 'The directory path to check.',
+                    default: process.cwd(),
+                },
+                {
+                    name: 'threshold',
+                    type: 'number',
+                    required: false,
+                    description: 'Health score threshold (0-100) for pass/fail.',
+                    default: 70,
+                },
+                {
+                    name: 'indexFunctions',
+                    type: 'boolean',
+                    required: false,
+                    description: 'Automatically index functions during health check.',
+                    default: true,
+                },
+                {
+                    name: 'analyzerConfigs',
+                    type: 'object',
+                    required: false,
+                    description: 'Analyzer-specific configuration overrides.',
+                },
+                {
+                    name: 'generateCodeMap',
+                    type: 'boolean',
+                    required: false,
+                    description: 'Generate and return a human-readable code map.',
+                    default: true,
+                },
+            ],
+            handler: async (args) => {
+                const auditPath = path.resolve(args.path || process.cwd());
+                await assertAuditPathExists(auditPath);
+                const threshold = args.threshold || 70;
+                const indexFunctions = args.indexFunctions !== false;
+                const generateCodeMap = args.generateCodeMap !== false;
+                const db = CodeIndexDB.getInstance();
+                await db.initialize();
+                const storedConfigs = await db.getAllAnalyzerConfigs(auditPath);
+                const analyzerConfigs = {
+                    ...storedConfigs,
+                    ...(args.analyzerConfigs || {}),
+                };
+                const runner = createAuditRunner({
+                    projectRoot: auditPath,
+                    enabledAnalyzers: DEFAULT_ANALYZERS,
+                    minSeverity: 'warning',
+                    verbose: false,
+                    indexFunctions,
+                    ...(Object.keys(analyzerConfigs).length > 0 && { analyzerConfigs }),
+                    progressCallback: (p) => {
+                        if (p.phase === 'function-indexing' &&
+                            typeof p.current === 'number' &&
+                            typeof p.total === 'number' &&
+                            p.total > 0 &&
+                            p.current % 50 !== 0 &&
+                            p.current !== p.total)
+                            return;
+                        logMcpDebug('audit.health', p.message ?? p.phase ?? 'progress', {
+                            phase: p.phase,
+                            analyzer: p.analyzer,
+                            current: p.current,
+                            total: p.total,
+                        });
+                    },
+                });
+                const auditResult = await runner.run();
+                const healthScore = calculateHealthScore(auditResult);
+                let indexingResult = null;
+                if (indexFunctions && auditResult.metadata.fileToFunctionsMap) {
+                    try {
+                        const syncStats = { added: 0, updated: 0, removed: 0 };
+                        for (const [filePath, functions] of Object.entries(auditResult.metadata.fileToFunctionsMap)) {
+                            const fileStats = await syncFileIndex(filePath, functions);
+                            syncStats.added += fileStats.added;
+                            syncStats.updated += fileStats.updated;
+                            syncStats.removed += fileStats.removed;
+                        }
+                        indexingResult = {
+                            success: true,
+                            registered: syncStats.added + syncStats.updated,
+                            failed: 0,
+                            syncStats,
+                        };
+                    }
+                    catch {
+                        // best-effort
+                    }
+                }
+                let codeMapResult = null;
+                if (generateCodeMap && indexingResult && indexingResult.success) {
+                    try {
+                        const mapGenerator = new CodeMapGenerator();
+                        const mapOptions = {
+                            includeComplexity: true,
+                            includeDocumentation: true,
+                            includeDependencies: true,
+                            includeUsage: false,
+                            groupByDirectory: true,
+                            maxDepth: 8,
+                            showUnusedImports: true,
+                            minComplexity: 7,
+                        };
+                        let documentation;
                         try {
-                            const mapGenerator = new CodeMapGenerator();
-                            const mapOptions = {
-                                includeComplexity: true,
-                                includeDocumentation: true,
-                                includeDependencies: true,
-                                includeUsage: false,
-                                groupByDirectory: true,
-                                maxDepth: 8, // Slightly smaller for health check
-                                showUnusedImports: true,
-                                minComplexity: 7,
-                            };
-                            // Generate documentation metrics
-                            let documentation = undefined;
-                            try {
-                                // Use existing file discovery from audit result
-                                const files = Object.keys(auditResult.metadata.fileToFunctionsMap || {});
-                                if (files.length > 0) {
-                                    const docResult = await analyzeDocumentation(files);
-                                    documentation = docResult.metrics;
-                                }
+                            const files = Object.keys(auditResult.metadata.fileToFunctionsMap || {});
+                            if (files.length > 0) {
+                                const docResult = await analyzeDocumentation(files);
+                                documentation = docResult.metrics;
                             }
-                            catch (docError) {
-                                console.error(chalk.yellow('[WARN]'), 'Failed to analyze documentation:', docError);
-                            }
-                            // Use paginated code map generation for health check too
-                            const paginatedResult = await mapGenerator.generatePaginatedCodeMap(auditPath, {
-                                ...mapOptions,
-                                includeDocumentation: !!documentation
-                            });
-                            codeMapResult = {
-                                success: true,
-                                mapId: paginatedResult.mapId,
-                                summary: paginatedResult.summary,
-                                quickPreview: paginatedResult.quickPreview,
-                                sections: paginatedResult.summary.sectionsAvailable,
-                                documentationCoverage: documentation?.coverageScore
-                            };
-                            mcpDebugStderr(chalk.blue('[INFO]'), `Generated paginated code map: ${paginatedResult.summary.stats.totalFiles} files, ${paginatedResult.summary.totalSections} sections`);
                         }
-                        catch (error) {
-                            console.error(chalk.yellow('[WARN]'), 'Failed to generate code map:', error);
-                            codeMapResult = {
-                                success: false,
-                                error: error instanceof Error ? error.message : 'Failed to generate code map'
-                            };
+                        catch {
+                            // best-effort
                         }
+                        const paginatedResult = await mapGenerator.generatePaginatedCodeMap(auditPath, {
+                            ...mapOptions,
+                            includeDocumentation: !!documentation,
+                        });
+                        codeMapResult = {
+                            success: true,
+                            mapId: paginatedResult.mapId,
+                            summary: paginatedResult.summary,
+                            quickPreview: paginatedResult.quickPreview,
+                            sections: paginatedResult.summary.sectionsAvailable,
+                            documentationCoverage: documentation?.coverageScore,
+                        };
+                    }
+                    catch (error) {
+                        codeMapResult = {
+                            success: false,
+                            error: error instanceof Error ? error.message : 'Failed to generate code map',
+                        };
                     }
-                    result = {
-                        healthScore,
-                        threshold,
-                        passed: healthScore >= threshold,
-                        status: healthScore >= threshold ? 'healthy' : 'needs-attention',
-                        metrics: {
-                            filesAnalyzed: auditResult.metadata.filesAnalyzed,
-                            totalViolations: auditResult.summary.totalViolations,
-                            criticalViolations: auditResult.summary.criticalIssues,
-                            warningViolations: auditResult.summary.warnings,
-                        },
-                        recommendation: getHealthRecommendation(healthScore, auditResult),
-                        ...(indexingResult && { functionIndexing: indexingResult }),
-                        ...(codeMapResult && { codeMap: codeMapResult }),
-                    };
-                    break;
                 }
-                case 'search_code': {
+                return {
+                    healthScore,
+                    threshold,
+                    passed: healthScore >= threshold,
+                    status: healthScore >= threshold ? 'healthy' : 'needs-attention',
+                    metrics: {
+                        filesAnalyzed: auditResult.metadata.filesAnalyzed,
+                        totalViolations: auditResult.summary.totalViolations,
+                        criticalViolations: auditResult.summary.criticalIssues,
+                        warningViolations: auditResult.summary.warnings,
+                    },
+                    recommendation: getHealthRecommendation(healthScore, auditResult),
+                    ...(indexingResult && { functionIndexing: indexingResult }),
+                    ...(codeMapResult && { codeMap: codeMapResult }),
+                };
+            },
+        },
+    ];
+    registry.register({
+        name: 'audit',
+        description: 'Run code quality audits (synchronous or background), check status, fetch paginated results, and get health checks. Actions: run (sync audit, returns full results), start (background job), status (poll a job), results (paginated violations), health (score + code map).',
+        actions: auditActions,
+    });
+    // ── search ─────────────────────────────────────────────────────────────────
+    registry.register({
+        name: 'search',
+        description: 'Search indexed functions and components. Actions: query (natural language + operators like entity:, component:, hook:, dep:, calls:, lang:, complexity:, exported:, jsdoc:, file:, unused-imports, name:), definition (exact function/component lookup).',
+        actions: [
+            {
+                name: 'query',
+                description: 'Search indexed functions with natural language queries and filter operators.',
+                parameters: [
+                    {
+                        name: 'query',
+                        type: 'string',
+                        required: true,
+                        description: 'Search query with natural language and/or operators. Examples: "Button component:functional", "calls:validateUser", "unused-imports".',
+                    },
+                    {
+                        name: 'filters',
+                        type: 'object',
+                        required: false,
+                        description: 'Optional filters (language, filePath, dependencies, componentType, entityType, searchMode).',
+                    },
+                    {
+                        name: 'limit',
+                        type: 'number',
+                        required: false,
+                        description: 'Maximum results to return.',
+                        default: 50,
+                    },
+                    {
+                        name: 'offset',
+                        type: 'number',
+                        required: false,
+                        description: 'Offset for pagination.',
+                        default: 0,
+                    },
+                ],
+                handler: async (args) => {
                     const query = args.query;
                     const filters = args.filters;
                     const limit = args.limit || 50;
                     const offset = args.offset || 0;
-                    // Allow empty query to return all results
-                    if (query !== undefined && typeof query !== 'string') {
+                    if (query !== undefined && typeof query !== 'string')
                         throw new Error('query must be a string');
-                    }
-                    result = await searchFunctions({
-                        query,
-                        filters,
-                        limit,
-                        offset
-                    });
-                    break;
-                }
-                case 'find_definition': {
+                    return searchFunctions({ query, filters, limit, offset });
+                },
+            },
+            {
+                name: 'definition',
+                description: 'Find the exact definition of a specific function or React component.',
+                parameters: [
+                    {
+                        name: 'name',
+                        type: 'string',
+                        required: true,
+                        description: 'Function or component name to find.',
+                    },
+                    {
+                        name: 'filePath',
+                        type: 'string',
+                        required: false,
+                        description: 'Optional file path to narrow search.',
+                    },
+                ],
+                handler: async (args) => {
                     const name = args.name;
                     const filePath = args.filePath;
-                    if (!name || typeof name !== 'string') {
+                    if (!name || typeof name !== 'string')
                         throw new Error('name must be a non-empty string');
-                    }
                     const definition = await findDefinition(name, filePath);
-                    result = definition || { error: 'Function not found' };
-                    break;
-                }
-                case 'generate_ai_config': {
+                    return definition || { error: 'Function not found' };
+                },
+            },
+        ],
+    });
+    // ── index ──────────────────────────────────────────────────────────────────
+    registry.register({
+        name: 'index',
+        description: 'Manage the code index. Actions: sync (update from files with optional auto-whitelist), cleanup (remove deleted files), reset (clear analysis data, preserve tasks/config/whitelist), status (index statistics).',
+        actions: [
+            {
+                name: 'sync',
+                description: 'Synchronize index from filesystem. Discovers TypeScript/JavaScript functions and updates the index.',
+                parameters: [
+                    {
+                        name: 'path',
+                        type: 'string',
+                        required: false,
+                        description: 'Optional specific path to sync. Omit for full deep sync.',
+                    },
+                ],
+                handler: async (args) => {
+                    const targetPath = args.path;
+                    const db = CodeIndexDB.getInstance();
+                    await db.initialize();
+                    if (targetPath) {
+                        const syncResult = await db.synchronizeFile(path.resolve(targetPath));
+                        return {
+                            mode: 'sync',
+                            success: true,
+                            path: targetPath,
+                            ...(syncResult || { message: 'File not found' }),
+                        };
+                    }
+                    const syncResult = await db.deepSync();
+                    const result = {
+                        mode: 'sync',
+                        success: true,
+                        syncedFiles: syncResult.syncedFiles,
+                        addedFunctions: syncResult.addedFunctions,
+                        updatedFunctions: syncResult.updatedFunctions,
+                        removedFunctions: syncResult.removedFunctions,
+                        errors: syncResult.errors,
+                        message: `Synced ${syncResult.syncedFiles} files: ${syncResult.addedFunctions} added, ${syncResult.updatedFunctions} updated, ${syncResult.removedFunctions} removed`,
+                    };
+                    // Auto-detect and populate whitelist entries (from standalone)
+                    try {
+                        const { WhitelistService } = await import('./services/whitelistService.js');
+                        const whitelistService = WhitelistService.getInstance();
+                        const whitelistResult = await whitelistService.whitelistAllDependencies(targetPath || process.cwd());
+                        if (whitelistResult.added > 0) {
+                            result.whitelistAdded = whitelistResult.added;
+                            result.whitelistMessage = `Auto-added ${whitelistResult.added} whitelist entries`;
+                        }
+                    }
+                    catch {
+                        // whitelist detection is best-effort
+                    }
+                    return result;
+                },
+            },
+            {
+                name: 'cleanup',
+                description: 'Remove index entries for files that no longer exist on disk.',
+                parameters: [],
+                handler: async () => {
+                    const db = CodeIndexDB.getInstance();
+                    await db.initialize();
+                    const cleanupResult = await db.bulkCleanup();
+                    return {
+                        mode: 'cleanup',
+                        success: true,
+                        scannedFiles: cleanupResult.scannedCount,
+                        removedEntries: cleanupResult.removedCount,
+                        removedFiles: cleanupResult.removedFiles,
+                        errors: cleanupResult.errors,
+                        message: `Cleaned up ${cleanupResult.removedCount} entries from ${cleanupResult.removedFiles.length} deleted files`,
+                    };
+                },
+            },
+            {
+                name: 'reset',
+                description: 'Clear all analysis-derived data (functions, search index, cached audits, code maps, schemas). Project tasks, whitelist, and analyzer configs are preserved.',
+                parameters: [],
+                handler: async () => {
+                    const db = CodeIndexDB.getInstance();
+                    await db.initialize();
+                    await db.clearIndex();
+                    return {
+                        mode: 'reset',
+                        success: true,
+                        message: 'Analysis-derived data cleared (functions, search index, cached audits, code maps, schemas). Project tasks, whitelist, and analyzer configs were preserved.',
+                    };
+                },
+            },
+            {
+                name: 'status',
+                description: 'Get index statistics (function count, file count, last sync time).',
+                parameters: [],
+                handler: async () => {
+                    const db = CodeIndexDB.getInstance();
+                    await db.initialize();
+                    const funcs = await db.getAllFunctions();
+                    return {
+                        success: true,
+                        functionCount: Array.isArray(funcs) ? funcs.length : 0,
+                    };
+                },
+            },
+        ],
+    });
+    // ── config ─────────────────────────────────────────────────────────────────
+    registry.register({
+        name: 'config',
+        description: 'Manage analyzer configurations, generate AI tool configs, manage whitelists, and manage invariant rules. Actions: get, set, reset (analyzer configs), generate (AI tool config files), whitelist_list, whitelist_add, whitelist_update, whitelist_detect, rules_list, rules_check.',
+        actions: [
+            {
+                name: 'get',
+                description: 'Get current configuration for an analyzer (or all).',
+                parameters: [
+                    {
+                        name: 'analyzerName',
+                        type: 'string',
+                        required: false,
+                        description: 'Specific analyzer name, or omit to get all configs.',
+                    },
+                    {
+                        name: 'projectPath',
+                        type: 'string',
+                        required: false,
+                        description: 'Optional project path for project-specific config.',
+                    },
+                ],
+                handler: async (args) => {
+                    const analyzerName = args.analyzerName;
+                    const projectPath = args.projectPath;
+                    const db = CodeIndexDB.getInstance();
+                    await db.initialize();
+                    if (analyzerName) {
+                        const config = await db.getAnalyzerConfig(analyzerName, projectPath);
+                        return {
+                            success: true,
+                            analyzer: analyzerName,
+                            config: config || null,
+                            scope: projectPath ? 'project' : 'global',
+                            message: config ? 'Configuration found' : 'No custom configuration found, using defaults',
+                        };
+                    }
+                    const configs = await db.getAllAnalyzerConfigs(projectPath);
+                    return {
+                        success: true,
+                        configs,
+                        scope: projectPath ? 'project' : 'global',
+                        message: `Found ${Object.keys(configs).length} analyzer configurations`,
+                    };
+                },
+            },
+            {
+                name: 'set',
+                description: 'Set or update analyzer configuration that persists across audit runs.',
+                parameters: [
+                    {
+                        name: 'analyzerName',
+                        type: 'string',
+                        required: true,
+                        description: 'The analyzer to configure (solid, dry, security, etc.).',
+                    },
+                    {
+                        name: 'config',
+                        type: 'object',
+                        required: true,
+                        description: 'Configuration object for the analyzer (e.g., thresholds, rules).',
+                    },
+                    {
+                        name: 'projectPath',
+                        type: 'string',
+                        required: false,
+                        description: 'Optional project path for project-specific config.',
+                    },
+                ],
+                handler: async (args) => {
+                    const analyzerName = args.analyzerName;
+                    const config = args.config;
+                    const projectPath = args.projectPath;
+                    const db = CodeIndexDB.getInstance();
+                    await db.initialize();
+                    await db.storeAnalyzerConfig(analyzerName, config, {
+                        projectPath,
+                        isGlobal: !projectPath,
+                    });
+                    return {
+                        success: true,
+                        message: `Configuration for ${analyzerName} analyzer has been saved${projectPath ? ` for project ${projectPath}` : ' globally'}`,
+                        analyzer: analyzerName,
+                        scope: projectPath ? 'project' : 'global',
+                        config,
+                    };
+                },
+            },
+            {
+                name: 'reset',
+                description: 'Reset analyzer configuration to defaults.',
+                parameters: [
+                    {
+                        name: 'analyzerName',
+                        type: 'string',
+                        required: false,
+                        description: 'Specific analyzer to reset, or omit to reset all.',
+                    },
+                    {
+                        name: 'projectPath',
+                        type: 'string',
+                        required: false,
+                        description: 'Optional project path to reset only project-specific config.',
+                    },
+                ],
+                handler: async (args) => {
+                    const analyzerName = args.analyzerName;
+                    const projectPath = args.projectPath;
+                    const db = CodeIndexDB.getInstance();
+                    await db.initialize();
+                    if (analyzerName) {
+                        const deleted = await db.deleteAnalyzerConfig(analyzerName, {
+                            projectPath,
+                            isGlobal: !projectPath,
+                        });
+                        return {
+                            success: deleted,
+                            message: deleted
+                                ? `Configuration for ${analyzerName} analyzer has been reset${projectPath ? ` for project ${projectPath}` : ' globally'}`
+                                : `No configuration found for ${analyzerName} analyzer`,
+                            analyzer: analyzerName,
+                            scope: projectPath ? 'project' : 'global',
+                        };
+                    }
+                    await db.resetAnalyzerConfigs(projectPath);
+                    return {
+                        success: true,
+                        message: projectPath
+                            ? `All project-specific configurations for ${projectPath} have been reset`
+                            : 'All analyzer configurations have been reset to defaults',
+                        scope: projectPath ? 'project' : 'global',
+                    };
+                },
+            },
+            {
+                name: 'generate',
+                description: 'Generate configuration files for AI coding assistants (Cursor, Claude, Copilot, etc.).',
+                parameters: [
+                    {
+                        name: 'tools',
+                        type: 'array',
+                        required: true,
+                        description: 'AI tools to configure (cursor, continue, copilot, claude, zed, windsurf, cody, aider, cline, pearai).',
+                    },
+                    {
+                        name: 'outputDir',
+                        type: 'string',
+                        required: false,
+                        description: 'Output directory for configuration files.',
+                        default: '.',
+                    },
+                    {
+                        name: 'serverUrl',
+                        type: 'string',
+                        required: false,
+                        description: 'MCP server URL (default: auto-detected).',
+                        default: DEFAULT_SERVER_URL,
+                    },
+                    {
+                        name: 'overwrite',
+                        type: 'boolean',
+                        required: false,
+                        description: 'Overwrite existing files (default: false).',
+                        default: false,
+                    },
+                ],
+                handler: async (args) => {
                     const tools = args.tools;
                     const serverUrl = args.serverUrl || DEFAULT_SERVER_URL;
                     const outputDir = args.outputDir || '.';
                     const overwrite = args.overwrite || false;
-                    if (!Array.isArray(tools) || tools.length === 0) {
+                    if (!Array.isArray(tools) || tools.length === 0)
                         throw new Error('tools parameter must be a non-empty array');
-                    }
                     const factory = new ConfigGeneratorFactory(serverUrl);
                     const generatedFiles = [];
                     const errors = [];
@@ -1002,25 +1012,21 @@ async function startMcpServer() {
                             }
                             const config = generator.generateConfig();
                             const outputPath = path.resolve(outputDir, config.filename);
-                            // Check if file exists
                             let fileExists = false;
                             try {
                                 await fs.access(outputPath);
                                 fileExists = true;
                             }
                             catch {
-                                // File doesn't exist
+                                // doesn't exist
                             }
                             if (fileExists && !overwrite) {
                                 errors.push(`File already exists: ${config.filename} (use overwrite: true to replace)`);
                                 continue;
                             }
-                            // Ensure directory exists
                             await fs.mkdir(path.dirname(outputPath), { recursive: true });
-                            // Write main config file
                             await fs.writeFile(outputPath, config.content);
                             generatedFiles.push(config.filename);
-                            // Write additional files if any
                             if (config.additionalFiles) {
                                 for (const additionalFile of config.additionalFiles) {
                                     const additionalPath = path.resolve(outputDir, additionalFile.filename);
@@ -1034,276 +1040,516 @@ async function startMcpServer() {
                             errors.push(`Failed to generate config for ${tool}: ${error instanceof Error ? error.message : 'Unknown error'}`);
                         }
                     }
-                    result = {
+                    return {
                         success: errors.length === 0,
                         generatedFiles,
                         errors: errors.length > 0 ? errors : undefined,
                         totalRequested: tools.length,
-                        totalGenerated: generatedFiles.length
+                        totalGenerated: generatedFiles.length,
                     };
-                    break;
-                }
-                case 'get_workflow_guide': {
-                    const scenario = args.scenario;
-                    const { getWorkflowGuide, getWorkflowTips } = await import('./mcp-tools/workflowGuide.js');
-                    try {
-                        const workflows = getWorkflowGuide(scenario);
-                        const tips = getWorkflowTips();
-                        result = {
-                            success: true,
-                            ...(scenario ? { workflow: workflows } : { workflows }),
-                            tips
-                        };
-                    }
-                    catch (error) {
-                        result = {
-                            success: false,
-                            error: error instanceof Error ? error.message : 'Unknown error',
-                            availableScenarios: ['initial-setup', 'react-development', 'code-review', 'find-patterns', 'maintenance', 'analyzer-configuration']
-                        };
-                    }
-                    break;
-                }
-                case 'sync_index': {
-                    const mode = args.mode || 'sync';
-                    const targetPath = args.path;
-                    const db = CodeIndexDB.getInstance();
-                    await db.initialize();
-                    switch (mode) {
-                        case 'cleanup': {
-                            const cleanupResult = await db.bulkCleanup();
-                            result = {
-                                mode: 'cleanup',
-                                success: true,
-                                scannedFiles: cleanupResult.scannedCount,
-                                removedEntries: cleanupResult.removedCount,
-                                removedFiles: cleanupResult.removedFiles,
-                                errors: cleanupResult.errors,
-                                message: `Cleaned up ${cleanupResult.removedCount} entries from ${cleanupResult.removedFiles.length} deleted files`
-                            };
-                            break;
-                        }
-                        case 'reset': {
-                            await db.clearIndex();
-                            result = {
-                                mode: 'reset',
-                                success: true,
-                                message: 'Analysis-derived data cleared (functions, search index, cached audits, code maps, schemas). Project tasks, whitelist, and analyzer configs were preserved.'
-                            };
-                            break;
-                        }
-                        case 'sync':
-                        default: {
-                            if (targetPath) {
-                                // Sync specific file
-                                const syncResult = await db.synchronizeFile(path.resolve(targetPath));
-                                result = {
-                                    mode: 'sync',
-                                    success: true,
-                                    path: targetPath,
-                                    ...(syncResult || { message: 'File not found' })
-                                };
-                            }
-                            else {
-                                // Deep sync all files
-                                const syncResult = await db.deepSync();
-                                result = {
-                                    mode: 'sync',
-                                    success: true,
-                                    syncedFiles: syncResult.syncedFiles,
-                                    addedFunctions: syncResult.addedFunctions,
-                                    updatedFunctions: syncResult.updatedFunctions,
-                                    removedFunctions: syncResult.removedFunctions,
-                                    errors: syncResult.errors,
-                                    message: `Synced ${syncResult.syncedFiles} files: ${syncResult.addedFunctions} added, ${syncResult.updatedFunctions} updated, ${syncResult.removedFunctions} removed`
-                                };
-                            }
-                            break;
-                        }
-                    }
-                    break;
-                }
-                case 'set_analyzer_config': {
-                    const analyzerName = args.analyzerName;
-                    const config = args.config;
-                    const projectPath = args.projectPath;
-                    const db = CodeIndexDB.getInstance();
-                    await db.initialize();
+                },
+            },
+            {
+                name: 'whitelist_list',
+                description: 'Get current whitelist entries for dependency and class instantiation checks.',
+                parameters: [
+                    {
+                        name: 'type',
+                        type: 'string',
+                        required: false,
+                        description: 'Filter by type: platform-api, framework-class, project-dep, shared-library, node-builtin.',
+                        enum: ['platform-api', 'framework-class', 'project-dep', 'shared-library', 'node-builtin'],
+                    },
+                    {
+                        name: 'status',
+                        type: 'string',
+                        required: false,
+                        description: 'Filter by status: active, pending, rejected, disabled.',
+                        enum: ['active', 'pending', 'rejected', 'disabled'],
+                    },
+                ],
+                handler: async (args) => {
+                    const { handleWhitelistGet } = await import('./mcp-tools/whitelistTools.js');
+                    return handleWhitelistGet(args);
+                },
+            },
+            {
+                name: 'whitelist_add',
+                description: 'Add a new entry to the whitelist.',
+                parameters: [
+                    {
+                        name: 'name',
+                        type: 'string',
+                        required: true,
+                        description: 'Class name or import path to whitelist.',
+                    },
+                    {
+                        name: 'type',
+                        type: 'string',
+                        required: true,
+                        description: 'Type of whitelist entry.',
+                        enum: ['platform-api', 'framework-class', 'project-dep', 'shared-library', 'node-builtin'],
+                    },
+                    {
+                        name: 'description',
+                        type: 'string',
+                        required: false,
+                        description: 'Explanation of why this is whitelisted.',
+                    },
+                    {
+                        name: 'patterns',
+                        type: 'array',
+                        required: false,
+                        description: 'Additional patterns to match (e.g., ["fs/*", "node:fs"]).',
+                    },
+                ],
+                handler: async (args) => {
+                    const { handleWhitelistAdd } = await import('./mcp-tools/whitelistTools.js');
+                    return handleWhitelistAdd(args);
+                },
+            },
+            {
+                name: 'whitelist_update',
+                description: 'Update the status of a whitelist entry.',
+                parameters: [
+                    {
+                        name: 'name',
+                        type: 'string',
+                        required: true,
+                        description: 'Name of the whitelist entry to update.',
+                    },
+                    {
+                        name: 'status',
+                        type: 'string',
+                        required: true,
+                        description: 'New status for the entry.',
+                        enum: ['active', 'pending', 'rejected', 'disabled'],
+                    },
+                ],
+                handler: async (args) => {
+                    const { handleWhitelistUpdateStatus } = await import('./mcp-tools/whitelistTools.js');
+                    return handleWhitelistUpdateStatus(args);
+                },
+            },
+            {
+                name: 'whitelist_detect',
+                description: 'Detect potential whitelist candidates from package.json and usage patterns.',
+                parameters: [
+                    {
+                        name: 'path',
+                        type: 'string',
+                        required: false,
+                        description: 'Project path to analyze (defaults to current directory).',
+                        default: process.cwd(),
+                    },
+                    {
+                        name: 'includePackageJson',
+                        type: 'boolean',
+                        required: false,
+                        description: 'Include dependencies from package.json.',
+                        default: true,
+                    },
+                    {
+                        name: 'autoPopulate',
+                        type: 'boolean',
+                        required: false,
+                        description: 'Automatically add high-confidence entries.',
+                        default: false,
+                    },
+                ],
+                handler: async (args) => {
+                    const { handleWhitelistDetect } = await import('./mcp-tools/whitelistTools.js');
+                    return handleWhitelistDetect(args);
+                },
+            },
+            {
+                name: 'rules_list',
+                description: 'List all configured invariant rules from .codeauditor.json. Shows rule IDs, kinds, severity, and messages.',
+                parameters: [
+                    {
+                        name: 'configPath',
+                        type: 'string',
+                        required: false,
+                        description: 'Path to .codeauditor.json (defaults to auto-detect in current working tree).',
+                    },
+                ],
+                handler: async (args) => {
+                    const { readFileSync } = await import('fs');
+                    const path = await import('path');
+                    const configPath = args.configPath ||
+                        path.join(process.cwd(), '.codeauditor.json');
                     try {
-                        await db.storeAnalyzerConfig(analyzerName, config, {
-                            projectPath,
-                            isGlobal: !projectPath
-                        });
-                        result = {
-                            success: true,
-                            message: `Configuration for ${analyzerName} analyzer has been saved${projectPath ? ` for project ${projectPath}` : ' globally'}`,
-                            analyzer: analyzerName,
-                            scope: projectPath ? 'project' : 'global',
-                            config
+                        const raw = readFileSync(configPath, 'utf-8');
+                        const config = JSON.parse(raw);
+                        const rules = config?.rules ?? [];
+                        return {
+                            rules: rules.map((r) => ({
+                                id: r.id,
+                                kind: r.kind,
+                                severity: r.severity,
+                                message: r.message || null,
+                            })),
+                            count: rules.length,
+                            configPath,
                         };
                     }
-                    catch (error) {
-                        result = {
-                            success: false,
-                            error: error instanceof Error ? error.message : 'Failed to save configuration'
+                    catch (err) {
+                        return {
+                            error: `Failed to read rules: ${err.message}`,
+                            configPath,
+                            rules: [],
+                            count: 0,
                         };
                     }
-                    break;
-                }
-                case 'get_analyzer_config': {
-                    const analyzerName = args.analyzerName;
-                    const projectPath = args.projectPath;
-                    const db = CodeIndexDB.getInstance();
-                    await db.initialize();
+                },
+            },
+            {
+                name: 'rules_check',
+                description: 'Validate the current .codeauditor.json rules (schema, duplicate IDs, valid globs/regex, mutual exclusivity). Returns any config errors.',
+                parameters: [
+                    {
+                        name: 'configPath',
+                        type: 'string',
+                        required: false,
+                        description: 'Path to .codeauditor.json (defaults to auto-detect in current working tree).',
+                    },
+                ],
+                handler: async (args) => {
+                    const { validateRulesConfig } = await import('./invariants/ruleValidator.js');
+                    const { readFileSync } = await import('fs');
+                    const path = await import('path');
+                    const configPath = args.configPath ||
+                        path.join(process.cwd(), '.codeauditor.json');
                     try {
-                        if (analyzerName) {
-                            const config = await db.getAnalyzerConfig(analyzerName, projectPath);
-                            result = {
-                                success: true,
-                                analyzer: analyzerName,
-                                config: config || null,
-                                scope: projectPath ? 'project' : 'global',
-                                message: config ? 'Configuration found' : 'No custom configuration found, using defaults'
-                            };
-                        }
-                        else {
-                            const configs = await db.getAllAnalyzerConfigs(projectPath);
-                            result = {
-                                success: true,
-                                configs,
-                                scope: projectPath ? 'project' : 'global',
-                                message: `Found ${Object.keys(configs).length} analyzer configurations`
-                            };
-                        }
-                    }
-                    catch (error) {
-                        result = {
-                            success: false,
-                            error: error instanceof Error ? error.message : 'Failed to get configuration'
+                        const raw = readFileSync(configPath, 'utf-8');
+                        const config = JSON.parse(raw);
+                        const rulesArray = config?.rules;
+                        const errors = validateRulesConfig({ rules: rulesArray ?? [] });
+                        return {
+                            valid: errors.length === 0,
+                            errors: errors.map(e => ({ ruleId: e.ruleId || null, message: e.message })),
+                            configPath,
                         };
                     }
-                    break;
-                }
-                case 'reset_analyzer_config': {
-                    const analyzerName = args.analyzerName;
-                    const projectPath = args.projectPath;
-                    const db = CodeIndexDB.getInstance();
-                    await db.initialize();
-                    try {
-                        if (analyzerName) {
-                            const deleted = await db.deleteAnalyzerConfig(analyzerName, {
-                                projectPath,
-                                isGlobal: !projectPath
-                            });
-                            result = {
-                                success: deleted,
-                                message: deleted
-                                    ? `Configuration for ${analyzerName} analyzer has been reset${projectPath ? ` for project ${projectPath}` : ' globally'}`
-                                    : `No configuration found for ${analyzerName} analyzer`,
-                                analyzer: analyzerName,
-                                scope: projectPath ? 'project' : 'global'
-                            };
-                        }
-                        else {
-                            await db.resetAnalyzerConfigs(projectPath);
-                            result = {
-                                success: true,
-                                message: projectPath
-                                    ? `All project-specific configurations for ${projectPath} have been reset`
-                                    : 'All analyzer configurations have been reset to defaults',
-                                scope: projectPath ? 'project' : 'global'
-                            };
-                        }
-                    }
-                    catch (error) {
-                        result = {
-                            success: false,
-                            error: error instanceof Error ? error.message : 'Failed to reset configuration'
+                    catch (err) {
+                        return {
+                            valid: false,
+                            errors: [{ message: `Failed to read/parse config: ${err.message}` }],
+                            configPath,
                         };
                     }
-                    break;
-                }
-                case 'get_code_map_section': {
+                },
+            },
+        ],
+    });
+    // ── code_map ───────────────────────────────────────────────────────────────
+    registry.register({
+        name: 'code_map',
+        description: 'Retrieve sections of previously generated code maps. Actions: get (retrieve a specific section), list (list all available sections for a map).',
+        actions: [
+            {
+                name: 'get',
+                description: 'Retrieve a specific section of a previously generated code map.',
+                parameters: [
+                    {
+                        name: 'mapId',
+                        type: 'string',
+                        required: true,
+                        description: 'The map ID returned from a previous audit with code map generation.',
+                    },
+                    {
+                        name: 'sectionType',
+                        type: 'string',
+                        required: true,
+                        description: 'The section type to retrieve (e.g., overview, files, dependencies, documentation).',
+                    },
+                ],
+                handler: async (args) => {
                     const mapId = args.mapId;
                     const sectionType = args.sectionType;
-                    if (!mapId || !sectionType) {
-                        result = {
-                            success: false,
-                            error: 'Both mapId and sectionType are required'
-                        };
-                        break;
-                    }
-                    try {
-                        const db = await getDatabase();
-                        const section = await db.getCodeMapSection(mapId, sectionType);
-                        if (section) {
-                            result = {
-                                success: true,
-                                mapId,
-                                sectionType,
-                                content: section.content,
-                                metadata: section.metadata
-                            };
-                        }
-                        else {
-                            result = {
-                                success: false,
-                                error: `Section '${sectionType}' not found for map '${mapId}'`
-                            };
-                        }
-                    }
-                    catch (error) {
-                        result = {
-                            success: false,
-                            error: error instanceof Error ? error.message : 'Failed to retrieve code map section'
-                        };
+                    if (!mapId || !sectionType)
+                        return { success: false, error: 'Both mapId and sectionType are required' };
+                    const db = await getDatabase();
+                    const section = await db.getCodeMapSection(mapId, sectionType);
+                    if (section) {
+                        return { success: true, mapId, sectionType, content: section.content, metadata: section.metadata };
                     }
-                    break;
-                }
-                case 'list_code_map_sections': {
+                    return { success: false, error: `Section '${sectionType}' not found for map '${mapId}'` };
+                },
+            },
+            {
+                name: 'list',
+                description: 'List all available sections for a code map.',
+                parameters: [
+                    {
+                        name: 'mapId',
+                        type: 'string',
+                        required: true,
+                        description: 'The map ID returned from a previous audit.',
+                    },
+                ],
+                handler: async (args) => {
                     const mapId = args.mapId;
-                    if (!mapId) {
-                        result = {
-                            success: false,
-                            error: 'mapId is required'
-                        };
-                        break;
-                    }
+                    if (!mapId)
+                        return { success: false, error: 'mapId is required' };
+                    const db = await getDatabase();
+                    const sections = await db.listCodeMapSections(mapId);
+                    return { success: true, mapId, sections, totalSections: sections.length };
+                },
+            },
+        ],
+    });
+    // ── tasks ──────────────────────────────────────────────────────────────────
+    registry.register({
+        name: 'tasks',
+        description: 'Manage a persistent per-project task queue. Tasks survive index resets. Actions: create, list, list_tree, get, update, complete, delete, from_audit (create tasks from audit violations with deduplication).',
+        actions: [
+            {
+                name: 'create',
+                description: 'Create a new task.',
+                parameters: [
+                    { name: 'projectPath', type: 'string', required: false, description: 'Project root.' },
+                    { name: 'title', type: 'string', required: true, description: 'Task title.' },
+                    { name: 'description', type: 'string', required: false, description: 'Longer description.' },
+                    { name: 'status', type: 'string', required: false, description: 'Initial status.', enum: ['pending', 'in_progress', 'blocked', 'done', 'cancelled'] },
+                    { name: 'priority', type: 'string', required: false, description: 'Priority.', enum: ['low', 'medium', 'high'] },
+                    { name: 'labels', type: 'array', required: false, description: 'String tags.' },
+                    { name: 'metadata', type: 'object', required: false, description: 'Arbitrary JSON.' },
+                    { name: 'parentTaskId', type: 'string', required: false, description: 'Optional parent.' },
+                    { name: 'source', type: 'string', required: false, description: 'Provenance.', enum: ['manual', 'audit', 'mcp'] },
+                    { name: 'blockedBy', type: 'array', required: false, description: 'Blocking task IDs.' },
+                    { name: 'dueAt', type: 'string', required: false, description: 'ISO 8601 due datetime.' },
+                    { name: 'sortOrder', type: 'number', required: false, description: 'Sort position (default 0).' },
+                    { name: 'relatedFiles', type: 'array', required: false, description: 'File paths.' },
+                    { name: 'relatedSymbols', type: 'array', required: false, description: 'Symbol names.' },
+                ],
+                handler: async (args, signal) => {
+                    const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
+                    return handleProjectTasks({ ...args, action: 'create' }, { signal });
+                },
+            },
+            {
+                name: 'list',
+                description: 'List tasks (flat). Supports filtering by status, priority, labels, source, query text search.',
+                parameters: [
+                    { name: 'projectPath', type: 'string', required: false, description: 'Project root.' },
+                    { name: 'status', type: 'string', required: false, description: 'Filter by status.', enum: ['pending', 'in_progress', 'blocked', 'done', 'cancelled'] },
+                    { name: 'priority', type: 'string', required: false, description: 'Filter by priority.', enum: ['low', 'medium', 'high'] },
+                    { name: 'label', type: 'string', required: false, description: 'Filter by label.' },
+                    { name: 'source', type: 'string', required: false, description: 'Filter by source.', enum: ['manual', 'audit', 'mcp'] },
+                    { name: 'query', type: 'string', required: false, description: 'Text search across title/description.' },
+                    { name: 'hasChildren', type: 'boolean', required: false, description: 'Filter by subtask presence.' },
+                    { name: 'overdueOnly', type: 'boolean', required: false, description: 'Only overdue tasks.' },
+                    { name: 'actionableOnly', type: 'boolean', required: false, description: 'Only open + unblocked.' },
+                    { name: 'limit', type: 'number', required: false, description: 'Max results (default 500).' },
+                ],
+                handler: async (args, signal) => {
+                    const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
+                    return handleProjectTasks({ ...args, action: 'list' }, { signal });
+                },
+            },
+            {
+                name: 'list_tree',
+                description: 'List tasks as a tree (parent-child hierarchy).',
+                parameters: [
+                    { name: 'projectPath', type: 'string', required: false, description: 'Project root.' },
+                    { name: 'status', type: 'string', required: false, description: 'Filter by status.', enum: ['pending', 'in_progress', 'blocked', 'done', 'cancelled'] },
+                    { name: 'limit', type: 'number', required: false, description: 'Max tasks (default 500).' },
+                ],
+                handler: async (args, signal) => {
+                    const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
+                    return handleProjectTasks({ ...args, action: 'list_tree' }, { signal });
+                },
+            },
+            {
+                name: 'get',
+                description: 'Get a single task by ID.',
+                parameters: [
+                    { name: 'projectPath', type: 'string', required: false, description: 'Project root.' },
+                    { name: 'taskId', type: 'string', required: true, description: 'Task ID.' },
+                ],
+                handler: async (args, signal) => {
+                    const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
+                    return handleProjectTasks({ ...args, action: 'get' }, { signal });
+                },
+            },
+            {
+                name: 'update',
+                description: 'Update a task with a patch of partial fields.',
+                parameters: [
+                    { name: 'projectPath', type: 'string', required: false, description: 'Project root.' },
+                    { name: 'taskId', type: 'string', required: true, description: 'Task ID.' },
+                    { name: 'patch', type: 'object', required: true, description: 'Partial fields to update.' },
+                ],
+                handler: async (args, signal) => {
+                    const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
+                    return handleProjectTasks({ ...args, action: 'update' }, { signal });
+                },
+            },
+            {
+                name: 'complete',
+                description: 'Mark a task as completed.',
+                parameters: [
+                    { name: 'projectPath', type: 'string', required: false, description: 'Project root.' },
+                    { name: 'taskId', type: 'string', required: true, description: 'Task ID.' },
+                ],
+                handler: async (args, signal) => {
+                    const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
+                    return handleProjectTasks({ ...args, action: 'complete_task' }, { signal });
+                },
+            },
+            {
+                name: 'delete',
+                description: 'Delete a task. Mode: reject (default, refuse if subtasks exist), detach (move subtasks up), cascade (delete subtree).',
+                parameters: [
+                    { name: 'projectPath', type: 'string', required: false, description: 'Project root.' },
+                    { name: 'taskId', type: 'string', required: true, description: 'Task ID.' },
+                    { name: 'mode', type: 'string', required: false, description: 'Delete mode.', enum: ['reject', 'detach', 'cascade'] },
+                ],
+                handler: async (args, signal) => {
+                    const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
+                    return handleProjectTasks({ ...args, action: 'delete' }, { signal });
+                },
+            },
+            {
+                name: 'from_audit',
+                description: 'Create tasks from audit violations with deduplication. Each violation gets a stable fingerprint; violations matching existing open tasks are skipped.',
+                parameters: [
+                    { name: 'projectPath', type: 'string', required: false, description: 'Project root.' },
+                    { name: 'auditJobId', type: 'string', required: false, description: 'Audit job ID. Omit to use most recent completed audit.' },
+                    { name: 'severities', type: 'array', required: false, description: 'Severities to include (default: critical, warning).' },
+                    { name: 'analyzers', type: 'array', required: false, description: 'Filter violations by analyzer name.' },
+                    { name: 'paths', type: 'array', required: false, description: 'Filter violations by file path globs.' },
+                ],
+                handler: async (args, signal) => {
+                    const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
+                    return handleProjectTasks({ ...args, action: 'from_audit' }, { signal });
+                },
+            },
+        ],
+    });
+    // ── guide ──────────────────────────────────────────────────────────────────
+    registry.register({
+        name: 'guide',
+        description: 'Get recommended workflows and best practices for using the code auditor tools effectively. Single action: get.',
+        actions: [
+            {
+                name: 'get',
+                description: 'Get workflow guide for a specific scenario or all scenarios.',
+                parameters: [
+                    {
+                        name: 'scenario',
+                        type: 'string',
+                        required: false,
+                        description: 'Specific scenario: initial-setup, react-development, code-review, find-patterns, maintenance. Leave empty to see all.',
+                    },
+                ],
+                handler: async (args) => {
+                    const scenario = args.scenario;
+                    const { getWorkflowGuide, getWorkflowTips } = await import('./mcp-tools/workflowGuide.js');
                     try {
-                        const db = await getDatabase();
-                        const sections = await db.listCodeMapSections(mapId);
-                        result = {
+                        const workflows = getWorkflowGuide(scenario);
+                        const tips = getWorkflowTips();
+                        return {
                             success: true,
-                            mapId,
-                            sections,
-                            totalSections: sections.length
+                            ...(scenario ? { workflow: workflows } : { workflows }),
+                            tips,
                         };
                     }
                     catch (error) {
-                        result = {
+                        return {
                             success: false,
-                            error: error instanceof Error ? error.message : 'Failed to list code map sections'
+                            error: error instanceof Error ? error.message : 'Unknown error',
+                            availableScenarios: [
+                                'initial-setup',
+                                'react-development',
+                                'code-review',
+                                'find-patterns',
+                                'maintenance',
+                                'analyzer-configuration',
+                            ],
                         };
                     }
-                    break;
-                }
-                case 'project_tasks': {
-                    const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
-                    result = await withAbortSignal(requestSignal, 'project_tasks', () => handleProjectTasks((args || {}), {
-                        signal: requestSignal
-                    }));
-                    break;
-                }
-                default:
-                    throw new Error(`Unknown tool: ${name}`);
+                },
+            },
+        ],
+    });
+}
+// ── MCP Server ───────────────────────────────────────────────────────────────
+async function startMcpServer() {
+    logMcpInfo('startup', `code-auditor-mcp ${PACKAGE_VERSION} (stdio)`, {
+        pid: process.pid,
+        cwd: process.cwd(),
+        dataDir: process.env.CODE_AUDITOR_DATA_DIR ?? '(default)',
+        debug: process.env.CODE_AUDITOR_DEBUG ?? '0',
+        logFile: process.env.CODE_AUDITOR_LOG_FILE ?? '(none)',
+    });
+    mcpDebugStderr(chalk.blue('[DEBUG]'), `Node ${process.version} · cwd ${process.cwd()}`);
+    const registry = new ToolRegistry();
+    registerAllTools(registry);
+    const allTools = registry.getAllTools();
+    const toolCount = allTools.length;
+    const server = new Server({ name: 'code-auditor', version: PACKAGE_VERSION }, { capabilities: { tools: {} } });
+    server.onerror = (error) => {
+        console.error(chalk.red('[ERROR]'), 'Server error occurred:', error);
+        console.error(chalk.red('[ERROR]'), 'Error stack:', error.stack);
+    };
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const schemas = registry.getMCPToolSchemas();
+        mcpTraceStderr(chalk.blue('[DEBUG]'), `ListTools → ${schemas.length} tools`);
+        return { tools: schemas };
+    });
+    server.setRequestHandler(InitializeRequestSchema, async (request) => {
+        mcpTraceStderr(chalk.blue('[DEBUG]'), 'initialize', JSON.stringify(request, null, 2));
+        return {
+            protocolVersion: '2024-11-05',
+            capabilities: { tools: {} },
+            serverInfo: { name: 'code-auditor', version: PACKAGE_VERSION },
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const { name, arguments: args = {} } = request.params;
+        mcpTraceStderr(chalk.blue('[DEBUG]'), `CallTool ${name}`, JSON.stringify({
+            argKeys: args && typeof args === 'object' ? Object.keys(args) : [],
+            hasArgs: !!args,
+        }));
+        const requestSignal = extra?.signal;
+        const toolStartedAt = Date.now();
+        try {
+            if (name !== 'notify') {
+                logMcpDebug('tool', `call ${name}`, {
+                    argKeys: args && typeof args === 'object' ? Object.keys(args) : [],
+                    pathArg: args?.path,
+                    cwd: process.cwd(),
+                });
+            }
+            throwIfRequestAborted(requestSignal, `start ${name}`);
+            const tool = registry.getTool(name);
+            if (!tool) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: serializeForMcp({
+                                success: false,
+                                error: `Unknown tool: "${name}". Available tools: ${allTools.map((t) => t.name).join(', ')}.`,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const action = args.action;
+            const result = await registry.dispatch(name, action, args, requestSignal);
+            // Check if registry returned a structured error
+            if (result && typeof result === 'object' && 'success' in result && result.success === false && 'validActions' in result) {
+                return {
+                    content: [{ type: 'text', text: serializeForMcp(result) }],
+                    isError: true,
+                };
             }
             const response = {
-                content: [
-                    {
-                        type: 'text',
-                        text: serializeForMcp(result),
-                    },
-                ],
+                content: [{ type: 'text', text: serializeForMcp(result) }],
             };
             mcpTraceStderr(chalk.blue('[DEBUG]'), `Tool ${name} ok`, `responseBytes=${response.content[0].text.length}`);
             throwIfRequestAborted(requestSignal, `before response ${name}`);
@@ -1312,9 +1558,7 @@ async function startMcpServer() {
         catch (error) {
             if (error instanceof RequestAbortedError) {
                 if (name !== 'audit_status') {
-                    logMcpDebug('tool', `call ${name} aborted`, {
-                        ms: Date.now() - toolStartedAt
-                    });
+                    logMcpDebug('tool', `call ${name} aborted`, { ms: Date.now() - toolStartedAt });
                 }
                 throw error;
             }
@@ -1323,16 +1567,11 @@ async function startMcpServer() {
             if (name !== 'audit_status') {
                 logMcpDebug('tool', `call ${name} failed`, {
                     ms: Date.now() - toolStartedAt,
-                    error: error instanceof Error ? error.message : String(error)
+                    error: error instanceof Error ? error.message : String(error),
                 });
             }
             return {
-                content: [
-                    {
-                        type: 'text',
-                        text: serializeForMcp(formatMcpToolErrorPayload(name, error)),
-                    },
-                ],
+                content: [{ type: 'text', text: serializeForMcp(formatMcpToolErrorPayload(name, error)) }],
                 isError: true,
             };
         }
@@ -1343,84 +1582,23 @@ async function startMcpServer() {
         }
     });
     const transport = new StdioServerTransport();
-    // Add transport event handlers if available
     if (transport.onclose) {
-        transport.onclose = () => {
-            console.error(chalk.yellow('[WARN]'), 'Transport closed');
-        };
+        transport.onclose = () => console.error(chalk.yellow('[WARN]'), 'Transport closed');
     }
     if (transport.onerror) {
-        transport.onerror = (error) => {
-            console.error(chalk.red('[ERROR]'), 'Transport error:', error);
-        };
+        transport.onerror = (error) => console.error(chalk.red('[ERROR]'), 'Transport error:', error);
     }
     await server.connect(transport);
     console.error(chalk.green('✓ Code Auditor MCP Server started'));
-    console.error(chalk.gray(`Listening on stdio · ${tools.length} tools · ${PACKAGE_VERSION}`));
+    console.error(chalk.gray(`Listening on stdio · ${toolCount} tools · ${PACKAGE_VERSION}`));
     mcpDebugStderr(chalk.blue('[DEBUG]'), 'Server ready', {
         name: 'code-auditor',
         transport: 'stdio',
-        toolCount: tools.length
+        toolCount,
     });
 }
-function getAllViolations(result) {
-    const violations = [];
-    for (const [analyzerName, analyzerResult] of Object.entries(result.analyzerResults)) {
-        for (const violation of analyzerResult.violations) {
-            violations.push({
-                ...violation,
-                analyzer: analyzerName,
-            });
-        }
-    }
-    return violations;
-}
-function calculateHealthScore(result) {
-    const filesAnalyzed = result.metadata?.filesAnalyzed || 1;
-    const critical = result.summary.criticalIssues || 0;
-    const warnings = result.summary.warnings || 0;
-    const suggestions = result.summary.suggestions || 0;
-    // Weight factors for different severity levels
-    const weights = {
-        critical: 10,
-        warning: 3,
-        suggestion: 0.5
-    };
-    // Calculate weighted violations per file
-    const weightedViolations = (critical * weights.critical) +
-        (warnings * weights.warning) +
-        (suggestions * weights.suggestion);
-    const violationsPerFile = weightedViolations / filesAnalyzed;
-    // Score calculation: 100 points minus deductions
-    // Each weighted violation per file reduces score
-    // Critical-heavy codebases drop faster than suggestion-heavy ones
-    let score = 100 - (violationsPerFile * 2);
-    return Math.max(0, Math.round(Math.min(100, score)));
-}
-function generateRecommendations(result) {
-    const recommendations = [];
-    if (result.summary.criticalIssues > 0) {
-        recommendations.push({
-            priority: 'high',
-            title: 'Fix critical violations immediately',
-            description: `${result.summary.criticalIssues} critical issues require immediate attention`,
-        });
-    }
-    // Add more recommendation logic based on patterns
-    return recommendations;
-}
-function getHealthRecommendation(score, result) {
-    if (score >= 90)
-        return 'Excellent code health!';
-    if (score >= 70)
-        return 'Good code health with room for improvement';
-    if (result.summary.criticalIssues > 0) {
-        return `Fix ${result.summary.criticalIssues} critical violations first`;
-    }
-    return 'Code health needs attention - run detailed audit';
-}
+// ── Process setup ────────────────────────────────────────────────────────────
 registerProcessReliabilityHandlers();
-// Add SIGTERM and SIGINT handlers
 process.on('SIGTERM', () => {
     console.error(chalk.yellow('[WARN]'), 'Received SIGTERM, shutting down gracefully...');
     process.exitCode = 0;
@@ -1429,15 +1607,32 @@ process.on('SIGINT', () => {
     console.error(chalk.yellow('[WARN]'), 'Received SIGINT, shutting down gracefully...');
     process.exitCode = 0;
 });
-// Log when stdin/stdout events occur
 process.stdin.on('error', (error) => {
     console.error(chalk.red('[ERROR]'), 'stdin error:', error);
 });
 process.stdout.on('error', (error) => {
     console.error(chalk.red('[ERROR]'), 'stdout error:', error);
 });
-startMcpServer().catch(error => {
-    console.error(chalk.red('[ERROR]'), 'Failed to start MCP server:', error);
+// ── Mode dispatch ────────────────────────────────────────────────────────────
+async function main() {
+    await initParsers();
+    if (autoIndexPath) {
+        // --auto-index: sync the index and exit
+        const { runAutoIndex } = await import('./mcpAutoIndex.js');
+        await runAutoIndex(autoIndexPath);
+        process.exit(0);
+    }
+    if (uiMode) {
+        // --ui: start the HTTP UI server
+        const { startMcpUIServer } = await import('./mcp-ui-simple.js');
+        await startMcpUIServer();
+        return;
+    }
+    // --stdio (default): start the MCP server
+    await startMcpServer();
+}
+main().catch((error) => {
+    console.error(chalk.red('[ERROR]'), 'Failed to start:', error);
     console.error(chalk.red('[ERROR]'), 'Stack:', error.stack);
     process.exitCode = 1;
 });