@navigation-agent/mcp-server 0.1.0

package/dist/services/searchTextService.js

@@ -0,0 +1,233 @@
+import { normalizeSearchTextInput, } from "../contracts/public/code.js";
+import { createResponseMeta, } from "../contracts/public/common.js";
+import { nextRequestId, } from "../engine/protocol.js";
+const TOOL_NAME = "code.search_text";
+export function createSearchTextService(options) {
+    return {
+        async execute(input) {
+            let response;
+            try {
+                response = await options.engineClient.request({
+                    id: nextRequestId(),
+                    capability: "workspace.search_text",
+                    workspaceRoot: options.workspaceRoot,
+                    payload: {
+                        query: input.query,
+                        path: input.path ?? null,
+                        publicLanguageFilter: resolveEffectiveLanguage(input.language, input.framework),
+                        include: input.include ?? null,
+                        regex: input.regex,
+                        context: input.context,
+                        limit: input.limit,
+                    },
+                });
+            }
+            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 = normalizeSearchTextInput(payload);
+            if (!normalized.ok) {
+                return buildValidationErrorResponse(normalized.issues);
+            }
+            return this.execute(normalized.value);
+        },
+    };
+}
+function buildSuccessResponse(input, result) {
+    const returnedFileCount = result.items.length;
+    const returnedMatchCount = result.items.reduce((total, item) => total + item.matchCount, 0);
+    const effectiveLanguage = resolveEffectiveLanguage(input.language, input.framework);
+    return {
+        tool: TOOL_NAME,
+        status: result.truncated ? "partial" : "ok",
+        summary: buildSummary(input.query, result.totalFileCount, result.totalMatchCount, result.truncated),
+        data: {
+            fileCount: result.truncated ? returnedFileCount : result.totalFileCount,
+            matchCount: result.truncated ? returnedMatchCount : result.totalMatchCount,
+            totalFileCount: result.totalFileCount,
+            totalMatchCount: result.totalMatchCount,
+            items: result.items.map((item) => ({
+                path: item.path,
+                language: item.language,
+                matchCount: item.matchCount,
+                matches: item.matches.map((match) => ({
+                    line: match.line,
+                    text: match.text,
+                    submatches: match.submatches.map((submatch) => ({ ...submatch })),
+                    before: match.before.map((contextLine) => ({ ...contextLine })),
+                    after: match.after.map((contextLine) => ({ ...contextLine })),
+                })),
+            })),
+        },
+        errors: result.truncated
+            ? [
+                {
+                    code: "RESULT_TRUNCATED",
+                    message: `Result set exceeded the requested limit of ${input.limit} files.`,
+                    retryable: false,
+                    suggestion: "Increase limit or narrow the path/include/language filters.",
+                    details: {
+                        returnedFiles: returnedFileCount,
+                        totalFiles: result.totalFileCount,
+                        returnedMatches: returnedMatchCount,
+                        totalMatches: result.totalMatchCount,
+                        limit: input.limit,
+                    },
+                },
+            ]
+            : [],
+        meta: createResponseMeta({
+            query: { ...input },
+            resolvedPath: result.resolvedPath,
+            truncated: result.truncated,
+            counts: {
+                returnedFileCount,
+                totalFileCount: result.totalFileCount,
+                returnedMatchCount,
+                totalMatchCount: result.totalMatchCount,
+            },
+            detection: {
+                effectiveLanguage,
+                framework: input.framework ?? null,
+            },
+        }),
+    };
+}
+function buildValidationErrorResponse(issues) {
+    return {
+        tool: TOOL_NAME,
+        status: "error",
+        summary: "Request validation failed.",
+        data: {
+            fileCount: 0,
+            matchCount: 0,
+            totalFileCount: 0,
+            totalMatchCount: 0,
+            items: [],
+        },
+        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(),
+            errors: [
+                {
+                    code,
+                    message,
+                    retryable,
+                    suggestion: "Provide an existing file or directory 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(),
+            errors: [
+                {
+                    code,
+                    message,
+                    retryable,
+                    suggestion: "Use a path inside the workspace root or omit the path filter.",
+                    details,
+                },
+            ],
+            meta: createResponseMeta({ query }),
+        };
+    }
+    if (code === "UNSUPPORTED_CAPABILITY") {
+        return {
+            tool: TOOL_NAME,
+            status: "error",
+            summary: "Text search failed.",
+            data: emptyData(),
+            errors: [
+                {
+                    code: "BACKEND_EXECUTION_FAILED",
+                    message,
+                    retryable,
+                    suggestion: "Verify the engine supports workspace.search_text and retry.",
+                    details,
+                },
+            ],
+            meta: createResponseMeta({ query }),
+        };
+    }
+    return {
+        tool: TOOL_NAME,
+        status: "error",
+        summary: "Text search failed.",
+        data: emptyData(),
+        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() {
+    return {
+        fileCount: 0,
+        matchCount: 0,
+        totalFileCount: 0,
+        totalMatchCount: 0,
+        items: [],
+    };
+}
+function buildSummary(query, fileCount, matchCount, truncated) {
+    if (matchCount === 0) {
+        return `No text matches found for '${query}'.`;
+    }
+    if (truncated) {
+        return `Found ${matchCount} text matches across ${fileCount} files for '${query}' and returned a truncated subset.`;
+    }
+    if (matchCount === 1) {
+        return `Found 1 text match in 1 file for '${query}'.`;
+    }
+    return `Found ${matchCount} text matches across ${fileCount} files for '${query}'.`;
+}
+function resolveEffectiveLanguage(language, framework) {
+    if (language) {
+        return language;
+    }
+    if (framework === "react-router") {
+        return "typescript";
+    }
+    if (framework === "spring") {
+        return "java";
+    }
+    return null;
+}

package/dist/services/traceCallersService.d.ts

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

package/dist/services/traceCallersService.js

@@ -0,0 +1,256 @@
+import { normalizeTraceCallersInput, } from "../contracts/public/code.js";
+import { createResponseMeta, } from "../contracts/public/common.js";
+import { nextRequestId, } from "../engine/protocol.js";
+const TOOL_NAME = "code.trace_callers";
+const DEFAULT_MAX_DEPTH = 3;
+const MAX_MAX_DEPTH = 8;
+export function createTraceCallersService(options) {
+    return {
+        async execute(input) {
+            let response;
+            try {
+                response = await options.engineClient.request({
+                    id: nextRequestId(),
+                    capability: "workspace.trace_callers",
+                    workspaceRoot: options.workspaceRoot,
+                    payload: {
+                        path: input.path,
+                        symbol: input.symbol,
+                        analyzerLanguage: resolveAnalyzerLanguage(input.language, input.framework),
+                        publicLanguageFilter: resolveEffectiveLanguage(input.language, input.framework),
+                        recursive: input.recursive,
+                        maxDepth: input.recursive ? resolveMaxDepth(input.max_depth) : null,
+                    },
+                });
+            }
+            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 = normalizeTraceCallersInput(payload);
+            if (!normalized.ok) {
+                return buildValidationErrorResponse(normalized.issues);
+            }
+            return this.execute(normalized.value);
+        },
+    };
+}
+function buildSuccessResponse(input, result) {
+    const effectiveLanguage = resolveEffectiveLanguage(input.language, input.framework);
+    const count = result.totalMatched;
+    return {
+        tool: TOOL_NAME,
+        status: result.truncated ? "partial" : "ok",
+        summary: buildSummary(input.symbol, input.path, count, input.recursive),
+        data: {
+            target: {
+                path: input.path,
+                symbol: input.symbol,
+                language: inferLanguageFromPath(input.path),
+            },
+            count,
+            returnedCount: result.items.length,
+            items: result.items,
+            recursive: result.recursive,
+        },
+        errors: result.truncated
+            ? [
+                {
+                    code: "RESULT_TRUNCATED",
+                    message: "Recursive reverse-trace payload exceeded the response safety caps.",
+                    retryable: false,
+                    suggestion: "Retry with a lower max_depth or disable recursive mode.",
+                    details: {
+                        maxDepth: input.recursive ? resolveMaxDepth(input.max_depth) : null,
+                    },
+                },
+            ]
+            : [],
+        meta: createResponseMeta({
+            query: { ...input },
+            resolvedPath: result.resolvedPath,
+            truncated: result.truncated,
+            counts: {
+                returnedCount: result.items.length,
+                totalMatched: count,
+            },
+            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: "Caller trace failed.",
+            data: emptyData(input.path, input.symbol),
+            errors: [
+                {
+                    code: "BACKEND_EXECUTION_FAILED",
+                    message,
+                    retryable,
+                    suggestion: "Verify the engine supports workspace.trace_callers and retry.",
+                    details,
+                },
+            ],
+            meta: createResponseMeta({ query }),
+        };
+    }
+    return {
+        tool: TOOL_NAME,
+        status: "error",
+        summary: "Caller trace failed.",
+        data: emptyData(input.path, input.symbol),
+        errors: [
+            {
+                code: code === "BACKEND_EXECUTION_FAILED" ? code : "BACKEND_EXECUTION_FAILED",
+                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 {
+        target: {
+            path,
+            symbol,
+            language: inferLanguageFromPath(path),
+        },
+        count: 0,
+        returnedCount: 0,
+        items: [],
+        recursive: null,
+    };
+}
+function buildSummary(symbol, path, count, recursive) {
+    if (count === 0) {
+        return `Trace completed for incoming callers of '${symbol}' from '${path}' with no callers found.`;
+    }
+    if (recursive) {
+        if (count === 1) {
+            return `Found 1 incoming caller for '${symbol}' from '${path}' with recursive reverse trace.`;
+        }
+        return `Found ${count} incoming callers for '${symbol}' from '${path}' with recursive reverse trace.`;
+    }
+    if (count === 1) {
+        return `Found 1 incoming caller for '${symbol}' from '${path}'.`;
+    }
+    return `Found ${count} incoming callers for '${symbol}' from '${path}'.`;
+}
+function resolveMaxDepth(maxDepth) {
+    return Math.min(maxDepth ?? DEFAULT_MAX_DEPTH, MAX_MAX_DEPTH);
+}
+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/services/traceSymbolService.d.ts

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