@navigation-agent/mcp-server 0.1.0

package/dist/engine/protocol.d.ts

@@ -0,0 +1,290 @@
+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 type EngineCapability = (typeof ENGINE_CAPABILITIES)[number];
+export type AnalyzerLanguage = "auto" | "java" | "typescript" | "python" | "rust";
+export interface InspectTreeEnginePayload {
+    path: string | null;
+    maxDepth: number;
+    extensions: string[];
+    filePattern: string | null;
+    includeStats: boolean;
+    includeHidden: boolean;
+}
+export interface EngineRequest<TPayload = unknown> {
+    id: string;
+    capability: EngineCapability | string;
+    workspaceRoot: string;
+    payload: TPayload;
+}
+export interface EngineError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    suggestion?: string | null;
+    details: Record<string, unknown>;
+}
+export interface InspectTreeEngineItemStats {
+    sizeBytes: number;
+    modifiedAt: string;
+    isSymlink: boolean;
+}
+export interface InspectTreeEngineItem {
+    path: string;
+    name: string;
+    type: "directory" | "file";
+    depth: number;
+    extension?: string | null;
+    stats?: InspectTreeEngineItemStats | null;
+}
+export interface InspectTreeEngineResult {
+    root: string;
+    items: InspectTreeEngineItem[];
+    truncated: boolean;
+    maxItems: number;
+    ignoredDirectories: string[];
+}
+export interface FindSymbolEnginePayload {
+    symbol: string;
+    path: string | null;
+    analyzerLanguage: AnalyzerLanguage;
+    publicLanguageFilter: PublicLanguage | null;
+    kind: PublicSymbolKind;
+    matchMode: MatchMode;
+    limit: number;
+}
+export interface FindSymbolEngineItem {
+    symbol: string;
+    kind: PublicSymbolKind;
+    path: string;
+    line: number;
+    language: PublicLanguage | null;
+}
+export interface FindSymbolEngineResult {
+    resolvedPath: string | null;
+    items: FindSymbolEngineItem[];
+    totalMatched: number;
+    truncated: boolean;
+}
+export interface ListEndpointsEnginePayload {
+    path: string | null;
+    analyzerLanguage: AnalyzerLanguage;
+    publicLanguageFilter: PublicLanguage | null;
+    publicFrameworkFilter: PublicFramework | null;
+    kind: PublicEndpointKind;
+    limit: number;
+}
+export interface ListEndpointsEngineItem {
+    name: string;
+    kind: string;
+    path: string | null;
+    file: string;
+    line: number;
+    language: PublicLanguage | null;
+    framework: PublicFramework | null;
+}
+export interface ListEndpointsEngineCounts {
+    byKind: Record<string, number>;
+    byLanguage: Record<string, number>;
+    byFramework: Record<string, number>;
+}
+export interface ListEndpointsEngineResult {
+    resolvedPath: string | null;
+    items: ListEndpointsEngineItem[];
+    totalMatched: number;
+    truncated: boolean;
+    counts: ListEndpointsEngineCounts;
+}
+export interface SearchTextEnginePayload {
+    query: string;
+    path: string | null;
+    publicLanguageFilter: PublicLanguage | null;
+    include: string | null;
+    regex: boolean;
+    context: number;
+    limit: number;
+}
+export interface SearchTextEngineContextLine {
+    line: number;
+    text: string;
+}
+export interface SearchTextEngineSubmatch {
+    start: number;
+    end: number;
+    text: string;
+}
+export interface SearchTextEngineMatch {
+    line: number;
+    text: string;
+    submatches: SearchTextEngineSubmatch[];
+    before: SearchTextEngineContextLine[];
+    after: SearchTextEngineContextLine[];
+}
+export interface SearchTextEngineFileMatch {
+    path: string;
+    language: PublicLanguage | null;
+    matchCount: number;
+    matches: SearchTextEngineMatch[];
+}
+export interface SearchTextEngineResult {
+    resolvedPath: string | null;
+    items: SearchTextEngineFileMatch[];
+    totalFileCount: number;
+    totalMatchCount: number;
+    truncated: boolean;
+}
+export interface TraceSymbolEnginePayload {
+    path: string;
+    symbol: string;
+    analyzerLanguage: AnalyzerLanguage;
+    publicLanguageFilter: PublicLanguage | null;
+}
+export interface TraceSymbolEngineItem {
+    path: string;
+    language: PublicLanguage | null;
+}
+export interface TraceSymbolEngineResult {
+    resolvedPath: string | null;
+    items: TraceSymbolEngineItem[];
+    totalMatched: number;
+    truncated: boolean;
+}
+export interface TraceCallersEnginePayload {
+    path: string;
+    symbol: string;
+    analyzerLanguage: AnalyzerLanguage;
+    publicLanguageFilter: PublicLanguage | null;
+    recursive: boolean;
+    maxDepth: number | null;
+}
+export interface TraceCallersEngineTarget {
+    path: string;
+    symbol: string;
+}
+export interface TraceCallersEngineItem {
+    path: string;
+    line: number;
+    column: number | null;
+    caller: string;
+    callerSymbol: string | null;
+    relation: string;
+    language: PublicLanguage | null;
+    snippet: string | null;
+    receiverType: string | null;
+}
+export interface TraceCallersEngineRecursiveVia {
+    relation: string | null;
+    line: number | null;
+    column: number | null;
+    snippet: string | null;
+}
+export interface TraceCallersEngineRecursiveNode {
+    key: string;
+    path: string;
+    symbol: string;
+    depth: number;
+    via: TraceCallersEngineRecursiveVia | null;
+}
+export interface TraceCallersEngineRecursivePathSegment {
+    path: string;
+    symbol: string;
+    depth: number;
+}
+export interface TraceCallersEngineRecursiveCycle {
+    fromKey: string;
+    toKey: string;
+    path: string[];
+}
+export interface TraceCallersEngineRecursiveTruncatedNode {
+    key: string;
+    path: string;
+    symbol: string;
+    depth: number;
+}
+export interface TraceCallersEngineProbableEntryPoint {
+    key: string | null;
+    path: string;
+    symbol: string;
+    depth: number | null;
+    reasons: string[];
+    probable: boolean | null;
+    pathFromTarget: TraceCallersEngineRecursivePathSegment[];
+}
+export interface TraceCallersEngineClassificationRecord {
+    path: string;
+    symbol: string;
+    caller: string;
+    depth: number;
+    line: number;
+    column: number | null;
+    relation: string;
+    language: PublicLanguage | null;
+    receiverType: string | null;
+    snippet: string | null;
+    calls: TraceCallersEngineTarget;
+    pathFromTarget: TraceCallersEngineRecursivePathSegment[];
+}
+export interface TraceCallersEngineImplementationInterface {
+    name: string | null;
+    path: string | null;
+    symbol: string | null;
+}
+export interface TraceCallersEngineImplementationReference {
+    path: string;
+    symbol: string | null;
+}
+export interface TraceCallersEngineImplementationInterfaceChain {
+    kind: string;
+    probable: boolean | null;
+    interface: TraceCallersEngineImplementationInterface | null;
+    implementation: TraceCallersEngineImplementationReference | null;
+    implementations: TraceCallersEngineImplementationReference[];
+    callers: TraceCallersEngineClassificationRecord[];
+}
+export interface TraceCallersEngineRecursiveSummary {
+    directCallerCount: number;
+    indirectCallerCount: number;
+    probablePublicEntryPointCount: number;
+    implementationInterfaceChainCount: number;
+}
+export interface TraceCallersEngineRecursiveClassifications {
+    summary: TraceCallersEngineRecursiveSummary;
+    directCallers: TraceCallersEngineClassificationRecord[];
+    indirectCallers: TraceCallersEngineClassificationRecord[];
+    probablePublicEntryPoints: TraceCallersEngineProbableEntryPoint[];
+    implementationInterfaceChain: TraceCallersEngineImplementationInterfaceChain[];
+}
+export interface TraceCallersEngineRecursiveResult {
+    enabled: boolean;
+    root: TraceCallersEngineRecursiveNode;
+    maxDepth: number;
+    maxDepthObserved: number;
+    nodeCount: number;
+    edgeCount: number;
+    pathCount: number;
+    nodes: TraceCallersEngineRecursiveNode[];
+    adjacency: Record<string, string[]>;
+    paths: TraceCallersEngineRecursivePathSegment[][];
+    cycles: TraceCallersEngineRecursiveCycle[];
+    truncated: TraceCallersEngineRecursiveTruncatedNode[];
+    probableEntryPoints: TraceCallersEngineProbableEntryPoint[];
+    classifications: TraceCallersEngineRecursiveClassifications;
+}
+export interface TraceCallersEngineResult {
+    resolvedPath: string | null;
+    items: TraceCallersEngineItem[];
+    totalMatched: number;
+    truncated: boolean;
+    recursive: TraceCallersEngineRecursiveResult | null;
+}
+export interface EngineSuccess<TResult = unknown> {
+    id: string;
+    ok: true;
+    result: TResult;
+}
+export interface EngineFailure {
+    id: string;
+    ok: false;
+    error: EngineError;
+}
+export type EngineResponse<TResult = unknown> = EngineSuccess<TResult> | EngineFailure;
+export declare function nextRequestId(prefix?: string): string;

