@skyelight/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plastr Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @skyelight/mcp
+
+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.
+
+Works with anything that speaks MCP over stdio: Claude Code, Cursor, Codex
+CLI. For hosted agents that cannot spawn a local process, use the remote
+endpoint instead (SKY-274).
+
+## Setup
+
+> **Not published yet.** Until `@skyelight/mcp` is on npm, the `npx` form
+> below will fail to resolve. Run it from a checkout instead — same server,
+> same behaviour:
+>
+> ```bash
+> claude mcp add skyelight \
+>   --env SKYELIGHT_API_URL=https://<deployment>.convex.site \
+>   --env SKYELIGHT_API_TOKEN=sk_live_... \
+>   -- node /path/to/skyelight-app/integrations/skyelight-mcp/src/index.js
+> ```
+>
+> The connect snippet generated in Settings → API keys uses the `npx` form,
+> which is what will be correct once this ships. Swap the command for the
+> node path in the meantime.
+
+Create a key under **Settings → API keys** in the Skyelight web app. Bind it
+to a project if the agent only ever works on one — a bound key needs no
+further configuration and cannot read anything else.
+
+Then add the server to your client:
+
+```json
+{
+  "mcpServers": {
+    "skyelight": {
+      "command": "npx",
+      "args": ["-y", "@skyelight/mcp"],
+      "env": {
+        "SKYELIGHT_API_URL": "https://<deployment>.convex.site",
+        "SKYELIGHT_API_TOKEN": "sk_live_..."
+      }
+    }
+  }
+}
+```
+
+Claude Code users can skip the file:
+
+```bash
+claude mcp add skyelight \
+  --env SKYELIGHT_API_URL=https://<deployment>.convex.site \
+  --env SKYELIGHT_API_TOKEN=sk_live_... \
+  -- npx -y @skyelight/mcp
+```
+
+### Credentials
+
+Checked in order, so an existing Skyelight setup keeps working:
+
+1. `SKYELIGHT_API_TOKEN` / `SKYELIGHT_API_URL` in the environment
+2. `.env.local`, then `.env`, in the working directory
+3. `~/.skyelight/credentials` — `{"apiUrl": "...", "token": "sk_live_..."}`
+
+### Binding a repo to a project
+
+With a workspace-wide key used across several repos, drop a `.skyelight.json`
+at the repo root:
+
+```json
+{ "projectId": "j57abc...", "projectName": "Checkout rebuild" }
+```
+
+Tools then default to that project, and nobody has to pass an id. A
+project-bound API key makes this unnecessary — the server already knows.
+
+## Tools
+
+| Tool           | What it is for                                                 |
+| -------------- | -------------------------------------------------------------- |
+| `list_items`   | What is outstanding. Filter by page, type, status, assignee.   |
+| `search_items` | Find items whose thread mentions some text, replies included.  |
+| `get_item`     | Everything needed to work one item: full thread, page, anchor. |
+
+`list_items` leads with a summary — totals, breakdown by type and by page —
+so an agent can tell you the shape of the work before pulling any of it.
+Rows are stubs; `get_item` is where the thread and the anchor live.
+
+## What the agent sees
+
+```
+Alpha: 12 items total — 9 open, 3 resolved, 7 unassigned.
+By type: bug (7), idea (4), feedback (1).
+Busiest pages: /checkout (8), /settings (4).
+
+2 matches:
+- The pay button does nothing on the second click
+  bug · open · /checkout · unassigned · 2 replies — id i1
+```
+
+Deliberately prose rather than JSON. A tool that returns a bare array invites
+a model to read the array out; this one invites it to summarise.
+
+## Permissions
+
+The key's role decides what the agent can do, and the API enforces it —
+nothing here is client-side. A reviewer-role key can read but not write. A
+project-bound key 404s on anything outside its project rather than reporting
+that it exists but is forbidden.
+
+## Supersedes
+
+`integrations/skyelight-skill/`, the Python Claude Code skill — **removed** in
+SKY-291 along with the `/api/v1/brief` and `/api/v1/feedback/ship` endpoints
+it called.
+
+That skill was brief-shaped: pull a synthesized decision brief, mark decisions
+shipped. This is item-shaped, which is what an agent working a specific piece
+of feedback actually needs, and it works across clients rather than Claude
+Code alone.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@skyelight/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Skyelight \u2014 read feedback items from your project as an agent",
+  "type": "module",
+  "bin": {
+    "skyelight-mcp": "./src/index.js"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test 'test/**/*.test.js'",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "mcp",
+    "skyelight",
+    "feedback"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plastrlab/skyelight.git",
+    "directory": "integrations/skyelight-mcp"
+  },
+  "homepage": "https://github.com/plastrlab/skyelight/tree/main/integrations/skyelight-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/plastrlab/skyelight/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.js

