@skyelight/mcp 0.1.0

package/src/itemCard.js

@@ -0,0 +1,335 @@
+/**
+ * The `ui://` item card (SKY-278), per MCP Apps spec revision 2026-01-26.
+ *
+ * Lives in the package, like tools.js, and is imported by convex/mcp — one
+ * definition of what the host renders, for both transports.
+ *
+ * A STATIC template, not a per-item render. The host fetches it once, then
+ * pushes each tool result into the running iframe as a
+ * `ui/notifications/tool-result` notification — so one cacheable resource
+ * serves every item, and the card updates in place when the user asks about
+ * another one.
+ *
+ * Self-contained by construction: no external scripts, styles or fonts, so
+ * every CSP domain list is empty. That is the strongest sandbox the host can
+ * give us, and it costs nothing here — the card is a few hundred lines of
+ * markup, not an application.
+ *
+ * TWO DELIBERATE OMISSIONS, both worth knowing before reading the markup:
+ *
+ * No screenshot. The ticket asks for "screenshot with the anchor
+ * highlighted", and the data for that does not exist yet. Screenshots live on
+ * the SURFACE, which is keyed by host — so a pin on /checkout and a pin on
+ * /settings share one image, and a marker placed from the pin's coordinates
+ * would sit on the wrong page most of the time. Per-pin capture is SKY-282.
+ * A card showing the wrong page confidently is worse than one showing none.
+ *
+ * Not Preact. The ticket asks to share rendering with overlay-next rather
+ * than duplicate it, and those components are being extracted into shared/ by
+ * SKY-298 and the chip deleted in Phase 12. Building on them now means
+ * building on something mid-demolition, and bundling Preact into a resource
+ * that must be a single self-contained document buys nothing for markup this
+ * small. When SKY-298 lands, this template is the natural consumer.
+ */
+
+export const ITEM_CARD_URI = "ui://skyelight/item-card";
+
+/** Required by the spec for HTML apps. */
+export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+
+/** The extension identifier a client declares support with. */
+export const UI_EXTENSION_KEY = "io.modelcontextprotocol/ui";
+
+/**
+ * The app dialect version this template speaks in its `ui/initialize`.
+ * Distinct from the core protocol version — MCP Apps revs separately.
+ */
+export const APPS_PROTOCOL_VERSION = "2026-01-26";
+
+/**
+ * Whether a client can render the card.
+ *
+ * Read from two places because the two transports differ. stdio has a session
+ * and declares capabilities once at `initialize`; the remote endpoint is
+ * stateless and carries them per request in `_meta` (SKY-279, and the reason
+ * spec 2026-07-28 moved them there at all).
+ *
+ * Absent means no. A client that says nothing gets the text experience, which
+ * is complete on its own — the card is strictly additive.
+ */
+export function clientSupportsUi(source) {
+  const caps = source?.capabilities ?? source;
+  const ext = caps?.extensions?.[UI_EXTENSION_KEY];
+  if (!ext) return false;
+  const mimeTypes = ext.mimeTypes;
+  // A client that declares the extension but no mime types is taken at its
+  // word; one that lists them must include ours.
+  if (!Array.isArray(mimeTypes) || mimeTypes.length === 0) return true;
+  return mimeTypes.some(
+    (m) => typeof m === "string" && m.startsWith("text/html"),
+  );
+}
+
+/** The resource entry for `resources/list`. */
+export function itemCardResource() {
+  return {
+    uri: ITEM_CARD_URI,
+    name: "Skyelight item card",
+    description:
+      "Renders a feedback item as an interactive card: the thread, the page it is on, and what the person pointed at.",
+    mimeType: MCP_APP_MIME_TYPE,
+  };
+}
+
+/** The `resources/read` payload, including sandbox metadata. */
+export function itemCardContents() {
+  return {
+    uri: ITEM_CARD_URI,
+    mimeType: MCP_APP_MIME_TYPE,
+    text: ITEM_CARD_HTML,
+    _meta: {
+      ui: {
+        // Everything is inline. Nothing to allow, so nothing is allowed.
+        csp: {
+          connectDomains: [],
+          resourceDomains: [],
+          frameDomains: [],
+          baseUriDomains: [],
+        },
+        permissions: {},
+        prefersBorder: true,
+      },
+    },
+  };
+}
+
+const ITEM_CARD_HTML = String.raw`<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Skyelight item</title>
+<style>
+  :root {
+    color-scheme: light dark;
+    --bg: #ffffff; --fg: #17181a; --muted: #6b7280;
+    --line: #e5e7eb; --chip: #f3f4f6; --accent: #2563eb;
+  }
+  [data-theme="dark"] {
+    --bg: #17181a; --fg: #f3f4f6; --muted: #9ca3af;
+    --line: #2c2e33; --chip: #232529; --accent: #60a5fa;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; padding: 16px; background: var(--bg); color: var(--fg);
+    font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  }
+  .row { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+  .chips { margin-bottom: 10px; }
+  .chip {
+    font-size: 11px; letter-spacing: .02em; text-transform: uppercase;
+    font-weight: 600; color: var(--muted);
+    border: 1px solid var(--line); border-radius: 999px; padding: 3px 8px;
+  }
+  .chip-open { color: #b45309; border-color: #b4530933; }
+  .chip-resolved { color: #15803d; border-color: #15803d33; }
+  h1 { font-size: 15px; font-weight: 600; margin: 0 0 2px; }
+  a { color: var(--accent); }
+  .page { font-size: 12px; color: var(--muted); word-break: break-all; margin-bottom: 14px; }
+  .msg { padding: 10px 0; border-top: 1px solid var(--line); }
+  .msg:first-of-type { border-top: 0; }
+  .who { font-weight: 600; font-size: 13px; }
+  .agent {
+    font-size: 10px; text-transform: uppercase; letter-spacing: .03em;
+    font-weight: 700; color: var(--muted);
+    border: 1px solid var(--line); border-radius: 999px; padding: 1px 6px;
+  }
+  .body { white-space: pre-wrap; overflow-wrap: anywhere; margin-top: 3px; }
+  .anchor {
+    margin-top: 14px; padding: 10px; border: 1px solid var(--line);
+    border-radius: 8px; background: var(--chip); font-size: 12px;
+  }
+  .anchor b { font-weight: 600; }
+  .anchor code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; }
+  .actions { margin-top: 14px; display: flex; gap: 8px; flex-wrap: wrap; }
+  button {
+    font: inherit; font-size: 13px; padding: 6px 12px; border-radius: 7px;
+    border: 1px solid var(--line); background: var(--chip); color: var(--fg);
+    cursor: pointer;
+  }
+  button:hover { border-color: var(--accent); }
+  button[disabled] { opacity: .5; cursor: default; }
+  .note { margin-top: 10px; font-size: 12px; color: var(--muted); }
+  .empty { color: var(--muted); }
+</style>
+</head>
+<body>
+<div id="root"><p class="empty">Loading item…</p></div>
+<script>
+(function () {
+  "use strict";
+
+  // --- postMessage JSON-RPC to the host -----------------------------------
+  var nextId = 1;
+  var pending = {};
+  var item = null;
+
+  function send(msg) {
+    // The host is the only possible parent; "*" is safe inside a sandboxed
+    // iframe whose parent we cannot address by origin.
+    window.parent.postMessage(msg, "*");
+  }
+
+  function request(method, params) {
+    var id = nextId++;
+    return new Promise(function (resolve, reject) {
+      pending[id] = { resolve: resolve, reject: reject };
+      send({ jsonrpc: "2.0", id: id, method: method, params: params || {} });
+    });
+  }
+
+  window.addEventListener("message", function (event) {
+    var msg = event.data;
+    if (!msg || msg.jsonrpc !== "2.0") return;
+
+    if (msg.id !== undefined && msg.id !== null && pending[msg.id]) {
+      var p = pending[msg.id];
+      delete pending[msg.id];
+      if (msg.error) p.reject(new Error(msg.error.message || "Request failed"));
+      else p.resolve(msg.result);
+      return;
+    }
+
+    // The host pushes each tool result in rather than the card fetching it.
+    // One cached template therefore serves every item, and asking about a
+    // different one re-renders in place.
+    if (msg.method === "ui/notifications/tool-result") {
+      var structured = msg.params && msg.params.structuredContent;
+      if (structured && structured.thread) {
+        item = structured;
+        render();
+      }
+      return;
+    }
+  });
+
+  request("ui/initialize", {
+    protocolVersion: "2026-01-26",
+    clientInfo: { name: "skyelight-item-card", version: "0.1.0" },
+    appCapabilities: {
+      availableDisplayModes: ["inline"],
+      tools: { listChanged: false }
+    }
+  }).then(function (result) {
+    var theme = result && result.hostContext && result.hostContext.theme;
+    if (theme) document.documentElement.setAttribute("data-theme", theme);
+  }).catch(function () {
+    // A host that never answers still leaves a readable card once a result
+    // arrives; the handshake only supplies theming.
+  });
+
+  // --- rendering ----------------------------------------------------------
+  function el(tag, cls, text) {
+    var n = document.createElement(tag);
+    if (cls) n.className = cls;
+    if (text !== undefined && text !== null) n.textContent = String(text);
+    return n;
+  }
+
+  function isAgent(id) {
+    return typeof id === "string" && id.indexOf("agent:") === 0;
+  }
+
+  function message(m) {
+    var wrap = el("div", "msg");
+    var head = el("div", "row");
+    head.appendChild(el("span", "who", m.author));
+    if (isAgent(m.authorId)) head.appendChild(el("span", "agent", "agent"));
+    wrap.appendChild(head);
+    wrap.appendChild(el("div", "body", m.content));
+    return wrap;
+  }
+
+  function render() {
+    var root = document.getElementById("root");
+    root.textContent = "";
+
+    var chips = el("div", "row chips");
+    if (item.type) chips.appendChild(el("span", "chip", item.type));
+    chips.appendChild(
+      el("span", "chip " + (item.status === "resolved" ? "chip-resolved" : "chip-open"), item.status)
+    );
+    if (item.project && item.project.name) {
+      chips.appendChild(el("span", "chip", item.project.name));
+    }
+    root.appendChild(chips);
+
+    root.appendChild(el("h1", null, item.pageTitle || item.page || "Item"));
+    var page = el("div", "page");
+    if (item.url) {
+      var a = el("a", null, item.url);
+      a.href = item.url;
+      a.target = "_blank";
+      a.rel = "noreferrer";
+      page.appendChild(a);
+    } else {
+      page.textContent = item.page || "";
+    }
+    root.appendChild(page);
+
+    root.appendChild(message(item.thread.root));
+    (item.thread.replies || []).forEach(function (r) {
+      root.appendChild(message(r));
+    });
+
+    // What the person was pointing at. Visible text first: it is what they
+    // would have named, and the part that survives the markup changing.
+    if (item.anchor) {
+      var box = el("div", "anchor");
+      box.appendChild(el("b", null, "Pointing at"));
+      if (item.anchor.elementText) {
+        box.appendChild(el("div", null, '“' + item.anchor.elementText + '”'));
+      }
+      if (item.anchor.selectedText) {
+        box.appendChild(el("div", null, "selected: " + item.anchor.selectedText));
+      }
+      var sel = el("div");
+      sel.appendChild(el("code", null, item.anchor.selector || "—"));
+      box.appendChild(sel);
+      root.appendChild(box);
+    }
+
+    var actions = el("div", "actions");
+    var open = el("button", null, "Open in Skyelight");
+    open.addEventListener("click", function () {
+      request("ui/open-link", { url: item.url }).catch(function () {});
+    });
+    actions.appendChild(open);
+
+    // Calls the same tool the model would. The host proxies it to the server
+    // and applies whatever consent it requires — the card never talks to the
+    // API itself, and could not: it has no credential.
+    var ack = el("button", null, "Reply: looking into it");
+    ack.addEventListener("click", function () {
+      ack.disabled = true;
+      ack.textContent = "Posting…";
+      request("tools/call", {
+        name: "post_update",
+        arguments: { itemId: item.id, body: "Looking into this now." }
+      }).then(function () {
+        ack.textContent = "Posted";
+      }).catch(function (err) {
+        ack.disabled = false;
+        ack.textContent = "Reply: looking into it";
+        var note = document.querySelector(".note") || el("div", "note");
+        note.textContent = err.message;
+        root.appendChild(note);
+      });
+    });
+    actions.appendChild(ack);
+    root.appendChild(actions);
+  }
+})();
+</script>
+</body>
+</html>`;

