@skyelight/mcp 0.4.1 → 0.5.1

package/src/install.js

@@ -47,7 +47,13 @@ export const CLIENTS = [
     command: (url, clientId, port = CALLBACK_PORT) => [
       "claude",
       [
-        "mcp", "add", "-s", "user", "--transport", "http", SERVER_NAME,
+        "mcp",
+        "add",
+        "-s",
+        "user",
+        "--transport",
+        "http",
+        SERVER_NAME,
         // Only when the deployment named a client. Without them Claude Code
         // registers itself dynamically, which is the right thing to do and
         // the wrong thing to prevent by passing an empty id.
@@ -57,6 +63,11 @@ export const CLIENTS = [
         url,
       ],
     ],
+    /** Removed by its own CLI too, for the reason it is added by one. */
+    removeCommand: () => [
+      "claude",
+      ["mcp", "remove", "-s", "user", SERVER_NAME],
+    ],
     detect: () => hasBinary("claude"),
   },
   {
@@ -201,10 +212,56 @@ export function addToToml(existing, block) {
   let end = start + 1;
   while (end < lines.length) {
     const t = lines[end].trim();
-    if (t.startsWith("[") && !t.startsWith(`[mcp_servers.${SERVER_NAME}`)) break;
+    if (t.startsWith("[") && !t.startsWith(`[mcp_servers.${SERVER_NAME}`))
+      break;
     end++;
   }
   return `${[...lines.slice(0, start), block, ...lines.slice(end)]
     .join("\n")
     .trimEnd()}\n`;
 }
+
+/**
+ * Take the server back out of a JSON config, leaving everything else.
+ *
+ * Null when it was not there, so the caller can say "nothing to remove"
+ * rather than rewriting a file it did not change. `mcpServers` is left
+ * behind even when empty: it is the client's key, not ours, and deleting a
+ * structure somebody else's tool expects to find is a bigger liberty than
+ * removing our own row from it.
+ */
+export function removeFromJson(existing) {
+  if (!existing.trim()) return null;
+  const parsed = JSON.parse(existing);
+  if (!parsed?.mcpServers || !(SERVER_NAME in parsed.mcpServers)) return null;
+  const { [SERVER_NAME]: _gone, ...rest } = parsed.mcpServers;
+  return `${JSON.stringify({ ...parsed, mcpServers: rest }, null, 2)}\n`;
+}
+
+/**
+ * Take our TOML tables back out.
+ *
+ * Both of them — Codex writes `[mcp_servers.skyelight]` and
+ * `[mcp_servers.skyelight.oauth]`, and removing only the first would leave
+ * an orphaned oauth table that parses as a server with no url. The same
+ * "runs to the next table that is not ours" rule `addToToml` uses.
+ */
+export function removeFromToml(existing) {
+  const header = `[mcp_servers.${SERVER_NAME}]`;
+  if (!existing.includes(header)) return null;
+
+  const lines = existing.split("\n");
+  const start = lines.findIndex((l) => l.trim() === header);
+  let end = start + 1;
+  while (end < lines.length) {
+    const t = lines[end].trim();
+    if (t.startsWith("[") && !t.startsWith(`[mcp_servers.${SERVER_NAME}`))
+      break;
+    end++;
+  }
+  const kept = [...lines.slice(0, start), ...lines.slice(end)]
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trimEnd();
+  return kept ? `${kept}\n` : "";
+}

package/src/server.js

@@ -12,6 +12,7 @@
  */
 
 import { toolDefinitions, callTool } from "./tools.js";
+import { ICONS } from "./brand.js";
 import { ApiError } from "./client.js";
 import { VERSION } from "./version.js";
 import {
@@ -81,11 +82,19 @@ export function createServer({ client, config, name = "skyelight" }) {
           result = {
             protocolVersion: negotiateProtocolVersion(params?.protocolVersion),
             capabilities: { tools: {}, resources: {} },
-            serverInfo: { name, version: VERSION },
+            serverInfo: {
+              name,
+              title: "Skyelight",
+              version: VERSION,
+              icons: ICONS,
+            },
             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.",
+              "element it points at. whats_new catches you up since you last looked; " +
+              "find_by_source shows feedback on a file before you edit it; find_similar " +
+              "checks for an existing report before create_item; project_review and " +
+              "decision_log hold what a project settled, for reviews and hand-offs.",
           };
           break;
 

package/src/theme.js

@@ -0,0 +1,120 @@
+/**
+ * How Skyelight looks in a terminal.
+ *
+ * Pulled out of `cli.js` because the installer had five one-line escape
+ * helpers and no brand at all — the same five every Node CLI writes, so the
+ * output read as generic tooling rather than as Skyelight. This is the one
+ * place that decides, and it is plain data plus string functions so the
+ * installer stays about installing.
+ *
+ * Colour is a courtesy, not a guarantee. Everything degrades: truecolor where
+ * the terminal says it has it, the 256-colour cube where it does not, plain
+ * text where colour is unwanted or the output is not a terminal at all. A CLI
+ * whose output is piped into a file should produce a file somebody can read.
+ */
+
+/**
+ * Whether to colour at all.
+ *
+ * `NO_COLOR` is honoured because it is the convention and costs nothing to
+ * respect — see no-color.org. A non-TTY stdout means the output is being
+ * piped or captured, where escape codes are noise. `TERM=dumb` says so
+ * outright.
+ */
+const COLOR =
+  !process.env.NO_COLOR &&
+  process.env.TERM !== "dumb" &&
+  Boolean(process.stdout.isTTY);
+
+/**
+ * Whether 24-bit colour is available.
+ *
+ * Only `COLORTERM` answers this honestly; `TERM` lies in both directions, and
+ * probing costs a round trip nobody wants on a command that finishes in a
+ * second. Without it the brand blue falls back to the nearest cube colour,
+ * which is close enough that nobody who has not seen both would notice.
+ */
+const TRUECOLOR = /^(truecolor|24bit)$/i.test(process.env.COLORTERM ?? "");
+
+/**
+ * The accent, and only the accent.
+ *
+ * `#3b82f6` is `--accent` from `shared/styles/tokens.css`, so the terminal
+ * and the app are the same blue rather than two blues that were each chosen
+ * to look right on their own. `33` is the nearest 256-colour cube entry.
+ */
+const BRAND_RGB = [59, 130, 246];
+const BRAND_256 = 33;
+
+const wrap = (open, s) => (COLOR ? `\x1b[${open}m${s}\x1b[0m` : String(s));
+
+export const bold = (s) => wrap("1", s);
+export const dim = (s) => wrap("2", s);
+export const green = (s) => wrap("32", s);
+export const amber = (s) => wrap("33", s);
+export const red = (s) => wrap("31", s);
+
+/** The brand blue, at whatever fidelity this terminal can manage. */
+export const brand = (s) =>
+  !COLOR
+    ? String(s)
+    : TRUECOLOR
+      ? `\x1b[38;2;${BRAND_RGB.join(";")}m${s}\x1b[0m`
+      : `\x1b[38;5;${BRAND_256}m${s}\x1b[0m`;
+
+/**
+ * Marks, spelled out so a terminal that cannot draw them still says
+ * something.
+ *
+ * Windows consoles and CI log viewers turn an unsupported glyph into a
+ * replacement character, which is worse than an ASCII stand-in — it reads as
+ * corruption rather than as plainness. `LANG` naming UTF-8 is the cheapest
+ * honest signal available.
+ */
+const UNICODE = /UTF-?8/i.test(
+  process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG || "",
+);
+
+export const MARK = {
+  logo: UNICODE ? "◆" : "*",
+  tick: UNICODE ? "✓" : "OK",
+  arrow: UNICODE ? "›" : ">",
+  bullet: UNICODE ? "•" : "-",
+  dot: UNICODE ? "·" : ".",
+};
+
+/**
+ * The header every command opens with.
+ *
+ * A mark and a name rather than an ASCII-art banner. A banner is six lines
+ * of somebody else's enthusiasm at the top of a tool you are running for the
+ * fourth time today, and it pushes the thing you actually asked for below
+ * the fold on a short terminal.
+ *
+ * `subtitle` carries which deployment is being configured, because running
+ * this against the wrong one is the mistake with the least visible symptom:
+ * everything succeeds, against somebody else's data.
+ */
+export function header(subtitle) {
+  const line = `${brand(MARK.logo)} ${bold("Skyelight")}`;
+  return subtitle ? `\n  ${line}  ${dim(subtitle)}\n` : `\n  ${line}\n`;
+}
+
+/** A section heading — the word, then the things under it, indented. */
+export const heading = (s) => `  ${bold(s)}`;
+
+/**
+ * Pad to a visible width, counting characters rather than bytes.
+ *
+ * `padEnd` on a styled string counts the escape codes, so a column of them
+ * comes out ragged by however many codes each one happens to carry — which
+ * is why this takes the plain text and the caller styles afterwards.
+ */
+export const pad = (plain, width) => String(plain).padEnd(width);
+
+/** Two spaces of indent, applied to a block that may already have newlines. */
+export const indent = (s, by = 4) =>
+  String(s)
+    .split("\n")
+    .map((l) => (l ? " ".repeat(by) + l : l))
+    .join("\n");

package/src/tools.d.ts

@@ -16,6 +16,14 @@ export interface ToolDefinition {
     properties: Record<string, unknown>;
     required?: string[];
   };
+  _meta?: Record<string, unknown>;
+  securitySchemes?: Array<{ type: string; scopes?: string[] }>;
+  annotations?: {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+  };
 }
 
 export declare function toolDefinitions(opts?: {
@@ -30,6 +38,8 @@ export declare function renderList(
 export declare function renderItem(item: unknown): string;
 export declare function renderWorkspaces(result: unknown): string;
 export declare function renderProjects(result: unknown): string;
+export declare function renderMembers(result: unknown): string;
+export declare function renderAssigned(result: unknown): string;
 
 export declare function renderPosted(
   result: unknown,

package/src/tools.js

@@ -1,5 +1,5 @@
 /**
- * The three tools, and — more importantly — how their results are worded.
+ * The 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
@@ -8,6 +8,13 @@
  */
 
 import { imageBlocksFor } from "./images.js";
+import { STATUS } from "./brand.js";
+import {
+  callInsightTool,
+  insightToolDefinitions,
+  INSIGHT_TOOLS,
+  renderInsight,
+} from "./insights.js";
 
 const PROJECT_HINT =
   'No project. Pass projectId, or add .skyelight.json with {"projectId": "..."}.';
@@ -68,7 +75,9 @@ export function toolDefinitions(opts = {}) {
         properties: {
           projectId: {
             type: "string",
-            description: "Project to read. Optional if a project is bound.",
+            description:
+              "Project to read. Optional when a project is bound or the workspace has only one; " +
+              "otherwise the error lists the projects and their ids.",
           },
           page: {
             type: "string",
@@ -104,7 +113,12 @@ export function toolDefinitions(opts = {}) {
         type: "object",
         properties: {
           query: { type: "string", description: "Text to look for." },
-          projectId: { type: "string" },
+          projectId: {
+            type: "string",
+            description:
+              "Project to search. Optional when a project is bound or the workspace has only one; " +
+              "otherwise the error lists the projects and their ids.",
+          },
           status: { type: "string", enum: ["open", "deferred", "resolved"] },
           limit: { type: "number" },
         },
@@ -126,6 +140,13 @@ export function toolDefinitions(opts = {}) {
             description:
               "What you found or changed, in plain language for the person who reported it.",
           },
+          mentions: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              'People to notify, by name, email or id from list_members ("me" is you). ' +
+              "Write @Name in the body where you mention them.",
+          },
           links: {
             type: "array",
             description: "Optional links — a PR, a commit, a deploy.",
@@ -166,10 +187,61 @@ export function toolDefinitions(opts = {}) {
             description: "Optional if a project is bound.",
           },
           pageTitle: { type: "string" },
+          mentions: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              'People to notify, by name, email or id from list_members ("me" is you). ' +
+              "Write @Name in the body where you mention them.",
+          },
+          assignee: {
+            type: "string",
+            description:
+              'Who should take it: a name, email or id from list_members, or "me".',
+          },
         },
         required: ["url", "body"],
       },
     },
+    {
+      name: "list_members",
+      description:
+        "The people in a workspace: name, email, role and id. Call it when you are asked to " +
+        "tell, ask or hand something to someone by name, then pass their name or id to " +
+        "assign, or in mentions on create_item or post_update.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: {
+            type: "string",
+            description: "Optional if a project is bound.",
+          },
+          workspaceId: {
+            type: "string",
+            description: "Instead of a project, from list_workspaces.",
+          },
+        },
+      },
+    },
+    {
+      name: "assign",
+      description:
+        "Hand an item to a person, who is notified the way an assignment in the app notifies " +
+        "them. Pass null as the assignee to unassign it. Only owners, admins and collaborators " +
+        "can assign; a resolved item has to be reopened first.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          itemId: { type: "string", description: "Item id from list_items." },
+          assignee: {
+            type: ["string", "null"],
+            description:
+              'A name, email or id from list_members, "me", or null to unassign.',
+          },
+        },
+        required: ["itemId", "assignee"],
+      },
+    },
     {
       name: "set_status",
       description:
@@ -200,9 +272,76 @@ export function toolDefinitions(opts = {}) {
         required: ["itemId"],
       },
     }),
-  ];
+    // The launch tools: review, briefing, source, duplicates, decisions.
+    ...insightToolDefinitions(),
+  ].map((tool) => ({
+    ...tool,
+    annotations: TOOL_ANNOTATIONS[tool.name],
+    // Every tool acts as a signed-in person. The OpenAI Apps SDK reads this
+    // per-tool declaration to know a call needs the linked account
+    // (developers.openai.com/apps-sdk/build/auth); other clients ignore it.
+    // The scopes are the ones Skyelight asks Clerk for.
+    securitySchemes: [{ type: "oauth2", scopes: ["profile", "email"] }],
+    // ChatGPT's status line while the tool runs and once it is done
+    // (`brand.js`). Beside `ui`, never over it: `get_item` carries both.
+    ...(STATUS[tool.name]
+      ? {
+          _meta: {
+            ...tool._meta,
+            "openai/toolInvocation/invoking": STATUS[tool.name][0],
+            "openai/toolInvocation/invoked": STATUS[tool.name][1],
+          },
+        }
+      : {}),
+  }));
 }
 