@@ -0,0 +1,96 @@
+/**
+ * HTTP calls to the Skyelight public API. No business logic — the server
+ * decides what a key may see; this just carries the bearer token and turns
+ * error bodies into readable messages.
+ */
+
+export class ApiError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+}
+
+export function createClient({ apiUrl, token, fetchImpl = fetch }) {
+  async function post(path, body) {
+    let res;
+    try {
+      res = await fetchImpl(apiUrl + path, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+      });
+    } catch (err) {
+      throw new ApiError(`Could not reach ${apiUrl}: ${err.message}`, 0);
+    }
+    const text = await res.text();
+    let parsed;
+    try {
+      parsed = text ? JSON.parse(text) : {};
+    } catch {
+      throw new ApiError(
+        `${res.status} from ${path}, and the body was not JSON`,
+        res.status,
+      );
+    }
+    if (!res.ok) {
+      throw new ApiError(
+        parsed.error ?? `Request failed (${res.status})`,
+        res.status,
+      );
+    }
+    return parsed;
+  }
+
+  async function request(path, params = {}) {
+    const url = new URL(apiUrl + path);
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined && v !== null && v !== "") {
+        url.searchParams.set(k, String(v));
+      }
+    }
+
+    let res;
+    try {
+      res = await fetchImpl(url.toString(), {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+    } catch (err) {
+      throw new ApiError(`Could not reach ${apiUrl}: ${err.message}`, 0);
+    }
+
+    const text = await res.text();
+    let body;
+    try {
+      body = text ? JSON.parse(text) : {};
+    } catch {
+      throw new ApiError(
+        `${res.status} from ${path}, and the body was not JSON`,
+        res.status,
+      );
+    }
+
+    if (!res.ok) {
+      // The API's own message is more useful than anything invented here —
+      // it says which role the key has, or that a project is out of scope.
+      throw new ApiError(
+        body.error ?? `Request failed (${res.status})`,
+        res.status,
+      );
+    }
+    return body;
+  }
+
+  return {
+    listWorkspaces: () => request("/api/v1/workspaces"),
+    listProjects: (params) => request("/api/v1/projects", params),
+    listItems: (params) => request("/api/v1/items", params),
+    getItem: (id) => request(`/api/v1/items/${encodeURIComponent(id)}`),
+    postUpdate: (body) => post("/api/v1/items/update", body),
+    createItem: (body) => post("/api/v1/items/create", body),
+    setStatus: (body) => post("/api/v1/items/status", body),
+  };
+}

package/src/config.js