package/dist/engine/protocol.js

@@ -0,0 +1,13 @@
+export const ENGINE_CAPABILITIES = [
+    "workspace.inspect_tree",
+    "workspace.find_symbol",
+    "workspace.list_endpoints",
+    "workspace.search_text",
+    "workspace.trace_symbol",
+    "workspace.trace_callers",
+];
+let requestSequence = 0;
+export function nextRequestId(prefix = "req") {
+    requestSequence += 1;
+    return `${prefix}-${requestSequence}`;
+}

package/dist/engine/rustEngineClient.d.ts

@@ -0,0 +1,16 @@
+import type { EngineRequest, EngineResponse } from "./protocol.ts";
+export interface EngineClient {
+    request<TResult = unknown>(request: EngineRequest): Promise<EngineResponse<TResult>>;
+    close(): Promise<void>;
+}
+export interface RustEngineClientOptions {
+    command?: readonly string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare class RustEngineClient implements EngineClient {
+    #private;
+    constructor(options?: RustEngineClientOptions);
+    request<TResult = unknown>(request: EngineRequest): Promise<EngineResponse<TResult>>;
+    close(): Promise<void>;
+}

package/dist/engine/rustEngineClient.js

@@ -0,0 +1,138 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { once } from "node:events";
+import { EOL } from "node:os";
+const _require = createRequire(import.meta.url);
+export class RustEngineClient {
+    #options;
+    #child = null;
+    #pending = new Map();
+    #buffer = "";
+    constructor(options = {}) {
+        this.#options = options;
+    }
+    async request(request) {
+        const child = this.#ensureChild();
+        const responsePromise = new Promise((resolve, reject) => {
+            this.#pending.set(request.id, {
+                resolve: resolve,
+                reject,
+            });
+        });
+        child.stdin.write(`${JSON.stringify(request)}${EOL}`);
+        return responsePromise;
+    }
+    async close() {
+        if (!this.#child) {
+            return;
+        }
+        const child = this.#child;
+        this.#child = null;
+        child.stdin.end();
+        child.kill();
+        await once(child, "exit").catch(() => undefined);
+    }
+    #ensureChild() {
+        if (this.#child) {
+            return this.#child;
+        }
+        const command = resolveEngineCommand(this.#options.command);
+        const [executable, ...args] = command;
+        const child = spawn(executable, args, {
+            cwd: this.#options.cwd ?? process.cwd(),
+            env: { ...process.env, ...this.#options.env },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            this.#buffer += chunk;
+            const lines = this.#buffer.split(/\r?\n/);
+            this.#buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed) {
+                    continue;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(trimmed);
+                }
+                catch (error) {
+                    this.#failAll(new Error(`Rust engine returned invalid JSON: ${error.message}`));
+                    continue;
+                }
+                const pending = this.#pending.get(parsed.id);
+                if (!pending) {
+                    continue;
+                }
+                this.#pending.delete(parsed.id);
+                pending.resolve(parsed);
+            }
+        });
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", () => {
+            // keep stderr attached for debugging without leaking into public protocol handling
+        });
+        child.on("error", (error) => {
+            this.#failAll(error instanceof Error ? error : new Error(String(error)));
+            this.#child = null;
+        });
+        child.on("exit", (code, signal) => {
+            this.#failAll(new Error(`Rust engine exited unexpectedly (code=${code ?? "null"}, signal=${signal ?? "null"}).`));
+            this.#child = null;
+        });
+        this.#child = child;
+        return child;
+    }
+    #failAll(error) {
+        for (const pending of this.#pending.values()) {
+            pending.reject(error);
+        }
+        this.#pending.clear();
+    }
+}
+function resolveEngineCommand(override) {
+    if (override && override.length > 0) {
+        return override;
+    }
+    const configured = process.env.NAVIGATION_MCP_RUST_ENGINE_CMD;
+    if (configured) {
+        const parsed = JSON.parse(configured);
+        if (Array.isArray(parsed) && parsed.every((value) => typeof value === "string")) {
+            return parsed;
+        }
+        throw new Error("NAVIGATION_MCP_RUST_ENGINE_CMD must be a JSON array of strings.");
+    }
+    // Try to find the pre-compiled binary bundled in the platform-specific optional package.
+    const binaryName = process.platform === "win32" ? "navigation-engine.exe" : "navigation-engine";
+    const platformPackages = {
+        "linux-x64": "@navigation-agent/mcp-server-linux-x64",
+        "linux-arm64": "@navigation-agent/mcp-server-linux-arm64",
+        "darwin-x64": "@navigation-agent/mcp-server-darwin-x64",
+        "darwin-arm64": "@navigation-agent/mcp-server-darwin-arm64",
+        "win32-x64": "@navigation-agent/mcp-server-win32-x64",
+    };
+    const pkgName = platformPackages[`${process.platform}-${process.arch}`];
+    if (pkgName) {
+        try {
+            const pkgJsonPath = _require.resolve(`${pkgName}/package.json`);
+            const binaryPath = join(dirname(pkgJsonPath), binaryName);
+            if (existsSync(binaryPath)) {
+                return [binaryPath];
+            }
+        }
+        catch {
+            // Optional package not installed — fall through to dev fallback.
+        }
+    }
+    // Dev fallback: build and run via cargo.
+    return [
+        "cargo",
+        "run",
+        "--quiet",
+        "--manifest-path",
+        "crates/navigation-engine/Cargo.toml",
+    ];
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./app/createMcpServer.ts";
+export * from "./contracts/public/code.ts";
+export * from "./contracts/public/common.ts";
+export * from "./engine/protocol.ts";
+export * from "./engine/rustEngineClient.ts";
+export * from "./services/findSymbolService.ts";
+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 "./tools/registerCodeTools.ts";

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from "./app/createMcpServer.js";
+export * from "./contracts/public/code.js";
+export * from "./contracts/public/common.js";
+export * from "./engine/protocol.js";
+export * from "./engine/rustEngineClient.js";
+export * from "./services/findSymbolService.js";
+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 "./tools/registerCodeTools.js";

package/dist/services/findSymbolService.d.ts

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