feat(mcp): show + snippet MCP tools (Tracer 5 of 6)

Wires the show + snippet CLI verbs as MCP tools per Q-1 settled. Both follow the established cmd-* ↔ register*Tool pattern from PR #35; both reuse the same engine helpers (findSymbolsByName, buildShowResult, buildSnippetResult) so output shape is verbatim from each tool's CLI counterpart's --json envelope.

- registerShowTool — args {name, kind?, in?}, returns the {matches, disambiguation?} envelope. Tool description teaches: 'Use snippet for source text; use query with LIKE for fuzzy lookup' so agents know when to reach for which tool.

- registerSnippetTool — args {name, kind?, in?}, returns the same envelope with source/stale/missing on each match. Description spells out the stale semantics (read + flag, agent decides) since that's the one non-obvious bit.

Both tools route the in arg through toProjectRelative(opts.root, args.in) so MCP callers get the same path-shape leniency as the CLI (--in ./src/cli/, --in src/cli, --in src/cli/cmd-show.ts all work identically).

8 new in-process MCP tests via @modelcontextprotocol/sdk's InMemoryTransport: tools/list lists both, single-match envelope, multi-match disambiguation, in-filter narrows, unknown-name returns empty, snippet source on fresh file (stale: false), stale flag on hash drift, missing flag on rm'd file.

Total now 38 MCP tests pass.

Author: SutuSebastian

src/application/mcp-server.test.ts

@@ -625,3 +625,193 @@ describe("MCP server — resources", () => {
     }
   });
 });
