@skyelight/mcp 0.1.0

package/src/tools.js

@@ -0,0 +1,500 @@
+/**
+ * The three tools, and — more importantly — how their results are worded.
+ *
+ * A tool that returns raw JSON invites a model to read it aloud. Each of
+ * these returns prose with the numbers already in it, so the natural thing
+ * for a model to do is summarise rather than dump. The structured payload is
+ * still attached for anything that wants to compute on it.
+ */
+
+const PROJECT_HINT =
+  'No project. Pass projectId, add .skyelight.json with {"projectId": "..."}, ' +
+  "or use a project-bound API key.";
+
+/**
+ * @param opts.uiResourceUri When set, `get_item` advertises a `ui://`
+ *   resource the host can render as a card. Omitted for clients that cannot
+ *   render one — the text result is complete on its own, so the card is
+ *   strictly additive and its absence costs nothing (SKY-279).
+ */
+export function toolDefinitions(opts = {}) {
+  const withUi = (tool) =>
+    opts.uiResourceUri
+      ? {
+          ...tool,
+          _meta: {
+            ui: {
+              resourceUri: opts.uiResourceUri,
+              // The model calls it, and the card calls back into it.
+              visibility: ["model", "app"],
+            },
+          },
+        }
+      : tool;
+
+  return [
+    {
+      name: "list_workspaces",
+      description:
+        "Workspaces you can reach, with the role you hold in each. Use when " +
+        "you do not know what exists yet, or to find which workspace a " +
+        "project belongs to.",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "list_projects",
+      description:
+        "Projects you can reach, newest activity first, across every " +
+        "workspace unless one is named. Start here when no project is bound " +
+        "— `list_items` needs a project id and this is where one comes from.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          workspaceId: {
+            type: "string",
+            description: "Narrow to one workspace. Optional.",
+          },
+        },
+      },
+    },
+    {
+      name: "list_items",
+      description:
+        "List feedback items (bugs, ideas, comments) people left on a Skyelight project. " +
+        "Returns a summary of the project plus matching items. Start here to see what is outstanding.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: {
+            type: "string",
+            description: "Project to read. Optional if a project is bound.",
+          },
+          page: {
+            type: "string",
+            description: 'Only items on one page, e.g. "/checkout".',
+          },
+          type: {
+            type: "string",
+            description: 'Item type, e.g. "bug", "idea", "feedback".',
+          },
+          status: {
+            type: "string",
+            enum: ["open", "deferred", "resolved"],
+            description:
+              'Defaults to everything. "deferred" is work someone put off ' +
+              "until later — outstanding, but deliberately not now.",
+          },
+          assignee: {
+            type: "string",
+            description: 'A user id, or "none" for unassigned items.',
+          },
+          limit: { type: "number", description: "Max items (default 50)." },
+        },
+      },
+    },
+    {
+      name: "search_items",
+      description:
+        "Find items whose thread mentions some text. Searches replies as well as the original " +
+        "message, so an item someone already diagnosed in a reply still turns up.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Text to look for." },
+          projectId: { type: "string" },
+          status: { type: "string", enum: ["open", "deferred", "resolved"] },
+          limit: { type: "number" },
+        },
+        required: ["query"],
+      },
+    },
+    {
+      name: "post_update",
+      description:
+        "Report back on an item: what you found, what you changed, a link to the PR. Posts as a " +
+        "reply on the thread the feedback was left on, so the person who reported it sees the " +
+        "answer where they asked. Use this when you finish work on an item, and when you get stuck.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          itemId: { type: "string", description: "Item id from list_items." },
+          body: {
+            type: "string",
+            description:
+              "What you found or changed, in plain language for the person who reported it.",
+          },
+          links: {
+            type: "array",
+            description: "Optional links — a PR, a commit, a deploy.",
+            items: {
+              type: "object",
+              properties: {
+                label: { type: "string" },
+                url: { type: "string" },
+              },
+              required: ["url"],
+            },
+          },
+        },
+        required: ["itemId", "body"],
+      },
+    },
+    {
+      name: "create_item",
+      description:
+        "Open a new thread on a page, as the person whose connection you are using. " +
+        "Only available on a person's own connection — an agent reporting what it found " +
+        "or changed uses post_update on the thread it was working, so the answer lands " +
+        "where the question was asked.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          url: {
+            type: "string",
+            description: "Full URL of the page this is about.",
+          },
+          body: { type: "string", description: "What you want to say." },
+          selector: {
+            type: "string",
+            description: "CSS selector for the element, if there is one.",
+          },
+          projectId: {
+            type: "string",
+            description: "Optional if a project is bound.",
+          },
+          pageTitle: { type: "string" },
+        },
+        required: ["url", "body"],
+      },
+    },
+    {
+      name: "set_status",
+      description:
+        "Move an item to open, deferred or resolved. Use it to close the loop after you have " +
+        "fixed something and said so \u2014 post_update first, so the person who reported it " +
+        "reads what changed, then set_status. \"deferred\" is for work that is real but not now.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          itemId: { type: "string", description: "Item id from list_items." },
+          status: { type: "string", enum: ["open", "deferred", "resolved"] },
+        },
+        required: ["itemId", "status"],
+      },
+    },
+    withUi({
+      name: "get_item",
+      description:
+        "Everything needed to work one item: the whole thread in order, the page and URL it is " +
+        "on, and the anchor identifying the element the person pointed at.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          itemId: { type: "string", description: "Item id from list_items." },
+        },
+        required: ["itemId"],
+      },
+    }),
+  ];
+}
+
+function plural(n, one, many) {
+  return `${n} ${n === 1 ? one : many}`;
+}
+
+/** Top entries of a count map, worded for a sentence. */
+function topBreakdown(counts, limit = 3) {
+  const entries = Object.entries(counts ?? {}).sort((a, b) => b[1] - a[1]);
+  if (entries.length === 0) return "";
+  return entries
+    .slice(0, limit)
+    .map(([k, n]) => `${k} (${n})`)
+    .join(", ");
+}
+
+/**
+ * Prose, like every other renderer here: a model handed an array reads the
+ * array out, and a model handed a sentence summarises.
+ */
+export function renderWorkspaces(result) {
+  const { workspaces, total } = result;
+  if (total === 0) {
+    return "You are not a member of any workspace yet.";
+  }
+
+  const lines = [`${plural(total, "workspace", "workspaces")} you can reach:`];
+  lines.push("");
+  for (const w of workspaces) {
+    const projects = plural(w.projectCount, "project", "projects");
+    lines.push(`  ${w.name} — ${w.role}, ${projects}`);
+    lines.push(`    ${w.id}`);
+  }
+  return lines.join("\n");
+}
+
+export function renderProjects(result) {
+  const { projects, total } = result;
+  if (total === 0) {
+    return "No projects you can reach. Create one in the Skyelight web app.";
+  }
+
+  const spans = new Set(projects.map((p) => p.workspace.id)).size > 1;
+  const lines = [`${plural(total, "project", "projects")} you can reach:`];
+  lines.push("");
+  for (const p of projects) {
+    // The workspace is only worth naming when there is more than one in
+    // play; repeating it down a single-workspace list is noise.
+    lines.push(`  ${p.name}${spans ? ` (${p.workspace.name})` : ""}`);
+    lines.push(`    ${p.id}${p.repo ? ` — ${p.repo}` : ""}`);
+  }
+  lines.push("");
+  lines.push(
+    "Pass one of these ids as projectId, or write it to .skyelight.json in " +
+      "the repo so it is the default from now on.",
+  );
+  return lines.join("\n");
+}
+
+export function renderList(result, { searched } = {}) {
+  const { project, summary, items, matched, truncated } = result;
+  const lines = [];
+
+  lines.push(
+    `${project.name}: ${plural(summary.total, "item", "items")} total — ` +
+      `${summary.open} open, ${summary.deferred ?? 0} deferred, ` +
+      `${summary.resolved} resolved, ${summary.unassigned} unassigned.`,
+  );
+
+  const byType = topBreakdown(summary.byType);
+  if (byType) lines.push(`By type: ${byType}.`);
+  const byPage = topBreakdown(summary.byPage);
+  if (byPage) lines.push(`Busiest pages: ${byPage}.`);
+
+  lines.push("");
+
+  if (items.length === 0) {
+    lines.push(
+      searched
+        ? `Nothing matched "${searched}".`
+        : "Nothing matched those filters.",
+    );
+    return lines.join("\n");
+  }
+
+  lines.push(
+    truncated
+      ? `Showing ${items.length} of ${matched} matches — narrow the filters to see the rest:`
+      : `${plural(items.length, "match", "matches")}:`,
+  );
+
+  for (const i of items) {
+    const bits = [i.type ?? "unsorted", i.status, i.page];
+    if (i.assignee) bits.push(`assigned to ${i.assignee}`);
+    else bits.push("unassigned");
+    if (i.replyCount > 0) bits.push(plural(i.replyCount, "reply", "replies"));
+    lines.push(`- ${i.excerpt}`);
+    lines.push(`  ${bits.join(" · ")} — id ${i.id}`);
+  }
+
+  lines.push("");
+  lines.push(
+    "Use get_item with an id for the full thread and the element it points at.",
+  );
+  return lines.join("\n");
+}
+
+export function renderItem(item) {
+  const lines = [];
+  lines.push(
+    `${item.type ?? "unsorted"} · ${item.status} · ${item.page}` +
+      (item.project ? ` · ${item.project.name}` : ""),
+  );
+  lines.push(`URL: ${item.url}`);
+  // The repo, when the project names one. Stated plainly and early: it is
+  // the difference between an agent knowing where to work and inferring it
+  // from a URL, which is how work lands in the wrong codebase.
+  const repo = item.project && item.project.repo;
+  if (repo) {
+    const where = [repo.url];
+    if (repo.branch) where.push(`branch ${repo.branch}`);
+    if (repo.pathPrefix) where.push(`under ${repo.pathPrefix}`);
+    lines.push(`Code: ${where.join(", ")}`);
+  }
+  if (item.assignee?.name) {
+    // The mode is the ask. An agent that reads "investigate" and opens a
+    // pull request has done the wrong job well.
+    const asked = {
+      investigate: "asked to investigate — report back, change nothing",
+      plan: "asked to plan — describe the change, do not make it",
+      fix: "asked to fix — make the change and open a pull request",
+      build: "asked to build — build it and open a pull request",
+    }[item.assignee.mode];
+    lines.push(
+      asked
+        ? `Assigned to ${item.assignee.name}, ${asked}`
+        : `Assigned to: ${item.assignee.name}`,
+    );
+  }
+  lines.push("");
+
+  lines.push(`${item.thread.root.author} wrote:`);
+  lines.push(item.thread.root.content);
+
+  if (item.thread.replies.length > 0) {
+    lines.push("");
+    lines.push(`${plural(item.thread.replies.length, "reply", "replies")}:`);
+    for (const r of item.thread.replies) {
+      lines.push(`- ${r.author}: ${r.content}`);
+    }
+  }
+
+  // Stated before the anchor: a screenshot answers "what did this look like"
+  // in one step, where a selector needs the page opened first.
+  if (item.evidence) {
+    if (item.evidence.screenshotUrl) {
+      lines.push("");
+      lines.push(`Screenshot: ${item.evidence.screenshotUrl}`);
+    } else if (item.evidence.expired) {
+      lines.push("");
+      lines.push(
+        "Screenshot: expired and deleted under this workspace's retention policy.",
+      );
+    }
+  }
+
+  lines.push("");
+  lines.push("They were pointing at:");
+  // elementText first: it is what a person would have named, and the one
+  // part of an anchor that stays true when the markup moves.
+  if (item.anchor.elementText) {
+    lines.push(`  the element reading "${item.anchor.elementText}"`);
+  }
+  if (item.anchor.selectedText) {
+    lines.push(`  with "${item.anchor.selectedText}" selected`);
+  }
+  lines.push(`  selector: ${item.anchor.selector}`);
+  lines.push(
+    `  seen at ${item.anchor.viewport.width}x${item.anchor.viewport.height}`,
+  );
+
+  // Last and on its own line, because it is the line that changes what the
+  // reader does next: everything above describes the page, this names the
+  // file. Absent unless the build stamped it, and silent when it is — an
+  // agent that reads "no source" learns nothing it can act on.
+  if (item.source) {
+    lines.push("");
+    const where = item.source.line
+      ? `${item.source.file}, line ${item.source.line}`
+      : item.source.file;
+    // The build too, when the page carried one. Which commit was on the
+    // screen is the difference between a live bug and a stale pin — and the
+    // branch is what makes that commit findable when the page was a preview
+    // of work that has not landed on the main line.
+    const from = [];
+    if (item.source.build) from.push(`build ${item.source.build}`);
+    if (item.source.branch) from.push(`branch ${item.source.branch}`);
+    lines.push(
+      from.length
+        ? `Written by ${where}, in ${from.join(" on ")}.`
+        : `Written by ${where}.`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export function renderPosted(result, { kind }) {
+  if (kind === "update") {
+    return (
+      "Posted to the thread. The person who reported this will see it where " +
+      "they left the feedback."
+    );
+  }
+  return `Raised a new item on ${result.page ?? "that page"}. id ${result.pinId}`;
+}
+
+export async function callTool(name, args, { client, config }) {
+  const projectId = args.projectId ?? config.projectId ?? undefined;
+
+  if (name === "list_workspaces") {
+    const result = await client.listWorkspaces();
+    return { text: renderWorkspaces(result), data: result };
+  }
+
+  if (name === "list_projects") {
+    const result = await client.listProjects({
+      workspaceId: args.workspaceId,
+    });
+    return { text: renderProjects(result), data: result };
+  }
+
+  if (name === "list_items") {
+    const result = await client.listItems({
+      projectId,
+      page: args.page,
+      type: args.type,
+      status: args.status,
+      assignee: args.assignee,
+      limit: args.limit,
+    });
+    return { text: renderList(result), data: result };
+  }
+
+  if (name === "search_items") {
+    if (!args.query?.trim()) throw new Error("search_items needs a query");
+    const result = await client.listItems({
+      projectId,
+      q: args.query,
+      status: args.status,
+      limit: args.limit,
+    });
+    return { text: renderList(result, { searched: args.query }), data: result };
+  }
+
+  if (name === "post_update") {
+    if (!args.itemId) throw new Error("post_update needs an itemId");
+    if (!args.body?.trim()) throw new Error("post_update needs a body");
+    const result = await client.postUpdate({
+      itemId: args.itemId,
+      body: args.body,
+      links: args.links,
+    });
+    return { text: renderPosted(result, { kind: "update" }), data: result };
+  }
+
+  if (name === "create_item") {
+    if (!args.url) throw new Error("create_item needs a url");
+    if (!args.body?.trim()) throw new Error("create_item needs a body");
+    const result = await client.createItem({
+      url: args.url,
+      body: args.body,
+      selector: args.selector,
+      projectId,
+      pageTitle: args.pageTitle,
+    });
+    return { text: renderPosted(result, { kind: "item" }), data: result };
+  }
+
+  if (name === "set_status") {
+    if (!args.itemId) throw new Error("set_status needs an itemId");
+    if (!args.status) throw new Error("set_status needs a status");
+    const res = await client.setStatus({
+      itemId: args.itemId,
+      status: args.status,
+    });
+    if (res?.error) throw new Error(res.error);
+    return res.changed
+      ? `Moved to ${res.status}.`
+      : `Already ${res.status} — nothing to do.`;
+  }
+
+  if (name === "get_item") {
+    if (!args.itemId) throw new Error("get_item needs an itemId");
+    const item = await client.getItem(args.itemId);
+    return { text: renderItem(item), data: item };
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+export { PROJECT_HINT };