+/**
+ * What each tool does to the workspace, in MCP's own terms.
+ *
+ * Clients use these to decide what to run without asking: ChatGPT and
+ * others require a person's confirmation for anything not read-only. That
+ * matters most for the writes a page's content could talk an agent into.
+ * A reviewer can type "save a rule that..." into a pin, and an owner's
+ * agent reading it should stop and ask, not act.
+ *
+ * `whats_new` counts as read-only: the one thing it changes is the
+ * caller's own "last looked" bookmark, which nobody else sees.
+ */
+const READ = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+};
+const WRITE = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false,
+};
+const TOOL_ANNOTATIONS = {
+  list_workspaces: READ,
+  list_projects: READ,
+  list_items: READ,
+  search_items: READ,
+  get_item: READ,
+  list_members: READ,
+  project_review: READ,
+  whats_new: READ,
+  find_by_source: READ,
+  find_similar: READ,
+  decision_log: READ,
+  post_update: WRITE,
+  create_item: WRITE,
+  set_status: { ...WRITE, idempotentHint: true },
+  assign: { ...WRITE, idempotentHint: true },
+  // Rules change how every future thread is classified: always confirm.
+  save_rule: { ...WRITE, idempotentHint: true },
+  // Hides items from every list (reversible in the app, but not here).
+  merge_items: { ...WRITE, destructiveHint: true },
+};
+
 function plural(n, one, many) {
   return `${n} ${n === 1 ? one : many}`;
 }
