@navigation-agent/mcp-server 0.1.5 → 0.3.0

package/dist/app/createMcpServer.js

@@ -6,7 +6,7 @@ import { createInspectTreeService } from "../services/inspectTreeService.js";
 import { createListEndpointsService } from "../services/listEndpointsService.js";
 import { createSearchTextService } from "../services/searchTextService.js";
 import { createTraceCallersService } from "../services/traceCallersService.js";
-import { createTraceSymbolService } from "../services/traceSymbolService.js";
+import { createTraceFlowService } from "../services/traceFlowService.js";
 import { registerCodeTools, } from "../tools/registerCodeTools.js";
 function toSdkToolResult(result) {
     return {
@@ -38,7 +38,7 @@ export function createMcpServer(options) {
         workspaceRoot: options.workspaceRoot,
         engineClient,
     });
-    const traceSymbolService = createTraceSymbolService({
+    const traceFlowService = createTraceFlowService({
         workspaceRoot: options.workspaceRoot,
         engineClient,
     });
@@ -52,7 +52,7 @@ export function createMcpServer(options) {
         listEndpointsHandler: (payload) => listEndpointsService.validateAndExecute(payload),
         searchTextHandler: (payload) => searchTextService.validateAndExecute(payload),
         traceCallersHandler: (payload) => traceCallersService.validateAndExecute(payload),
-        traceSymbolHandler: (payload) => traceSymbolService.validateAndExecute(payload),
+        traceFlowHandler: (payload) => traceFlowService.validateAndExecute(payload),
     });
     const sdkServer = new SdkMcpServer({
         name: "navigation-agent-mcp",

package/dist/contracts/public/code.d.ts

@@ -8,7 +8,7 @@ export declare const PUBLIC_SYMBOL_KINDS: readonly ["any", "class", "interface",
 export type PublicSymbolKind = (typeof PUBLIC_SYMBOL_KINDS)[number];
 export declare const MATCH_MODES: readonly ["exact", "fuzzy"];
 export type MatchMode = (typeof MATCH_MODES)[number];
-export declare const CODE_TOOL_NAMES: readonly ["code.inspect_tree", "code.list_endpoints", "code.find_symbol", "code.search_text", "code.trace_symbol", "code.trace_callers"];
+export declare const CODE_TOOL_NAMES: readonly ["code.inspect_tree", "code.list_endpoints", "code.find_symbol", "code.search_text", "code.trace_flow", "code.trace_callers"];
 export type CodeToolName = (typeof CODE_TOOL_NAMES)[number];
 export interface InspectTreeInput {
     path?: string | null;
@@ -50,6 +50,7 @@ export interface PublicSymbolDefinition {
     kind: PublicSymbolKind;
     path: string;
     line: number;
+    lineEnd: number;
     language: PublicLanguage | null;
 }
 export interface FindSymbolData {
@@ -124,25 +125,38 @@ export interface SearchTextData {
     totalMatchCount: number;
     items: SearchTextFileMatch[];
 }
-export interface TraceSymbolInput {
+export interface TraceFlowInput {
     path: string;
     symbol: string;
     language?: PublicLanguage | null;
     framework?: PublicFramework | null;
 }
-export interface TraceSymbolEntrypoint {
+export interface TraceFlowEntrypoint {
     path: string;
     symbol: string;
     language: PublicLanguage | null;
 }
-export interface TraceSymbolFile {
+export interface TraceFlowFile {
     path: string;
     language: PublicLanguage | null;
 }
-export interface TraceSymbolData {
-    entrypoint: TraceSymbolEntrypoint;
+export interface TraceFlowCallee {
+    path: string;
+    line: number;
+    endLine: number;
+    column: number | null;
+    callee: string;
+    calleeSymbol: string | null;
+    relation: string;
+    language: PublicLanguage | null;
+    snippet: string | null;
+    depth: number;
+}
+export interface TraceFlowData {
+    entrypoint: TraceFlowEntrypoint;
     fileCount: number;
-    items: TraceSymbolFile[];
+    items: TraceFlowFile[];
+    callees: TraceFlowCallee[];
 }
 export interface TraceCallersInput {
     path: string;
@@ -553,7 +567,7 @@ export declare const searchTextInputSchema: {
         };
     };
 };
-export declare const traceSymbolInputSchema: {
+export declare const traceFlowInputSchema: {
     readonly type: "object";
     readonly properties: {
         readonly path: {
@@ -943,7 +957,7 @@ export declare const codeToolSchemas: {
             };
         };
     };
-    readonly "code.trace_symbol": {
+    readonly "code.trace_flow": {
         readonly type: "object";
         readonly properties: {
             readonly path: {
@@ -1090,9 +1104,9 @@ export declare function normalizeSearchTextInput(payload: Record<string, unknown
     ok: false;
     issues: ValidationIssue[];
 };
-export declare function normalizeTraceSymbolInput(payload: Record<string, unknown>): {
+export declare function normalizeTraceFlowInput(payload: Record<string, unknown>): {
     ok: true;
-    value: TraceSymbolInput;
+    value: TraceFlowInput;
 } | {
     ok: false;
     issues: ValidationIssue[];

package/dist/contracts/public/code.js

@@ -18,7 +18,7 @@ export const CODE_TOOL_NAMES = [
     "code.list_endpoints",
     "code.find_symbol",
     "code.search_text",
-    "code.trace_symbol",
+    "code.trace_flow",
     "code.trace_callers",
 ];
 const sharedDefs = {
@@ -196,7 +196,7 @@ export const searchTextInputSchema = {
     required: ["query"],
     $defs: sharedDefs,
 };
-export const traceSymbolInputSchema = {
+export const traceFlowInputSchema = {
     type: "object",
     properties: {
         path: { type: "string", minLength: 1 },
@@ -252,7 +252,7 @@ export const codeToolSchemas = {
     "code.list_endpoints": listEndpointsInputSchema,
     "code.find_symbol": findSymbolInputSchema,
     "code.search_text": searchTextInputSchema,
-    "code.trace_symbol": traceSymbolInputSchema,
+    "code.trace_flow": traceFlowInputSchema,
     "code.trace_callers": traceCallersInputSchema,
 };
 export function normalizeInspectTreeInput(payload) {
@@ -351,7 +351,7 @@ export function normalizeSearchTextInput(payload) {
         },
     };
 }
-export function normalizeTraceSymbolInput(payload) {
+export function normalizeTraceFlowInput(payload) {
     const issues = [];
     const scopedPath = normalizeRequiredTrimmedString(payload.path, "path", issues);
     const symbol = normalizeRequiredTrimmedString(payload.symbol, "symbol", issues);

package/dist/engine/protocol.d.ts

@@ -1,5 +1,5 @@
 import type { MatchMode, PublicFramework, PublicLanguage, PublicEndpointKind, PublicSymbolKind } from "../contracts/public/code.ts";
-export declare const ENGINE_CAPABILITIES: readonly ["workspace.inspect_tree", "workspace.find_symbol", "workspace.list_endpoints", "workspace.search_text", "workspace.trace_symbol", "workspace.trace_callers"];
+export declare const ENGINE_CAPABILITIES: readonly ["workspace.inspect_tree", "workspace.find_symbol", "workspace.list_endpoints", "workspace.search_text", "workspace.trace_flow", "workspace.trace_callers"];
 export type EngineCapability = (typeof ENGINE_CAPABILITIES)[number];
 export type AnalyzerLanguage = "auto" | "java" | "typescript" | "python" | "rust";
 export interface InspectTreeEnginePayload {
@@ -57,6 +57,7 @@ export interface FindSymbolEngineItem {
     kind: PublicSymbolKind;
     path: string;
     line: number;
+    lineEnd: number;
     language: PublicLanguage | null;
 }
 export interface FindSymbolEngineResult {
@@ -132,19 +133,32 @@ export interface SearchTextEngineResult {
     totalMatchCount: number;
     truncated: boolean;
 }
-export interface TraceSymbolEnginePayload {
+export interface TraceFlowEnginePayload {
     path: string;
     symbol: string;
     analyzerLanguage: AnalyzerLanguage;
     publicLanguageFilter: PublicLanguage | null;
 }
-export interface TraceSymbolEngineItem {
+export interface TraceFlowEngineItem {
     path: string;
     language: PublicLanguage | null;
 }
-export interface TraceSymbolEngineResult {
+export interface TraceFlowEngineCallee {
+    path: string;
+    line: number;
+    endLine: number;
+    column: number | null;
+    callee: string;
+    calleeSymbol: string | null;
+    relation: string;
+    language: PublicLanguage | null;
+    snippet: string | null;
+    depth: number;
+}
+export interface TraceFlowEngineResult {
     resolvedPath: string | null;
-    items: TraceSymbolEngineItem[];
+    items: TraceFlowEngineItem[];
+    callees: TraceFlowEngineCallee[];
     totalMatched: number;
     truncated: boolean;
 }

package/dist/engine/protocol.js

@@ -3,7 +3,7 @@ export const ENGINE_CAPABILITIES = [
     "workspace.find_symbol",
     "workspace.list_endpoints",
     "workspace.search_text",
-    "workspace.trace_symbol",
+    "workspace.trace_flow",
     "workspace.trace_callers",
 ];
 let requestSequence = 0;

package/dist/index.d.ts

@@ -8,5 +8,5 @@ export * from "./services/inspectTreeService.ts";
 export * from "./services/listEndpointsService.ts";
 export * from "./services/searchTextService.ts";
 export * from "./services/traceCallersService.ts";
-export * from "./services/traceSymbolService.ts";
+export * from "./services/traceFlowService.ts";
 export * from "./tools/registerCodeTools.ts";

package/dist/index.js

@@ -8,5 +8,5 @@ export * from "./services/inspectTreeService.js";
 export * from "./services/listEndpointsService.js";
 export * from "./services/searchTextService.js";
 export * from "./services/traceCallersService.js";
-export * from "./services/traceSymbolService.js";
+export * from "./services/traceFlowService.js";
 export * from "./tools/registerCodeTools.js";

package/dist/services/findSymbolService.js

@@ -56,6 +56,7 @@ function buildSuccessResponse(input, result) {
                 kind: item.kind,
                 path: item.path,
                 line: item.line,
+                lineEnd: item.lineEnd,
                 language: item.language,
             })),
         },

package/dist/services/traceFlowService.d.ts

@@ -0,0 +1,11 @@
+import { type TraceFlowData, type TraceFlowInput } from "../contracts/public/code.ts";
+import { type ResponseEnvelope } from "../contracts/public/common.ts";
+import type { EngineClient } from "../engine/rustEngineClient.ts";
+export interface TraceFlowService {
+    execute(input: TraceFlowInput): Promise<ResponseEnvelope<TraceFlowData>>;
+    validateAndExecute(payload: Record<string, unknown>): Promise<ResponseEnvelope<TraceFlowData>>;
+}
+export declare function createTraceFlowService(options: {
+    workspaceRoot: string;
+    engineClient: EngineClient;
+}): TraceFlowService;

package/dist/services/traceFlowService.js

@@ -0,0 +1,245 @@
+import { normalizeTraceFlowInput, } from "../contracts/public/code.js";
+import { createResponseMeta, } from "../contracts/public/common.js";
+import { nextRequestId, } from "../engine/protocol.js";
+const TOOL_NAME = "code.trace_flow";
+export function createTraceFlowService(options) {
+    return {
+        async execute(input) {
+            let response;
+            try {
+                response = await options.engineClient.request({
+                    id: nextRequestId(),
+                    capability: "workspace.trace_flow",
+                    workspaceRoot: options.workspaceRoot,
+                    payload: {
+                        path: input.path,
+                        symbol: input.symbol,
+                        analyzerLanguage: resolveAnalyzerLanguage(input.language, input.framework),
+                        publicLanguageFilter: resolveEffectiveLanguage(input.language, input.framework),
+                    },
+                });
+            }
+            catch (error) {
+                return buildEngineFailureResponse(input, error);
+            }
+            if (!response.ok) {
+                return buildMappedErrorResponse(input, response.error.code, response.error.message, response.error.details, response.error.retryable);
+            }
+            return buildSuccessResponse(input, response.result);
+        },
+        async validateAndExecute(payload) {
+            const normalized = normalizeTraceFlowInput(payload);
+            if (!normalized.ok) {
+                return buildValidationErrorResponse(normalized.issues);
+            }
+            return this.execute(normalized.value);
+        },
+    };
+}
+function buildSuccessResponse(input, result) {
+    const entrypointPath = result.resolvedPath ?? input.path;
+    const effectiveLanguage = resolveEffectiveLanguage(input.language, input.framework);
+    const fileCount = result.items.length;
+    const calleeCount = result.callees?.length ?? 0;
+    return {
+        tool: TOOL_NAME,
+        status: result.truncated ? "partial" : "ok",
+        summary: buildSummary(input.symbol, entrypointPath, calleeCount),
+        data: {
+            entrypoint: {
+                path: entrypointPath,
+                symbol: input.symbol,
+                language: inferLanguageFromPath(entrypointPath),
+            },
+            fileCount,
+            items: result.items.map((item) => ({
+                path: item.path,
+                language: item.language,
+            })),
+            callees: (result.callees ?? []).map((callee) => ({
+                path: callee.path,
+                line: callee.line,
+                endLine: callee.endLine,
+                column: callee.column,
+                callee: callee.callee,
+                calleeSymbol: callee.calleeSymbol,
+                relation: callee.relation,
+                language: callee.language,
+                snippet: callee.snippet,
+                depth: callee.depth,
+            })),
+        },
+        errors: [],
+        meta: createResponseMeta({
+            query: { ...input },
+            resolvedPath: result.resolvedPath,
+            truncated: result.truncated,
+            counts: {
+                returnedCount: fileCount,
+                totalMatched: result.totalMatched,
+            },
+            detection: {
+                effectiveLanguage,
+                framework: input.framework ?? null,
+            },
+        }),
+    };
+}
+function buildValidationErrorResponse(issues) {
+    return {
+        tool: TOOL_NAME,
+        status: "error",
+        summary: "Request validation failed.",
+        data: emptyData(),
+        errors: [
+            {
+                code: "INVALID_INPUT",
+                message: "One or more input fields are invalid.",
+                retryable: false,
+                suggestion: "Correct the invalid fields and try again.",
+                details: { issues },
+            },
+        ],
+        meta: createResponseMeta({ query: {} }),
+    };
+}
+function buildMappedErrorResponse(input, code, message, details, retryable) {
+    const query = { ...input };
+    if (code === "FILE_NOT_FOUND") {
+        return {
+            tool: TOOL_NAME,
+            status: "error",
+            summary: "Path not found.",
+            data: emptyData(input.path, input.symbol),
+            errors: [
+                {
+                    code,
+                    message,
+                    retryable,
+                    suggestion: "Provide an existing file path inside the workspace root.",
+                    details,
+                },
+            ],
+            meta: createResponseMeta({ query }),
+        };
+    }
+    if (code === "PATH_OUTSIDE_WORKSPACE") {
+        return {
+            tool: TOOL_NAME,
+            status: "error",
+            summary: "Path validation failed.",
+            data: emptyData(input.path, input.symbol),
+            errors: [
+                {
+                    code,
+                    message,
+                    retryable,
+                    suggestion: "Use a file path inside the workspace root.",
+                    details,
+                },
+            ],
+            meta: createResponseMeta({ query }),
+        };
+    }
+    if (code === "UNSUPPORTED_CAPABILITY") {
+        return {
+            tool: TOOL_NAME,
+            status: "error",
+            summary: "Flow trace failed.",
+            data: emptyData(input.path, input.symbol),
+            errors: [
+                {
+                    code: "BACKEND_EXECUTION_FAILED",
+                    message,
+                    retryable,
+                    suggestion: "Verify the engine supports workspace.trace_flow and retry.",
+                    details,
+                },
+            ],
+            meta: createResponseMeta({ query }),
+        };
+    }
+    return {
+        tool: TOOL_NAME,
+        status: "error",
+        summary: "Flow trace failed.",
+        data: emptyData(input.path, input.symbol),
+        errors: [
+            {
+                code,
+                message,
+                retryable,
+                details,
+            },
+        ],
+        meta: createResponseMeta({ query }),
+    };
+}
+function buildEngineFailureResponse(input, error) {
+    return buildMappedErrorResponse(input, "BACKEND_EXECUTION_FAILED", error instanceof Error ? error.message : String(error), {}, false);
+}
+function emptyData(path = "", symbol = "") {
+    return {
+        entrypoint: {
+            path,
+            symbol,
+            language: inferLanguageFromPath(path),
+        },
+        fileCount: 0,
+        items: [],
+        callees: [],
+    };
+}
+function buildSummary(symbol, path, calleeCount) {
+    if (calleeCount === 0) {
+        return `Trace completed for '${symbol}' from '${path}' with no callees found.`;
+    }
+    if (calleeCount === 1) {
+        return `Traced 1 callee for '${symbol}' from '${path}'.`;
+    }
+    return `Traced ${calleeCount} callees for '${symbol}' from '${path}'.`;
+}
+function resolveEffectiveLanguage(language, framework) {
+    if (language) {
+        return language;
+    }
+    if (framework === "react-router") {
+        return "typescript";
+    }
+    if (framework === "spring") {
+        return "java";
+    }
+    return null;
+}
+function resolveAnalyzerLanguage(language, framework) {
+    const effective = resolveEffectiveLanguage(language, framework);
+    if (effective === "java") {
+        return "java";
+    }
+    if (effective === "python") {
+        return "python";
+    }
+    if (effective === "rust") {
+        return "rust";
+    }
+    return "typescript";
+}
+function inferLanguageFromPath(path) {
+    const normalized = path.toLowerCase();
+    if (normalized.endsWith(".ts") || normalized.endsWith(".tsx")) {
+        return "typescript";
+    }
+    if (normalized.endsWith(".js") || normalized.endsWith(".jsx")) {
+        return "javascript";
+    }
+    if (normalized.endsWith(".java")) {
+        return "java";
+    }
+    if (normalized.endsWith(".py")) {
+        return "python";
+    }
+    if (normalized.endsWith(".rs")) {
+        return "rust";
+    }
+    return null;
+}

package/dist/tools/registerCodeTools.d.ts

@@ -15,6 +15,6 @@ export interface RegisterCodeToolsOptions {
     listEndpointsHandler?: (payload: Record<string, unknown>) => Promise<ResponseEnvelope<unknown>>;
     searchTextHandler?: (payload: Record<string, unknown>) => Promise<ResponseEnvelope<unknown>>;
     traceCallersHandler?: (payload: Record<string, unknown>) => Promise<ResponseEnvelope<unknown>>;
-    traceSymbolHandler?: (payload: Record<string, unknown>) => Promise<ResponseEnvelope<unknown>>;
+    traceFlowHandler?: (payload: Record<string, unknown>) => Promise<ResponseEnvelope<unknown>>;
 }
 export declare function registerCodeTools(options: RegisterCodeToolsOptions): RegisteredCodeTool[];

package/dist/tools/registerCodeTools.js

@@ -89,10 +89,10 @@ const toolMetadata = [
         },
     },
     {
-        name: "code.trace_symbol",
-        title: "Trace symbol forward",
-        description: "Trace a symbol forward from a starting file to related workspace files. The starting path must exist inside the workspace.",
-        inputSchema: { ...codeToolSchemas["code.trace_symbol"] },
+        name: "code.trace_flow",
+        title: "Trace execution flow forward",
+        description: "Trace execution flow forward from a starting file and symbol to related workspace files. The starting path must exist inside the workspace.",
+        inputSchema: { ...codeToolSchemas["code.trace_flow"] },
         sdkInputSchema: {
             path: z.string().trim().min(1),
             symbol: z.string().trim().min(1),
@@ -161,14 +161,14 @@ export function registerCodeTools(options) {
                 },
             };
         }
-        if (tool.name === "code.trace_symbol") {
+        if (tool.name === "code.trace_flow") {
             return {
                 ...tool,
                 execute: async (payload) => {
-                    if (!options.traceSymbolHandler) {
-                        throw new Error("Trace symbol migrated handler is scaffolded but not yet wired.");
+                    if (!options.traceFlowHandler) {
+                        throw new Error("Trace flow migrated handler is scaffolded but not yet wired.");
                     }
-                    return options.traceSymbolHandler(payload);
+                    return options.traceFlowHandler(payload);
                 },
             };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navigation-agent/mcp-server",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "description": "MCP server for AI-assisted code navigation — find symbols, trace callers, list endpoints and more.",
   "type": "module",
   "bin": {
@@ -22,11 +22,11 @@
     "check": "tsc --noEmit"
   },
   "optionalDependencies": {
-    "@navigation-agent/mcp-server-linux-x64": "0.1.5",
-    "@navigation-agent/mcp-server-linux-arm64": "0.1.5",
-    "@navigation-agent/mcp-server-darwin-x64": "0.1.5",
-    "@navigation-agent/mcp-server-darwin-arm64": "0.1.5",
-    "@navigation-agent/mcp-server-win32-x64": "0.1.5"
+    "@navigation-agent/mcp-server-linux-x64": "0.3.0",
+    "@navigation-agent/mcp-server-linux-arm64": "0.3.0",
+    "@navigation-agent/mcp-server-darwin-x64": "0.3.0",
+    "@navigation-agent/mcp-server-darwin-arm64": "0.3.0",
+    "@navigation-agent/mcp-server-win32-x64": "0.3.0"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",