ucn 3.8.18 → 3.8.20

package/mcp/server.js

@@ -33,7 +33,7 @@ try {
 const { ProjectIndex } = require('../core/project');
 const { findProjectRoot } = require('../core/discovery');
 const output = require('../core/output');
-const { getMcpCommandEnum, normalizeParams, BROAD_COMMANDS: BROAD_CANONICAL, toMcpName } = require('../core/registry');
+const { getMcpCommandEnum, normalizeParams, BROAD_COMMANDS: BROAD_CANONICAL, toMcpName, FLAG_APPLICABILITY, REVERSE_PARAM_MAP, generateMcpParamSection } = require('../core/registry');
 const { execute } = require('../core/execute');
 const { ExpandCache } = require('../core/expand-cache');
 
@@ -123,8 +123,9 @@ const MAX_OUTPUT_CHARS = 100000;     // hard ceiling even with max_chars overrid
 // Broad commands (derived from registry): output is project-wide, truncation means you need a filter
 const BROAD_COMMANDS = new Set([...BROAD_CANONICAL].map(toMcpName));
 
-function toolResult(text, command, maxChars) {
-    if (!text) return { content: [{ type: 'text', text: '(no output)' }] };
+function toolResult(text, command, maxChars, suffixNote) {
+    const suffix = suffixNote || '';
+    if (!text) return { content: [{ type: 'text', text: '(no output)' + suffix }] };
     const defaultLimit = BROAD_COMMANDS.has(command) ? BROAD_OUTPUT_CHARS : DEFAULT_OUTPUT_CHARS;
     const limit = Math.min(maxChars || defaultLimit, MAX_OUTPUT_CHARS);
     if (text.length > limit) {
@@ -144,9 +145,9 @@ function toolResult(text, command, maxChars) {
             usages: 'Use file= to scope to specific files.',
         };
         const narrow = hints[command] || 'Use file=/in=/exclude= to narrow scope.';
-        return { content: [{ type: 'text', text: cleanCut + `\n\n... OUTPUT TRUNCATED: showing ${limit} of ${fullSize} chars. Full output would be ~${fullTokens} tokens. ${narrow} Or use all=true to see everything (warning: ~${fullTokens} tokens).` }] };
+        return { content: [{ type: 'text', text: cleanCut + `\n\n... OUTPUT TRUNCATED: showing ${limit} of ${fullSize} chars. Full output would be ~${fullTokens} tokens. ${narrow} Or use all=true to see everything (warning: ~${fullTokens} tokens).` + suffix }] };
     }
-    return { content: [{ type: 'text', text }] };
+    return { content: [{ type: 'text', text: text + suffix }] };
 }
 
 function toolError(message) {
@@ -238,7 +239,7 @@ OTHER:
 - typedef <name>: Find type definitions matching a name: interfaces, enums, structs, traits, type aliases. See field shapes, required methods, or enum values.
 - stacktrace: Parse a stack trace, show source context per frame. Requires stack param. Handles JS, Python, Go, Rust, Java formats.
 - api: Public API surface of project or file: all exported/public symbols with signatures. Use to understand what a library exposes. Pass file to scope to one file. Python needs __all__; use toc instead.
-- stats: Quick project stats: file counts, symbol counts, lines of code by language and symbol type. Use functions=true for per-function line counts sorted by size (complexity audit).`;
+- stats: Quick project stats: file counts, symbol counts, lines of code by language and symbol type. Use functions=true for per-function line counts sorted by size (complexity audit).` + generateMcpParamSection();
 
 server.registerTool(
     'ucn',
@@ -307,11 +308,39 @@ server.registerTool(
         // This eliminates per-case param selection and prevents CLI/MCP drift.
         const { command: _c, project_dir: _p, ...rawParams } = args;
         const ep = normalizeParams(rawParams);
+
+        // Strip params not applicable to this command (prevents silent no-ops).
+        // Global/core params are always allowed — only optional flags are filtered.
+        const strippedParams = [];
+        const applicable = FLAG_APPLICABILITY[command];
+        if (applicable) {
+            // Truly global options — apply to all commands (build/display control).
+            // Command-specific params (name, term, stack, range, etc.) are in FLAG_APPLICABILITY.
+            const coreParams = new Set(['maxChars', 'maxFiles', 'followSymlinks']);
+            for (const key of Object.keys(ep)) {
+                if (coreParams.has(key)) continue;
+                if (!applicable.includes(key) && ep[key] !== undefined &&
+                    !(Array.isArray(ep[key]) && ep[key].length === 0)) {
+                    strippedParams.push(REVERSE_PARAM_MAP[key] || key);
+                    delete ep[key];
+                }
+            }
+        }
+
         // all=true bypasses both formatter caps AND char truncation (parity with CLI --all)
         const maxChars = ep.all ? MAX_OUTPUT_CHARS : ep.maxChars;
 
-        // Wrap toolResult to auto-inject command + maxChars from this request
-        const tr = (text) => toolResult(text, command, maxChars);
+        // Build stripping note (appended inside truncation boundary on success paths)
+        const strippedNote = strippedParams.length > 0
+            ? `\n\nNote: ${strippedParams.join(', ')} ignored (not applicable to ${command}).`
+            : '';
+
+        // Wrap toolResult to auto-inject command + maxChars + stripping note
+        const tr = (text) => toolResult(text, command, maxChars, strippedNote);
+        // Wrap toolError to include stripping note on error paths too
+        const te = strippedNote
+            ? (msg) => toolError(msg + strippedNote)
+            : toolError;
 
         let index = null; // Track for post-command cache save
         try {
@@ -326,7 +355,7 @@ server.registerTool(
             case 'about': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'about', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let aboutText = output.formatAbout(result, {
                     allHint: 'Repeat with all=true to show all.',
                     methodsHint: 'Note: obj.method() callers/callees excluded. Use include_methods=true to include them.',
@@ -339,7 +368,7 @@ server.registerTool(
             case 'context': {
                 index = getIndex(project_dir, ep);
                 const { ok, result: ctx, error, note } = execute(index, 'context', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 const { text, expandable } = output.formatContext(ctx, {
                     expandHint: 'Use expand command with item number to see code for any item.',
                     showConfidence: ep.showConfidence !== false,
@@ -353,7 +382,7 @@ server.registerTool(
             case 'impact': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'impact', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let impactText = output.formatImpact(result);
                 if (note) impactText += '\n\n' + note;
                 return tr(impactText);
@@ -362,7 +391,7 @@ server.registerTool(
             case 'blast': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'blast', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let blastText = output.formatBlast(result, {
                     allHint: 'Set depth to expand all children.',
                 });
@@ -373,7 +402,7 @@ server.registerTool(
             case 'smart': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'smart', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let smartText = output.formatSmart(result);
                 if (note) smartText += '\n\n' + note;
                 return tr(smartText);
@@ -382,7 +411,7 @@ server.registerTool(
             case 'trace': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'trace', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let traceText = output.formatTrace(result, {
                     allHint: 'Set depth to expand all children.',
                     methodsHint: 'Note: obj.method() calls excluded. Use include_methods=true to include them.'
@@ -394,7 +423,7 @@ server.registerTool(
             case 'reverse_trace': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'reverseTrace', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let rtText = output.formatReverseTrace(result, {
                     allHint: 'Set depth to expand all children.',
                 });
@@ -405,14 +434,14 @@ server.registerTool(
             case 'example': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'example', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 return tr(output.formatExample(result, ep.name));
             }
 
             case 'related': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'related', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let relText = output.formatRelated(result, {
                     all: ep.all || false, top: ep.top,
                     allHint: 'Repeat with all=true to show all.'
@@ -426,7 +455,7 @@ server.registerTool(
             case 'find': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'find', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let text = output.formatFind(result, ep.name, ep.top);
                 if (note) text += '\n\n' + note;
                 return tr(text);
@@ -435,7 +464,7 @@ server.registerTool(
             case 'usages': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'usages', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let text = output.formatUsages(result, ep.name);
                 if (note) text += '\n\n' + note;
                 return tr(text);
@@ -444,7 +473,7 @@ server.registerTool(
             case 'toc': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'toc', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let text = output.formatToc(result, {
                     topHint: 'Set top=N or use detailed=false for compact view.'
                 });
@@ -455,7 +484,7 @@ server.registerTool(
             case 'search': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, structural, note } = execute(index, 'search', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let searchText;
                 if (structural) {
                     searchText = output.formatStructuralSearch(result);
@@ -469,7 +498,7 @@ server.registerTool(
             case 'tests': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'tests', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let testsText = output.formatTests(result, ep.name);
                 if (note) testsText += '\n\n' + note;
                 return tr(testsText);
@@ -478,7 +507,7 @@ server.registerTool(
             case 'affected_tests': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'affectedTests', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let atText = output.formatAffectedTests(result, { all: ep.all });
                 if (note) atText += '\n\n' + note;
                 return tr(atText);
@@ -487,7 +516,7 @@ server.registerTool(
             case 'deadcode': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'deadcode', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 const dcNote = note;
                 let dcText = output.formatDeadcode(result, {
                     top: ep.top || 0,
@@ -501,7 +530,7 @@ server.registerTool(
             case 'entrypoints': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'entrypoints', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let epText = output.formatEntrypoints(result);
                 if (note) epText += '\n\n' + note;
                 return tr(epText);
@@ -512,28 +541,28 @@ server.registerTool(
             case 'imports': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'imports', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 return tr(output.formatImports(result, ep.file));
             }
 
             case 'exporters': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'exporters', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 return tr(output.formatExporters(result, ep.file));
             }
 
             case 'file_exports': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'fileExports', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 return tr(output.formatFileExports(result, ep.file));
             }
 
             case 'graph': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'graph', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 return tr(output.formatGraph(result, {
                     showAll: ep.all || ep.depth !== undefined,
                     maxDepth: ep.depth ?? 2, file: ep.file,
@@ -545,7 +574,7 @@ server.registerTool(
             case 'circular_deps': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'circularDeps', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 return tr(output.formatCircularDeps(result));
             }
 
@@ -554,21 +583,21 @@ server.registerTool(
             case 'verify': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'verify', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 return tr(output.formatVerify(result));
             }
 
             case 'plan': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'plan', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 return tr(output.formatPlan(result));
             }
 
             case 'diff_impact': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'diffImpact', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let diText = output.formatDiffImpact(result, { all: ep.all });
                 if (note) diText += '\n\n' + note;
                 return tr(diText);
@@ -579,21 +608,21 @@ server.registerTool(
             case 'typedef': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'typedef', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 return tr(output.formatTypedef(result, ep.name));
             }
 
             case 'stacktrace': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'stacktrace', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 return tr(output.formatStackTrace(result));
             }
 
             case 'api': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'api', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let apiText = output.formatApi(result, ep.file || '.');
                 if (note) apiText += '\n\n' + note;
                 return tr(apiText);
@@ -602,7 +631,7 @@ server.registerTool(
             case 'stats': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'stats', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 let statsText = output.formatStats(result, { top: ep.top || 0 });
                 if (note) statsText += '\n\n' + note;
                 return tr(statsText);
@@ -613,7 +642,7 @@ server.registerTool(
             case 'fn': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'fn', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 // MCP path security: validate all result files are within project root
                 for (const entry of result.entries) {
                     const check = resolveAndValidatePath(index, entry.match.relativePath || path.relative(index.root, entry.match.file));
@@ -626,7 +655,7 @@ server.registerTool(
             case 'class': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'class', ep);
-                if (!ok) return toolError(error);  // soft error (class not found)
+                if (!ok) return te(error);  // soft error (class not found)
                 // MCP path security: validate all result files are within project root
                 for (const entry of result.entries) {
                     const check = resolveAndValidatePath(index, entry.match.relativePath || path.relative(index.root, entry.match.file));
@@ -639,7 +668,7 @@ server.registerTool(
             case 'lines': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'lines', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 // MCP path security: validate file is within project root
                 const check = resolveAndValidatePath(index, result.relativePath);
                 if (typeof check !== 'string') return check;
@@ -648,7 +677,7 @@ server.registerTool(
 
             case 'expand': {
                 if (ep.item === undefined || ep.item === null) {
-                    return toolError('Item number is required (e.g. item=1).');
+                    return te('Item number is required (e.g. item=1).');
                 }
                 index = getIndex(project_dir, ep);
                 const lookup = expandCacheInstance.lookup(index.root, ep.item);
@@ -657,15 +686,15 @@ server.registerTool(
                     itemCount: lookup.itemCount, symbolName: lookup.symbolName,
                     validateRoot: true
                 });
-                if (!ok) return toolError(error);
+                if (!ok) return te(error);
                 return tr(result.text);
             }
 
             default:
-                return toolError(`Unknown command: ${command}`);
+                return te(`Unknown command: ${command}`);
             }
         } catch (e) {
-            return toolError(e.message);
+            return te(e.message);
         } finally {
             // Persist calls cache after command execution.
             // getIndex() only saves after build (when callsCache is empty).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.8.18",
+  "version": "3.8.20",
   "mcpName": "io.github.mleoca/ucn",
   "description": "Code intelligence toolkit for AI agents — extract functions, trace call chains, find callers, detect dead code without reading entire files. Works as MCP server, CLI, or agent skill. Supports JS/TS, Python, Go, Rust, Java.",
   "main": "index.js",