@tng-sh/mcp-server 1.0.1 → 1.0.4

package/README.md

@@ -10,7 +10,7 @@ The [Model Context Protocol](https://modelcontextprotocol.io) allows AI assistan
 
 - *"Audit the `process_payment` method in `app/services/payment_processor.rb`"*
 - *"Generate comprehensive tests for the UserController#create method"*
-- *"Check the impact of changes to `Order#checkout`"*
+- *"Run a regression check on `Order#checkout`"*
 - *"What can TNG do here?"*
 
 And the AI will use TNG automatically to provide detailed, actionable results.
@@ -21,7 +21,7 @@ And the AI will use TNG automatically to provide detailed, actionable results.
 -  **Test Generation** - Automatic test creation for Ruby, Python, and JavaScript
 -  **X-Ray Visualization** - Generate Mermaid flowcharts to visualize method logic
 -  **Symbolic Trace** - Execution path analysis for debugging and understanding code flow
--  **Impact Analysis** - Blast radius check for changes to a method vs Git HEAD
+-  **Regression Check** - Blast radius check for changes to a method vs Git HEAD
 -  **Clone Detection** - Find duplicate code with token-based, structural, and fuzzy matching
 -  **Dead Code Detection** - Identify unused imports, variables, functions, and unreachable code
 -  **Capabilities Listing** - List available TNG MCP tools and when to use them
@@ -310,7 +310,7 @@ AI: I'll analyze that file for dead code.
 
 ## Available Tools
 
-The MCP server exposes six tools:
+The MCP server exposes seven tools:
 
 ### 1. `audit_method`
 
@@ -365,7 +365,21 @@ Generate symbolic trace execution path for a method.
 - Variable states at each step
 - Control flow analysis
 
-### 5. `detect_clones`
+### 5. `impact_method` (Regression Check)
+
+Analyze the impact (blast radius) of changes to a method vs its committed version (`HEAD`).
+
+**Parameters:**
+- `file_path` (required) - Path to the source file
+- `method_name` (required) - Name of the method
+- `class_name` (optional) - Class name (Python only)
+
+**Returns:**
+- Breaking changes detected
+- Informational changes
+- Impacted call sites (where this method is used)
+
+### 6. `detect_clones`
 
 Detect code duplication within a file.
 
@@ -378,18 +392,34 @@ Detect code duplication within a file.
 - Locations of duplicated code
 - Refactoring recommendations
 
-### 6. `detect_deadcode`
+### 7. `detect_deadcode`
 
-Detect dead code in a file.
+Detect dead code in a file or across the whole project.
 
 **Parameters:**
-- `file_path` (required) - Path to the source file
+- `file_path` (optional) - Path to the source file (omit when using `all=true`)
+- `all` (optional) - Set to true for a project-wide scan (uses CLI flag `--all`)
+- `project_root` (required when `all=true`) - Project root to run the scan from
 
 **Returns:**
 - Unused imports, variables, and functions
 - Unreachable code blocks
 - Cleanup recommendations
 
+### 8. `find_call_sites`
+
+Find in-repo call sites for a method/function.
+
+**Parameters:**
+- `file_path` (required) - Path to the source file containing the method
+- `method_name` (required) - Method/function name
+- `class_name` (optional) - Class/module name to disambiguate methods with the same name
+- `project_root` (optional) - Project root to resolve relative paths
+
+**Returns:**
+- Files and line numbers where the method is called
+- Snippet/context lines (when available)
+
 ## Development
 
 ### Building

package/dist/index.js

@@ -8,11 +8,13 @@ import { xrayMethod } from './tools/xray.js';
 import { traceMethod } from './tools/trace.js';
 import { detectClones } from './tools/clones.js';
 import { detectDeadCode } from './tools/deadcode.js';
+import { findCallSites } from './tools/call_sites.js';
 import { impactMethod } from './tools/impact.js';
 import { runInit } from './init.js';
+import { preflightTarget, buildMcpResponse } from './tools/utils.js';
 const server = new McpServer({
     name: 'tng-mcp',
-    version: '1.0.0',
+    version: '1.1.0',
 });
 if (process.argv.includes('init')) {
     const code = runInit();
@@ -21,100 +23,186 @@ if (process.argv.includes('init')) {
 const auditSchema = {
     file_path: z.string().describe('Relative or absolute path to the source file (e.g., "app/services/payment_processor.rb", "src/utils/validator.ts")'),
     method_name: z.string().describe('Name of the method/function to audit (e.g., "process_payment", "validateUser", "handleSubmit")'),
+    class_name: z.string().optional().describe('Class or module name to disambiguate methods with the same name'),
     test_type: z.string().optional().describe('Component type - REQUIRED for JavaScript/Python: "utility", "react_component", "express_handler", "django_view", etc. Ignored for Ruby/Rails.'),
     response_format: z.string().optional().describe('Response format: "text" (default), "json", or "both".'),
     raw_json: z.boolean().optional().describe('If true, return JSON envelope with raw tool output.'),
+    project_root: z.string().optional().describe('Project root for deterministic relative-path resolution.'),
+    timeout_sec: z.number().int().positive().optional().describe('Execution timeout in seconds (default 420).'),
+    retries: z.number().int().min(0).max(3).optional().describe('Retry attempts for transient failures (default 0).'),
+    debug: z.boolean().optional().describe('Return additional diagnostics in server logs/metadata.'),
 };
 const generateSchema = {
     file_path: z.string().describe('Relative or absolute path to the source file to generate tests for'),
     method_name: z.string().describe('Name of the method/function to generate tests for'),
+    class_name: z.string().optional().describe('Class or module name to disambiguate methods with the same name'),
     test_type: z.string().optional().describe('Component type or test framework hint - REQUIRED for JS/Python: "utility", "react_component", "express_handler", etc.'),
     response_format: z.string().optional().describe('Response format: "text" (default), "json", or "both".'),
     raw_json: z.boolean().optional().describe('If true, return JSON envelope with raw tool output.'),
+    project_root: z.string().optional().describe('Project root for deterministic relative-path resolution.'),
+    timeout_sec: z.number().int().positive().optional().describe('Execution timeout in seconds (default 420).'),
+    retries: z.number().int().min(0).max(3).optional().describe('Retry attempts for transient failures (default 0).'),
+    debug: z.boolean().optional().describe('Return additional diagnostics in server logs/metadata.'),
 };
 const methodSchema = {
     file_path: z.string().describe('Relative or absolute path to the source file'),
     method_name: z.string().describe('Name of the method/function'),
+    class_name: z.string().optional().describe('Class or module name to disambiguate methods with the same name'),
     response_format: z.string().optional().describe('Response format: "text" (default), "json", or "both".'),
     raw_json: z.boolean().optional().describe('If true, return JSON envelope with raw tool output.'),
+    project_root: z.string().optional().describe('Project root for deterministic relative-path resolution.'),
+    timeout_sec: z.number().int().positive().optional().describe('Execution timeout in seconds (default 120 for trace/xray).'),
+    retries: z.number().int().min(0).max(3).optional().describe('Retry attempts for transient failures (default 0).'),
+    debug: z.boolean().optional().describe('Return additional diagnostics in server logs/metadata.'),
 };
 const impactSchema = {
     file_path: z.string().describe('Relative or absolute path to the source file'),
     method_name: z.string().describe('Name of the method/function'),
-    class_name: z.string().optional().describe('Class name (Python only, optional)'),
+    class_name: z.string().optional().describe('Class or module name to disambiguate methods with the same name'),
     response_format: z.string().optional().describe('Response format: "text" (default), "json", or "both".'),
     raw_json: z.boolean().optional().describe('If true, return JSON envelope with raw tool output.'),
+    project_root: z.string().optional().describe('Project root for deterministic relative-path resolution.'),
+    timeout_sec: z.number().int().positive().optional().describe('Execution timeout in seconds (default 180).'),
+    retries: z.number().int().min(0).max(3).optional().describe('Retry attempts for transient failures (default 0).'),
+    debug: z.boolean().optional().describe('Return additional diagnostics in server logs/metadata.'),
 };
 const clonesSchema = {
     file_path: z.string().describe('Relative or absolute path to the source file to analyze for duplication'),
     level: z.string().optional().describe('Clone detection level: "1" (exact), "2" (structural), "3" (fuzzy/near-miss), or "all" (default - detects all types)'),
     response_format: z.string().optional().describe('Response format: "text" (default), "json", or "both".'),
     raw_json: z.boolean().optional().describe('If true, return JSON envelope with raw tool output.'),
+    project_root: z.string().optional().describe('Project root for deterministic relative-path resolution.'),
+    timeout_sec: z.number().int().positive().optional().describe('Execution timeout in seconds (default 180).'),
+    retries: z.number().int().min(0).max(3).optional().describe('Retry attempts for transient failures (default 0).'),
+    debug: z.boolean().optional().describe('Return additional diagnostics in server logs/metadata.'),
 };
 const deadCodeSchema = {
     file_path: z.string().optional().describe('Relative or absolute path to the source file to analyze for dead code (omit when using all=true)'),
+    project_root: z.string().optional().describe('Project root to resolve relative paths and run project-wide scans (recommended when all=true)'),
     all: z.boolean().optional().describe('If true, analyze dead code across the entire project (passes --all).'),
     response_format: z.string().optional().describe('Response format: "text" (default), "json", or "both".'),
     raw_json: z.boolean().optional().describe('If true, return JSON envelope with raw tool output.'),
+    timeout_sec: z.number().int().positive().optional().describe('Execution timeout in seconds (default 600).'),
+    retries: z.number().int().min(0).max(3).optional().describe('Retry attempts for transient failures (default 0).'),
+    debug: z.boolean().optional().describe('Return additional diagnostics in server logs/metadata.'),
+};
+const callSitesSchema = {
+    file_path: z.string().describe('Relative or absolute path to the source file containing the method'),
+    method_name: z.string().describe('Name of the method/function'),
+    class_name: z.string().optional().describe('Class or module name to disambiguate methods with the same name'),
+    project_root: z.string().optional().describe('Project root to resolve relative paths'),
+    response_format: z.string().optional().describe('Response format: "text" (default), "json", or "both".'),
+    raw_json: z.boolean().optional().describe('If true, return JSON envelope with raw tool output.'),
+    timeout_sec: z.number().int().positive().optional().describe('Execution timeout in seconds (default 600).'),
+    retries: z.number().int().min(0).max(3).optional().describe('Retry attempts for transient failures (default 0).'),
+    debug: z.boolean().optional().describe('Return additional diagnostics in server logs/metadata.'),
 };
 const auditDescription = `Audit a specific method/function for security, bugs, performance, and code quality issues.
 Use when the user asks to audit, review, analyze, inspect, or check code.
 Returns findings with severity, line locations, and suggested fixes.
-Supports: Ruby, Python, JavaScript/TypeScript.`;
+Supports: Ruby, Python, JavaScript/TypeScript.
+Example: audit_method { file_path: "app/services/payment_processor.rb", method_name: "process_payment" }`;
 const generateDescription = `Generate tests for a specific method/function.
 Use when the user asks to write tests, create specs, or add coverage.
 Returns complete test code with suggested file path and command to run.
-Supports: Ruby, Python, JavaScript/TypeScript.`;
+Supports: Ruby, Python, JavaScript/TypeScript.
+Example: generate_test { file_path: "src/utils/validator.ts", method_name: "validateUser", test_type: "utility" }`;
 const xrayDescription = `Generate a Mermaid flowchart for a method/function (X-Ray).
 Use when the user asks for a diagram, flowchart, or visual explanation.
-Returns Mermaid code suitable for Markdown renderers.`;
+Returns Mermaid code suitable for Markdown renderers.
+Example: xray_method { file_path: "lib/order.rb", method_name: "checkout" }`;
 const traceDescription = `Generate a symbolic execution trace for a method/function.
 Use when the user asks to trace, step through, or debug execution flow.
-Returns step-by-step trace output.`;
-const impactDescription = `Analyze impact (blast radius) of changes to a method/function vs Git HEAD.
-Use when the user asks about impact, breaking changes, or blast radius.
-Returns breaking/informational changes and impacted call sites.`;
+Returns step-by-step trace output.
+Example: trace_method { file_path: "src/controllers/cart.ts", method_name: "addItem" }`;
+const impactDescription = `Run a regression check (blast radius analysis) on changes to a method vs Git HEAD.
+Use when the user asks about regressions, impact, breaking changes, or blast radius.
+Returns breaking/informational changes and impacted call sites.
+Example: impact_method { file_path: "app/models/user.rb", method_name: "full_name" }`;
 const clonesDescription = `Detect code duplication (clones) within a file.
 Use when the user asks to find duplicates or copy-paste code.
-Returns clone pairs with similarity and locations.`;
+Returns clone pairs with similarity and locations.
+Example: detect_clones { file_path: "src/services/order.ts", level: "2" }`;
 const deadcodeDescription = `Detect unused or unreachable code in a file or entire project.
 Use when the user asks to find dead code or unused imports/variables.
-Set all=true to scan the whole project.
-Returns unused elements with locations and cleanup suggestions.`;
+Set all=true to scan the whole project (CLI flag: --all).
+Returns unused elements with locations and cleanup suggestions.
+Example: detect_deadcode { file_path: "src/api/auth.ts" }
+Example (project-wide): detect_deadcode { all: true }`;
+const callSitesDescription = `Find in-repo call sites for a method/function.
+Use when the user asks "who calls this?" or "where is this used?".
+Example: find_call_sites { file_path: "src/utils/auth.ts", method_name: "validateUser" }`;
+async function callWithPreflight(toolName, args, handler, options = { requireMethod: false }) {
+    const filePath = args?.file_path ? String(args.file_path) : '';
+    const allMode = !!args?.all;
+    if (!options.allowMissingFilePath || !allMode) {
+        const preflight = preflightTarget({
+            tool: toolName,
+            filePath,
+            methodName: args?.method_name ? String(args.method_name) : undefined,
+            className: args?.class_name ? String(args.class_name) : undefined,
+            projectRoot: args?.project_root ? String(args.project_root) : undefined,
+            requireMethod: options.requireMethod,
+        });
+        if (!preflight.ok) {
+            const format = args?.response_format || (args?.raw_json ? 'json' : 'text');
+            return buildMcpResponse({
+                tool: toolName,
+                text: preflight.message,
+                isError: true,
+                format,
+                code: preflight.code,
+                details: preflight.details,
+                meta: { project_root: preflight.projectRoot },
+            });
+        }
+        args = {
+            ...args,
+            project_root: preflight.projectRoot,
+            file_path: preflight.resolvedPath || filePath,
+        };
+    }
+    return handler(args);
+}
 // 1. Audit Method - AI-Powered Code Analysis
-server.registerTool('audit_method', { description: auditDescription, inputSchema: auditSchema }, async (args) => await auditMethod(args));
+server.registerTool('audit_method', { description: auditDescription, inputSchema: auditSchema }, async (args) => await callWithPreflight('audit_method', args, auditMethod, { requireMethod: true }));
 // Aliases for audit_method
-server.registerTool('review_method', { description: 'Alias of audit_method. Use for "review this method" or "code review".', inputSchema: auditSchema }, async (args) => await auditMethod(args));
-server.registerTool('analyze_method', { description: 'Alias of audit_method. Use for "analyze this method".', inputSchema: auditSchema }, async (args) => await auditMethod(args));
+server.registerTool('review_method', { description: 'Alias of audit_method. Use for "review this method" or "code review".', inputSchema: auditSchema }, async (args) => await callWithPreflight('audit_method', args, auditMethod, { requireMethod: true }));
+server.registerTool('analyze_method', { description: 'Alias of audit_method. Use for "analyze this method".', inputSchema: auditSchema }, async (args) => await callWithPreflight('audit_method', args, auditMethod, { requireMethod: true }));
 // 2. Generate Test - AI Test Generation
-server.registerTool('generate_test', { description: generateDescription, inputSchema: generateSchema }, async (args) => await generateTest(args));
+server.registerTool('generate_test', { description: generateDescription, inputSchema: generateSchema }, async (args) => await callWithPreflight('generate_test', args, generateTest, { requireMethod: true }));
 // Aliases for generate_test
-server.registerTool('generate_tests', { description: 'Alias of generate_test. Use for "generate tests".', inputSchema: generateSchema }, async (args) => await generateTest(args));
-server.registerTool('write_tests', { description: 'Alias of generate_test. Use for "write tests".', inputSchema: generateSchema }, async (args) => await generateTest(args));
+server.registerTool('generate_tests', { description: 'Alias of generate_test. Use for "generate tests".', inputSchema: generateSchema }, async (args) => await callWithPreflight('generate_test', args, generateTest, { requireMethod: true }));
+server.registerTool('write_tests', { description: 'Alias of generate_test. Use for "write tests".', inputSchema: generateSchema }, async (args) => await callWithPreflight('generate_test', args, generateTest, { requireMethod: true }));
 // 3. X-Ray Visualization - Code Flow Diagrams
-server.registerTool('xray_method', { description: xrayDescription, inputSchema: methodSchema }, async (args) => await xrayMethod(args));
+server.registerTool('xray_method', { description: xrayDescription, inputSchema: methodSchema }, async (args) => await callWithPreflight('xray_method', args, xrayMethod, { requireMethod: true }));
 // Aliases for xray_method
-server.registerTool('xray_diagram', { description: 'Alias of xray_method. Use for "diagram" or "flowchart".', inputSchema: methodSchema }, async (args) => await xrayMethod(args));
-server.registerTool('visualize_flow', { description: 'Alias of xray_method. Use for "visualize flow".', inputSchema: methodSchema }, async (args) => await xrayMethod(args));
+server.registerTool('xray_diagram', { description: 'Alias of xray_method. Use for "diagram" or "flowchart".', inputSchema: methodSchema }, async (args) => await callWithPreflight('xray_method', args, xrayMethod, { requireMethod: true }));
+server.registerTool('visualize_flow', { description: 'Alias of xray_method. Use for "visualize flow".', inputSchema: methodSchema }, async (args) => await callWithPreflight('xray_method', args, xrayMethod, { requireMethod: true }));
 // 4. Trace Method - Symbolic Execution Analysis
-server.registerTool('trace_method', { description: traceDescription, inputSchema: methodSchema }, async (args) => await traceMethod(args));
+server.registerTool('trace_method', { description: traceDescription, inputSchema: methodSchema }, async (args) => await callWithPreflight('trace_method', args, traceMethod, { requireMethod: true }));
 // 4.5 Impact Method - Blast Radius Analysis
-server.registerTool('impact_method', { description: impactDescription, inputSchema: impactSchema }, async (args) => await impactMethod(args));
+server.registerTool('impact_method', { description: impactDescription, inputSchema: impactSchema }, async (args) => await callWithPreflight('impact_method', args, impactMethod, { requireMethod: true }));
 // Aliases for impact_method
-server.registerTool('impact_analysis', { description: 'Alias of impact_method. Use for "impact analysis" or "blast radius".', inputSchema: impactSchema }, async (args) => await impactMethod(args));
-server.registerTool('impact_audit', { description: 'Alias of impact_method. Use for "impact audit".', inputSchema: impactSchema }, async (args) => await impactMethod(args));
-server.registerTool('blast_radius', { description: 'Alias of impact_method. Use for "blast radius check".', inputSchema: impactSchema }, async (args) => await impactMethod(args));
+server.registerTool('impact_analysis', { description: 'Alias of impact_method. Use for "impact analysis" or "blast radius".', inputSchema: impactSchema }, async (args) => await callWithPreflight('impact_method', args, impactMethod, { requireMethod: true }));
+server.registerTool('impact_audit', { description: 'Alias of impact_method. Use for "regression check".', inputSchema: impactSchema }, async (args) => await callWithPreflight('impact_method', args, impactMethod, { requireMethod: true }));
+server.registerTool('regression_check', { description: 'Alias of impact_method. Use for "regression check".', inputSchema: impactSchema }, async (args) => await callWithPreflight('impact_method', args, impactMethod, { requireMethod: true }));
+server.registerTool('blast_radius', { description: 'Alias of impact_method. Use for "blast radius check".', inputSchema: impactSchema }, async (args) => await callWithPreflight('impact_method', args, impactMethod, { requireMethod: true }));
 // Aliases for trace_method
-server.registerTool('trace_execution', { description: 'Alias of trace_method. Use for "trace execution".', inputSchema: methodSchema }, async (args) => await traceMethod(args));
+server.registerTool('trace_execution', { description: 'Alias of trace_method. Use for "trace execution".', inputSchema: methodSchema }, async (args) => await callWithPreflight('trace_method', args, traceMethod, { requireMethod: true }));
 // 5. Detect Clones - Code Duplication Detection
-server.registerTool('detect_clones', { description: clonesDescription, inputSchema: clonesSchema }, async (args) => await detectClones(args));
+server.registerTool('detect_clones', { description: clonesDescription, inputSchema: clonesSchema }, async (args) => await callWithPreflight('detect_clones', args, detectClones, { requireMethod: false }));
 // Aliases for detect_clones
-server.registerTool('find_clones', { description: 'Alias of detect_clones. Use for "find duplicates".', inputSchema: clonesSchema }, async (args) => await detectClones(args));
+server.registerTool('find_clones', { description: 'Alias of detect_clones. Use for "find duplicates".', inputSchema: clonesSchema }, async (args) => await callWithPreflight('detect_clones', args, detectClones, { requireMethod: false }));
 // 6. Detect Dead Code - Unused Code Detection
-server.registerTool('detect_deadcode', { description: deadcodeDescription, inputSchema: deadCodeSchema }, async (args) => await detectDeadCode(args));
+server.registerTool('detect_deadcode', { description: deadcodeDescription, inputSchema: deadCodeSchema }, async (args) => await callWithPreflight('detect_deadcode', args, detectDeadCode, { requireMethod: false, allowMissingFilePath: true }));
 // Aliases for detect_deadcode
-server.registerTool('find_deadcode', { description: 'Alias of detect_deadcode. Use for "find unused code".', inputSchema: deadCodeSchema }, async (args) => await detectDeadCode(args));
-// 7. Capabilities - List Available Tools
+server.registerTool('find_deadcode', { description: 'Alias of detect_deadcode. Use for "find unused code".', inputSchema: deadCodeSchema }, async (args) => await callWithPreflight('detect_deadcode', args, detectDeadCode, { requireMethod: false, allowMissingFilePath: true }));
+// 7. Find Call Sites - Usage Detection
+server.registerTool('find_call_sites', { description: callSitesDescription, inputSchema: callSitesSchema }, async (args) => await callWithPreflight('find_call_sites', args, findCallSites, { requireMethod: true }));
+// Alias for find_call_sites
+server.registerTool('call_sites', { description: 'Alias of find_call_sites. Use for "find usages" or "where is this called".', inputSchema: callSitesSchema }, async (args) => await callWithPreflight('find_call_sites', args, findCallSites, { requireMethod: true }));
+// 8. Capabilities - List Available Tools
 server.registerTool('list_capabilities', {
     description: 'List available TNG MCP tools and when to use them.',
     inputSchema: {},
@@ -128,15 +216,169 @@ server.registerTool('list_capabilities', {
                 '- generate_test: generate tests for a method',
                 '- xray_method: Mermaid flow diagram for a method',
                 '- trace_method: symbolic execution trace',
-                '- impact_method: impact analysis (blast radius) for a method',
+                '- impact_method: run a regression check (blast radius) for a method',
                 '- detect_clones: find duplicate code in a file',
-                '- detect_deadcode: find unused/unreachable code in a file',
+                '- detect_deadcode: find unused/unreachable code in a file (or whole project with all=true)',
+                '- find_call_sites: locate in-repo call sites for a method/function',
+                '',
+                'Best practices:',
+                '- Prefer file paths relative to the project root.',
+                '- If the server runs outside the repo, pass project_root or use absolute file paths.',
+                '- For JS/Python, include test_type when generating tests or auditing.',
+                '- All execution tools support timeout_sec, retries, and debug.',
+                '- Preflight validates file/method and ignore rules before execution.',
                 '',
-                'Aliases: review_method, analyze_method, generate_tests, write_tests, xray_diagram, visualize_flow, trace_execution, impact_analysis, impact_audit, blast_radius, find_clones, find_deadcode.',
+                'Aliases: review_method, analyze_method, generate_tests, write_tests, xray_diagram, visualize_flow, trace_execution, impact_analysis, impact_audit, regression_check, blast_radius, find_clones, find_deadcode.',
+                '',
+                `Server version: 1.1.0`,
+                'Defaults: timeout (audit/generate)=420s, xray/trace=120s, impact/clones=180s, deadcode/callsites=600s; retries=0.',
             ].join('\n'),
         },
     ],
 }));
+// 7.5 Validate Request - Preflight check for file/method existence
+server.registerTool('validate_request', {
+    description: 'Validate file_path and optional method_name before running a TNG tool. Returns a checklist and recommendations.',
+    inputSchema: {
+        file_path: z.string().describe('Relative or absolute path to the source file'),
+        method_name: z.string().optional().describe('Name of the method/function (optional)'),
+        project_root: z.string().optional().describe('Project root to resolve relative paths (optional)'),
+    },
+}, async (args) => {
+    const filePath = String(args?.file_path || '');
+    const methodName = args?.method_name ? String(args.method_name) : '';
+    const projectRoot = args?.project_root ? String(args.project_root) : undefined;
+    const preflight = preflightTarget({
+        tool: 'validate_request',
+        filePath,
+        methodName: methodName || undefined,
+        projectRoot,
+        requireMethod: false,
+    });
+    const response = {
+        ok: preflight.ok,
+        code: preflight.code,
+        message: preflight.message,
+        details: preflight.details,
+        project_root: preflight.projectRoot,
+        recommendations: preflight.ok ? [] : ['Fix the preflight error and retry the requested TNG tool.'],
+    };
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(response, null, 2),
+            },
+        ],
+    };
+});
+const PROJECT_WIDE_PHRASES = ['project', 'entire project', 'whole project', 'project-wide', 'all files', 'scan all', 'repository'];
+const INTENT_DEFINITIONS = [
+    {
+        tool: 'generate_test',
+        strongPhrases: ['generate tests', 'generate test', 'write tests', 'write test', 'create specs', 'create spec', 'add test coverage'],
+        phrases: ['test coverage', 'unit test', 'integration test', 'spec file', 'test suite'],
+        tokens: ['test', 'tests', 'spec', 'coverage'],
+        negativeTokens: ['diagram', 'trace', 'impact', 'dead', 'unused', 'usage'],
+    },
+    {
+        tool: 'impact_method',
+        strongPhrases: ['blast radius', 'regression check', 'change impact', 'what breaks'],
+        phrases: ['regression', 'breaking change', 'breakage', 'impact analysis', 'risk analysis'],
+        tokens: ['impact', 'regression', 'breaks', 'breakage', 'risk'],
+        negativeTokens: ['diagram', 'trace'],
+    },
+    {
+        tool: 'audit_method',
+        strongPhrases: ['code review', 'review this method', 'audit this method', 'find issues'],
+        phrases: ['audit', 'review', 'analyze', 'inspect', 'security issues', 'code smells', 'bugs'],
+        tokens: ['audit', 'review', 'analyze', 'inspect', 'security', 'vulnerability', 'bug', 'issue', 'smell'],
+        negativeTokens: ['diagram', 'flowchart'],
+    },
+    {
+        tool: 'xray_method',
+        strongPhrases: ['xray diagram', 'x-ray diagram', 'flow chart', 'visualize flow'],
+        phrases: ['diagram', 'flowchart', 'mermaid', 'visual', 'xray', 'x-ray'],
+        tokens: ['diagram', 'flowchart', 'mermaid', 'visualize'],
+        negativeTokens: ['unused', 'dead'],
+    },
+    {
+        tool: 'trace_method',
+        strongPhrases: ['execution trace', 'trace method', 'step by step', 'step-by-step'],
+        phrases: ['trace execution', 'runtime flow', 'execution path', 'what happens when'],
+        tokens: ['trace', 'execution', 'runtime', 'debug'],
+        negativeTokens: ['diagram', 'mermaid', 'unused'],
+    },
+    {
+        tool: 'find_call_sites',
+        strongPhrases: ['where is this used', 'who calls', 'find references', 'find usages', 'call sites'],
+        phrases: ['callsite', 'usages', 'usage', 'references', 'where used'],
+        tokens: ['used', 'usage', 'usages', 'reference', 'references', 'calls', 'called'],
+        negativeTokens: ['unused', 'dead', 'unreachable', 'orphaned'],
+    },
+    {
+        tool: 'detect_clones',
+        strongPhrases: ['duplicate code', 'find duplicates', 'copy paste code'],
+        phrases: ['clone', 'clones', 'copy-paste', 'repeated code', 'similar code'],
+        tokens: ['clone', 'duplicate', 'duplicates', 'copy', 'paste', 'similar'],
+    },
+    {
+        tool: 'detect_deadcode',
+        strongPhrases: ['dead code', 'unused code', 'never used', 'not used', 'unreachable code'],
+        phrases: ['unused import', 'unused variable', 'unused function', 'orphaned code', 'stale code'],
+        tokens: ['dead', 'unused', 'unreachable', 'orphaned', 'stale', 'ununsed'],
+        negativeTokens: ['where', 'who', 'calls', 'reference', 'references'],
+    },
+];
+function normalizeIntentText(text) {
+    return text
+        .toLowerCase()
+        .replace(/[`"'()[\]{}:;,.!?]/g, ' ')
+        .replace(/[-_/]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function singularizeToken(token) {
+    if (token.endsWith('ies') && token.length > 3)
+        return `${token.slice(0, -3)}y`;
+    if (token.endsWith('ses') && token.length > 3)
+        return token.slice(0, -2);
+    if (token.endsWith('s') && token.length > 3)
+        return token.slice(0, -1);
+    return token;
+}
+function scoreIntent(normalized) {
+    const tokens = normalized.split(' ').filter(Boolean);
+    const tokenSet = new Set(tokens.flatMap((token) => [token, singularizeToken(token)]));
+    const hasWhereUsedPattern = /\bwhere\s+is\s+.+\s+used\b/.test(normalized) || /\bwhere\s+.+\s+used\b/.test(normalized);
+    const hasWhoCallsPattern = /\bwho\s+calls\b/.test(normalized);
+    const hasUnusedPattern = /\b(unused|ununsed|dead|unreachable|never used|not used|orphaned)\b/.test(normalized);
+    const scores = INTENT_DEFINITIONS.map((definition) => {
+        let score = 0;
+        for (const phrase of definition.strongPhrases) {
+            if (normalized.includes(phrase))
+                score += 3.0;
+        }
+        for (const phrase of definition.phrases) {
+            if (normalized.includes(phrase))
+                score += 1.5;
+        }
+        for (const token of definition.tokens) {
+            if (tokenSet.has(token))
+                score += 0.7;
+        }
+        for (const token of definition.negativeTokens || []) {
+            if (tokenSet.has(token))
+                score -= 0.8;
+        }
+        if (definition.tool === 'find_call_sites' && (hasWhereUsedPattern || hasWhoCallsPattern))
+            score += 2.2;
+        if (definition.tool === 'detect_deadcode' && hasUnusedPattern)
+            score += 2.2;
+        return { tool: definition.tool, score };
+    });
+    return scores.sort((a, b) => b.score - a.score);
+}
 // 8. Request Router - Map Natural Language to a Tool
 server.registerTool('route_tng_request', {
     description: 'Route a natural-language request to the best TNG tool and list required arguments.',
@@ -145,19 +387,15 @@ server.registerTool('route_tng_request', {
     },
 }, async (args) => {
     const rawRequest = String(args?.request || '');
-    const request = rawRequest.toLowerCase();
-    const matchAny = (phrases) => phrases.some((p) => request.includes(p));
-    const toolOrder = [
-        { tool: 'generate_test', phrases: ['write test', 'write tests', 'generate test', 'generate tests', 'create specs', 'add test coverage', 'test coverage'] },
-        { tool: 'impact_method', phrases: ['impact', 'blast radius', 'breaking change', 'breakage', 'what breaks', 'change impact'] },
-        { tool: 'audit_method', phrases: ['audit', 'review', 'analyze', 'inspect', 'check', 'security', 'vulnerab', 'bug', 'issue', 'code smell'] },
-        { tool: 'xray_method', phrases: ['diagram', 'flowchart', 'visual', 'mermaid', 'xray', 'x-ray', 'flow'] },
-        { tool: 'trace_method', phrases: ['trace', 'step through', 'step-by-step', 'execution', 'debug flow'] },
-        { tool: 'detect_clones', phrases: ['clone', 'duplicate', 'copy-paste', 'repeated code', 'similar code'] },
-        { tool: 'detect_deadcode', phrases: ['dead code', 'unused', 'unreachable', 'unused import', 'unused variable'] },
-    ];
-    const matched = toolOrder.find((entry) => matchAny(entry.phrases));
-    const tool = matched?.tool || null;
+    const normalizedRequest = normalizeIntentText(rawRequest);
+    const ranked = scoreIntent(normalizedRequest);
+    const top = ranked[0];
+    const second = ranked[1];
+    const ambiguous = !!top && !!second && top.score >= 1.5 && second.score >= 1.5 && (top.score - second.score) < 1.0;
+    const tool = top && top.score >= 1.5 ? top.tool : null;
+    const confidence = !tool ? 0.0 : ambiguous ? 0.55 : Math.min(0.97, 0.6 + top.score / 10);
+    const matchAny = (phrases) => phrases.some((p) => normalizedRequest.includes(p));
+    const wantsAllDeadCode = matchAny(PROJECT_WIDE_PHRASES);
     const backticks = [...rawRequest.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
     let file_path = null;
     let method_name = null;
@@ -179,31 +417,47 @@ server.registerTool('route_tng_request', {
         }
     }
     const required = [];
-    if (tool === 'audit_method' || tool === 'generate_test' || tool === 'xray_method' || tool === 'trace_method' || tool === 'impact_method') {
+    if (tool === 'audit_method' || tool === 'generate_test' || tool === 'xray_method' || tool === 'trace_method' || tool === 'impact_method' || tool === 'find_call_sites') {
         required.push('file_path', 'method_name');
     }
     if (tool === 'detect_clones') {
         required.push('file_path');
     }
     if (tool === 'detect_deadcode') {
-        const wantsAll = matchAny(['project', 'entire project', 'whole project', 'project-wide', 'all files', 'scan all', 'repository']);
-        if (!wantsAll) {
+        if (!wantsAllDeadCode) {
             required.push('file_path');
         }
     }
     const missing = required.filter((key) => (key === 'file_path' ? !file_path : !method_name));
+    const alternatives = ranked.filter((entry) => entry.score >= 1.5).slice(0, 3);
+    const reason = !tool
+        ? 'No strong tool intent match. Ask the user to clarify the task.'
+        : ambiguous
+            ? `Ambiguous between ${top.tool} and ${second.tool}; defaulting to ${top.tool}.`
+            : `Matched weighted intent patterns for ${tool}.`;
     const response = {
         tool,
-        reason: tool ? `Matched keywords for ${tool}.` : 'No matching keywords found. Ask the user to clarify the intent.',
+        confidence,
+        reason,
+        alternatives,
         suggested_args: {
             file_path,
             method_name,
-            all: tool === 'detect_deadcode' && matchAny(['project', 'entire project', 'whole project', 'project-wide', 'all files', 'scan all', 'repository']),
+            all: tool === 'detect_deadcode' && wantsAllDeadCode,
             note: tool === 'generate_test' || tool === 'audit_method'
                 ? 'For JS/Python, test_type may be required (e.g., utility, react_component, express_handler).'
                 : undefined,
         },
         missing_required_args: missing,
+        suggested_invocation: tool
+            ? {
+                tool,
+                args: {
+                    ...(file_path ? { file_path } : {}),
+                    ...(method_name ? { method_name } : {}),
+                },
+            }
+            : null,
     };
     return {
         content: [