ucn 3.8.23 → 3.8.26

package/languages/utils.js

@@ -46,10 +46,14 @@ function nodeToLocation(node, codeOrLines) {
  * @returns {string}
  */
 function extractParams(paramsNode) {
+    // Distinguish "we have no node" (genuinely unknown) from "node is empty".
+    // Returning '...' for empty parens caused signatures like `main(...)` for
+    // functions that actually take zero arguments. Empty → '' so callers can
+    // render `main()` cleanly.
     if (!paramsNode) return '...';
     const text = paramsNode.text;
-    // Remove outer parens and trim
-    return text.replace(/^\(|\)$/g, '').trim() || '...';
+    const stripped = text.replace(/^\(|\)$/g, '').trim();
+    return stripped;  // '' for empty params, '...' only when paramsNode missing
 }
 
 /**
@@ -159,8 +163,10 @@ function parsePythonParam(param, info) {
     } else if (param.type === 'default_parameter' || param.type === 'typed_default_parameter') {
         const nameNode = param.childForFieldName('name');
         const valueNode = param.childForFieldName('value');
+        const typeNode = param.childForFieldName('type');
         if (nameNode) info.name = nameNode.text;
         if (valueNode) info.default = valueNode.text;
+        if (typeNode) info.type = typeNode.text;
         info.optional = true;
     } else if (param.type === 'list_splat_pattern' || param.type === 'dictionary_splat_pattern') {
         info.name = param.text;
@@ -390,6 +396,126 @@ function extractJavaDocstring(code, startLine) {
     return extractJSDocstring(code, startLine);
 }
 
+/**
+ * Build a paramTypes map from a structured-params array.
+ * Skips entries without a `type`. Preserves the structured order via plain object.
+ * @param {Array<{name: string, type?: string}>} paramsStructured
+ * @returns {Object<string,string>|null} map { paramName: typeString } or null if empty
+ */
+function paramTypesFromStructured(paramsStructured) {
+    if (!Array.isArray(paramsStructured) || paramsStructured.length === 0) return null;
+    const map = {};
+    let any = false;
+    for (const p of paramsStructured) {
+        if (p && p.name && p.type) {
+            map[p.name] = p.type;
+            any = true;
+        }
+    }
+    return any ? map : null;
+}
+
+/**
+ * Parse @param and @returns/@return tags from a JSDoc block above the given line.
+ * Returns { paramTypes, returnType } where paramTypes is { name: type } and
+ * returnType is a string, both possibly omitted if not present.
+ *
+ * Tag forms supported:
+ *   @param {Type} name           - typed param
+ *   @param {Type} name - desc    - typed param with description
+ *   @returns {Type} desc         - return type (also @return)
+ * Untyped @param tags are ignored.
+ *
+ * @param {string|string[]} codeOrLines
+ * @param {number} startLine - 1-indexed line of the function/method declaration
+ * @returns {{ paramTypes?: Object, returnType?: string }}
+ */
+function parseJSDocTags(codeOrLines, startLine) {
+    const lines = Array.isArray(codeOrLines) ? codeOrLines : codeOrLines.split('\n');
+    const lineIndex = startLine - 1;
+    if (lineIndex <= 0) return {};
+
+    // Walk up past blank lines and decorators to find a JSDoc end line `*/`
+    let i = lineIndex - 1;
+    while (i >= 0 && (lines[i].trim() === '' || lines[i].trim().startsWith('@'))) {
+        i--;
+    }
+    if (i < 0) return {};
+    if (!lines[i].trim().endsWith('*/')) return {};
+
+    const docEnd = i;
+    while (i >= 0 && !lines[i].includes('/**')) {
+        i--;
+    }
+    if (i < 0) return {};
+
+    // Collect block text lines, stripping leading `*` and surrounding whitespace
+    const blockLines = [];
+    for (let j = i; j <= docEnd; j++) {
+        const line = lines[j]
+            .replace(/^\s*\/\*\*\s?/, '')
+            .replace(/\s*\*\/\s*$/, '')
+            .replace(/^\s*\*\s?/, '');
+        blockLines.push(line);
+    }
+    const block = blockLines.join('\n');
+
+    // @param {Type} name  — capture balanced braces (no nested braces in JSDoc types in practice)
+    const paramTypes = {};
+    let any = false;
+    const paramRegex = /@param\s+\{([^}]+)\}\s+([A-Za-z_$][\w$]*)/g;
+    let m;
+    while ((m = paramRegex.exec(block)) !== null) {
+        const type = m[1].trim();
+        const name = m[2];
+        // Strip optional brackets if author wrote @param {Type} [name]; here we already excluded that
+        // but also handle @param {Type} [name=default] form by scanning a separate regex
+        paramTypes[name] = type;
+        any = true;
+    }
+    // Optional-bracket form: @param {Type} [name] or [name=default]
+    const paramOptRegex = /@param\s+\{([^}]+)\}\s+\[([A-Za-z_$][\w$]*)(?:\s*=[^\]]*)?\]/g;
+    while ((m = paramOptRegex.exec(block)) !== null) {
+        const type = m[1].trim();
+        const name = m[2];
+        if (!paramTypes[name]) paramTypes[name] = type;
+        any = true;
+    }
+
+    // @returns {Type} or @return {Type}
+    const retMatch = block.match(/@returns?\s+\{([^}]+)\}/);
+    const result = {};
+    if (any) result.paramTypes = paramTypes;
+    if (retMatch) result.returnType = retMatch[1].trim();
+    return result;
+}
+
+/**
+ * Compute the final paramTypes/returnType for a function symbol.
+ * Native AST types take precedence; JSDoc fills gaps.
+ * @param {Array} paramsStructured - parser output
+ * @param {string|null} nativeReturnType - return type extracted from AST (TS/Py)
+ * @param {string|string[]} codeOrLines - source for JSDoc lookup
+ * @param {number} startLine - function start line
+ * @param {boolean} useJSDoc - whether to consult JSDoc (true for JS/TS, false for Py)
+ * @returns {{ paramTypes?: Object, returnType?: string }}
+ */
+function buildTypeAnnotations(paramsStructured, nativeReturnType, codeOrLines, startLine, useJSDoc) {
+    const native = paramTypesFromStructured(paramsStructured);
+    let jsdoc = {};
+    if (useJSDoc) jsdoc = parseJSDocTags(codeOrLines, startLine);
+
+    const out = {};
+    // Merge: JSDoc first, native overrides
+    if (jsdoc.paramTypes || native) {
+        const merged = { ...(jsdoc.paramTypes || {}), ...(native || {}) };
+        if (Object.keys(merged).length > 0) out.paramTypes = merged;
+    }
+    const rt = nativeReturnType || jsdoc.returnType;
+    if (rt) out.returnType = rt;
+    return out;
+}
+
 /**
  * Get the token type at a specific position using AST
  * @param {object} rootNode - Tree-sitter root node
@@ -591,6 +717,186 @@ function clearNodeListCache() {
     _cachedSubtreeEnds = null;
 }
 
+/**
+ * Extract a string value from a tree-sitter argument node, returning
+ * `{ value, interp }` where:
+ *   - value is the literal portion (with quotes stripped)
+ *   - interp is true when the argument is interpolated (template literal,
+ *     f-string, format!() macro, fmt.Sprintf), in which case `value` is the
+ *     literal *prefix* before the first interpolation, suffixed with '*'.
+ *
+ * Returns null when the node isn't a string-like value.
+ *
+ * Used by route extraction: server `app.get('/users/:id')` → '/users/:id';
+ * client `fetch(\`/users/${id}\`)` → '/users/*' (interp).
+ *
+ * @param {object} node - Tree-sitter node (any language)
+ * @returns {{ value: string, interp: boolean }|null}
+ */
+function extractStringArg(node) {
+    if (!node) return null;
+    const t = node.type;
+
+    // JS/TS string literals
+    if (t === 'string') {
+        const text = node.text;
+        return { value: stripQuotes(text), interp: false };
+    }
+
+    // JS/TS template literal: `/users/${id}` or plain `/users/all`
+    if (t === 'template_string' || t === 'template_literal') {
+        return parseTemplateLiteral(node);
+    }
+
+    // Python string
+    if (t === 'string') {
+        return { value: stripQuotes(node.text), interp: false };
+    }
+
+    // Python concatenated strings: 'a' 'b' → 'ab'
+    if (t === 'concatenated_string') {
+        let acc = '';
+        let interp = false;
+        for (let i = 0; i < node.namedChildCount; i++) {
+            const child = node.namedChild(i);
+            const r = extractStringArg(child);
+            if (r) {
+                acc += r.value;
+                if (r.interp) { interp = true; break; }
+            } else {
+                interp = true;
+                break;
+            }
+        }
+        return { value: acc, interp };
+    }
+
+    // Go interpreted/raw string
+    if (t === 'interpreted_string_literal' || t === 'raw_string_literal') {
+        return { value: stripQuotes(node.text), interp: false };
+    }
+
+    // Java string literal / text block
+    if (t === 'string_literal' || t === 'text_block') {
+        return { value: stripQuotes(node.text), interp: false };
+    }
+
+    // Rust string literal: "..." or raw r"..." / r#"..."#
+    if (t === 'string_literal') {
+        return { value: stripRustString(node.text), interp: false };
+    }
+    if (t === 'raw_string_literal') {
+        return { value: stripRustString(node.text), interp: false };
+    }
+
+    // Rust macro_invocation: format!("/users/{}", id), format!("/path") → extract first string arg
+    if (t === 'macro_invocation') {
+        const argsNode = node.childForFieldName('arguments');
+        if (!argsNode) return null;
+        // Find first string-like child of token_tree
+        const first = findFirstStringInRustMacro(argsNode);
+        if (first == null) return null;
+        // Detect interpolation by presence of `{}` or `{...}` placeholders or extra args
+        const hasPlaceholder = /\{[^}]*\}/.test(first);
+        // Truncate at first placeholder
+        const m = first.match(/^([^{]*)/);
+        return { value: (m ? m[1] : first), interp: hasPlaceholder };
+    }
+
+    return null;
+}
+
+/** Strip surrounding quotes (' " `) from a literal, leaving the inner content. */
+function stripQuotes(text) {
+    if (typeof text !== 'string' || text.length < 2) return text;
+    const first = text[0];
+    const last = text[text.length - 1];
+    if ((first === '"' || first === "'" || first === '`') && first === last) {
+        return text.slice(1, -1);
+    }
+    return text;
+}
+
+/** Strip Rust string literal quoting: "..." or r"..." or r#"..."# etc. */
+function stripRustString(text) {
+    if (typeof text !== 'string') return text;
+    // r#"..."# (any number of #)
+    const rawHash = text.match(/^r(#+)"([\s\S]*)"\1$/);
+    if (rawHash) return rawHash[2];
+    // r"..."
+    const raw = text.match(/^r"([\s\S]*)"$/);
+    if (raw) return raw[1];
+    // "..."
+    if (text.startsWith('"') && text.endsWith('"')) return text.slice(1, -1);
+    return text;
+}
+
+/**
+ * Parse a JS template literal AST node and return literal prefix + interp flag.
+ * `/users/all` → { value: '/users/all', interp: false }
+ * `/users/${id}` → { value: '/users/*', interp: true }
+ */
+function parseTemplateLiteral(node) {
+    let prefix = '';
+    let interp = false;
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        // template_substitution = ${...}
+        if (child.type === 'template_substitution') {
+            interp = true;
+            break;
+        }
+        // string_fragment / template_chars: literal segment
+        if (child.type === 'string_fragment' || child.type === 'template_chars') {
+            prefix += child.text;
+        }
+    }
+    if (interp && !prefix.endsWith('*')) prefix += '*';
+    return { value: prefix, interp };
+}
+
+/** Find the first quoted string inside a Rust macro_invocation token_tree. */
+function findFirstStringInRustMacro(tokenTree) {
+    if (!tokenTree) return null;
+    for (let i = 0; i < tokenTree.namedChildCount; i++) {
+        const child = tokenTree.namedChild(i);
+        if (child.type === 'string_literal' || child.type === 'raw_string_literal') {
+            return stripRustString(child.text);
+        }
+        // Recurse into nested token_trees (rare)
+        if (child.namedChildCount > 0) {
+            const r = findFirstStringInRustMacro(child);
+            if (r != null) return r;
+        }
+    }
+    // Fallback: scan raw text for first quoted string
+    const m = tokenTree.text.match(/"([^"\\]|\\.)*"/);
+    if (m) {
+        const raw = m[0];
+        return raw.slice(1, -1);
+    }
+    return null;
+}
+
+/**
+ * Extract path/method from a fmt.Sprintf("...", args) call inside Go.
+ * Returns the literal prefix before the first %v/%s/%d etc. with '*' suffix.
+ */
+function extractSprintfPrefix(callNode) {
+    // call_expression with function = selector_expression "fmt.Sprintf"
+    const argsNode = callNode.childForFieldName('arguments');
+    if (!argsNode) return null;
+    const first = argsNode.namedChildCount > 0 ? argsNode.namedChild(0) : null;
+    if (!first) return null;
+    const r = extractStringArg(first);
+    if (!r) return null;
+    // Find first format directive %x and truncate
+    const m = r.value.match(/^([^%]*)/);
+    const literal = m ? m[1] : r.value;
+    const hasFmt = /%/.test(r.value);
+    return { value: hasFmt ? (literal + '*') : literal, interp: hasFmt };
+}
+
 module.exports = {
     traverseTree,
     traverseTreeCached,
@@ -604,7 +910,13 @@ module.exports = {
     extractGoDocstring,
     extractRustDocstring,
     extractJavaDocstring,
+    paramTypesFromStructured,
+    parseJSDocTags,
+    buildTypeAnnotations,
     getTokenTypeAtPosition,
     isMatchInCommentOrString,
-    findMatchesWithASTFilter
+    findMatchesWithASTFilter,
+    extractStringArg,
+    stripQuotes,
+    extractSprintfPrefix,
 };

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, FLAG_APPLICABILITY, REVERSE_PARAM_MAP, generateMcpParamSection } = require('../core/registry');
+const { getMcpCommandEnum, normalizeParams, BROAD_COMMANDS: BROAD_CANONICAL, toMcpName, FLAG_APPLICABILITY, REVERSE_PARAM_MAP, generateMcpParamSection, resolveCommand } = require('../core/registry');
 const { execute } = require('../core/execute');
 const { ExpandCache } = require('../core/expand-cache');
 
