@skyelight/mcp 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyelight/mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MCP server for Skyelight \u2014 read feedback items from your project as an agent",
   "type": "module",
   "bin": {

package/src/client.js

@@ -85,6 +85,15 @@ export function createClient({ apiUrl, token, fetchImpl = fetch }) {
   }
 
   return {
+    /**
+     * The fetch this client was built with, for the one thing that is not an
+     * API call: pulling a storage URL the API just handed us so its bytes can
+     * be returned as an image. Exposed rather than wrapped because it carries
+     * no bearer token — those links are their own credential, and attaching
+     * ours to an off-API request is how a token ends up somewhere it was
+     * never meant to go.
+     */
+    fetchImpl,
     listWorkspaces: () => request("/api/v1/workspaces"),
     listProjects: (params) => request("/api/v1/projects", params),
     listItems: (params) => request("/api/v1/items", params),

package/src/images.d.ts

@@ -0,0 +1,42 @@
+/** Types for images.js — see tools.d.ts for why declarations are shipped. */
+
+export interface TextBlock {
+  type: "text";
+  text: string;
+}
+
+export interface ImageBlock {
+  type: "image";
+  /** Base64, no data: prefix — what the MCP content block wants. */
+  data: string;
+  mimeType: string;
+}
+
+export type ContentBlock = TextBlock | ImageBlock;
+
+export declare const MAX_IMAGES: number;
+export declare const MAX_IMAGE_BYTES: number;
+
+export interface ImageSource {
+  url: string;
+  storageId: string | null;
+  label: string;
+}
+
+/** What a loader hands back: the bytes, or why there are none. */
+export type LoadedImage =
+  | { bytes: Uint8Array; mimeType?: string; skipped?: undefined }
+  | { skipped: string };
+
+export declare function imageSources(item: unknown): ImageSource[];
+
+export declare function imageBlocksFor(
+  item: unknown,
+  options?: {
+    /** Where the bytes come from. Defaults to fetching `source.url`. */
+    load?: (source: ImageSource) => Promise<LoadedImage>;
+    fetchImpl?: typeof fetch;
+    maxImages?: number;
+    maxBytes?: number;
+  },
+): Promise<ContentBlock[]>;

package/src/images.js

@@ -0,0 +1,193 @@
+/**
+ * Evidence, as something a model can actually look at.
+ *
+ * `get_item` used to print `Screenshot: https://…` and stop there. No agent
+ * tool turns a link into a picture, so the most expensive thing Skyelight
+ * captures — the state of the page at the moment somebody pinned it — reached
+ * nobody. The same was true of the images people attach themselves, which are
+ * frequently the whole diagnosis: the reply that says "here, look".
+ *
+ * MCP tool results are a LIST of content blocks and an image is one of them,
+ * so the fix is to fetch the bytes and hand them over as
+ * `{ type: "image", data, mimeType }`.
+ *
+ * Shared by both transports on purpose. The stdio package and the remote
+ * endpoint are two doors onto the same server, and an agent that can see a
+ * screenshot through one and not the other is the kind of difference nobody
+ * can debug from the outside.
+ */
+
+/**
+ * How many pictures one call may carry.
+ *
+ * A thread with a screenshot on every reply would otherwise put a dozen
+ * images into a single result. Four is the evidence capture plus the first
+ * few things people attached, which is where the information is — an
+ * eleventh screenshot of the same page has never changed a diagnosis.
+ */
+export const MAX_IMAGES = 4;
+
+/**
+ * The most one picture may weigh.
+ *
+ * Captures are JPEG at quality 0.85 and at most 2x device density, so a large
+ * viewport lands around a megabyte and nothing legitimate comes close to this.
+ * The cap is here for what people attach, which is arbitrary: somebody drags
+ * in a full-resolution phone screenshot and every subsequent call carries it.
+ *
+ * Over the line, the link is reported instead, with the size, so the reader
+ * knows a picture exists and why it is not here. Downscaling would be better
+ * and is not available: neither the dependency-free stdio package nor the
+ * Convex runtime has an image codec to re-encode with.
+ */
+export const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
+
+/** Bytes to base64, in both runtimes this module is loaded into. */
+function toBase64(bytes) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  // Convex runs a V8 isolate with no Buffer. `btoa` takes a binary string,
+  // and building one in chunks keeps the argument list to `fromCharCode`
+  // inside what a call stack will take.
+  let binary = "";
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode.apply(
+      null,
+      Array.from(bytes.subarray(i, i + CHUNK)),
+    );
+  }
+  return btoa(binary);
+}
+
+/**
+ * The pictures on one item, in the order a reader wants them.
+ *
+ * Evidence first: it answers "what did this look like" without opening
+ * anything. Then what people attached, thread before replies, which is the
+ * order `attachments` already arrives in.
+ */
+export function imageSources(item) {
+  const sources = [];
+  if (item?.evidence?.screenshotUrl) {
+    sources.push({
+      url: item.evidence.screenshotUrl,
+      storageId: item.evidence.screenshotStorageId ?? null,
+      label: "The page when this was pinned:",
+    });
+  }
+  for (const a of item?.attachments ?? []) {
+    if (!a?.url) continue;
+    sources.push({
+      url: a.url,
+      storageId: a.storageId ?? null,
+      label: `Attached by ${a.author ?? "someone"}${
+        a.where === "reply" ? ", on a reply" : ""
+      }:`,
+    });
+  }
+  return sources;
+}
+
+/**
+ * The default loader: pull the storage URL over HTTP.
+ *
+ * What the stdio package has to do, because the bytes are on the other side
+ * of the network from it. The remote endpoint runs inside the deployment that
+ * holds them and passes its own loader instead — see `load` below.
+ */
+function httpLoader(fetchImpl) {
+  return async (source) => {
+    let res;
+    try {
+      res = await fetchImpl(source.url);
+    } catch (err) {
+      return { skipped: `could not be fetched (${err.message})` };
+    }
+    if (!res.ok) return { skipped: `could not be fetched (${res.status})` };
+    const mimeType = (res.headers?.get?.("content-type") ?? "")
+      .split(";")[0]
+      .trim();
+    return { bytes: new Uint8Array(await res.arrayBuffer()), mimeType };
+  };
+}
+
+/**
+ * Content blocks to append after `get_item`'s text.
+ *
+ * Each picture is introduced by a line saying what it is, because four
+ * unlabelled images of the same application are four things a reader has to
+ * work out. Anything that could not be inlined comes back as a closing note
+ * with its link, so a picture never disappears silently.
+ *
+ * Never throws. A screenshot that will not load is a worse work order, not a
+ * failed tool call — the thread, the anchor and the source line are all still
+ * in the text block above it.
+ *
+ * `load` is how the bytes arrive. It is injected because the two transports
+ * are in different places relative to the file: the stdio package is across a
+ * network and fetches the URL, and the remote endpoint is inside the
+ * deployment that stores it and reads it straight out of storage. Everything
+ * after that — the labels, the size ceiling, the cap, the notes — is one code
+ * path, which is the only way the two doors keep answering the same.
+ */
+export async function imageBlocksFor(item, options = {}) {
+  const {
+    fetchImpl = fetch,
+    load,
+    maxImages = MAX_IMAGES,
+    maxBytes = MAX_IMAGE_BYTES,
+  } = options;
+  const loader = load ?? httpLoader(fetchImpl);
+
+  const sources = imageSources(item);
+  if (sources.length === 0) return [];
+
+  const blocks = [];
+  const notes = [];
+  for (const source of sources.slice(0, maxImages)) {
+    let got;
+    try {
+      got = await loader(source);
+    } catch (err) {
+      got = { skipped: `could not be read (${err.message})` };
+    }
+
+    // Storage serves what was uploaded. Anything that is not an image is a
+    // misfiled attachment, and a non-image in an image block fails at the
+    // client rather than here, which is a worse place to find out.
+    if (!got.skipped && got.mimeType && !got.mimeType.startsWith("image/")) {
+      got = { skipped: `is not an image (${got.mimeType})` };
+    }
+    if (!got.skipped && got.bytes.byteLength > maxBytes) {
+      got = {
+        skipped:
+          `is ${Math.round(got.bytes.byteLength / 1024)}KB, over the ` +
+          `${Math.round(maxBytes / 1024)}KB limit for an inline image`,
+      };
+    }
+
+    if (got.skipped) {
+      notes.push(`${source.label} ${source.url} — ${got.skipped}.`);
+      continue;
+    }
+    blocks.push({ type: "text", text: source.label });
+    blocks.push({
+      type: "image",
+      data: toBase64(got.bytes),
+      mimeType: got.mimeType || "image/jpeg",
+    });
+  }
+
+  const overflow = sources.length - maxImages;
+  if (overflow > 0) {
+    notes.push(
+      `${overflow} more image${overflow === 1 ? "" : "s"} on this thread, not shown.`,
+    );
+  }
+  if (notes.length > 0) {
+    blocks.push({ type: "text", text: notes.join("\n") });
+  }
+  return blocks;
+}

