@skyelight/mcp 0.1.4 → 0.3.0

package/README.md

@@ -4,12 +4,29 @@ An MCP server that lets a coding agent read the feedback people left on your
 running app — the thread, the page, and the element they were pointing at —
 and report back on it when the work is done.
 
-Works with anything that speaks MCP over stdio: Claude Code, Cursor, Codex.
+Works with anything that speaks MCP over stdio: Claude Code, Cursor, Grok, Codex.
 
 ## Setup
 
 **Get a personal access token.** In the Skyelight web app, go to your account
-settings → **Personal access tokens** → create one. It is shown once.
+settings → **API Keys** → create one. It is shown once, and you can give
+it an expiry.
+
+## The short way
+
+```bash
+npx @skyelight/mcp init
+```
+
+Finds your coding agent, registers the remote server with it, and leaves the
+sign-in to OAuth — nothing is pasted and no key is stored on disk. It shows
+what it will change and waits; `--yes` skips that once you have read it.
+
+It knows Claude Code, Cursor, Grok, Codex and Windsurf. Name one with
+`--client cursor` when more than one is installed, and point at another deployment with
+`SKYELIGHT_URL=https://…`. The deployment tells the installer its own MCP URL
+and OAuth client over `/mcp/install-config`, so this package holds no
+environment-specific constants.
 
 The token is yours, not a service account's: anything the agent writes is
 attributed to you, marked with the tool it came through. That is deliberate —
@@ -119,10 +136,10 @@ There is no service-account mode. Synthetic agent identities existed and were
 removed: a workspace should not grow a member for every tool somebody plugs in,
 and a reply nobody is accountable for is worse than one attributed plainly.
 
-A consequence worth knowing: a **workspace API key cannot write.** It stands
-for a role, not a person, so there is nobody to attribute a reply to, and the
-write tools refuse it with a message saying so. Keys still read, and still
-respect a project binding — they are for scripts and CI, not for agents.
+Workspace API keys (`sk_live_...`) used to be a second way in, for scripts and
+CI. They are gone — a credential that outlives whoever minted it is one nobody
+is accountable for, and the write tools already refused them for exactly that
+reason. A personal token is the only credential the API accepts.
 
 ## Permissions
 

package/package.json

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