@@ -139,6 +139,7 @@ function toolResult(text, command, maxChars, suffixNote) {
         const hints = {
             toc: 'Use in= to scope to a subdirectory, or detailed=false for compact view.',
             entrypoints: 'Use framework= to filter by framework, exclude= to skip patterns.',
+            endpoints: 'Use prefix= to filter by URL prefix, method= to filter by HTTP method, server_only/client_only to halve output.',
             diff_impact: 'Use file= to scope to specific files/directories.',
             affected_tests: 'Use file= to scope, exclude= to skip patterns.',
             deadcode: 'Use file= to scope, exclude= to skip patterns.',
@@ -197,15 +198,16 @@ QUICK GUIDE — choosing the right command:
 Commands:
 
 UNDERSTANDING CODE:
-- about <name>: Definition, source, callers, callees, and tests — everything in one call. Replaces 3-4 grep+read cycles. Your first stop for any function or class.
+- about <name>: Definition, source, callers, callees, and tests — everything in one call. Replaces 3-4 grep+read cycles. Your first stop for any function or class. Pass git=true for last-modified, author, and recent-changes (last 30d).
 - context <name>: Who calls it and what does it call, without source code. Results are numbered for use with expand. For classes/structs, shows all methods instead.
 - impact <name>: Every call site with actual arguments passed, grouped by file. Essential before changing a function signature — shows exactly what breaks.
 - blast <name>: Transitive blast radius — callers of callers. Shows the full chain of functions affected if you change something. Like impact but recursive. Use depth (default: 3) to control how far up the chain to walk.
 - smart <name>: Get a function's source with all called functions expanded inline (not constants/variables). Use to understand or modify a function and its dependencies in one read.
 - trace <name>: Call tree from a function downward. Use to understand "what happens when X runs" — maps which modules a pipeline touches without reading files. Set depth (default: 3); setting depth expands all children.
-- example <name>: Best real-world usage example. Automatically scores call sites by quality and returns the top one with context. Use to understand expected calling patterns.
+- example <name>: Best real-world usage example. Automatically scores call sites by quality and returns the top one with context. Use to understand expected calling patterns. Set diverse=true to cluster call sites by argument shape and return one representative per cluster (pair with top=N, default 3).
 - reverse_trace <name>: Upward call chain to entry points — who calls this, who calls those callers, etc. Use to find all paths that lead to a function. Set depth (default: 5) to control how far up. Complement to trace (which goes downward).
 - related <name>: Sibling functions: same file, similar names, or shared callers/callees. Find companions to update together (e.g., serialize when you're changing deserialize). Name-based, not semantic.
+- brief <name>: Compact summary of a function: typed signature, first sentence of docstring, side-effect classification (fs/network/process/global_mutation), complexity (branches, depth, lines). Cheaper than about; more useful than fn when you don't need the body. Pass git=true for last-modified info.
 
 FINDING CODE:
 - find <name>: Locate definitions ranked by usage count. Supports glob patterns (e.g. find "handle*" or "_update*"). Use when you know the name but not the file.
@@ -216,6 +218,7 @@ FINDING CODE:
 - affected_tests <name>: Which tests to run after changing a function. Combines blast (transitive callers) with test detection. Shows test files, coverage %, and uncovered functions. Use depth= to control depth.
 - deadcode: Find dead code: functions/classes with zero callers. Use during cleanup to identify safely deletable code. Excludes exported, decorated, and test symbols by default — use include_exported/include_decorated/include_tests to expand.
 - entrypoints: Detect framework entry points: routes, handlers, DI providers, tasks. Auto-detects Express, Flask, Spring, Gin, Actix, and more. Use framework= to filter by specific framework.
+- endpoints: HTTP API surface — list server routes (Express/Fastify/Koa/NestJS/Flask/FastAPI/Spring/JAX-RS/Gin/Echo/Chi/Fiber/axum/actix/Next.js) and client requests (fetch/axios/requests/httpx/http/restTemplate/webClient/reqwest). Use bridge=true to match clients to servers across language boundaries; method=/prefix= to filter; server_only/client_only to halve output.
 
 EXTRACTING CODE (use instead of reading entire files):
 - fn <name>: Extract one or more functions. Comma-separated for bulk extraction (e.g. "parse,format,validate"). Use file to disambiguate.
@@ -234,12 +237,17 @@ REFACTORING:
 - verify <name>: Check all call sites match function signature (argument count). Run before adding/removing parameters to catch breakage early.
 - plan <name>: Preview refactoring: before/after signatures and call sites needing updates. Use add_param (with optional default_value), remove_param, or rename_to. Pair with verify.
 - diff_impact: Which functions changed in git diff and who calls them. Use to understand impact of recent changes before committing or reviewing. Use base, staged, or file params to scope.
+- check: Pre-commit lint of pending changes against the index. Composes diff_impact + verify + affected_tests; flags ADDED functions with zero callers (ORPHAN), BROKEN_IMPORT, signature drift across call sites, and recommends which tests to run. Use base= to compare against a branch, staged=true for staged changes only.
+
+DIAGNOSTICS:
+- doctor: Index health/coverage report — file/symbol counts, language breakdown, dynamic-import / eval / reflection blind spots, parse failures, and a verdict (HIGH/MEDIUM/LOW trust). Use deep=true to also sample resolution coverage and bucket edges by confidence. Use in= to scope to a subtree.
 
 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).` + generateMcpParamSection();
+- 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). Set hot=true with top=N for the most-called functions (project orientation primitive).
+- audit_async: Find async calls inside async functions that are likely missing await (probable bugs). JS/TS/Python only. Filter with file/exclude/limit.` + generateMcpParamSection();
 
 server.registerTool(
     'ucn',
@@ -252,42 +260,50 @@ server.registerTool(
             file: z.string().optional().describe('File path (imports/exporters/graph/file_exports/lines/api/diff_impact) or filter pattern for disambiguation (e.g. "parser", "src/core")'),
             exclude: z.string().optional().describe('Comma-separated patterns to exclude (e.g. "test,mock,vendor")'),
             include_tests: z.boolean().optional().describe('Include test files in results (excluded by default)'),
+            exclude_tests: z.boolean().optional().describe('Exclude test files from results. Used by entrypoints (where tests are included by default).'),
             include_methods: z.boolean().optional().describe('Include obj.method() calls (default: true for about/trace)'),
             include_uncertain: z.boolean().optional().describe('Include uncertain/ambiguous matches'),
-            min_confidence: z.number().optional().describe('Minimum confidence threshold (0.0-1.0) to filter caller/callee edges'),
+            min_confidence: z.number().min(0).max(1).optional().describe('Minimum confidence threshold (0.0-1.0) to filter caller/callee edges'),
             show_confidence: z.boolean().optional().describe('Show confidence scores per edge (default: true). Set false to hide.'),
+            hide_confidence: z.boolean().optional().describe('Hide confidence scores per edge (alias of show_confidence=false).'),
+            unreachable_only: z.boolean().optional().describe('Show only callers/callees that are unreachable from any detected entry point (about, context, impact).'),
             with_types: z.boolean().optional().describe('Include related type definitions in output'),
             detailed: z.boolean().optional().describe('Show full symbol listing per file'),
             exact: z.boolean().optional().describe('Exact name match only (no substring matching)'),
             in: z.string().optional().describe('Only search in this directory path (e.g. "src/core")'),
-            top: z.number().optional().describe('Max results to show (default: 10)'),
-            depth: z.number().optional().describe('Max depth (default: 3 for trace, 2 for graph); expands all children'),
+            top: z.number().int().positive().max(10000).optional().describe('Max results to show (default: 10). Must be a positive integer.'),
+            depth: z.number().int().nonnegative().max(100).optional().describe('Max depth (default: 3 for trace, 2 for graph); expands all children. Non-negative integer.'),
             code_only: z.boolean().optional().describe('Exclude matches in comments and strings'),
-            context: z.number().optional().describe('Lines of context around each match'),
+            context: z.number().int().nonnegative().max(1000).optional().describe('Lines of context around each match. Non-negative integer.'),
             include_exported: z.boolean().optional().describe('Include exported symbols in deadcode results'),
             include_decorated: z.boolean().optional().describe('Include decorated/annotated symbols in deadcode results'),
             calls_only: z.boolean().optional().describe('Only direct calls and test-case matches (tests command)'),
-            max_lines: z.number().optional().describe('Max source lines for class (large classes show summary by default)'),
+            max_lines: z.number().int().positive().max(1000000).optional().describe('Max source lines for class (large classes show summary by default). Must be a positive integer.'),
             direction: z.enum(['imports', 'importers', 'both']).optional().describe('Graph direction: imports (what this file uses), importers (who uses this file), both (default: both)'),
             term: z.string().optional().describe('Search term (regex by default; set regex=false to force plain text)'),
             regex: z.boolean().optional().describe('Treat search term as a regex pattern (default: true). Set false to force plain text escaping.'),
             functions: z.boolean().optional().describe('Include per-function line counts in stats output, sorted by size (complexity audit)'),
+            hot: z.boolean().optional().describe('Include top N most-called functions in stats output (orientation primitive). Pair with top=N (default 10).'),
+            diverse: z.boolean().optional().describe('For example: cluster call sites by argument shape and return one representative per cluster. Pair with top=N (default 3).'),
+            git: z.boolean().optional().describe('Attach git enrichment (last modified, author, recent change count last 30d) to about/brief output. Returns gracefully when not a git repo.'),
             add_param: z.string().optional().describe('Parameter name to add (plan command)'),
             remove_param: z.string().optional().describe('Parameter name to remove (plan command)'),
             rename_to: z.string().optional().describe('New function name (plan command)'),
             default_value: z.string().optional().describe('Default value for added parameter (plan command)'),
             stack: z.string().optional().describe('The stack trace text to parse (stacktrace command)'),
-            item: z.number().optional().describe('Item number from context output to expand (e.g. 1, 2, 3)'),
+            item: z.number().int().positive().max(1000000).optional().describe('Item number from context output to expand (e.g. 1, 2, 3). Must be a positive integer.'),
             range: z.string().optional().describe('Line range to extract, e.g. "10-20" or "15" (lines command)'),
             base: z.string().optional().describe('Git ref to diff against (default: HEAD). E.g. "HEAD~3", "main", a commit SHA'),
             staged: z.boolean().optional().describe('Analyze staged changes (diff_impact command)'),
+            deep: z.boolean().optional().describe('Run a deeper analysis (doctor: sample resolution coverage)'),
+            compact: z.boolean().optional().describe('Compact one-line-per-item output for about/context (saves tokens)'),
             case_sensitive: z.boolean().optional().describe('Case-sensitive search (default: false, case-insensitive)'),
             all: z.boolean().optional().describe('Show all results (expand truncated sections). Applies to about, toc, related, trace, and others.'),
             top_level: z.boolean().optional().describe('Show only top-level functions in toc (exclude nested/indented)'),
             class_name: z.string().optional().describe('Class name to scope method analysis (e.g. "MarketDataFetcher" for close)'),
-            limit: z.number().optional().describe('Max results to return (default: 500). Caps find, usages, search, deadcode, api, toc --detailed.'),
-            max_files: z.number().optional().describe('Max files to index (default: 10000). Use for very large codebases.'),
-            max_chars: z.number().optional().describe('Max output chars before truncation. Targeted commands (about, context, smart, etc.): 10K default. Broad commands (toc, entrypoints, deadcode, etc.): 3K default. Max: 100K. Use all=true to bypass all caps.'),
+            limit: z.number().int().positive().max(1000000).optional().describe('Max results to return (default: 500). Caps find, usages, search, deadcode, api, toc --detailed. Must be a positive integer.'),
+            max_files: z.number().int().positive().max(10000000).optional().describe('Max files to index (default: 10000). Use for very large codebases. Must be a positive integer.'),
+            max_chars: z.number().int().positive().max(10000000).optional().describe('Max output chars before truncation. Targeted commands (about, context, smart, etc.): 10K default. Broad commands (toc, entrypoints, deadcode, etc.): 3K default. Max: 100K. Use all=true to bypass all caps.'),
             // Structural search flags (search command)
             type: z.string().optional().describe('Symbol type filter for structural search: function, class, call, method, type. Triggers index-based search.'),
             param: z.string().optional().describe('Filter by parameter name or type (structural search). E.g. "Request", "ctx".'),
@@ -297,7 +313,15 @@ server.registerTool(
             exported: z.boolean().optional().describe('Only exported/public symbols (structural search).'),
             unused: z.boolean().optional().describe('Only symbols with zero callers (structural search).'),
             framework: z.string().optional().describe('Filter entrypoints by framework (e.g. "express", "spring", "flask"). Comma-separated for multiple.'),
-            follow_symlinks: z.boolean().optional().describe('Follow symlinks during file discovery (default: true)')
+            follow_symlinks: z.boolean().optional().describe('Follow symlinks during file discovery (default: true)'),
+            // endpoints command
+            bridge: z.boolean().optional().describe('Match server routes to client requests (endpoints command).'),
+            server_only: z.boolean().optional().describe('Only list server routes (endpoints command).'),
+            client_only: z.boolean().optional().describe('Only list client requests (endpoints command).'),
+            unmatched: z.boolean().optional().describe('Only show unmatched routes/requests (endpoints command).'),
+            method: z.string().optional().describe('Filter by HTTP method (e.g. "GET", "POST") — endpoints command.'),
+            prefix: z.string().optional().describe('Filter routes/requests by path prefix (endpoints command).'),
+            hide_uncertain: z.boolean().optional().describe('Hide uncertain (interpolated-path) bridges (endpoints command).')
 
         })
     },
@@ -309,10 +333,20 @@ server.registerTool(
         const { command: _c, project_dir: _p, ...rawParams } = args;
         const ep = normalizeParams(rawParams);
 
+        // Translate hide_confidence → showConfidence:false (canonical inverse).
+        if (ep.hideConfidence === true && ep.showConfidence === undefined) {
+            ep.showConfidence = false;
+        }
+        delete ep.hideConfidence;
+
         // Strip params not applicable to this command (prevents silent no-ops).
         // Global/core params are always allowed — only optional flags are filtered.
+        // FLAG_APPLICABILITY is keyed by canonical (camelCase) names, but `command`
+        // is the MCP (snake_case) name — resolve to canonical first to avoid
+        // silently skipping multi-word commands (circular_deps, diff_impact, etc.).
         const strippedParams = [];
-        const applicable = FLAG_APPLICABILITY[command];
+        const canonicalCommand = resolveCommand(command, 'mcp') || command;
+        const applicable = FLAG_APPLICABILITY[canonicalCommand];
         if (applicable) {
             // Truly global options — apply to all commands (build/display control).
             // Command-specific params (name, term, stack, range, etc.) are in FLAG_APPLICABILITY.
@@ -450,6 +484,27 @@ server.registerTool(
                 return tr(relText);
             }
 
+            case 'brief': {
+                index = getIndex(project_dir, ep);
+                const { ok, result, error } = execute(index, 'brief', ep);
+                if (!ok) return te(error);
+                return tr(output.formatBrief(result));
+            }
+
+            case 'doctor': {
+                index = getIndex(project_dir, ep);
+                const { ok, result, error } = execute(index, 'doctor', ep);
+                if (!ok) return te(error);
+                return tr(output.formatDoctor(result));
+            }
+
+            case 'check': {
+                index = getIndex(project_dir, ep);
+                const { ok, result, error } = execute(index, 'check', ep);
+                if (!ok) return te(error);
+                return tr(output.formatCheck(result));
+            }
+
             // ── Finding Code ────────────────────────────────────────────
 
             case 'find': {
@@ -536,6 +591,15 @@ server.registerTool(
                 return tr(epText);
             }
 
+            case 'endpoints': {
+                index = getIndex(project_dir, ep);
+                const { ok, result, error, note } = execute(index, 'endpoints', ep);
+                if (!ok) return te(error);
+                let endText = output.formatEndpoints(result, { bridge: result._bridge, unmatched: result._unmatched });
+                if (note) endText += '\n\n' + note;
+                return tr(endText);
+            }
+
             // ── File Dependencies ───────────────────────────────────────
 
             case 'imports': {
@@ -637,6 +701,15 @@ server.registerTool(
                 return tr(statsText);
             }
 
+            case 'audit_async': {
+                index = getIndex(project_dir, ep);
+                const { ok, result, error, note } = execute(index, 'auditAsync', ep);
+                if (!ok) return te(error);
+                let text = output.formatAuditAsync(result);
+                if (note) text += '\n\n' + note;
+                return tr(text);
+            }
+
             // ── Extracting Code (via execute) ────────────────────────────
 
             case 'fn': {
@@ -700,7 +773,9 @@ server.registerTool(
             // getIndex() only saves after build (when callsCache is empty).
             // Commands like context/about/impact populate callsCache lazily,
             // so we save here to avoid re-parsing all files on every MCP session.
-            if (index && index.callsCacheDirty) {
+            // MED-1: also persist when reachability was computed in-process so
+            // long-lived MCP servers carry the BFS result forward to disk.
+            if (index && (index.callsCacheDirty || index.reachabilityDirty)) {
                 try { index.saveCache(); } catch (_) { /* best-effort */ }
                 index.callsCacheDirty = false;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.8.23",
+  "version": "3.8.26",
   "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",
@@ -28,6 +28,14 @@
     "impact-analysis",
     "dead-code",
     "deadcode",
+    "endpoints",
+    "polyglot",
+    "audit",
+    "async",
+    "api-bridge",
+    "http",
+    "route",
+    "fetch",
     "agent-skill",
     "skill",
     "cli",