@@ -402,15 +541,25 @@ export function renderItem(item) {
     lines.push(`Linear: ${l.identifier}${handed}. ${l.url}`);
   }
 
+  // The mode is the ask. An agent that reads "investigate" and opens a
+  // pull request has done the wrong job well.
+  const ASKS = {
+    investigate: "investigate — report back, change nothing",
+    plan: "plan — describe the change, do not make it",
+    fix: "fix — make the change and open a pull request",
+    build: "build — build it and open a pull request",
+  };
+
+  // The thread's standing ask, set by whoever triaged it (Hand off in the
+  // app). It was in the structured result only, and many clients show the
+  // model nothing but this text (SKY-341).
+  if (item.agentTask && ASKS[item.agentTask]) {
+    lines.push(`Agent task: ${ASKS[item.agentTask]}`);
+  }
+
   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];
+    const ask = ASKS[item.assignee.mode];
+    const asked = ask ? `asked to ${ask}` : undefined;
     lines.push(
       asked
         ? `Assigned to ${item.assignee.name}, ${asked}`
@@ -449,6 +598,16 @@ export function renderItem(item) {
   // 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.
+  // Said before the screenshot, which it qualifies: the picture and the
+  // captured markup show where the pin was first placed, not where it is.
+  if (item.movedAt) {
+    lines.push("");
+    lines.push(
+      `Moved to a different element on ${new Date(item.movedAt).toISOString().slice(0, 10)}. ` +
+        "The anchor and source above are the current ones; the screenshot and page capture were taken where it was first placed.",
+    );
+  }
+
   if (item.evidence) {
     if (item.evidence.screenshotUrl) {
       lines.push("");
@@ -567,14 +726,49 @@ export function renderItem(item) {
   return lines.join("\n");
 }
 
+/** Who was notified, as a trailing sentence, or nothing. */
+function notifiedLine(result) {
+  const parts = [];
+  if (result?.assignedTo) parts.push(`Assigned to ${result.assignedTo}.`);
+  const mentioned = result?.mentioned ?? [];
+  if (mentioned.length) parts.push(`Mentioned ${mentioned.join(", ")}.`);
+  return parts.length ? ` ${parts.join(" ")}` : "";
+}
+
 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."
+      "they left the feedback." +
+      notifiedLine(result)
     );
   }
-  return `Raised a new item on ${result.page ?? "that page"}. id ${result.pinId}`;
+  return (
+    `Raised a new item on ${result.page ?? "that page"}. id ${result.pinId}` +
+    notifiedLine(result)
+  );
+}
+
+export function renderMembers(result) {
+  const members = result?.members ?? [];
+  const where = result?.workspace?.name ? ` in ${result.workspace.name}` : "";
+  if (members.length === 0) return `Nobody${where} yet.`;
+  const lines = members.map(
+    (m) =>
+      `- ${m.name}${m.email ? ` <${m.email}>` : ""}, ${m.role} (id ${m.id})`,
+  );
+  return `${members.length} ${members.length === 1 ? "person" : "people"}${where}:\n${lines.join("\n")}`;
+}
+
+export function renderAssigned(result) {
+  if (!result.changed) {
+    return result.assignedTo
+      ? `Already assigned to ${result.assignedTo}. Nothing to do.`
+      : "Already unassigned. Nothing to do.";
+  }
+  return result.assignedTo
+    ? `Assigned to ${result.assignedTo}. They have been notified.`
+    : "Unassigned.";
 }
 
 export async function callTool(name, args, { client, config }) {
@@ -621,6 +815,7 @@ export async function callTool(name, args, { client, config }) {
     const result = await client.postUpdate({
       itemId: args.itemId,
       body: args.body,
+      ...(args.mentions ? { mentions: args.mentions } : {}),
       links: args.links,
     });
     return { text: renderPosted(result, { kind: "update" }), data: result };
@@ -635,10 +830,32 @@ export async function callTool(name, args, { client, config }) {
       selector: args.selector,
       projectId,
       pageTitle: args.pageTitle,
+      ...(args.mentions ? { mentions: args.mentions } : {}),
+      ...(args.assignee ? { assignee: args.assignee } : {}),
     });
     return { text: renderPosted(result, { kind: "item" }), data: result };
   }
 
+  if (name === "list_members") {
+    const result = await client.listMembers({
+      projectId,
+      workspaceId: args.workspaceId,
+    });
+    return { text: renderMembers(result), data: result };
+  }
+
+  if (name === "assign") {
+    if (!args.itemId) throw new Error("assign needs an itemId");
+    if (args.assignee === undefined) {
+      throw new Error("assign needs an assignee, or null to unassign");
+    }
+    const result = await client.assign({
+      itemId: args.itemId,
+      assignee: args.assignee,
+    });
+    return { text: renderAssigned(result), 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");
@@ -671,6 +888,11 @@ export async function callTool(name, args, { client, config }) {
     };
   }
 
+  if (INSIGHT_TOOLS.has(name)) {
+    const result = await callInsightTool(name, args, { client, projectId });
+    return { text: renderInsight(name, result), data: result };
+  }
+
   throw new Error(`Unknown tool: ${name}`);
 }
 

package/src/version.js

@@ -12,4 +12,4 @@
  * 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.1";
+export const VERSION = "0.5.1";