package/src/server.js

@@ -0,0 +1,218 @@
+/**
+ * MCP over stdio, JSON-RPC 2.0, newline-delimited.
+ *
+ * Written against the protocol directly rather than the SDK. The surface a
+ * read-only server needs is four methods, and a package people run with
+ * `npx` is worth keeping dependency-free — nothing to install, nothing to
+ * audit, and the whole thing is testable by feeding it strings.
+ *
+ * stdout is the protocol channel. Anything diagnostic goes to stderr; a
+ * stray console.log here corrupts the stream and the failure looks like the
+ * client being broken.
+ */
+
+import { toolDefinitions, callTool } from "./tools.js";
+import { ApiError } from "./client.js";
+import {
+  ITEM_CARD_URI,
+  clientSupportsUi,
+  itemCardResource,
+  itemCardContents,
+} from "./itemCard.js";
+
+/**
+ * Protocol revisions this server speaks, newest first.
+ *
+ * Only `tools` is implemented, and that surface has been stable across all of
+ * these, so supporting the range costs nothing and is what keeps a client on
+ * an older revision working.
+ *
+ * `initialize` MUST echo the client's requested version when we support it.
+ * Answering with our own newest instead is a hard failure on the client side,
+ * not a downgrade — Claude Code 2.1.x asks for 2025-11-25 and refuses a
+ * server that replies 2026-07-28 with "protocol version is not supported".
+ */
+export const SUPPORTED_PROTOCOL_VERSIONS = [
+  "2026-07-28",
+  "2025-11-25",
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05",
+];
+
+/** Newest we speak. Used where there is no client to negotiate with. */
+export const PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
+
+/**
+ * Pick the version to answer `initialize` with: the client's, when we speak
+ * it. Otherwise our newest, and the client decides whether to continue —
+ * which is the spec's escape hatch, not an error to raise here.
+ */
+export function negotiateProtocolVersion(requested) {
+  return SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+    ? requested
+    : PROTOCOL_VERSION;
+}
+
+const PARSE_ERROR = -32700;
+const METHOD_NOT_FOUND = -32601;
+const INTERNAL_ERROR = -32603;
+
+export function createServer({ client, config, name = "skyelight" }) {
+  /**
+   * Whether this client can render the item card. Unlike the remote endpoint,
+   * stdio HAS a session — the capability is declared once at `initialize` and
+   * remembered for the connection (SKY-279).
+   */
+  let supportsUi = false;
+
+  async function handle(message) {
+    const { id, method, params } = message;
+    // A notification has no id and takes no reply — including
+    // notifications/initialized, which is the client saying it is ready.
+    const isNotification = id === undefined || id === null;
+
+    try {
+      let result;
+      switch (method) {
+        case "initialize":
+          supportsUi = clientSupportsUi(params?.capabilities);
+          result = {
+            protocolVersion: negotiateProtocolVersion(params?.protocolVersion),
+            capabilities: { tools: {}, resources: {} },
+            serverInfo: { name, version: "0.1.0" },
+            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 " +
+              "element it points at.",
+          };
+          break;
+
+        case "tools/list":
+          result = {
+            tools: toolDefinitions(
+              supportsUi ? { uiResourceUri: ITEM_CARD_URI } : undefined,
+            ),
+          };
+          break;
+
+        case "resources/list":
+          result = { resources: [itemCardResource()] };
+          break;
+
+        case "resources/read":
+          if (params?.uri !== ITEM_CARD_URI) {
+            if (isNotification) return null;
+            return {
+              jsonrpc: "2.0",
+              id,
+              error: { code: -32602, message: `Unknown resource: ${params?.uri}` },
+            };
+          }
+          result = { contents: [itemCardContents()] };
+          break;
+
+        case "tools/call": {
+          const { name: toolName, arguments: args = {} } = params ?? {};
+          try {
+            const { text, data } = await callTool(toolName, args, {
+              client,
+              config,
+            });
+            result = {
+              content: [{ type: "text", text }],
+              structuredContent: data,
+            };
+          } catch (err) {
+            // A failed tool call is a RESULT with isError, not a protocol
+            // error — the model should see what went wrong and adjust, not
+            // have the call vanish into a transport failure.
+            result = {
+              content: [{ type: "text", text: toolErrorText(err) }],
+              isError: true,
+            };
+          }
+          break;
+        }
+
+        case "ping":
+          result = {};
+          break;
+
+        default:
+          if (isNotification) return null;
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: METHOD_NOT_FOUND, message: `Unknown method: ${method}` },
+          };
+      }
+
+      if (isNotification) return null;
+      return { jsonrpc: "2.0", id, result };
+    } catch (err) {
+      if (isNotification) return null;
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: INTERNAL_ERROR, message: err.message },
+      };
+    }
+  }
+
+  return { handle };
+}
+
+/** Turn an API failure into something a model can act on. */
+function toolErrorText(err) {
+  if (err instanceof ApiError) {
+    if (err.status === 401) {
+      return "Skyelight rejected the API key. Check SKYELIGHT_API_TOKEN — it may have been revoked.";
+    }
+    if (err.status === 403) {
+      // The server's message names the role and what was required.
+      return `Not permitted: ${err.message}`;
+    }
+    if (err.status === 404) {
+      return `Not found: ${err.message}`;
+    }
+    return err.message;
+  }
+  return err.message;
+}
+
+/**
+ * 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 } = {}) {
+  let buffer = "";
+
+  input.setEncoding?.("utf8");
+  input.on("data", async (chunk) => {
+    buffer += chunk;
+    let newline;
+    while ((newline = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        output.write(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            id: null,
+            error: { code: PARSE_ERROR, message: "Invalid JSON" },
+          }) + "\n",
+        );
+        continue;
+      }
+
+      const response = await server.handle(message);
+      if (response) output.write(JSON.stringify(response) + "\n");
+    }
+  });
+}

package/src/tools.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Types for tools.js.
+ *
+ * The module is plain JavaScript so the package stays dependency-free and
+ * runnable with no build step. It is also imported by convex/mcp/protocol.ts,
+ * which is TypeScript — and by the extension's tsconfig, which does not
+ * enable allowJs. Shipping declarations is what lets one definition of the
+ * tool set serve all three without a build.
+ */
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+export declare function toolDefinitions(opts?: {
+  uiResourceUri?: string;
+}): ToolDefinition[];
+
+export declare function renderList(
+  result: unknown,
+  opts?: { searched?: string },
+): string;
+
+export declare function renderItem(item: unknown): string;
+export declare function renderWorkspaces(result: unknown): string;
+export declare function renderProjects(result: unknown): string;
+
+export declare function renderPosted(
+  result: unknown,
+  opts: { kind: "update" | "item" },
+): string;
+
+export declare function callTool(
+  name: string,
+  args: Record<string, unknown>,
+  deps: { client: unknown; config: { projectId?: string | null } },
+): Promise<{ text: string; data: unknown }>;
+
+export declare const PROJECT_HINT: string;