@loupekit/mcp 0.10.18 → 0.10.19-next.65

package/dist/index.js

@@ -419,6 +419,581 @@ data: ${JSON.stringify(event)}
   res.on("close", done);
 }
 
+// src/mapper.ts
+import { readdir, readFile, stat } from "fs/promises";
+import { basename, join, relative, sep } from "path";
+var SIGNAL_WEIGHTS = {
+  id: 0.85,
+  "aria-label": 0.8,
+  text: 0.7,
+  class: 0.5,
+  "plain-text": 0.4,
+  filename: 0.6
+};
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  ".nuxt",
+  ".svelte-kit",
+  "coverage",
+  "vendor",
+  "__pycache__",
+  ".venv",
+  "venv",
+  "target",
+  ".cache",
+  ".turbo",
+  ".parcel-cache",
+  ".idea",
+  ".vscode",
+  ".output",
+  ".angular",
+  "bower_components"
+]);
+var SEARCH_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".vue",
+  ".svelte",
+  ".astro",
+  ".html",
+  ".htm",
+  ".php",
+  ".blade.php",
+  ".erb",
+  ".liquid",
+  ".twig",
+  ".css",
+  ".scss"
+]);
+function isComponentishName(filePath) {
+  const name = basename(filePath).replace(/\.[^.]+$/, "").replace(/\.blade$/, "");
+  if (name.startsWith("use") && name.length > 3) return true;
+  return /^[A-Z][A-Za-z0-9]*$/.test(name);
+}
+function isViewFile(filePath) {
+  return /\.(tsx|jsx|vue|svelte|astro|html?|blade\.php|erb|liquid|twig)$/i.test(filePath);
+}
+var BARE_UTILITIES = /* @__PURE__ */ new Set([
+  "flex",
+  "grid",
+  "block",
+  "inline",
+  "inline-block",
+  "hidden",
+  "relative",
+  "absolute",
+  "fixed",
+  "sticky",
+  "static",
+  "container",
+  "truncate",
+  "italic",
+  "underline",
+  "uppercase",
+  "lowercase",
+  "capitalize",
+  "antialiased",
+  "invisible",
+  "visible",
+  "contents",
+  "isolate",
+  "group",
+  "peer",
+  "clearfix",
+  "shadow",
+  "border",
+  "rounded",
+  "outline",
+  "ring",
+  "transition",
+  "transform",
+  "animate",
+  "cursor-pointer",
+  "overflow-hidden"
+]);
+var SCALE_SUFFIX = /^(?:[0-9]+(?:\.[0-9]+)?|px|full|auto|none|screen|min|max|fit|prose|xs|sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl|tight|wide|wider|widest|loose|normal|bold|semibold|medium|light|thin|black|white|solid|dashed|dotted|double|hidden|visible|scroll|clip|ellipsis|wrap|nowrap|center|left|right|top|bottom|start|end|baseline|stretch|around|between|evenly|reverse|row|col|nowrap|\[.*\])$/;
+function isUtilityClass(name) {
+  const cls = name.trim();
+  if (!cls) return true;
+  if (cls.includes(":")) return true;
+  if (BARE_UTILITIES.has(cls)) return true;
+  const parts = cls.split("-");
+  if (parts.length >= 2 && /^[a-z]{1,12}$/.test(parts[0]) && SCALE_SUFFIX.test(parts[parts.length - 1])) {
+    return true;
+  }
+  if (parts.length >= 2 && /^(?:bg|text|border|font|leading|tracking|from|to|via|fill|stroke|ring|shadow)$/.test(parts[0])) {
+    return true;
+  }
+  return false;
+}
+function searchableClasses(classes) {
+  return [...new Set((classes ?? []).map((c) => c.trim()).filter((c) => c && !isUtilityClass(c)))];
+}
+var MAX_LINE_LENGTH = 1500;
+function looksGenerated(source) {
+  let run = 0;
+  for (let i = 0; i < source.length; i++) {
+    if (source.charCodeAt(i) === 10) {
+      run = 0;
+    } else if (++run > MAX_LINE_LENGTH) {
+      return true;
+    }
+  }
+  return false;
+}
+function isSourcePath(filePath) {
+  return filePath.startsWith("src/") || filePath.includes("/src/");
+}
+var DEFAULTS = {
+  maxFiles: 4e3,
+  maxFileBytes: 512 * 1024,
+  maxScanBytes: 64 * 1024 * 1024,
+  ttlMs: 15e3,
+  maxCandidates: 10,
+  linePadding: 2
+};
+async function collectFiles(root, opts = {}) {
+  const { maxFiles } = { ...DEFAULTS, ...opts };
+  const files = [];
+  const queue = [root];
+  let truncated = false;
+  while (queue.length) {
+    const dir = queue.shift();
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (files.length >= maxFiles) {
+        truncated = true;
+        break;
+      }
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+        queue.push(full);
+      } else if (entry.isFile()) {
+        if (entry.name.endsWith(".d.ts")) continue;
+        const ext = entry.name.includes(".blade.php") ? ".blade.php" : entry.name.slice(entry.name.lastIndexOf("."));
+        if (!SEARCH_EXTENSIONS.has(ext)) continue;
+        files.push(full);
+      }
+    }
+  }
+  return { files, truncated };
+}
+var listCache = /* @__PURE__ */ new Map();
+async function cachedFiles(root, opts) {
+  const ttl = opts.ttlMs ?? DEFAULTS.ttlMs;
+  const hit = listCache.get(root);
+  if (hit && Date.now() - hit.at < ttl) return hit.result;
+  const result = await collectFiles(root, opts);
+  listCache.set(root, { at: Date.now(), result });
+  return result;
+}
+function lineOf(source, needle) {
+  const at = source.indexOf(needle);
+  if (at < 0) return 0;
+  return source.slice(0, at).split("\n").length;
+}
+async function mapElementToSource(signals, workspaceRoot, opts = {}) {
+  const o = { ...DEFAULTS, ...opts };
+  if (!workspaceRoot || !signals) return [];
+  const needles = [];
+  const id = signals.id?.trim();
+  if (id && id.length >= 3) needles.push({ value: id, type: "id" });
+  const aria = signals.ariaLabel?.trim();
+  if (aria && aria.length >= 3) needles.push({ value: aria, type: "aria-label" });
+  const text = signals.text?.trim();
+  if (text && text.length >= 3) needles.push({ value: text, type: "text" });
+  for (const cls of searchableClasses(signals.classes)) {
+    if (cls.length >= 4) needles.push({ value: cls, type: "class" });
+  }
+  if (!needles.length) return [];
+  let outcome;
+  try {
+    const rootStat = await stat(workspaceRoot);
+    if (!rootStat.isDirectory()) return [];
+    outcome = await cachedFiles(workspaceRoot, o);
+  } catch {
+    return [];
+  }
+  const matches = [];
+  let scanned = 0;
+  const CONCURRENCY = 16;
+  for (let i = 0; i < outcome.files.length; i += CONCURRENCY) {
+    if (scanned > o.maxScanBytes) break;
+    const batch = outcome.files.slice(i, i + CONCURRENCY);
+    const read = await Promise.all(batch.map(async (file) => {
+      try {
+        const info = await stat(file);
+        if (info.size > o.maxFileBytes) return null;
+        const source = await readFile(file, "utf8");
+        return { file, source };
+      } catch {
+        return null;
+      }
+    }));
+    for (const entry of read) {
+      if (!entry) continue;
+      scanned += entry.source.length;
+      if (looksGenerated(entry.source)) continue;
+      const rel = relative(workspaceRoot, entry.file).split(sep).join("/");
+      for (const needle of needles) {
+        if (!entry.source.includes(needle.value)) continue;
+        matches.push({ filePath: rel, line: lineOf(entry.source, needle.value), matchType: needle.type, needle: needle.value });
+      }
+      if (text && text.length >= 4) {
+        const stem = basename(rel).replace(/\.[^.]+$/, "");
+        if (stem.toLowerCase().includes(text.toLowerCase().replace(/\s+/g, ""))) {
+          matches.push({ filePath: rel, line: 1, matchType: "filename", needle: stem });
+        }
+      }
+    }
+  }
+  return rankMatches(matches, o);
+}
+function rankMatches(raw, opts = {}) {
+  const o = { ...DEFAULTS, ...opts };
+  if (!raw.length) return [];
+  const perFile = /* @__PURE__ */ new Map();
+  for (const m of raw) {
+    const list = perFile.get(m.filePath) ?? [];
+    list.push(m);
+    perFile.set(m.filePath, list);
+  }
+  const candidates = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [filePath, list] of perFile) {
+    const best = list.reduce((a, b) => SIGNAL_WEIGHTS[b.matchType] > SIGNAL_WEIGHTS[a.matchType] ? b : a);
+    const key = `${filePath}:${best.line}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    let score = SIGNAL_WEIGHTS[best.matchType];
+    const boosts = [];
+    if (isComponentishName(filePath)) {
+      score += 0.12;
+      boosts.push("component filename");
+    }
+    if (isViewFile(filePath)) {
+      score += 0.08;
+      boosts.push("view file");
+    }
+    if (isSourcePath(filePath)) {
+      score += 0.05;
+      boosts.push("src");
+    }
+    const distinct = new Set(list.map((m) => m.matchType)).size;
+    if (distinct > 1) {
+      score += Math.min(0.12, 0.06 * (distinct - 1));
+      boosts.push(`${distinct} signals agree`);
+    }
+    if (list.length > 1) {
+      score += Math.min(0.06, 0.02 * (list.length - 1));
+      boosts.push(`${list.length} matches`);
+    }
+    const reason = `matched ${best.matchType} \u201C${best.needle}\u201D` + (boosts.length ? ` \xB7 ${boosts.join(", ")}` : "");
+    candidates.push({
+      filePath,
+      lineStart: best.line,
+      lineEnd: best.line,
+      confidence: Math.max(0, Math.min(1, score)),
+      reason,
+      matchType: best.matchType
+    });
+  }
+  candidates.sort((a, b) => b.confidence - a.confidence || a.filePath.localeCompare(b.filePath));
+  return candidates.slice(0, o.maxCandidates).map((c) => ({
+    ...c,
+    lineStart: Math.max(1, c.lineStart - o.linePadding),
+    lineEnd: c.lineEnd + o.linePadding
+  }));
+}
+
+// src/prompt-template.ts
+function describeElement(ctx) {
+  const parts = [];
+  parts.push(ctx.tag ? `a <${ctx.tag}>` : "an element");
+  if (ctx.testid) parts.push(`with data-testid="${ctx.testid}"`);
+  else if (ctx.selector) parts.push(`matching ${ctx.selector}`);
+  if (ctx.text) parts.push(`containing \u201C${ctx.text.slice(0, 80)}\u201D`);
+  return parts.join(" ");
+}
+function generateEditPrompt(ctx) {
+  const lines = [];
+  lines.push("# Task");
+  if (ctx.request) {
+    lines.push("");
+    lines.push(`The request, in the reporter's words:`);
+    lines.push("");
+    lines.push(`> ${ctx.request.replace(/\n/g, "\n> ")}`);
+    lines.push("");
+  }
+  lines.push(
+    `Implement this for ${describeElement(ctx)}` + (ctx.pageUrl ? ` on ${ctx.pageUrl}` : "") + "."
+  );
+  if (ctx.candidates?.length) {
+    lines.push("");
+    lines.push("## Where it probably lives");
+    lines.push("");
+    lines.push("Ranked by how well each file matched the captured element. **Check the top one before editing it** \u2014 this is a heuristic from the built page, not a resolver:");
+    lines.push("");
+    for (const c of ctx.candidates) {
+      lines.push(`- \`${c.filePath}:${c.lineStart}\` \u2014 ${(c.confidence * 100).toFixed(0)}% \xB7 ${c.reason}`);
+    }
+    lines.push("");
+    lines.push(dedent(`
+      If none of these is the component that renders the element, say so and name the
+      file you did find, rather than editing the closest-looking candidate. A confident
+      edit to the wrong file is worse than a question.
+    `));
+  } else {
+    lines.push("");
+    lines.push("## Where it lives");
+    lines.push("");
+    lines.push("No source candidates were found for this element. Locate the component yourself before editing, and say which file you chose.");
+  }
+  lines.push("");
+  lines.push("## How to make the change");
+  lines.push("");
+  lines.push(dedent(`
+    - **Smallest diff that satisfies the request.** Do not reformat, rename, reorder or
+      "tidy" anything you were not asked to touch. If a one-line change does it, that is
+      the change.
+    - **Follow the file's own conventions** \u2014 its naming, its styling approach, its
+      component patterns. If the file uses utility classes, use them; if it uses a
+      stylesheet, use that. Match what is there rather than what you would have written.
+    - **Keep the element's existing behaviour and accessibility.** Preserve the test id,
+      the aria attributes and the event handlers unless the request is about them.
+    - **Do not touch unrelated files.**
+  `));
+  if (ctx.isThread && ctx.threadId) {
+    lines.push("");
+    lines.push("## What happens next");
+    lines.push("");
+    lines.push(dedent(`
+      1. Edit the file.
+      2. Call \`propose_change(id: "${ctx.threadId}", html, css?, notes?)\` with the element's
+         rewritten markup, so a human can review the change against the original request.
+      3. Call \`update_status(id: "${ctx.threadId}", status: "in_review")\` when it is ready.
+         **Never set it to resolved** \u2014 only a person closes a thread. Moving it to In
+         Review is what puts it in front of a reviewer.
+      4. If the work lands in a pull request, that is what the panel's PR chip is for; keep
+         the diff reviewable.
+    `));
+    if (ctx.hasProposal) {
+      lines.push("");
+      lines.push("A proposal already exists for this thread \u2014 call `get_comment` first if you are iterating on it, rather than starting over.");
+    }
+  }
+  return lines.join("\n");
+}
+function dedent(text) {
+  const lines = text.replace(/^\n/, "").replace(/\n\s*$/, "").split("\n");
+  const indent = Math.min(...lines.filter((l) => l.trim()).map((l) => l.match(/^ */)[0].length));
+  return lines.map((l) => l.slice(indent)).join("\n");
+}
+
+// src/tools/element-context.ts
+function threadContextToPayload(thread) {
+  const anchor = thread.anchor;
+  const attrs = thread.context;
+  return {
+    source: "thread",
+    threadId: thread.id,
+    page: { url: thread.url, title: thread.title },
+    element: {
+      tag: anchor?.tag ?? "unknown",
+      selector: anchor?.cssPath,
+      testid: anchor?.testid ?? null,
+      id: null,
+      text: anchor?.text,
+      classes: void 0,
+      attrs: anchor?.attrs,
+      box: anchor?.rect
+    },
+    styles: attrs?.styles ?? {},
+    screenshot: thread.screenshot
+  };
+}
+function selectionToPayload(selection) {
+  return {
+    source: "selection",
+    correlationId: selection.correlationId,
+    page: { url: selection.url },
+    element: {
+      tag: selection.tag,
+      selector: selection.selector,
+      testid: selection.testid ?? null,
+      id: selection.id ?? null,
+      text: selection.text,
+      classes: selection.classes,
+      attrs: selection.attrs,
+      box: selection.box
+    },
+    styles: selection.styles ?? {},
+    screenshot: selection.screenshot
+  };
+}
+function formatElementContext(payload) {
+  const e = payload.element;
+  const lines = [];
+  lines.push(`# Selected element`);
+  lines.push("");
+  lines.push(`- **Where**: ${payload.page.url}${payload.page.title ? ` \u2014 \u201C${payload.page.title}\u201D` : ""}`);
+  lines.push(`- **Tag**: \`<${e.tag}>\``);
+  if (e.selector) lines.push(`- **Selector**: \`${e.selector}\``);
+  if (e.testid) lines.push(`- **Test id**: \`${e.testid}\``);
+  if (e.id) lines.push(`- **Id**: \`${e.id}\``);
+  if (e.text) lines.push(`- **Text**: \u201C${e.text}\u201D`);
+  if (e.classes?.length) lines.push(`- **Classes**: \`${e.classes.join(" ")}\``);
+  if (e.box) lines.push(`- **Box**: ${Math.round(e.box.w)}\xD7${Math.round(e.box.h)} at ${Math.round(e.box.x)},${Math.round(e.box.y)}`);
+  if (payload.source === "thread" && payload.threadId) lines.push(`- **Thread**: #${payload.threadId}`);
+  const styleKeys = Object.keys(payload.styles);
+  if (styleKeys.length) {
+    lines.push("");
+    lines.push("## Computed styles");
+    lines.push("");
+    for (const key of styleKeys) lines.push(`- \`${key}: ${payload.styles[key]}\``);
+  }
+  if (payload.sourceCandidates) {
+    lines.push("");
+    lines.push("## Source candidates");
+    lines.push("");
+    if (payload.sourceCandidates.length) {
+      for (const c of payload.sourceCandidates) {
+        lines.push(`- \`${c.filePath}:${c.lineStart}-${c.lineEnd}\` \u2014 ${(c.confidence * 100).toFixed(0)}% \xB7 ${c.reason}`);
+      }
+    } else {
+      lines.push("_No source candidates found for this element in the workspace._");
+    }
+  }
+  if (payload.editPrompt) {
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push(payload.editPrompt);
+  }
+  return lines.join("\n");
+}
+async function resolvePayload(deps, args) {
+  if (args.thread_id) {
+    const thread = await deps.fetchThread(args.thread_id);
+    return thread ? threadContextToPayload(thread) : null;
+  }
+  if (args.selection_id) {
+    const found = deps.store.get(args.selection_id);
+    return found ? selectionToPayload(found) : null;
+  }
+  const latest = deps.store.latest();
+  return latest ? selectionToPayload(latest) : null;
+}
+var NOTHING_SELECTED = "Nothing has been selected yet.\n\nClick an element in the browser with the Loupe widget open, then call this tool again \u2014 the selection reaches the bridge automatically. You can also pass `thread_id` to work from a stored thread instead (see `list_comments`).";
+var NOT_FOUND = (what, id) => `No ${what} found for \`${id}\`.
+
+` + (what === "thread" ? "Use `list_comments` to see the available ids." : "It may have been evicted \u2014 the bridge keeps the most recent 50 selections.");
+function createElementContextTools(deps) {
+  const withSource = async (payload) => {
+    const signals = {
+      tag: payload.element.tag,
+      id: payload.element.id,
+      text: payload.element.text,
+      classes: payload.element.classes,
+      attrs: payload.element.attrs
+    };
+    try {
+      payload.sourceCandidates = await mapElementToSource(signals, deps.workspaceRoot, deps.mapperOptions);
+    } catch {
+      payload.sourceCandidates = [];
+    }
+    return payload;
+  };
+  return {
+    /** The most recent selection. */
+    async getLatestSelection() {
+      const latest = deps.store.latest();
+      if (!latest) return { text: NOTHING_SELECTED, unavailable: true };
+      return { text: formatElementContext(await withSource(selectionToPayload(latest))) };
+    },
+    /** Recent selections, newest first. */
+    async getSelectionHistory({ limit } = {}) {
+      const history = deps.store.history(limit ?? 10);
+      if (!history.length) return { text: NOTHING_SELECTED, unavailable: true };
+      const lines = [`# Recent selections (${history.length})`, ""];
+      for (const s of history) {
+        lines.push(`- \`${s.correlationId}\` \u2014 \`<${s.tag}>\` ${s.selector ? `\`${s.selector}\`` : ""} ${s.text ? `\u201C${s.text.slice(0, 60)}\u201D` : ""} on ${s.url} (${s.at})`);
+      }
+      lines.push("");
+      lines.push("Pass any correlation id to `get_element_context` for the full context.");
+      return { text: lines.join("\n") };
+    },
+    /** Everything about one element: payload, styles, candidates and the prompt. */
+    async getElementContext(args = {}, opts = {}) {
+      const payload = await resolvePayload(deps, args);
+      if (!payload) {
+        if (args.thread_id) return { text: NOT_FOUND("thread", args.thread_id), unavailable: true };
+        if (args.selection_id) return { text: NOT_FOUND("selection", args.selection_id), unavailable: true };
+        return { text: NOTHING_SELECTED, unavailable: true };
+      }
+      await withSource(payload);
+      if (opts.include_prompt !== false) {
+        payload.editPrompt = generateEditPrompt({
+          tag: payload.element.tag,
+          selector: payload.element.selector,
+          testid: payload.element.testid,
+          text: payload.element.text,
+          classes: payload.element.classes,
+          pageUrl: payload.page.url,
+          candidates: payload.sourceCandidates,
+          isThread: payload.source === "thread",
+          threadId: payload.threadId
+        });
+      }
+      return { text: formatElementContext(payload) };
+    },
+    /** Just the ranked files, for when the agent only needs to know where to look. */
+    async findSourceForSelection(args = {}) {
+      const payload = await resolvePayload(deps, args);
+      if (!payload) {
+        if (args.thread_id) return { text: NOT_FOUND("thread", args.thread_id), unavailable: true };
+        if (args.selection_id) return { text: NOT_FOUND("selection", args.selection_id), unavailable: true };
+        return { text: NOTHING_SELECTED, unavailable: true };
+      }
+      await withSource(payload);
+      const candidates = payload.sourceCandidates ?? [];
+      if (!candidates.length) {
+        return {
+          text: `No source candidates for ${payload.element.tag} in \`${deps.workspaceRoot}\`.
+
+The element's text, id, aria-label and non-utility classes were all searched. If the component lives outside this workspace, the agent will have to find it another way.`,
+          unavailable: true
+        };
+      }
+      const lines = [
+        `# Source candidates (${candidates.length})`,
+        "",
+        `Searched \`${deps.workspaceRoot}\` using the element's id, aria-label, text and app classes.`,
+        ""
+      ];
+      for (const c of candidates) lines.push(`- \`${c.filePath}:${c.lineStart}-${c.lineEnd}\` \u2014 ${(c.confidence * 100).toFixed(0)}% \xB7 ${c.reason}`);
+      lines.push("");
+      lines.push("This is a heuristic from the built page, not a resolver \u2014 verify before editing.");
+      return { text: lines.join("\n") };
+    }
+  };
+}
+
 // index.ts
 import {
   CHANGE_TYPE_LABELS,
@@ -588,7 +1163,7 @@ async function proposeChange({ id, html, css, notes }) {
   bus.publishThread(id, "preview_live", { author: proposal.author });
   return wrap(`Proposal saved for #${id}. The dev team can now review your modified HTML/CSS in the dashboard.`);
 }
-var server = new McpServer({ name: "loupe", version: "0.10.18" });
+var server = new McpServer({ name: "loupe", version: "0.10.19" });
 server.tool(
   "list_comments",
   "List Loupe product-feedback comments for the project as a task backlog. Each item carries its board stage, priority and change type, so you can start with the most urgent. Use this to see what a PM has flagged, then work through the items.",
@@ -625,6 +1200,52 @@ server.tool(
   },
   proposeChange
 );
+var WS = process.env.LOUPE_WORKSPACE || process.cwd();
+var elementTools = createElementContextTools({
+  store,
+  workspaceRoot: WS,
+  mapperOptions: { maxFiles: Number(process.env.LOUPE_MAP_MAX_FILES ?? 4e3) },
+  fetchThread: async (id) => {
+    try {
+      return await api(`/v1/comments/${encodeURIComponent(id)}`);
+    } catch {
+      return null;
+    }
+  }
+});
+var SELECTION_ARGS = {
+  thread_id: z.string().optional().describe("Work from a stored comment instead of a live selection."),
+  selection_id: z.string().optional().describe(
+    "A specific selection by correlation id (see get_selection_history). Omit for the most recent."
+  )
+};
+server.tool(
+  "get_latest_selection",
+  `What the user last selected in the browser, with its element, computed styles and the source files most likely to render it. Use this when someone says "this element" or "what I'm looking at" and no thread exists yet.`,
+  {},
+  async () => wrap((await elementTools.getLatestSelection()).text)
+);
+server.tool(
+  "get_selection_history",
+  "The recent element selections, newest first \u2014 useful when the user clicked a few things and you need to pick the right one.",
+  { limit: z.number().int().positive().max(50).optional().describe("How many to list. Defaults to 10.") },
+  async ({ limit }) => wrap((await elementTools.getSelectionHistory({ limit })).text)
+);
+server.tool(
+  "get_element_context",
+  "Full context for one element: the element, the page, its key computed styles, the ranked source files that probably render it, and a ready-made edit prompt. Pass thread_id to work from a stored comment, or nothing to use the latest live selection. Call this before editing anything.",
+  {
+    ...SELECTION_ARGS,
+    include_prompt: z.boolean().optional().describe("Include the edit prompt. Defaults to true.")
+  },
+  async ({ thread_id, selection_id, include_prompt }) => wrap((await elementTools.getElementContext({ thread_id, selection_id }, { include_prompt })).text)
+);
+server.tool(
+  "find_source_for_selection",
+  "Just the ranked source files for the current selection or a stored thread \u2014 for when you only need to know where the component lives. Heuristic: verify the top candidate before editing it.",
+  SELECTION_ARGS,
+  async ({ thread_id, selection_id }) => wrap((await elementTools.findSourceForSelection({ thread_id, selection_id })).text)
+);
 function isEntrypoint() {
   try {
     return import.meta.url === pathToFileURL(realpathSync(argv[1] ?? "")).href;

package/package.json

@@ -5,7 +5,7 @@
     "email": "m.ashraf.saed@gmail.com",
     "url": "https://www.linkedin.com/in/mohamedashrafelsaed/"
   },
-  "version": "0.10.18",
+  "version": "0.10.19-next.65",
   "description": "MCP server that exposes Loupe comments to Claude Code as an actionable, fully-contextualized backlog.",
   "keywords": [
     "loupe",
@@ -46,6 +46,6 @@
     "zod": "^3.24.1"
   },
   "devDependencies": {
-    "@loupekit/shared": "0.10.18"
+    "@loupekit/shared": "0.10.19-next.65"
   }
 }