package/src/server.js

@@ -13,6 +13,7 @@
 
 import { toolDefinitions, callTool } from "./tools.js";
 import { ApiError } from "./client.js";
+import { VERSION } from "./version.js";
 import {
   ITEM_CARD_URI,
   clientSupportsUi,
@@ -80,7 +81,7 @@ export function createServer({ client, config, name = "skyelight" }) {
           result = {
             protocolVersion: negotiateProtocolVersion(params?.protocolVersion),
             capabilities: { tools: {}, resources: {} },
-            serverInfo: { name, version: "0.1.0" },
+            serverInfo: { name, version: VERSION },
             instructions:
               "Skyelight holds feedback people left directly on pages of a running app. " +
               "list_items to see what is outstanding, get_item for the full thread and the " +
@@ -106,7 +107,10 @@ export function createServer({ client, config, name = "skyelight" }) {
             return {
               jsonrpc: "2.0",
               id,
-              error: { code: -32602, message: `Unknown resource: ${params?.uri}` },
+              error: {
+                code: -32602,
+                message: `Unknown resource: ${params?.uri}`,
+              },
             };
           }
           result = { contents: [itemCardContents()] };
@@ -115,12 +119,19 @@ export function createServer({ client, config, name = "skyelight" }) {
         case "tools/call": {
           const { name: toolName, arguments: args = {} } = params ?? {};
           try {
-            const { text, data } = await callTool(toolName, args, {
+            const {
+              text,
+              data,
+              content: extra,
+            } = await callTool(toolName, args, {
               client,
               config,
             });
             result = {
-              content: [{ type: "text", text }],
+              // A tool result is a LIST of blocks. `get_item` uses the rest
+              // of it for images; everything else returns the one block it
+              // always did.
+              content: [{ type: "text", text }, ...(extra ?? [])],
               structuredContent: data,
             };
           } catch (err) {
@@ -144,7 +155,10 @@ export function createServer({ client, config, name = "skyelight" }) {
           return {
             jsonrpc: "2.0",
             id,
-            error: { code: METHOD_NOT_FOUND, message: `Unknown method: ${method}` },
+            error: {
+              code: METHOD_NOT_FOUND,
+              message: `Unknown method: ${method}`,
+            },
           };
       }
 
@@ -185,7 +199,10 @@ function toolErrorText(err) {
  * Wire a server to a byte stream. Split on newlines and ignore blank lines;
  * a partial line is held until the rest arrives.
  */
-export function serveStdio(server, { input = process.stdin, output = process.stdout } = {}) {
+export function serveStdio(
+  server,
+  { input = process.stdin, output = process.stdout } = {},
+) {
   let buffer = "";
 
   input.setEncoding?.("utf8");

package/src/tools.d.ts

@@ -40,6 +40,11 @@ export declare function callTool(
   name: string,
   args: Record<string, unknown>,
   deps: { client: unknown; config: { projectId?: string | null } },
-): Promise<{ text: string; data: unknown }>;
+): Promise<{
+  text: string;
+  data: unknown;
+  /** Blocks to append after the text. `get_item` returns images here. */
+  content?: import("./images.js").ContentBlock[];
+}>;
 
 export declare const PROJECT_HINT: string;

package/src/tools.js

@@ -7,6 +7,8 @@
  * still attached for anything that wants to compute on it.
  */
 
+import { imageBlocksFor } from "./images.js";
+
 const PROJECT_HINT =
   'No project. Pass projectId, or add .skyelight.json with {"projectId": "..."}.';
 
@@ -35,9 +37,9 @@ export function toolDefinitions(opts = {}) {
     {
       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.",
+        "Workspaces you can reach, with the role you hold in each, and who " +
+        "you are. Use when you do not know what exists yet, to find which " +
+        "workspace a project belongs to, or to learn your own user id.",
       inputSchema: { type: "object", properties: {} },
     },
     {
@@ -85,7 +87,9 @@ export function toolDefinitions(opts = {}) {
           },
           assignee: {
             type: "string",
-            description: 'A user id, or "none" for unassigned items.',
+            description:
+              'A user id, "me" for whoever this connection belongs to, or ' +
+              '"none" for unassigned items.',
           },
           limit: { type: "number", description: "Max items (default 50)." },
         },
@@ -185,7 +189,9 @@ export function toolDefinitions(opts = {}) {
       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.",
+        "on, the anchor identifying the element the person pointed at, and the pictures \u2014 " +
+        "what the page looked like when it was pinned, plus anything people attached \u2014 " +
+        "returned as images you can look at rather than links you cannot.",
       inputSchema: {
         type: "object",
         properties: {
@@ -216,12 +222,25 @@ function topBreakdown(counts, limit = 3) {
  * array out, and a model handed a sentence summarises.
  */
 export function renderWorkspaces(result) {
-  const { workspaces, total } = result;
+  const { workspaces, total, you } = result;
+  const lines = [];
+
+  // First, because it is the answer to a question nothing else here can
+  // answer, and the id below is what `list_items` wants as `assignee`.
+  if (you) {
+    lines.push(
+      you.name ? `You are ${you.name} — ${you.id}.` : `You are ${you.id}.`,
+    );
+    lines.push('Pass "me" as assignee to list_items to see your own work.');
+    lines.push("");
+  }
+
   if (total === 0) {
-    return "You are not a member of any workspace yet.";
+    lines.push("You are not a member of any workspace yet.");
+    return lines.join("\n");
   }
 
-  const lines = [`${plural(total, "workspace", "workspaces")} you can reach:`];
+  lines.push(`${plural(total, "workspace", "workspaces")} you can reach:`);
   lines.push("");
   for (const w of workspaces) {
     const projects = plural(w.projectCount, "project", "projects");
@@ -279,7 +298,8 @@ export function renderProjects(result) {
 }
 
 export function renderList(result, { searched } = {}) {
-  const { project, summary, items, matched, truncated } = result;
+  const { project, summary, items, matched, truncated, capped, scanLimit } =
+    result;
   const lines = [];
 
   lines.push(
@@ -288,6 +308,17 @@ export function renderList(result, { searched } = {}) {
       `${summary.resolved} resolved, ${summary.unassigned} unassigned.`,
   );
 
+  // Said immediately after the counts, because it is what those counts mean.
+  // A floor stated as a total is the kind of wrong nobody catches: the number
+  // looks like every other number this tool has ever returned.
+  if (capped) {
+    lines.push(
+      `Those counts are a floor, not a total: this project is larger than ` +
+        `the ${(scanLimit ?? 2000).toLocaleString("en-US")} most recent items ` +
+        `one call reads. Filter by page, type or status for an exact count.`,
+    );
+  }
+
   const byType = topBreakdown(summary.byType);
   if (byType) lines.push(`By type: ${byType}.`);
   const byPage = topBreakdown(summary.byPage);
@@ -315,6 +346,10 @@ export function renderList(result, { searched } = {}) {
     if (i.assignee) bits.push(`assigned to ${i.assignee}`);
     else bits.push("unassigned");
     if (i.replyCount > 0) bits.push(plural(i.replyCount, "reply", "replies"));
+    // How many people hit this, once merging has told us they are the same
+    // thing. Silent at 1, which is almost every row — a list where every line
+    // ends in "1 report" has spent its width saying nothing.
+    if (i.reportCount > 1) bits.push(`${i.reportCount} reports`);
     lines.push(`- ${i.excerpt}`);
     lines.push(`  ${bits.join(" · ")} — id ${i.id}`);
   }
@@ -341,6 +376,32 @@ export function renderItem(item) {
   // line below, and that is the half an agent cannot work out for itself.
   const repo = item.project && item.project.repo;
   if (repo) lines.push(`Code: ${repo.url}`);
+
+  // Before anything else worth reading: this thread is not the one to work.
+  // Everything below still describes it faithfully, and acting on it would
+  // put the answer where nobody is looking.
+  if (item.duplicateOf) {
+    lines.push(
+      `Merged as a duplicate of item ${item.duplicateOf}. Work that one — ` +
+        `a reply here will not reach the thread people are following.`,
+    );
+  } else if (item.reportCount > 1) {
+    lines.push(
+      `${item.reportCount} people reported this ` +
+        `(${item.reportCount - 1} merged into it).`,
+    );
+  }
+
+  // Who else is already on it. An agent that starts work a Linear-hosted
+  // agent is finishing produces a second answer nobody asked for, and the
+  // first anyone hears of it is a duplicate branch.
+  for (const l of item.linear ?? []) {
+    const handed = l.delegateName
+      ? ` — handed to ${l.delegateName}${l.delegatedMode ? `, asked to ${l.delegatedMode}` : ""}`
+      : "";
+    lines.push(`Linear: ${l.identifier}${handed}. ${l.url}`);
+  }
+
   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.
@@ -369,12 +430,31 @@ export function renderItem(item) {
     }
   }
 
-  // Stated before the anchor: a screenshot answers "what did this look like"
-  // in one step, where a selector needs the page opened first.
+  // How many people felt strongly enough to say so without writing a reply.
+  // A thread with one comment and nine thumbs up is not a thread with one
+  // comment, and nothing here said so.
+  if (item.reactions?.length) {
+    lines.push("");
+    lines.push(
+      `Reactions: ${item.reactions
+        .map((r) => `${r.emoji} ${r.count}`)
+        .join(", ")}.`,
+    );
+  }
+
+  // Stated before the anchor: a picture answers "what did this look like" in
+  // one step, where a selector needs the page opened first.
+  //
+  // The URL is deliberately not here. These arrive as image blocks after this
+  // text, which is the point of the change — and a link that has already been
+  // honoured is a line a reader has to decide about for nothing. When one
+  // cannot be fetched, the block builder says so and prints the link then.
   if (item.evidence) {
     if (item.evidence.screenshotUrl) {
       lines.push("");
-      lines.push(`Screenshot: ${item.evidence.screenshotUrl}`);
+      lines.push(
+        "Screenshot of the page when this was pinned: attached below.",
+      );
     } else if (item.evidence.expired) {
       lines.push("");
       lines.push(
@@ -383,6 +463,13 @@ export function renderItem(item) {
     }
   }
 
+  if (item.attachments?.length) {
+    const n = item.attachments.length;
+    lines.push(
+      `${plural(n, "image", "images")} attached to this thread: also below.`,
+    );
+  }
+
   lines.push("");
   lines.push("They were pointing at:");
   // elementText first: it is what a person would have named, and the one
@@ -560,15 +647,28 @@ export async function callTool(name, args, { client, config }) {
       status: args.status,
     });
     if (res?.error) throw new Error(res.error);
-    return res.changed
-      ? `Moved to ${res.status}.`
-      : `Already ${res.status} — nothing to do.`;
+    // `{ text, data }` like every other tool. It used to return a bare
+    // string, which the stdio server destructured into `text: undefined` —
+    // so a successful set_status answered with an empty content block and
+    // the model had no way to tell it had worked.
+    return {
+      text: res.changed
+        ? `Moved to ${res.status}.`
+        : `Already ${res.status} — nothing to do.`,
+      data: res,
+    };
   }
 
   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 };
+    return {
+      text: renderItem(item),
+      data: item,
+      // The pictures, as pictures. Appended after the text so the work order
+      // still reads top-down, and empty whenever there is nothing to show.
+      content: await imageBlocksFor(item, { fetchImpl: client.fetchImpl }),
+    };
   }
 
   throw new Error(`Unknown tool: ${name}`);

package/src/version.d.ts

@@ -0,0 +1,3 @@
+/** Types for version.js — see tools.d.ts for why declarations are shipped. */
+
+export declare const VERSION: string;

package/src/version.js

@@ -0,0 +1,15 @@
+/**
+ * One version number, read by everything that reports one.
+ *
+ * `initialize` used to answer `0.1.0` from a literal in `server.js` while the
+ * package on npm was 0.3.0, and the remote endpoint had its own copy of the
+ * same stale literal. A client that logs the server version — or a person
+ * reading it to work out which build they are talking to — was told something
+ * that had not been true for two releases.
+ *
+ * A constant rather than a read of `package.json`, because this module is
+ * bundled into the Convex deployment for the remote endpoint and there is no
+ * filesystem there. `test/server.test.js` asserts the two agree, so the pair
+ * cannot drift again without a test going red.
+ */
+export const VERSION = "0.4.0";