package/src/cli.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+/**
+ * `npx @skyelight/mcp init`
+ *
+ * Finds your coding agent, registers Skyelight's MCP server with it, and
+ * leaves the sign-in to the agent — the server speaks OAuth, so the first
+ * time the agent connects it opens a browser and you approve it there. No
+ * token is pasted anywhere, and none is stored on disk by this.
+ *
+ * It shows the change and waits, like `@skyelight/build init` does. Editing
+ * a config somebody else wrote is the kind of help that has to ask first.
+ * `--yes` exists for people who have already read it once.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { spawnSync } from "node:child_process";
+import {
+  CLIENTS,
+  SERVER_NAME,
+  detectClients,
+  findClient,
+  addToJson,
+  addToToml,
+} from "./install.js";
+
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const amber = (s) => `\x1b[33m${s}\x1b[0m`;
+
+/**
+ * Which deployment to register. Production unless told otherwise.
+ */
+const ORIGIN = (
+  process.env.SKYELIGHT_URL ?? "https://mellow-zebra-383.convex.site"
+).replace(/\/+$/, "");
+
+/**
+ * Asked for rather than baked in.
+ *
+ * The OAuth client id is per deployment, so a published package cannot hold
+ * one — that would be an npm release per environment, and the first person
+ * to run it against the wrong one gets an OAuth error naming a client that
+ * is not theirs. `/mcp/install-config` is the deployment saying what it is.
+ *
+ * A deployment that answers without a client id is one doing dynamic client
+ * registration, which is the correct fallback rather than a failure: the
+ * flags that carry the id are simply left off.
+ */
+async function fetchConfig() {
+  const res = await fetch(`${ORIGIN}/mcp/install-config`, {
+    headers: { accept: "application/json" },
+  });
+  if (!res.ok) {
+    throw new Error(`${ORIGIN} answered ${res.status}`);
+  }
+  const body = await res.json();
+  if (typeof body?.url !== "string") {
+    throw new Error(`${ORIGIN} did not say where its MCP server is`);
+  }
+  return body;
+}
+
+async function confirm(question) {
+  if (!process.stdin.isTTY) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return /^y(es)?$/i.test((await rl.question(`${question} [y/N] `)).trim());
+  } finally {
+    rl.close();
+  }
+}
+
+function listClients() {
+  console.log("Say which one with:\n");
+  for (const c of CLIENTS) {
+    console.log(`  ${bold(`npx @skyelight/mcp init --client ${c.id}`)}  ${dim(c.label)}`);
+  }
+  console.log("");
+}
+
+async function init({ yes, clientFlag }) {
+  console.log(`\n${bold("Skyelight MCP")}\n`);
+
+  let config;
+  try {
+    config = await fetchConfig();
+  } catch (err) {
+    console.log(amber(`Could not reach Skyelight: ${err.message}\n`));
+    console.log(
+      dim("  Point at another deployment with SKYELIGHT_URL=https://…\n"),
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const { url: MCP_URL, clientId: CLIENT_ID, callbackPort } = config;
+
+  let client;
+  if (clientFlag) {
+    client = findClient(clientFlag);
+    if (!client) {
+      console.log(amber(`Unknown agent "${clientFlag}".\n`));
+      listClients();
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    const found = detectClients();
+    if (found.length === 0) {
+      console.log(amber("No coding agent found on this machine.\n"));
+      listClients();
+      process.exitCode = 1;
+      return;
+    }
+    if (found.length > 1) {
+      console.log(
+        `Found ${found.map((c) => bold(c.label)).join(", ")}.\n`,
+      );
+      listClients();
+      process.exitCode = 1;
+      return;
+    }
+    client = found[0];
+    console.log(`Found ${bold(client.label)}.\n`);
+  }
+
+  // Claude Code registers through its own CLI — see `install.js`.
+  if (client.command) {
+    const [bin, args] = client.command(MCP_URL, CLIENT_ID, callbackPort);
+    console.log(dim(`  ${bin} ${args.join(" ")}\n`));
+    if (!yes && !(await confirm("Run it?"))) {
+      console.log(dim("\nNothing changed.\n"));
+      return;
+    }
+    const res = spawnSync(bin, args, { stdio: "inherit" });
+    if (res.status !== 0) {
+      console.log(amber("\nThat command failed. Run it yourself to see why.\n"));
+      process.exitCode = 1;
+      return;
+    }
+    done(client);
+    return;
+  }
+
+  const file = client.file();
+  const before = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const after =
+    client.format === "json"
+      ? addToJson(before, client.entry(MCP_URL, CLIENT_ID))
+      : addToToml(before, client.entry(MCP_URL, CLIENT_ID));
+
+  if (after === null) {
+    console.log(green(`Already set up in ${file}\n`));
+    return;
+  }
+
+  console.log(`${bold(file)}\n`);
+  console.log(
+    dim(
+      client.format === "json"
+        ? `  mcpServers.${SERVER_NAME} → ${MCP_URL}`
+        : `  [mcp_servers.${SERVER_NAME}] → ${MCP_URL}`,
+    ),
+  );
+  console.log("");
+
+  if (!yes && !(await confirm("Write it?"))) {
+    console.log(dim("\nNothing written.\n"));
+    return;
+  }
+
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, after, "utf8");
+  done(client);
+}
+
+function done(client) {
+  console.log(green(`\n✓ Skyelight added to ${client.label}\n`));
+  console.log("Restart it, then ask it to list your Skyelight items.");
+  console.log(
+    dim("It will open a browser to sign you in the first time.\n"),
+  );
+}
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+
+if (cmd === "init") {
+  const yes = argv.includes("--yes") || argv.includes("-y");
+  const at = argv.indexOf("--client");
+  await init({ yes, clientFlag: at === -1 ? null : argv[at + 1] });
+} else {
+  console.log(`\n${bold("@skyelight/mcp")}\n`);
+  console.log("  npx @skyelight/mcp init            set up your coding agent");
+  console.log("  npx @skyelight/mcp init --client cursor\n");
+  console.log(dim("  Running with no command starts the stdio server.\n"));
+}

package/src/config.js

@@ -92,9 +92,10 @@ export function resolveConfig({
         "No Skyelight credentials found. Either:",
         "  • export SKYELIGHT_API_URL and SKYELIGHT_API_TOKEN, or",
         "  • put them in .env.local, or",
-        '  • save ~/.skyelight/credentials as {"apiUrl": "...", "token": "sk_live_..."}',
+        '  • save ~/.skyelight/credentials as {"apiUrl": "...", "token": "sky_..."}',
         "",
-        "Create a key under Settings → API keys in the Skyelight web app.",
+        "Create one under Account settings → API Keys in the",
+        "Skyelight web app. Workspace API keys (sk_live_...) no longer work.",
       ].join("\n"),
     );
   }

package/src/index.js

@@ -1,8 +1,25 @@
 #!/usr/bin/env node
 /**
- * Entry point. `npx @skyelight/mcp` — reads credentials, opens stdio.
+ * Entry point, wearing two hats.
+ *
+ * With no arguments this is the stdio MCP server, which is what a client
+ * spawns. With `init` it is the installer that registers the *remote* server
+ * with a coding agent — see `cli.js`.
+ *
+ * One binary rather than two, because npm resolves `npx @skyelight/mcp` to
+ * the package's only bin whatever it is called; a second bin would make that
+ * resolution ambiguous and `npx @skyelight/mcp init` would stop working.
+ * Dispatching here keeps the one-command install one command.
  */
 
+// The static import below is hoisted, so `config.js` is evaluated either
+// way — but `resolveConfig()` is only *called* past this point, and calling
+// it is what throws when there are no credentials. The installer needs none.
+if (process.argv[2] === "init" || process.argv[2] === "--help") {
+  await import("./cli.js");
+  process.exit(process.exitCode ?? 0);
+}
+
 import { resolveConfig, ConfigError } from "./config.js";
 import { createClient } from "./client.js";
 import { createServer, serveStdio } from "./server.js";

package/src/install.js

@@ -0,0 +1,210 @@
+/**
+ * Where each agent keeps its MCP servers, and what to write there.
+ *
+ * Pure functions, so the CLI is the part that touches the disk and this is
+ * the part that can be tested. Every entry answers three questions: how do
+ * we know this agent is on the machine, what file holds its servers, and
+ * what shape does an entry take in it.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+
+/** The name the server is registered under, in every client. */
+export const SERVER_NAME = "skyelight";
+
+/**
+ * The loopback port every client is told to listen on.
+ *
+ * Fixed rather than random because the redirect URI is registered with Clerk
+ * in advance, and only a stable one can be. Loopback, so it only ever
+ * resolves on the machine running the client.
+ */
+export const CALLBACK_PORT = 54545;
+
+const home = () => homedir();
+
+/**
+ * The agents this can configure.
+ *
+ * Ordered by how likely a given machine is to have one, because the first
+ * match wins when nothing is named. That is a guess, and `--client` exists
+ * for when it guesses wrong. The same order the settings card lists them in,
+ * so the two never disagree about which agent is the obvious one.
+ */
+export const CLIENTS = [
+  {
+    id: "claude",
+    label: "Claude Code",
+    /**
+     * Registered by its own CLI rather than by editing a file.
+     *
+     * `claude mcp add` knows where the config lives on this machine and what
+     * the current schema is; writing the file ourselves would be a guess at
+     * both, and a wrong guess silently produces an agent with no tools.
+     */
+    command: (url, clientId, port = CALLBACK_PORT) => [
+      "claude",
+      [
+        "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.
+        ...(clientId
+          ? ["--client-id", clientId, "--callback-port", String(port)]
+          : []),
+        url,
+      ],
+    ],
+    detect: () => hasBinary("claude"),
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    file: () => join(home(), ".cursor", "mcp.json"),
+    format: "json",
+    entry: (url) => ({ url }),
+    detect: () => existsSync(join(home(), ".cursor")),
+  },
+  {
+    /**
+     * Grok's own entry, which it needs despite appearing to work without one.
+     *
+     * It reads `~/.claude.json` as a compatibility source, so on a machine
+     * that also has Claude Code it inherits that registration — client id,
+     * callback port and all — and looks configured when nothing here ran.
+     * On a machine without Claude Code there is nothing to inherit.
+     *
+     * Two differences from Codex, both from Grok's own config reference:
+     * `oauth_client_id` is a flat key rather than a nested table, and there
+     * is no callback setting at all — Grok picks the loopback address, which
+     * is why both spellings of it are registered with Clerk.
+     *
+     * `oauth_scopes` is spelled out because Grok sends no `scope` parameter
+     * otherwise, and a token minted without `offline_access` carries no
+     * refresh: the session works, then quietly stops.
+     */
+    id: "grok",
+    label: "Grok",
+    file: () => join(home(), ".grok", "config.toml"),
+    format: "toml",
+    entry: (url, clientId) =>
+      [
+        `[mcp_servers.${SERVER_NAME}]`,
+        `url = "${url}"`,
+        "enabled = true",
+        ...(clientId
+          ? [
+              `oauth_client_id = "${clientId}"`,
+              'oauth_scopes = ["profile", "email", "offline_access"]',
+            ]
+          : []),
+      ].join("\n"),
+    detect: () => existsSync(join(home(), ".grok")),
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    file: () => join(home(), ".codex", "config.toml"),
+    format: "toml",
+    entry: (url, clientId, port = CALLBACK_PORT) =>
+      [
+        `[mcp_servers.${SERVER_NAME}]`,
+        `url = "${url}"`,
+        'auth = "oauth"',
+        // The oauth table only when there is a client to name.
+        ...(clientId
+          ? [
+              "",
+              `[mcp_servers.${SERVER_NAME}.oauth]`,
+              `client_id = "${clientId}"`,
+              `callback_url = "http://127.0.0.1:${port}/callback"`,
+            ]
+          : []),
+      ].join("\n"),
+    detect: () => existsSync(join(home(), ".codex")),
+  },
+  {
+    id: "windsurf",
+    label: "Windsurf",
+    file: () => join(home(), ".codeium", "windsurf", "mcp_config.json"),
+    format: "json",
+    entry: (url) => ({ serverUrl: url }),
+    detect: () => existsSync(join(home(), ".codeium", "windsurf")),
+  },
+];
+
+/** On PATH, without running the thing. */
+function hasBinary(name) {
+  const paths = (process.env.PATH ?? "").split(":").filter(Boolean);
+  return paths.some((p) => existsSync(join(p, name)));
+}
+
+/**
+ * Which agents are on this machine.
+ *
+ * All of them, not the first: somebody with Cursor and Claude Code installed
+ * should be told both were found rather than have one picked for them.
+ */
+export function detectClients(clients = CLIENTS) {
+  return clients.filter((c) => {
+    try {
+      return c.detect();
+    } catch {
+      return false;
+    }
+  });
+}
+
+export function findClient(id, clients = CLIENTS) {
+  return clients.find((c) => c.id === id) ?? null;
+}
+
+/**
+ * Add the server to a JSON config, preserving whatever else is in it.
+ *
+ * Returns the new text, or null when the server is already there and points
+ * at the same place — nothing to write is a better answer than an identical
+ * rewrite that churns the file's mtime.
+ */
+export function addToJson(existing, entry) {
+  const parsed = existing.trim() ? JSON.parse(existing) : {};
+  const servers = parsed.mcpServers ?? {};
+  const current = servers[SERVER_NAME];
+  if (current && JSON.stringify(current) === JSON.stringify(entry)) return null;
+  return `${JSON.stringify(
+    { ...parsed, mcpServers: { ...servers, [SERVER_NAME]: entry } },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * Append a TOML block, replacing an existing one for the same server.
+ *
+ * A parser would be the right tool for arbitrary TOML. This only ever writes
+ * two tables it wrote itself, so it finds them by their headers and swaps
+ * them; anything it does not recognise it leaves alone and appends after.
+ */
+export function addToToml(existing, block) {
+  const header = `[mcp_servers.${SERVER_NAME}]`;
+  if (!existing.includes(header)) {
+    const sep = existing.trim() ? "\n\n" : "";
+    return `${existing.trimEnd()}${sep}${block}\n`;
+  }
+  if (existing.includes(block)) return null;
+
+  const lines = existing.split("\n");
+  const start = lines.findIndex((l) => l.trim() === header);
+  // Ours runs to the next table that is not one of ours.
+  let end = start + 1;
+  while (end < lines.length) {
+    const t = lines[end].trim();
+    if (t.startsWith("[") && !t.startsWith(`[mcp_servers.${SERVER_NAME}`)) break;
+    end++;
+  }
+  return `${[...lines.slice(0, start), block, ...lines.slice(end)]
+    .join("\n")
+    .trimEnd()}\n`;
+}

package/src/tools.js

@@ -8,8 +8,7 @@
  */
 
 const PROJECT_HINT =
-  'No project. Pass projectId, add .skyelight.json with {"projectId": "..."}, ' +
-  "or use a project-bound API key.";
+  'No project. Pass projectId, or add .skyelight.json with {"projectId": "..."}.';
 
 /**
  * @param opts.uiResourceUri When set, `get_item` advertises a `ui://`
@@ -337,13 +336,11 @@ export function renderItem(item) {
   // 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.
+  // The repository and nothing else. Which branch to work on is the reader's
+  // own checkout to answer; which branch the page came from is on the source
+  // line below, and that is the half an agent cannot work out for itself.
   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 (repo) lines.push(`Code: ${repo.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.
@@ -396,6 +393,18 @@ export function renderItem(item) {
   if (item.anchor.selectedText) {
     lines.push(`  with "${item.anchor.selectedText}" selected`);
   }
+  // Which row, when the element is one of many the same component rendered.
+  // The author's own React key, so it reads as something from their codebase
+  // — "the row with key plan:pro" locates a record, which is a different and
+  // better question than where on the page it was drawn.
+  //
+  // `skyId` is deliberately not here. It is an opaque hash: it anchors the
+  // pin and tells a reader nothing they can act on, and `source` below
+  // already names the file. It stays in the structured response for anything
+  // resolving anchors, out of the prose for anything reading one.
+  if (item.anchor.skyKey) {
+    lines.push(`  the item with key ${item.anchor.skyKey}`);
+  }
   lines.push(`  selector: ${item.anchor.selector}`);
   lines.push(
     `  seen at ${item.anchor.viewport.width}x${item.anchor.viewport.height}`,