@navigation-agent/mcp-server 0.1.0

package/dist/services/traceSymbolService.js

@@ -0,0 +1,231 @@
+import { normalizeTraceSymbolInput, } from "../contracts/public/code.js";
+import { createResponseMeta, } from "../contracts/public/common.js";
+import { nextRequestId, } from "../engine/protocol.js";
+const TOOL_NAME = "code.trace_symbol";
+export function createTraceSymbolService(options) {
+    return {
+        async execute(input) {
+            let response;
+            try {
+                response = await options.engineClient.request({
+                    id: nextRequestId(),
+                    capability: "workspace.trace_symbol",
+                    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 = normalizeTraceSymbolInput(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;
+    return {
+        tool: TOOL_NAME,
+        status: result.truncated ? "partial" : "ok",
+        summary: buildSummary(input.symbol, entrypointPath, result.totalMatched),
+        data: {
+            entrypoint: {
+                path: entrypointPath,
+                symbol: input.symbol,
+                language: inferLanguageFromPath(entrypointPath),
+            },
+            fileCount,
+            items: result.items.map((item) => ({
+                path: item.path,
+                language: item.language,
+            })),
+        },
+        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: "Symbol trace failed.",
+            data: emptyData(input.path, input.symbol),
+            errors: [
+                {
+                    code: "BACKEND_EXECUTION_FAILED",
+                    message,
+                    retryable,
+                    suggestion: "Verify the engine supports workspace.trace_symbol and retry.",
+                    details,
+                },
+            ],
+            meta: createResponseMeta({ query }),
+        };
+    }
+    return {
+        tool: TOOL_NAME,
+        status: "error",
+        summary: "Symbol 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: [],
+    };
+}
+function buildSummary(symbol, path, fileCount) {
+    if (fileCount === 0) {
+        return `Trace completed for '${symbol}' from '${path}' with no related files found.`;
+    }
+    if (fileCount === 1) {
+        return `Traced 1 related file for '${symbol}' from '${path}'.`;
+    }
+    return `Traced ${fileCount} related files 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

@@ -0,0 +1,20 @@
+import { type CodeToolName } from "../contracts/public/code.ts";
+import type { ResponseEnvelope } from "../contracts/public/common.ts";
+import * as z from "zod/v4";
+export interface RegisteredCodeTool {
+    name: CodeToolName;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    sdkInputSchema: Record<string, z.ZodType>;
+    execute(payload: Record<string, unknown>): Promise<ResponseEnvelope<unknown>>;
+}
+export interface RegisterCodeToolsOptions {
+    inspectTreeHandler?: (payload: Record<string, unknown>) => Promise<ResponseEnvelope<unknown>>;
+    findSymbolHandler?: (payload: Record<string, unknown>) => Promise<ResponseEnvelope<unknown>>;
+    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>>;
+}
+export declare function registerCodeTools(options: RegisterCodeToolsOptions): RegisteredCodeTool[];

package/dist/tools/registerCodeTools.js

@@ -0,0 +1,188 @@
+import { codeToolSchemas, MATCH_MODES, PUBLIC_ENDPOINT_KINDS, PUBLIC_FRAMEWORKS, PUBLIC_LANGUAGES, PUBLIC_SYMBOL_KINDS, } from "../contracts/public/code.js";
+import * as z from "zod/v4";
+const toolMetadata = [
+    {
+        name: "code.inspect_tree",
+        title: "Inspect workspace tree",
+        description: "Inspect the workspace file tree without reading file contents. Supports path scoping, depth limits, extension filters, filename globs, and optional stats.",
+        inputSchema: { ...codeToolSchemas["code.inspect_tree"] },
+        sdkInputSchema: {
+            path: z
+                .string()
+                .nullable()
+                .optional()
+                .default(null)
+                .describe("Optional workspace-relative or absolute file/directory scope."),
+            max_depth: z
+                .int()
+                .min(0)
+                .max(20)
+                .optional()
+                .default(3)
+                .describe("Maximum depth relative to the resolved scope root."),
+            extensions: z
+                .array(z.string())
+                .nullable()
+                .optional()
+                .default(null)
+                .describe("Optional file extension filter such as ['.py', '.ts']. Directories remain visible."),
+            file_pattern: z
+                .string()
+                .nullable()
+                .optional()
+                .default(null)
+                .describe("Optional filename glob such as '*.py'."),
+            include_stats: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Include size, modified time, and symlink metadata."),
+            include_hidden: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Include hidden entries except the hard ignore list."),
+        },
+    },
+    {
+        name: "code.list_endpoints",
+        title: "List endpoints and routes",
+        description: "List backend endpoints and frontend routes in the workspace. Supports path scoping plus language, framework, kind, and limit filters.",
+        inputSchema: { ...codeToolSchemas["code.list_endpoints"] },
+        sdkInputSchema: {
+            path: z.string().nullable().optional().default(null),
+            language: z.enum(PUBLIC_LANGUAGES).nullable().optional().default(null),
+            framework: z.enum(PUBLIC_FRAMEWORKS).nullable().optional().default(null),
+            kind: z.enum(PUBLIC_ENDPOINT_KINDS).optional().default("any"),
+            limit: z.int().min(1).max(200).optional().default(50),
+        },
+    },
+    {
+        name: "code.find_symbol",
+        title: "Find symbol definitions",
+        description: "Locate symbol definitions in the workspace by name. Supports exact or fuzzy matching, path scoping, and language/framework/kind filtering.",
+        inputSchema: { ...codeToolSchemas["code.find_symbol"] },
+        sdkInputSchema: {
+            symbol: z.string().trim().min(1),
+            language: z.enum(PUBLIC_LANGUAGES).nullable().optional().default(null),
+            framework: z.enum(PUBLIC_FRAMEWORKS).nullable().optional().default(null),
+            kind: z.enum(PUBLIC_SYMBOL_KINDS).optional().default("any"),
+            match: z.enum(MATCH_MODES).optional().default("exact"),
+            path: z.string().nullable().optional().default(null),
+            limit: z.int().min(1).max(200).optional().default(50),
+        },
+    },
+    {
+        name: "code.search_text",
+        title: "Search text",
+        description: "Search text or regex patterns across the workspace with file, language, path, and context controls.",
+        inputSchema: { ...codeToolSchemas["code.search_text"] },
+        sdkInputSchema: {
+            query: z.string().trim().min(1),
+            path: z.string().nullable().optional().default(null),
+            language: z.enum(PUBLIC_LANGUAGES).nullable().optional().default(null),
+            framework: z.enum(PUBLIC_FRAMEWORKS).nullable().optional().default(null),
+            include: z.string().nullable().optional().default(null),
+            regex: z.boolean().optional().default(false),
+            context: z.int().min(0).max(10).optional().default(1),
+            limit: z.int().min(1).max(200).optional().default(50),
+        },
+    },
+    {
+        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"] },
+        sdkInputSchema: {
+            path: z.string().trim().min(1),
+            symbol: z.string().trim().min(1),
+            language: z.enum(PUBLIC_LANGUAGES).nullable().optional().default(null),
+            framework: z.enum(PUBLIC_FRAMEWORKS).nullable().optional().default(null),
+        },
+    },
+    {
+        name: "code.trace_callers",
+        title: "Trace incoming callers",
+        description: "Trace incoming callers for a symbol from a starting file. Recursive mode supports reverse traversal up to a bounded max_depth and may return a partial response for safety.",
+        inputSchema: { ...codeToolSchemas["code.trace_callers"] },
+        sdkInputSchema: {
+            path: z.string().trim().min(1),
+            symbol: z.string().trim().min(1),
+            language: z.enum(PUBLIC_LANGUAGES).nullable().optional().default(null),
+            framework: z.enum(PUBLIC_FRAMEWORKS).nullable().optional().default(null),
+            recursive: z.boolean().optional().default(false),
+            max_depth: z.int().min(1).max(8).nullable().optional().default(null),
+        },
+    },
+];
+export function registerCodeTools(options) {
+    return toolMetadata.map((tool) => {
+        if (tool.name === "code.inspect_tree") {
+            return {
+                ...tool,
+                execute: async (payload) => {
+                    if (!options.inspectTreeHandler) {
+                        throw new Error("Inspect tree migrated handler is scaffolded but not yet wired.");
+                    }
+                    return options.inspectTreeHandler(payload);
+                },
+            };
+        }
+        if (tool.name === "code.find_symbol") {
+            return {
+                ...tool,
+                execute: async (payload) => {
+                    if (!options.findSymbolHandler) {
+                        throw new Error("Find symbol migrated handler is scaffolded but not yet wired.");
+                    }
+                    return options.findSymbolHandler(payload);
+                },
+            };
+        }
+        if (tool.name === "code.list_endpoints") {
+            return {
+                ...tool,
+                execute: async (payload) => {
+                    if (!options.listEndpointsHandler) {
+                        throw new Error("List endpoints migrated handler is scaffolded but not yet wired.");
+                    }
+                    return options.listEndpointsHandler(payload);
+                },
+            };
+        }
+        if (tool.name === "code.search_text") {
+            return {
+                ...tool,
+                execute: async (payload) => {
+                    if (!options.searchTextHandler) {
+                        throw new Error("Search text migrated handler is scaffolded but not yet wired.");
+                    }
+                    return options.searchTextHandler(payload);
+                },
+            };
+        }
+        if (tool.name === "code.trace_symbol") {
+            return {
+                ...tool,
+                execute: async (payload) => {
+                    if (!options.traceSymbolHandler) {
+                        throw new Error("Trace symbol migrated handler is scaffolded but not yet wired.");
+                    }
+                    return options.traceSymbolHandler(payload);
+                },
+            };
+        }
+        if (tool.name === "code.trace_callers") {
+            return {
+                ...tool,
+                execute: async (payload) => {
+                    if (!options.traceCallersHandler) {
+                        throw new Error("Trace callers migrated handler is scaffolded but not yet wired.");
+                    }
+                    return options.traceCallersHandler(payload);
+                },
+            };
+        }
+        throw new Error(`Tool '${tool.name}' is not implemented.`);
+    });
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@navigation-agent/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for AI-assisted code navigation — find symbols, trace callers, list endpoints and more.",
+  "type": "module",
+  "bin": {
+    "navigation-mcp": "./dist/bin/navigation-mcp.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "node --experimental-strip-types ./src/bin/navigation-mcp.ts --transport stdio",
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/add-shebang.mjs dist/bin/navigation-mcp.js",
+    "test": "node --experimental-strip-types --test ./test/**/*.spec.ts",
+    "check": "tsc --noEmit"
+  },
+  "optionalDependencies": {
+    "@navigation-agent/mcp-server-linux-x64": "0.1.0",
+    "@navigation-agent/mcp-server-linux-arm64": "0.1.0",
+    "@navigation-agent/mcp-server-darwin-x64": "0.1.0",
+    "@navigation-agent/mcp-server-darwin-arm64": "0.1.0",
+    "@navigation-agent/mcp-server-win32-x64": "0.1.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/j0k3r-dev-rgl/navigation-agent-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "ai",
+    "code-navigation",
+    "typescript",
+    "rust"
+  ]
+}