@@ -0,0 +1,112 @@
+/**
+ * Where the token, the API and the project binding come from.
+ *
+ * Resolution order deliberately matches the Python skill this supersedes, so
+ * anyone who already has credentials on disk gets a working MCP server
+ * without moving anything:
+ *
+ *   1. SKYELIGHT_API_TOKEN / SKYELIGHT_API_URL in the environment
+ *   2. .env.local, then .env, in the working directory
+ *   3. ~/.skyelight/credentials  ({"apiUrl": "...", "token": "..."})
+ *
+ * The project binding is separate and comes from `.skyelight.json` in the
+ * working directory, so a repo can declare which Skyelight project it is
+ * without every developer configuring it.
+ *
+ * A project-bound API KEY (SKY-269) needs none of this — the server already
+ * knows its project. `.skyelight.json` is for workspace-wide keys used
+ * against several repos.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export class ConfigError extends Error {}
+
+/** Minimal .env parser: KEY=VALUE, optional quotes, # comments. */
+export function parseDotenv(text) {
+  const out = {};
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key) out[key] = value;
+  }
+  return out;
+}
+
+function readJsonIfPresent(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    // A malformed config should not take the server down — it should be
+    // reported and skipped. stderr is safe: stdout is the protocol channel.
+    process.stderr.write(`[skyelight-mcp] ignoring malformed ${path}\n`);
+    return null;
+  }
+}
+
+export function resolveConfig({
+  cwd = process.cwd(),
+  env = process.env,
+  // Injectable so tests do not read the developer's real credentials file
+  // and pass or fail depending on whose machine they run on.
+  home = homedir(),
+} = {}) {
+  let token = env.SKYELIGHT_API_TOKEN || null;
+  let apiUrl = env.SKYELIGHT_API_URL || null;
+
+  if (!token || !apiUrl) {
+    for (const name of [".env.local", ".env"]) {
+      const path = join(cwd, name);
+      if (!existsSync(path)) continue;
+      const parsed = parseDotenv(readFileSync(path, "utf8"));
+      token = token || parsed.SKYELIGHT_API_TOKEN || null;
+      apiUrl = apiUrl || parsed.SKYELIGHT_API_URL || null;
+      if (token && apiUrl) break;
+    }
+  }
+
+  if (!token || !apiUrl) {
+    const creds = readJsonIfPresent(join(home, ".skyelight", "credentials"));
+    if (creds) {
+      token = token || creds.token || null;
+      apiUrl = apiUrl || creds.apiUrl || null;
+    }
+  }
+
+  if (!token || !apiUrl) {
+    throw new ConfigError(
+      [
+        "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_..."}',
+        "",
+        "Create a key under Settings → API keys in the Skyelight web app.",
+      ].join("\n"),
+    );
+  }
+
+  const project = readJsonIfPresent(join(cwd, ".skyelight.json")) ?? {};
+
+  return {
+    token,
+    apiUrl: apiUrl.replace(/\/+$/, ""),
+    // Named projectId to match the API. A bound key overrides this anyway —
+    // the server ignores a projectId outside the key's binding.
+    projectId: project.projectId ?? null,
+    projectName: project.projectName ?? null,
+  };
+}

package/src/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * Entry point. `npx @skyelight/mcp` — reads credentials, opens stdio.
+ */
+
+import { resolveConfig, ConfigError } from "./config.js";
+import { createClient } from "./client.js";
+import { createServer, serveStdio } from "./server.js";
+
+let config;
+try {
+  config = resolveConfig();
+} catch (err) {
+  if (err instanceof ConfigError) {
+    // stderr, and a non-zero exit: an MCP client surfaces this as a failed
+    // server rather than hanging on a handshake that will never complete.
+    process.stderr.write(`${err.message}\n`);
+    process.exit(1);
+  }
+  throw err;
+}
+
+const client = createClient({ apiUrl: config.apiUrl, token: config.token });
+serveStdio(createServer({ client, config }));

package/src/itemCard.d.ts

@@ -0,0 +1,23 @@
+/** Types for itemCard.js — see tools.d.ts for why declarations are shipped. */
+
+export declare const ITEM_CARD_URI: string;
+export declare const MCP_APP_MIME_TYPE: string;
+export declare const UI_EXTENSION_KEY: string;
+export declare const APPS_PROTOCOL_VERSION: string;
+
+/** Whether a client declared it can render an MCP Apps HTML resource. */
+export declare function clientSupportsUi(source: unknown): boolean;
+
+export declare function itemCardResource(): {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+};
+
+export declare function itemCardContents(): {
+  uri: string;
+  mimeType: string;
+  text: string;
+  _meta: { ui: Record<string, unknown> };
+};