@navigation-agent/mcp-server 0.1.0

package/dist/services/findSymbolService.js

@@ -0,0 +1,224 @@
+import { normalizeFindSymbolInput, } from "../contracts/public/code.js";
+import { createResponseMeta, } from "../contracts/public/common.js";
+import { nextRequestId, } from "../engine/protocol.js";
+const TOOL_NAME = "code.find_symbol";
+export function createFindSymbolService(options) {
+    return {
+        async execute(input) {
+            let response;
+            try {
+                response = await options.engineClient.request({
+                    id: nextRequestId(),
+                    capability: "workspace.find_symbol",
+                    workspaceRoot: options.workspaceRoot,
+                    payload: {
+                        symbol: input.symbol,
+                        path: input.path ?? null,
+                        analyzerLanguage: resolveAnalyzerLanguage(input.language, input.framework),
+                        publicLanguageFilter: resolveEffectiveLanguage(input.language, input.framework),
+                        kind: input.kind,
+                        matchMode: input.match,
+                        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 = normalizeFindSymbolInput(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;
+    const returnedCount = result.items.length;
+    return {
+        tool: TOOL_NAME,
+        status: result.truncated ? "partial" : "ok",
+        summary: buildSummary(input.symbol, count, result.truncated),
+        data: {
+            count,
+            returnedCount,
+            totalMatched: result.totalMatched,
+            items: result.items.map((item) => ({
+                symbol: item.symbol,
+                kind: item.kind,
+                path: item.path,
+                line: item.line,
+                language: item.language,
+            })),
+        },
+        errors: result.truncated
+            ? [
+                {
+                    code: "RESULT_TRUNCATED",
+                    message: `Result set exceeded the requested limit of ${input.limit} items.`,
+                    retryable: false,
+                    suggestion: "Increase limit or narrow the path/language filter.",
+                    details: {
+                        returned: returnedCount,
+                        total: result.totalMatched,
+                        limit: input.limit,
+                    },
+                },
+            ]
+            : [],
+        meta: createResponseMeta({
+            query: { ...input },
+            resolvedPath: result.resolvedPath,
+            truncated: result.truncated,
+            counts: {
+                returnedCount,
+                totalMatched: result.totalMatched,
+            },
+            detection: {
+                effectiveLanguage,
+                framework: input.framework ?? null,
+            },
+        }),
+    };
+}
+function buildValidationErrorResponse(issues) {
+    return {
+        tool: TOOL_NAME,
+        status: "error",
+        summary: "Request validation failed.",
+        data: { count: 0, returnedCount: 0, totalMatched: 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: { count: 0, returnedCount: 0, totalMatched: 0, items: [] },
+            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: { count: 0, returnedCount: 0, totalMatched: 0, items: [] },
+            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: "Symbol analysis failed.",
+            data: { count: 0, returnedCount: 0, totalMatched: 0, items: [] },
+            errors: [
+                {
+                    code: "BACKEND_EXECUTION_FAILED",
+                    message,
+                    retryable,
+                    suggestion: "Verify the engine supports workspace.find_symbol and retry.",
+                    details,
+                },
+            ],
+            meta: createResponseMeta({ query }),
+        };
+    }
+    return {
+        tool: TOOL_NAME,
+        status: "error",
+        summary: "Symbol analysis failed.",
+        data: { count: 0, returnedCount: 0, totalMatched: 0, items: [] },
+        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 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";
+    }
+    if (effective === "typescript" || effective === "javascript") {
+        return "typescript";
+    }
+    return "auto";
+}
+function buildSummary(symbol, count, truncated) {
+    if (count === 0) {
+        return `No symbol definitions found for '${symbol}'.`;
+    }
+    if (truncated) {
+        return `Found ${count} symbol definitions for '${symbol}' and returned a truncated subset.`;
+    }
+    if (count === 1) {
+        return `Found 1 symbol definition for '${symbol}'.`;
+    }
+    return `Found ${count} symbol definitions for '${symbol}'.`;
+}

package/dist/services/inspectTreeService.d.ts

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

package/dist/services/inspectTreeService.js

@@ -0,0 +1,191 @@
+import { normalizeInspectTreeInput, } from "../contracts/public/code.js";
+import { createResponseMeta, } from "../contracts/public/common.js";
+import { nextRequestId, } from "../engine/protocol.js";
+export function createInspectTreeService(options) {
+    return {
+        async execute(input) {
+            let response;
+            try {
+                response = await options.engineClient.request({
+                    id: nextRequestId(),
+                    capability: "workspace.inspect_tree",
+                    workspaceRoot: options.workspaceRoot,
+                    payload: {
+                        path: input.path ?? null,
+                        maxDepth: input.max_depth,
+                        extensions: input.extensions,
+                        filePattern: input.file_pattern ?? null,
+                        includeStats: input.include_stats,
+                        includeHidden: input.include_hidden,
+                    },
+                });
+            }
+            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 {
+                tool: "code.inspect_tree",
+                status: response.result.truncated ? "partial" : "ok",
+                summary: buildSummary(response.result.root, response.result.items.length, response.result.truncated),
+                data: mapInspectTreeResult(response.result),
+                errors: response.result.truncated
+                    ? [
+                        {
+                            code: "RESULT_TRUNCATED",
+                            message: `Tree inspection hit the safety cap of ${response.result.maxItems} items.`,
+                            retryable: false,
+                            details: {
+                                returned: response.result.items.length,
+                                maxItems: response.result.maxItems,
+                            },
+                        },
+                    ]
+                    : [],
+                meta: createResponseMeta({
+                    query: { ...input },
+                    resolvedPath: response.result.root,
+                    truncated: response.result.truncated,
+                    counts: {
+                        returnedCount: response.result.items.length,
+                        totalMatched: response.result.truncated
+                            ? null
+                            : response.result.items.length,
+                    },
+                    detection: {
+                        includeHidden: input.include_hidden ? "true" : "false",
+                        stats: input.include_stats ? "true" : "false",
+                    },
+                }),
+            };
+        },
+        async validateAndExecute(payload) {
+            const normalized = normalizeInspectTreeInput(payload);
+            if (!normalized.ok) {
+                return buildValidationErrorResponse(normalized.issues);
+            }
+            return this.execute(normalized.value);
+        },
+    };
+}
+function mapInspectTreeResult(result) {
+    return {
+        root: result.root,
+        entryCount: result.items.length,
+        items: result.items.map((item) => ({
+            path: item.path,
+            name: item.name,
+            type: item.type,
+            depth: item.depth,
+            extension: item.extension ?? null,
+            stats: item.stats ?? null,
+        })),
+    };
+}
+function buildValidationErrorResponse(issues) {
+    return {
+        tool: "code.inspect_tree",
+        status: "error",
+        summary: "Request validation failed.",
+        data: { root: ".", entryCount: 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: "code.inspect_tree",
+            status: "error",
+            summary: "Path not found.",
+            data: { root: ".", entryCount: 0, items: [] },
+            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: "code.inspect_tree",
+            status: "error",
+            summary: "Path validation failed.",
+            data: { root: ".", entryCount: 0, items: [] },
+            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: "code.inspect_tree",
+            status: "error",
+            summary: "Inspect tree execution failed.",
+            data: { root: input.path ?? ".", entryCount: 0, items: [] },
+            errors: [
+                {
+                    code: "BACKEND_EXECUTION_FAILED",
+                    message,
+                    retryable,
+                    suggestion: "Verify the engine supports workspace.inspect_tree and retry.",
+                    details,
+                },
+            ],
+            meta: createResponseMeta({ query }),
+        };
+    }
+    return {
+        tool: "code.inspect_tree",
+        status: "error",
+        summary: "Inspect tree execution failed.",
+        data: { root: input.path ?? ".", entryCount: 0, items: [] },
+        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 buildSummary(root, entryCount, truncated) {
+    if (entryCount === 0) {
+        return `No tree entries found under '${root}'.`;
+    }
+    if (truncated) {
+        return `Inspected ${entryCount} tree entries under '${root}' and returned a truncated subset.`;
+    }
+    if (entryCount === 1) {
+        return `Inspected 1 tree entry under '${root}'.`;
+    }
+    return `Inspected ${entryCount} tree entries under '${root}'.`;
+}

package/dist/services/listEndpointsService.d.ts

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

package/dist/services/listEndpointsService.js

@@ -0,0 +1,233 @@
+import { normalizeListEndpointsInput, } from "../contracts/public/code.js";
+import { createResponseMeta, } from "../contracts/public/common.js";
+import { nextRequestId, } from "../engine/protocol.js";
+const TOOL_NAME = "code.list_endpoints";
+export function createListEndpointsService(options) {
+    return {
+        async execute(input) {
+            let response;
+            try {
+                response = await options.engineClient.request({
+                    id: nextRequestId(),
+                    capability: "workspace.list_endpoints",
+                    workspaceRoot: options.workspaceRoot,
+                    payload: {
+                        path: input.path ?? null,
+                        analyzerLanguage: resolveAnalyzerLanguage(input.language, input.framework),
+                        publicLanguageFilter: resolveEffectiveLanguage(input.language, input.framework),
+                        publicFrameworkFilter: input.framework ?? null,
+                        kind: input.kind,
+                        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 = normalizeListEndpointsInput(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 totalCount = result.totalMatched;
+    const returnedCount = result.items.length;
+    return {
+        tool: TOOL_NAME,
+        status: result.truncated ? "partial" : "ok",
+        summary: buildSummary(totalCount, result.truncated, input.kind),
+        data: {
+            totalCount,
+            returnedCount,
+            counts: mapCounts(result.counts),
+            items: result.items.map((item) => ({
+                name: item.name,
+                kind: item.kind,
+                path: item.path ?? null,
+                file: item.file,
+                line: item.line,
+                language: item.language ?? null,
+                framework: item.framework ?? null,
+            })),
+        },
+        errors: result.truncated
+            ? [
+                {
+                    code: "RESULT_TRUNCATED",
+                    message: `Result set exceeded the requested limit of ${input.limit} items.`,
+                    retryable: false,
+                    suggestion: "Increase limit or narrow the path/language/framework filter.",
+                    details: {
+                        returned: returnedCount,
+                        total: result.totalMatched,
+                        limit: input.limit,
+                    },
+                },
+            ]
+            : [],
+        meta: createResponseMeta({
+            query: { ...input },
+            resolvedPath: result.resolvedPath,
+            truncated: result.truncated,
+            counts: {
+                returnedCount,
+                totalMatched: result.totalMatched,
+            },
+            detection: {
+                effectiveLanguage,
+                framework: input.framework ?? null,
+            },
+        }),
+    };
+}
+function mapCounts(counts) {
+    return {
+        byKind: counts.byKind,
+        byLanguage: counts.byLanguage,
+        byFramework: counts.byFramework,
+    };
+}
+function buildValidationErrorResponse(issues) {
+    return {
+        tool: TOOL_NAME,
+        status: "error",
+        summary: "Request validation failed.",
+        data: { totalCount: 0, returnedCount: 0, counts: { byKind: {}, byLanguage: {}, byFramework: {} }, 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: { totalCount: 0, returnedCount: 0, counts: { byKind: {}, byLanguage: {}, byFramework: {} }, items: [] },
+            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: { totalCount: 0, returnedCount: 0, counts: { byKind: {}, byLanguage: {}, byFramework: {} }, items: [] },
+            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: "Endpoint analysis failed.",
+            data: { totalCount: 0, returnedCount: 0, counts: { byKind: {}, byLanguage: {}, byFramework: {} }, items: [] },
+            errors: [
+                {
+                    code: "BACKEND_EXECUTION_FAILED",
+                    message,
+                    retryable,
+                    suggestion: "Verify the engine supports workspace.list_endpoints and retry.",
+                    details,
+                },
+            ],
+            meta: createResponseMeta({ query }),
+        };
+    }
+    return {
+        tool: TOOL_NAME,
+        status: "error",
+        summary: "Endpoint analysis failed.",
+        data: { totalCount: 0, returnedCount: 0, counts: { byKind: {}, byLanguage: {}, byFramework: {} }, items: [] },
+        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 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";
+    }
+    if (effective === "typescript" || effective === "javascript") {
+        return "typescript";
+    }
+    return "auto";
+}
+function buildSummary(count, truncated, kind) {
+    const kindLabel = kind === "any" ? "endpoints" : `${kind} endpoints`;
+    if (count === 0) {
+        return `No${kindLabel} found.`;
+    }
+    if (truncated) {
+        return `Found ${count} ${kindLabel} and returned a truncated subset.`;
+    }
+    if (count === 1) {
+        return `Found 1 ${kindLabel.replace(/s$/, "")}.`;
+    }
+    return `Found ${count} ${kindLabel}.`;
+}

package/dist/services/searchTextService.d.ts

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