feat: expand MCP tool surface (#39)

* feat: expand MCP tool surface

* refactor: trim MCP navigation tools

Author: benvinegar

src/mcp/client.ts

@@ -1,4 +1,12 @@
-import type { AppliedCommentResult, HunkSessionRegistration, HunkSessionSnapshot, SessionClientMessage, SessionServerMessage } from "./types";
+import type {
+  AppliedCommentResult,
+  HunkSessionRegistration,
+  HunkSessionSnapshot,
+  NavigatedSelectionResult,
+  SessionClientMessage,
+  SessionCommandResult,
+  SessionServerMessage,
+} from "./types";
 import { HUNK_SESSION_SOCKET_PATH, resolveHunkMcpConfig } from "./config";
 import { isHunkDaemonHealthy, isLoopbackPortReachable, launchHunkDaemon, waitForHunkDaemonHealth } from "./daemonLauncher";
 
@@ -9,6 +17,7 @@ const HEARTBEAT_INTERVAL_MS = 10_000;
 
 export interface HunkAppBridge {
   applyComment: (message: Extract<SessionServerMessage, { command: "comment" }>) => Promise<AppliedCommentResult>;
+  navigateToHunk: (message: Extract<SessionServerMessage, { command: "navigate_to_hunk" }>) => Promise<NavigatedSelectionResult>;
 }
 
 /** Keep one running Hunk TUI session registered with the local MCP daemon. */
@@ -220,7 +229,7 @@ export class HunkHostClient {
     }
 
     try {
-      const result = await this.bridge.applyComment(message);
+      const result = await this.dispatchCommand(message);
       this.send({
         type: "command-result",
         requestId: message.requestId,
@@ -237,6 +246,19 @@ export class HunkHostClient {
     }
   }
 
+  private dispatchCommand(message: SessionServerMessage): Promise<SessionCommandResult> {
+    if (!this.bridge) {
+      throw new Error("Hunk MCP bridge is not connected.");
+    }
+
+    switch (message.command) {
+      case "comment":
+        return this.bridge.applyComment(message);
+      case "navigate_to_hunk":
+        return this.bridge.navigateToHunk(message);
+    }
+  }
+
   private async flushQueuedMessages() {
     if (!this.bridge || this.queuedMessages.length === 0) {
       return;

src/mcp/daemonState.ts

@@ -1,9 +1,21 @@
 import { randomUUID } from "node:crypto";
-import type { AppliedCommentResult, CommentToolInput, HunkSessionRegistration, HunkSessionSnapshot, ListedSession } from "./types";
+import type {
+  AppliedCommentResult,
+  CommentToolInput,
+  HunkSessionRegistration,
+  HunkSessionSnapshot,
+  ListedSession,
+  NavigateToHunkToolInput,
+  NavigatedSelectionResult,
+  SelectedSessionContext,
+  SessionCommandResult,
+  SessionServerMessage,
+  SessionTargetInput,
+} from "./types";
 
 interface PendingCommand {
   sessionId: string;
-  resolve: (result: AppliedCommentResult) => void;
+  resolve: (result: SessionCommandResult) => void;
   reject: (error: Error) => void;
   timeout: Timer;
 }
@@ -29,6 +41,14 @@ function describeSessionChoices(sessions: ListedSession[]) {
   return sessions.map((session) => `${session.sessionId} (${session.title})`).join(", ");
 }
 
+function findSelectedFile(session: ListedSession) {
+  return session.files.find(
+    (file) => file.id === session.snapshot.selectedFileId
+      || file.path === session.snapshot.selectedFilePath
+      || file.previousPath === session.snapshot.selectedFilePath,
+  ) ?? null;
+}
+
 /** Resolve which live Hunk session one external command should target. */
 export function resolveSessionTarget(sessions: ListedSession[], selector: SessionTargetSelector) {
   if (selector.sessionId) {
@@ -98,6 +118,29 @@ export class HunkDaemonState {
     return resolveSessionTarget(this.listSessions(), selector);
   }
 
+  getSelectedContext(selector: SessionTargetSelector): SelectedSessionContext {
+    const session = this.getSession(selector);
+    const selectedFile = findSelectedFile(session);
+
+    return {
+      sessionId: session.sessionId,
+      title: session.title,
+      sourceLabel: session.sourceLabel,
+      repoRoot: session.repoRoot,
+      inputKind: session.inputKind,
+      selectedFile,
+      selectedHunk: selectedFile
+        ? {
+            index: session.snapshot.selectedHunkIndex,
+            oldRange: session.snapshot.selectedHunkOldRange,
+            newRange: session.snapshot.selectedHunkNewRange,
+          }
+        : null,
+      showAgentNotes: session.snapshot.showAgentNotes,
+      liveCommentCount: session.snapshot.liveCommentCount,
+    };
+  }
+
   getPendingCommandCount() {
     return this.pendingCommands.size;
   }
@@ -182,52 +225,25 @@ export class HunkDaemonState {
     return removed;
   }
 
-  async sendComment(input: CommentToolInput) {
-    const session = resolveSessionTarget(this.listSessions(), {
-      sessionId: input.sessionId,
-      repoRoot: input.repoRoot,
-    });
-    const requestId = randomUUID();
-
-    return new Promise<AppliedCommentResult>((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.pendingCommands.delete(requestId);
-        reject(new Error("Timed out waiting for the Hunk session to apply the comment."));
-      }, 15_000);
-
-      this.pendingCommands.set(requestId, {
-        sessionId: session.sessionId,
-        resolve,
-        reject,
-        timeout,
-      });
-
-      const entry = this.sessions.get(session.sessionId);
-      if (!entry) {
-        clearTimeout(timeout);
-        this.pendingCommands.delete(requestId);
-        reject(new Error("The targeted Hunk session is no longer connected."));
-        return;
-      }
+  sendComment(input: CommentToolInput) {
+    return this.sendCommand<AppliedCommentResult, "comment">(
+      { sessionId: input.sessionId, repoRoot: input.repoRoot },
+      "comment",
+      input,
+      "Timed out waiting for the Hunk session to apply the comment.",
+    );
+  }
 
-      try {
-        entry.socket.send(
-          JSON.stringify({
-            type: "command",
-            requestId,
-            command: "comment",
-            input,
-          }),
-        );
-      } catch (error) {
-        clearTimeout(timeout);
-        this.pendingCommands.delete(requestId);
-        reject(error instanceof Error ? error : new Error("The targeted Hunk session could not receive the command."));
-      }
-    });
+  sendNavigateToHunk(input: NavigateToHunkToolInput) {
+    return this.sendCommand<NavigatedSelectionResult, "navigate_to_hunk">(
+      { sessionId: input.sessionId, repoRoot: input.repoRoot },
+      "navigate_to_hunk",
+      input,
+      "Timed out waiting for the Hunk session to navigate to the requested hunk.",
+    );
   }
 
-  handleCommandResult(message: { requestId: string; ok: boolean; result?: AppliedCommentResult; error?: string }) {
+  handleCommandResult(message: { requestId: string; ok: boolean; result?: SessionCommandResult; error?: string }) {
     const pending = this.pendingCommands.get(message.requestId);
     if (!pending) {
       return;
@@ -255,6 +271,53 @@ export class HunkDaemonState {
     this.sessions.clear();
   }
 
+  private sendCommand<ResultType extends SessionCommandResult, CommandName extends SessionServerMessage["command"]>(
+    selector: SessionTargetInput,
+    command: CommandName,
+    input: Extract<SessionServerMessage, { command: CommandName }>["input"],
+    timeoutMessage: string,
+  ) {
+    const session = resolveSessionTarget(this.listSessions(), selector);
+    const requestId = randomUUID();
+
+    return new Promise<ResultType>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingCommands.delete(requestId);
+        reject(new Error(timeoutMessage));
+      }, 15_000);
+
+      this.pendingCommands.set(requestId, {
+        sessionId: session.sessionId,
+        resolve: (result) => resolve(result as ResultType),
+        reject,
+        timeout,
+      });
+
+      const entry = this.sessions.get(session.sessionId);
+      if (!entry) {
+        clearTimeout(timeout);
+        this.pendingCommands.delete(requestId);
+        reject(new Error("The targeted Hunk session is no longer connected."));
+        return;
+      }
+
+      try {
+        const message = {
+          type: "command",
+          requestId,
+          command,
+          input,
+        } as Extract<SessionServerMessage, { command: CommandName }>;
+
+        entry.socket.send(JSON.stringify(message));
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pendingCommands.delete(requestId);
+        reject(error instanceof Error ? error : new Error("The targeted Hunk session could not receive the command."));
+      }
+    });
+  }
+
   private removeSession(sessionId: string, reason: string) {
     const entry = this.sessions.get(sessionId);
     if (!entry) {

src/mcp/server.ts

@@ -15,6 +15,24 @@ interface McpTransportEntry {
   transport: WebStandardStreamableHTTPServerTransport;
 }
 
+const sessionSelectorSchema = z.object({
+  sessionId: z.string().optional().describe("Explicit Hunk session id."),
+  repoRoot: z.string().optional().describe("Repo root fallback when exactly one session matches."),
+});
+
+const navigateToHunkSchema = sessionSelectorSchema.extend({
+  filePath: z.string().describe("Diff file path as shown by Hunk."),
+  hunkIndex: z.number().int().nonnegative().optional().describe("0-based hunk index within the file."),
+  side: z.enum(["old", "new"]).optional().describe("Optional diff side when resolving by line number."),
+  line: z.number().int().positive().optional().describe("Optional 1-based diff line number when resolving by line number."),
+}).refine(
+  (input) => input.hunkIndex !== undefined || (input.side !== undefined && input.line !== undefined),
+  {
+    error: "Provide either hunkIndex or both side and line.",
+    path: ["hunkIndex"],
+  },
+);
+
 function formatToolJson(value: unknown) {
   return JSON.stringify(value, null, 2);
 }
@@ -74,10 +92,7 @@ function createHunkMcpServer(state: HunkDaemonState) {
     {
       title: "Get one live Hunk session",
       description: "Fetch details for one live Hunk session by session id or repo root.",
-      inputSchema: z.object({
-        sessionId: z.string().optional().describe("Explicit Hunk session id."),
-        repoRoot: z.string().optional().describe("Repo root fallback when exactly one session matches."),
-      }) as any,
+      inputSchema: sessionSelectorSchema as any,
     } as any,
     (async (input: { sessionId?: string; repoRoot?: string }) => {
       const session = state.getSession({ sessionId: input.sessionId, repoRoot: input.repoRoot });
@@ -91,14 +106,57 @@ function createHunkMcpServer(state: HunkDaemonState) {
     }) as any,
   );
 
+  server.registerTool(
+    "get_selected_context",
+    {
+      title: "Get the selected file and hunk",
+      description: "Inspect which file and hunk the live Hunk session is currently focused on.",
+      inputSchema: sessionSelectorSchema as any,
+    } as any,
+    (async (input: { sessionId?: string; repoRoot?: string }) => {
+      const context = state.getSelectedContext({ sessionId: input.sessionId, repoRoot: input.repoRoot });
+
+      return {
+        content: textContent(formatToolJson(context)),
+        structuredContent: {
+          context,
+        },
+      };
+    }) as any,
+  );
+
+  server.registerTool(
+    "navigate_to_hunk",
+    {
+      title: "Focus one diff hunk",
+      description: "Move the live Hunk session to one diff hunk by index or by a specific diff line.",
+      inputSchema: navigateToHunkSchema as any,
+    } as any,
+    (async (input: {
+      sessionId?: string;
+      repoRoot?: string;
+      filePath: string;
+      hunkIndex?: number;
+      side?: "old" | "new";
+      line?: number;
+    }) => {
+      const result = await state.sendNavigateToHunk(input);
+
+      return {
+        content: textContent(formatToolJson(result)),
+        structuredContent: {
+          result,
+        },
+      };
+    }) as any,
+  );
+
   server.registerTool(
     "comment",
     {
       title: "Comment on a live Hunk diff",
       description: "Attach an inline review note to a specific diff line in a live Hunk session.",
-      inputSchema: z.object({
-        sessionId: z.string().optional().describe("Explicit Hunk session id."),
-        repoRoot: z.string().optional().describe("Repo root fallback when exactly one session matches."),
+      inputSchema: sessionSelectorSchema.extend({
         filePath: z.string().describe("Diff file path as shown by Hunk."),
         side: z.enum(["old", "new"]).describe("Which side of the diff the line belongs to."),
         line: z.number().int().positive().describe("1-based diff line number on the chosen side."),

src/mcp/sessionRegistration.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { AppBootstrap } from "../core/types";
+import { hunkLineRange } from "../core/liveComments";
 import type { HunkSessionRegistration, HunkSessionSnapshot } from "./types";
 
 function inferRepoRoot(bootstrap: AppBootstrap) {
@@ -32,10 +33,16 @@ export function createSessionRegistration(bootstrap: AppBootstrap): HunkSessionR
 
 /** Start with an empty-but-valid snapshot until the UI reports its first selection. */
 export function createInitialSessionSnapshot(bootstrap: AppBootstrap): HunkSessionSnapshot {
+  const firstFile = bootstrap.changeset.files[0];
+  const firstHunk = firstFile?.metadata.hunks[0];
+  const firstRange = firstHunk ? hunkLineRange(firstHunk) : null;
+
   return {
-    selectedFileId: bootstrap.changeset.files[0]?.id,
-    selectedFilePath: bootstrap.changeset.files[0]?.path,
+    selectedFileId: firstFile?.id,
+    selectedFilePath: firstFile?.path,
     selectedHunkIndex: 0,
+    selectedHunkOldRange: firstRange?.oldRange,
+    selectedHunkNewRange: firstRange?.newRange,
     showAgentNotes: bootstrap.initialShowAgentNotes ?? false,
     liveCommentCount: 0,
     updatedAt: new Date().toISOString(),