@colbymchenry/codegraph-darwin-arm64 0.9.3 → 0.9.5

package/lib/dist/mcp/session.js

@@ -0,0 +1,276 @@
+"use strict";
+/**
+ * MCP per-connection session — speaks the JSON-RPC protocol (initialize,
+ * tools/list, tools/call) over a single {@link JsonRpcTransport}. It owns
+ * per-client state only (which protocol version the client asked for, whether
+ * it advertised `roots`, the one-shot roots/list latch); the heavyweight
+ * resources (CodeGraph, watcher, ToolHandler) live in the shared
+ * {@link MCPEngine} so daemon mode can collapse N inotify sets / DB handles
+ * to one.
+ *
+ * The state-machine itself mirrors what `MCPServer` used to do inline before
+ * issue #411 split it out — the same regression tests in
+ * `__tests__/mcp-initialize.test.ts` still drive this code path.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPSession = void 0;
+const path = __importStar(require("path"));
+const transport_1 = require("./transport");
+const tools_1 = require("./tools");
+const server_instructions_1 = require("./server-instructions");
+const version_1 = require("./version");
+/**
+ * MCP Server Info — kept on the session because some clients log it. The
+ * version tracks the real package version (was a hard-coded '0.1.0').
+ */
+const SERVER_INFO = {
+    name: 'codegraph',
+    version: version_1.CodeGraphPackageVersion,
+};
+/** MCP Protocol Version (latest the server claims). */
+const PROTOCOL_VERSION = '2024-11-05';
+/**
+ * How long to wait for the client's `roots/list` response before giving up
+ * and falling back to the process cwd.
+ */
+const ROOTS_LIST_TIMEOUT_MS = 5000;
+/**
+ * Convert a file:// URI to a filesystem path. Handles URL encoding and
+ * Windows drive letter paths.
+ */
+function fileUriToPath(uri) {
+    try {
+        const url = new URL(uri);
+        let filePath = decodeURIComponent(url.pathname);
+        if (process.platform === 'win32' && /^\/[a-zA-Z]:/.test(filePath)) {
+            filePath = filePath.slice(1);
+        }
+        return path.resolve(filePath);
+    }
+    catch {
+        return uri.replace(/^file:\/\/\/?/, '');
+    }
+}
+/** First usable filesystem path from a `roots/list` result, or null. */
+function firstRootPath(result) {
+    if (!result || typeof result !== 'object')
+        return null;
+    const roots = result.roots;
+    if (!Array.isArray(roots) || roots.length === 0)
+        return null;
+    const first = roots[0];
+    if (typeof first?.uri !== 'string')
+        return null;
+    return fileUriToPath(first.uri);
+}
+/**
+ * One MCP client's view of the server. Created fresh per stdio launch
+ * (direct mode) or per socket connection (daemon mode).
+ */
+class MCPSession {
+    transport;
+    engine;
+    clientSupportsRoots = false;
+    rootsAttempted = false;
+    resolvePromise = null;
+    explicitProjectPath;
+    constructor(transport, engine, opts = {}) {
+        this.transport = transport;
+        this.engine = engine;
+        this.explicitProjectPath = opts.explicitProjectPath ?? null;
+    }
+    /**
+     * Start handling messages from the transport. Returns immediately — the
+     * session lives for as long as the transport is open.
+     */
+    start() {
+        this.transport.start(this.handleMessage.bind(this));
+    }
+    /**
+     * Tear down the session. Does NOT touch the engine (the engine may serve
+     * other sessions) or call `process.exit` (the daemon decides when to exit).
+     */
+    stop() {
+        this.transport.stop();
+    }
+    /** Underlying transport — exposed for daemon-side close hooks. */
+    getTransport() {
+        return this.transport;
+    }
+    async handleMessage(message) {
+        const isRequest = 'id' in message;
+        switch (message.method) {
+            case 'initialize':
+                if (isRequest)
+                    await this.handleInitialize(message);
+                break;
+            case 'initialized':
+                // Notification that client has finished initialization — no action needed.
+                break;
+            case 'tools/list':
+                if (isRequest)
+                    await this.handleToolsList(message);
+                break;
+            case 'tools/call':
+                if (isRequest)
+                    await this.handleToolsCall(message);
+                break;
+            case 'ping':
+                if (isRequest)
+                    this.transport.sendResult(message.id, {});
+                break;
+            default:
+                if (isRequest) {
+                    this.transport.sendError(message.id, transport_1.ErrorCodes.MethodNotFound, `Method not found: ${message.method}`);
+                }
+        }
+    }
+    async handleInitialize(request) {
+        const params = request.params;
+        this.clientSupportsRoots = !!params?.capabilities?.roots;
+        // Explicit project signal, strongest first: client-provided rootUri /
+        // workspaceFolders (LSP-style), else the --path the server was launched
+        // with. cwd is NOT used here — we defer it so a roots/list answer can
+        // win over it. See issue #196.
+        let explicitPath = null;
+        if (params?.rootUri) {
+            explicitPath = fileUriToPath(params.rootUri);
+        }
+        else if (params?.workspaceFolders?.[0]?.uri) {
+            explicitPath = fileUriToPath(params.workspaceFolders[0].uri);
+        }
+        else if (this.explicitProjectPath) {
+            explicitPath = this.explicitProjectPath;
+        }
+        // Respond to the handshake BEFORE doing any heavy init — see issue #172.
+        this.transport.sendResult(request.id, {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: { tools: {} },
+            serverInfo: SERVER_INFO,
+            instructions: server_instructions_1.SERVER_INSTRUCTIONS,
+        });
+        if (explicitPath) {
+            // Kick off engine init in the background. If another session in the
+            // same daemon already opened the project, `ensureInitialized` is a
+            // ~free no-op — N concurrent clients pay exactly one open.
+            this.resolvePromise = this.engine.ensureInitialized(explicitPath);
+        }
+    }
+    async handleToolsList(request) {
+        await this.retryInitIfNeeded();
+        this.transport.sendResult(request.id, {
+            tools: this.engine.getToolHandler().getTools(),
+        });
+    }
+    async handleToolsCall(request) {
+        const params = request.params;
+        if (!params || !params.name) {
+            this.transport.sendError(request.id, transport_1.ErrorCodes.InvalidParams, 'Missing tool name');
+            return;
+        }
+        const toolName = params.name;
+        const toolArgs = params.arguments || {};
+        const tool = tools_1.tools.find((t) => t.name === toolName);
+        if (!tool) {
+            this.transport.sendError(request.id, transport_1.ErrorCodes.InvalidParams, `Unknown tool: ${toolName}`);
+            return;
+        }
+        await this.retryInitIfNeeded();
+        const result = await this.engine.getToolHandler().execute(toolName, toolArgs);
+        this.transport.sendResult(request.id, result);
+    }
+    /**
+     * Lazy default-project resolution. Three layers:
+     *   1. await the in-flight init kicked off from `handleInitialize` (if any);
+     *   2. if still uninitialized and we never asked the client for its roots,
+     *      do so now (one-shot); fall back to cwd if the client lacks roots;
+     *   3. last-resort: re-walk from the best candidate — picks up projects
+     *      that were `codegraph init`'d *after* the server started.
+     */
+    async retryInitIfNeeded() {
+        if (this.resolvePromise) {
+            try {
+                await this.resolvePromise;
+            }
+            catch { /* fall through to retry */ }
+            this.resolvePromise = null;
+        }
+        if (this.engine.hasDefaultCodeGraph())
+            return;
+        const hint = this.explicitProjectPath ?? this.engine.getProjectPath();
+        if (!hint && !this.rootsAttempted) {
+            this.rootsAttempted = true;
+            this.resolvePromise = this.clientSupportsRoots
+                ? this.initFromRoots()
+                : this.engine.ensureInitialized(process.cwd());
+            try {
+                await this.resolvePromise;
+            }
+            catch { /* fall through */ }
+            this.resolvePromise = null;
+            if (this.engine.hasDefaultCodeGraph())
+                return;
+        }
+        // Last resort: walk from the best candidate (sync open). Picks up
+        // projects that appeared after the server started.
+        const candidate = hint ?? process.cwd();
+        this.engine.retryInitializeSync(candidate);
+    }
+    /**
+     * Ask the client for its workspace root via `roots/list` and open the
+     * first one. Falls back to `process.cwd()` on timeout or empty answer.
+     */
+    async initFromRoots() {
+        let target = process.cwd();
+        try {
+            const result = await this.transport.request('roots/list', undefined, ROOTS_LIST_TIMEOUT_MS);
+            const rootPath = firstRootPath(result);
+            if (rootPath) {
+                target = rootPath;
+            }
+            else {
+                process.stderr.write('[CodeGraph MCP] Client returned no workspace roots; falling back to process cwd.\n');
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[CodeGraph MCP] roots/list request failed (${msg}); falling back to process cwd.\n`);
+        }
+        await this.engine.ensureInitialized(target);
+    }
+}
+exports.MCPSession = MCPSession;
+//# sourceMappingURL=session.js.map

package/lib/dist/mcp/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/mcp/session.ts"],"names":[],"mappings":"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"}

package/lib/dist/mcp/tools.d.ts

@@ -4,6 +4,7 @@
  * Defines the tools exposed by the CodeGraph MCP server.
  */
 import CodeGraph from '../index';
+import type { PendingFile } from '../sync';
 /**
  * Calculate the recommended number of codegraph_explore calls based on project size.
  * Larger codebases need more exploration calls to cover their surface area,
@@ -51,6 +52,19 @@ export interface ExploreOutputBudget {
     includeBudgetNote: boolean;
 }
 export declare function getExploreOutputBudget(fileCount: number): ExploreOutputBudget;
+/**
+ * Per-file staleness banner emitted at the top of a tool response when the
+ * file watcher has pending events for files referenced by the response.
+ * The agent uses this to fall back to Read for those specific files
+ * without waiting for the debounced sync (issue #403).
+ */
+export declare function formatStaleBanner(stale: PendingFile[]): string;
+/**
+ * Compact footer listing pending files that are NOT referenced in this
+ * response. Gives the agent a complete project-wide freshness picture
+ * without bloating the main banner.
+ */
+export declare function formatStaleFooter(stale: PendingFile[]): string;
 /**
  * MCP Tool definition
  */
@@ -98,6 +112,7 @@ export declare class ToolHandler {
     private cg;
     private projectCache;
     private defaultProjectHint;
+    private worktreeMismatchCache;
     constructor(cg: CodeGraph | null);
     /**
      * Update the default CodeGraph instance (e.g. after lazy initialization)
@@ -112,10 +127,22 @@ export declare class ToolHandler {
      * Whether a default CodeGraph instance is available
      */
     hasDefaultCodeGraph(): boolean;
+    /**
+     * Optional allowlist of exposed tools, parsed from the CODEGRAPH_MCP_TOOLS
+     * env var (comma-separated short names, e.g. "trace,search,node,context").
+     * Unset/empty → every tool is exposed. Lets an operator (or an A/B harness)
+     * trim the tool surface without rebuilding the client config; the ablated
+     * tool is then truly absent from ListTools rather than merely denied on call.
+     * Matching is on the short form, so "trace" and "codegraph_trace" both work.
+     */
+    private toolAllowlist;
+    /** Whether a tool name passes the CODEGRAPH_MCP_TOOLS allowlist (if any). */
+    private isToolAllowed;
     /**
      * Get tool definitions with dynamic descriptions based on project size.
      * The codegraph_explore tool description includes a budget recommendation
-     * scaled to the number of indexed files.
+     * scaled to the number of indexed files. Honors the CODEGRAPH_MCP_TOOLS
+     * allowlist so a trimmed surface is reflected in ListTools.
      */
     getTools(): ToolDefinition[];
     /**
@@ -133,9 +160,53 @@ export declare class ToolHandler {
      */
     closeAll(): void;
     /**
-     * Validate that a value is a non-empty string
+     * Validate that a value is a non-empty string within length bounds.
+     *
+     * The `maxLength` cap protects against MCP clients that ship huge
+     * payloads (10MB+ query strings either by accident or maliciously).
+     * Without this, a single oversized input can pin the FTS5 index or
+     * exhaust memory before any real work runs.
      */
     private validateString;
+    /**
+     * Validate an optional path-like string input. Returns the value if
+     * valid (or undefined), or a ToolResult with the error.
+     */
+    private validateOptionalPath;
+    /**
+     * Cached git worktree/index mismatch for a tool call's effective project.
+     *
+     * The "effective project" is what the request targets: an explicit
+     * `projectPath` arg, else the directory the server resolved its default
+     * project from (`defaultProjectHint`), else cwd. Memoized per start path —
+     * see `worktreeMismatchCache`. Best-effort: if the project can't be resolved
+     * (e.g. nothing initialized yet), it reports "no mismatch" so a tool is never
+     * broken by this check.
+     */
+    private worktreeMismatchFor;
+    /**
+     * Prefix a successful read-tool result with a compact worktree-mismatch
+     * notice when the resolved index belongs to a different git working tree than
+     * the caller's (issue #155). Without this, an agent in a nested worktree
+     * silently trusts main-branch results. No-op on error results and when there
+     * is no mismatch. `codegraph_status` is excluded — it embeds its own verbose
+     * warning — so it stays out of this path.
+     */
+    private withWorktreeNotice;
+    /**
+     * Annotate a successful read-tool result with per-file staleness — the
+     * non-blocking answer to issue #403. The file watcher tracks every event
+     * it sees per path; here we intersect "files referenced in this response"
+     * against that pending set and prepend a compact banner so the agent can
+     * fall back to Read for those *specific* files without waiting for the
+     * debounced sync to fire. Other pending files in the project (not
+     * referenced by this response) get a small footer so the agent has a
+     * complete picture without bloating the banner.
+     *
+     * Cost when nothing is pending — the common case — is one boolean check.
+     * No I/O, no parsing of markdown beyond a per-pending-file substring scan.
+     */
+    private withStalenessNotice;
     /**
      * Execute a tool by name
      */
@@ -164,6 +235,53 @@ export declare class ToolHandler {
      * Handle codegraph_impact
      */
     private handleImpact;
+    /**
+     * Handle codegraph_trace — shortest CALL PATH between two symbols.
+     *
+     * Exposes GraphTraverser.findPath: the chain of functions from `from` to `to`,
+     * each hop annotated with file:line and the call-site line. This is the
+     * capability grep/Read structurally cannot provide. When no static path
+     * exists, the chain has almost certainly broken at dynamic dispatch
+     * (callbacks, descriptors, metaclasses) — we say so and surface the start
+     * symbol's outgoing calls so the agent bridges the one missing hop with
+     * codegraph_node rather than blindly reading.
+     */
+    private handleTrace;
+    /**
+     * Describe a synthesized (dynamic-dispatch) edge for human output: how the
+     * callback was wired up — the bridge static parsing can't see. Returns null
+     * for ordinary static edges. Used by trace + the node trail so a synthesized
+     * hop reads as "registered via onUpdate at App.tsx:3148", not a bare arrow.
+     */
+    private synthEdgeNote;
+    /**
+     * Read one trimmed source line at "relpath:line" (relative to the project
+     * root). `cache` holds split file contents so a multi-hop trace reads each
+     * file at most once. Returns null if the file/line can't be resolved.
+     */
+    private sourceLineAt;
+    /**
+     * Read a hop's body — filePath lines [startLine..endLine] — for inlining into
+     * a trace, capped (lines + chars) so the whole path stays path-scoped even on
+     * a 7-hop chain. Dedents to the body's own indentation and marks truncation.
+     * Shares `cache` with sourceLineAt so each file is read at most once per trace.
+     */
+    private sourceRangeAt;
+    /**
+     * Flow-from-named-symbols: an agent's codegraph_explore query is a bag of
+     * symbol names that usually spans the flow it's investigating (e.g.
+     * "PmsProductController getList PmsProductService list PmsProductServiceImpl").
+     * Surface the longest call chain AMONG those named symbols — scoped to what the
+     * agent explicitly named, so (unlike a fuzzy relevance set) there's no
+     * wrong-feature wandering. Rides synthesized edges, so controller→service-
+     * interface→impl shows up. Returns '' if no chain of >=3 nodes exists.
+     *
+     * Ambiguous tokens (Java `list` → dozens of nodes) are disambiguated by
+     * CO-NAMING: the agent names the class too, so we keep only `list` candidates
+     * whose qualifiedName contains another named token (`PmsProductServiceImpl::list`),
+     * dropping unrelated `OmsOrderService::list`.
+     */
+    private buildFlowFromNamedSymbols;
     /**
      * Handle codegraph_explore — deep exploration in a single call
      *
@@ -180,6 +298,16 @@ export declare class ToolHandler {
      * Handle codegraph_node
      */
     private handleNode;
+    /**
+     * Build the "trail" for a symbol: its direct callees (what it calls) and
+     * callers (what calls it), each with file:line — so codegraph_node doubles as
+     * the structural Grep→Read→expand primitive: a spot PLUS where to go next.
+     * Capped to stay cheap. Walk the graph by calling codegraph_node on a trail
+     * entry; no Read needed for covered hops. Empty edges on a non-leaf often mean
+     * dynamic dispatch the static graph couldn't resolve — that absence is itself
+     * a signal (read that one hop) rather than a dead end.
+     */
+    private formatTrail;
     /**
      * Handle codegraph_status
      */

package/lib/dist/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"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"}