+
+describe("MCP server — show + snippet tools", () => {
+  function seedSymbol(opts: {
+    file: string;
+    name: string;
+    kind?: string;
+    lineStart?: number;
+    lineEnd?: number;
+  }) {
+    const db = openDb();
+    try {
+      db.run(
+        `INSERT INTO symbols (file_path, name, kind, line_start, line_end, signature, is_exported, is_default_export)
+         VALUES (?, ?, ?, ?, ?, ?, 1, 0)`,
+        [
+          opts.file,
+          opts.name,
+          opts.kind ?? "function",
+          opts.lineStart ?? 1,
+          opts.lineEnd ?? 1,
+          `${opts.kind ?? "function"} ${opts.name}(): void`,
+        ],
+      );
+    } finally {
+      closeDb(db);
+    }
+  }
+
+  it("lists show + snippet in tools/list", async () => {
+    const { client, server } = await makeClient();
+    try {
+      const tools = await client.listTools();
+      const names = tools.tools.map((t) => t.name);
+      expect(names).toContain("show");
+      expect(names).toContain("snippet");
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("show returns {matches} envelope for single match", async () => {
+    seedSymbol({ file: "src/a.ts", name: "myFn", lineStart: 5, lineEnd: 10 });
+    const { client, server } = await makeClient();
+    try {
+      const r = await client.callTool({
+        name: "show",
+        arguments: { name: "myFn" },
+      });
+      const json = readJson(r);
+      expect(json.matches).toHaveLength(1);
+      expect(json.matches[0]).toMatchObject({
+        name: "myFn",
+        file_path: "src/a.ts",
+        line_start: 5,
+        line_end: 10,
+      });
+      expect(json.disambiguation).toBeUndefined();
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("show adds disambiguation block for multi-match", async () => {
+    seedSymbol({ file: "src/a.ts", name: "shared", kind: "function" });
+    seedSymbol({ file: "src/b.ts", name: "shared", kind: "const" });
+    const { client, server } = await makeClient();
+    try {
+      const r = await client.callTool({
+        name: "show",
+        arguments: { name: "shared" },
+      });
+      const json = readJson(r);
+      expect(json.matches).toHaveLength(2);
+      expect(json.disambiguation).toMatchObject({
+        n: 2,
+        by_kind: { function: 1, const: 1 },
+        files: ["src/a.ts", "src/b.ts"],
+      });
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("show with `in` filter narrows to one file", async () => {
+    seedSymbol({ file: "src/a.ts", name: "shared" });
+    seedSymbol({ file: "src/b.ts", name: "shared" });
+    const { client, server } = await makeClient();
+    try {
+      const r = await client.callTool({
+        name: "show",
+        arguments: { name: "shared", in: "src/a.ts" },
+      });
+      const json = readJson(r);
+      expect(json.matches).toHaveLength(1);
+      expect(json.matches[0].file_path).toBe("src/a.ts");
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("show returns empty matches when name unknown", async () => {
+    const { client, server } = await makeClient();
+    try {
+      const r = await client.callTool({
+        name: "show",
+        arguments: { name: "definitely-not-a-real-symbol-xyz" },
+      });
+      const json = readJson(r);
+      expect(json.matches).toEqual([]);
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("snippet returns source text from disk + stale: false on fresh file", async () => {
+    // Write a real file matching the seeded `files` row in the bench setup
+    // (src/a.ts already exists with hash 'h1' but content "export const A = 1;\n").
+    // Seed a symbol pointing at line 1.
+    seedSymbol({
+      file: "src/a.ts",
+      name: "A",
+      kind: "const",
+      lineStart: 1,
+      lineEnd: 1,
+    });
+    // The bench uses content_hash = 'h1' which DOES NOT match hashContent("export const A = 1;\n"),
+    // so the engine will report stale: true. To test stale: false we'd need to update the row's hash.
+    const db = openDb();
+    try {
+      const realHash = (
+        require("../hash") as typeof import("../hash")
+      ).hashContent("export const A = 1;\n");
+      db.run("UPDATE files SET content_hash = ? WHERE path = ?", [
+        realHash,
+        "src/a.ts",
+      ]);
+    } finally {
+      closeDb(db);
+    }
+    const { client, server } = await makeClient();
+    try {
+      const r = await client.callTool({
+        name: "snippet",
+        arguments: { name: "A" },
+      });
+      const json = readJson(r);
+      expect(json.matches).toHaveLength(1);
+      expect(json.matches[0].source).toBe("export const A = 1;");
+      expect(json.matches[0].stale).toBe(false);
+      expect(json.matches[0].missing).toBe(false);
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("snippet flags stale: true when on-disk content drifts from indexed hash", async () => {
+    // Bench file content is "export const A = 1;\n" but indexed hash is 'h1' (mismatch).
+    seedSymbol({ file: "src/a.ts", name: "A", lineStart: 1, lineEnd: 1 });
+    const { client, server } = await makeClient();
+    try {
+      const r = await client.callTool({
+        name: "snippet",
+        arguments: { name: "A" },
+      });
+      const json = readJson(r);
+      expect(json.matches[0].stale).toBe(true);
+      // Source is still returned per Q-6 settled.
+      expect(json.matches[0].source).toBe("export const A = 1;");
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("snippet flags missing: true when file is gone on disk", async () => {
+    seedSymbol({ file: "src/b.ts", name: "B", lineStart: 1, lineEnd: 1 });
+    // src/b.ts is in the indexed `files` but no actual file on disk in bench setup.
+    const { client, server } = await makeClient();
+    try {
+      const r = await client.callTool({
+        name: "snippet",
+        arguments: { name: "B" },
+      });
+      const json = readJson(r);
+      expect(json.matches[0].missing).toBe(true);
+      expect(json.matches[0].source).toBeUndefined();
+    } finally {
+      await server.close();
+    }
+  });
+});

src/application/mcp-server.ts

@@ -17,7 +17,9 @@ import { resolveAgentsTemplateDir } from "../agents-init";
 // once a second consumer (HTTP API) needs them.
 import { resolveAuditBaselines } from "../cli/cmd-audit";
 import { buildContextEnvelope } from "../cli/cmd-context";
-import { computeValidateRows } from "../cli/cmd-validate";
+import { buildShowResult } from "../cli/cmd-show";
+import { buildSnippetResult } from "../cli/cmd-snippet";
+import { computeValidateRows, toProjectRelative } from "../cli/cmd-validate";
 import {
   getQueryRecipeActions,
   getQueryRecipeCatalogEntry,
@@ -41,6 +43,7 @@ import { runAudit } from "./audit-engine";
 import { getCurrentCommit } from "./index-engine";
 import { executeQuery } from "./query-engine";
 import { runCodemapIndex } from "./run-index";
+import { findSymbolsByName } from "./show-engine";
 
 /**
  * MCP server engine — owns the tool / resource registry. CLI shell
@@ -154,6 +157,8 @@ export function createMcpServer(opts: ServerOpts): McpServer {
   registerSaveBaselineTool(server, opts);
   registerListBaselinesTool(server, opts);
   registerDropBaselineTool(server, opts);
+  registerShowTool(server, opts);
+  registerSnippetTool(server, opts);
   registerResources(server);
 
   return server;
@@ -570,6 +575,80 @@ function registerDropBaselineTool(server: McpServer, _opts: ServerOpts): void {
   );
 }
 
+function registerShowTool(server: McpServer, opts: ServerOpts): void {
+  server.registerTool(
+    "show",
+    {
+      description:
+        "Look up symbol(s) by exact name; returns {matches: [{name, kind, file_path, line_start, line_end, signature, ...}]} with structured `disambiguation` block when multiple matches. One-step lookup that beats composing `SELECT … FROM symbols WHERE name = ?` by hand. Use `snippet` for the actual source text; use `query` with `LIKE` for fuzzy lookup.",
+      inputSchema: {
+        name: z.string().min(1, "name must be a non-empty string"),
+        kind: z.string().optional(),
+        in: z.string().optional(),
+      },
+    },
+    (args) => {
+      try {
+        const db = openDb();
+        try {
+          const inPath =
+            args.in !== undefined && args.in.length > 0
+              ? toProjectRelative(opts.root, args.in)
+              : undefined;
+          const matches = findSymbolsByName(db, {
+            name: args.name,
+            kind: args.kind,
+            inPath,
+          });
+          return jsonResult(buildShowResult(matches));
+        } finally {
+          closeDb(db, { readonly: true });
+        }
+      } catch (err) {
+        return jsonError(err instanceof Error ? err.message : String(err));
+      }
+    },
+  );
+}
+
+function registerSnippetTool(server: McpServer, opts: ServerOpts): void {
+  server.registerTool(
+    "snippet",
+    {
+      description:
+        "Same lookup as `show` but each match carries `source` (file lines from disk at line_start..line_end) plus `stale` (true when content_hash drifted since indexing — line range may have shifted; agent decides whether to act or re-index) and `missing` (true when file is gone). Per-execution shape mirrors `show`'s envelope; source/stale/missing are additive fields on each match.",
+      inputSchema: {
+        name: z.string().min(1, "name must be a non-empty string"),
+        kind: z.string().optional(),
+        in: z.string().optional(),
+      },
+    },
+    (args) => {
+      try {
+        const db = openDb();
+        try {
+          const inPath =
+            args.in !== undefined && args.in.length > 0
+              ? toProjectRelative(opts.root, args.in)
+              : undefined;
+          const matches = findSymbolsByName(db, {
+            name: args.name,
+            kind: args.kind,
+            inPath,
+          });
+          return jsonResult(
+            buildSnippetResult({ db, matches, projectRoot: opts.root }),
+          );
+        } finally {
+          closeDb(db, { readonly: true });
+        }
+      } catch (err) {
+        return jsonError(err instanceof Error ? err.message : String(err));
+      }
+    },
+  );
+}
+
 /**
  * MCP resources are addressable read-only data the host can fetch ahead of
  * tool calls. Plan § 7 + grill round Q3 settled on **lazy memoisation**: