@skyelight/mcp 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +72 -56
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,32 +1,19 @@
1
1
  # @skyelight/mcp
2
2
 
3
3
  An MCP server that lets a coding agent read the feedback people left on your
4
- running app — the thread, the page, and the element they were pointing at.
4
+ running app — the thread, the page, and the element they were pointing at —
5
+ and report back on it when the work is done.
5
6
 
6
- Works with anything that speaks MCP over stdio: Claude Code, Cursor, Codex
7
- CLI. For hosted agents that cannot spawn a local process, use the remote
8
- endpoint instead (SKY-274).
7
+ Works with anything that speaks MCP over stdio: Claude Code, Cursor, Codex.
9
8
 
10
9
  ## Setup
11
10
 
12
- > **Not published yet.** Until `@skyelight/mcp` is on npm, the `npx` form
13
- > below will fail to resolve. Run it from a checkout instead — same server,
14
- > same behaviour:
15
- >
16
- > ```bash
17
- > claude mcp add skyelight \
18
- > --env SKYELIGHT_API_URL=https://<deployment>.convex.site \
19
- > --env SKYELIGHT_API_TOKEN=sk_live_... \
20
- > -- node /path/to/skyelight-app/integrations/skyelight-mcp/src/index.js
21
- > ```
22
- >
23
- > The connect snippet generated in Settings → API keys uses the `npx` form,
24
- > which is what will be correct once this ships. Swap the command for the
25
- > node path in the meantime.
26
-
27
- Create a key under **Settings → API keys** in the Skyelight web app. Bind it
28
- to a project if the agent only ever works on one — a bound key needs no
29
- further configuration and cannot read anything else.
11
+ **Get a personal access token.** In the Skyelight web app, go to your account
12
+ settings → **Personal access tokens** → create one. It is shown once.
13
+
14
+ The token is yours, not a service account's: anything the agent writes is
15
+ attributed to you, marked with the tool it came through. That is deliberate —
16
+ see [Who a write belongs to](#who-a-write-belongs-to).
30
17
 
31
18
  Then add the server to your client:
32
19
 
@@ -38,7 +25,7 @@ Then add the server to your client:
38
25
  "args": ["-y", "@skyelight/mcp"],
39
26
  "env": {
40
27
  "SKYELIGHT_API_URL": "https://<deployment>.convex.site",
41
- "SKYELIGHT_API_TOKEN": "sk_live_..."
28
+ "SKYELIGHT_API_TOKEN": "sky_..."
42
29
  }
43
30
  }
44
31
  }
@@ -50,47 +37,55 @@ Claude Code users can skip the file:
50
37
  ```bash
51
38
  claude mcp add skyelight \
52
39
  --env SKYELIGHT_API_URL=https://<deployment>.convex.site \
53
- --env SKYELIGHT_API_TOKEN=sk_live_... \
40
+ --env SKYELIGHT_API_TOKEN=sky_... \
54
41
  -- npx -y @skyelight/mcp
55
42
  ```
56
43
 
44
+ The API host is the Convex deployment with `.convex.cloud` swapped for
45
+ `.convex.site` — Convex serves HTTP actions from the latter. The web app shows
46
+ the right one when you create the token.
47
+
57
48
  ### Credentials
58
49
 
59
- Checked in order, so an existing Skyelight setup keeps working:
50
+ Checked in order, so an existing setup keeps working:
60
51
 
61
52
  1. `SKYELIGHT_API_TOKEN` / `SKYELIGHT_API_URL` in the environment
62
53
  2. `.env.local`, then `.env`, in the working directory
63
- 3. `~/.skyelight/credentials` — `{"apiUrl": "...", "token": "sk_live_..."}`
54
+ 3. `~/.skyelight/credentials` — `{"apiUrl": "...", "token": "sky_..."}`
64
55
 
65
56
  ### Binding a repo to a project
66
57
 
67
- With a workspace-wide key used across several repos, drop a `.skyelight.json`
68
- at the repo root:
58
+ If you can reach several projects, drop a `.skyelight.json` at the repo root:
69
59
 
70
60
  ```json
71
61
  { "projectId": "j57abc...", "projectName": "Checkout rebuild" }
72
62
  ```
73
63
 
74
- Tools then default to that project, and nobody has to pass an id. A
75
- project-bound API key makes this unnecessary — the server already knows.
64
+ Tools then default to that project and nobody has to pass an id. Without it,
65
+ `list_items` will ask you to call `list_projects` first rather than guess.
76
66
 
77
67
  ## Tools
78
68
 
79
- | Tool | What it is for |
80
- | -------------- | -------------------------------------------------------------- |
81
- | `list_items` | What is outstanding. Filter by page, type, status, assignee. |
82
- | `search_items` | Find items whose thread mentions some text, replies included. |
83
- | `get_item` | Everything needed to work one item: full thread, page, anchor. |
84
-
85
- `list_items` leads with a summary — totals, breakdown by type and by page —
86
- so an agent can tell you the shape of the work before pulling any of it.
87
- Rows are stubs; `get_item` is where the thread and the anchor live.
69
+ | Tool | What it is for |
70
+ | ----------------- | --------------------------------------------------------------- |
71
+ | `list_workspaces` | Which workspaces this credential can reach. |
72
+ | `list_projects` | The projects inside them, with the ids the other tools take. |
73
+ | `list_items` | What is outstanding. Filter by page, type, status, assignee. |
74
+ | `search_items` | Find items whose thread mentions some text, replies included. |
75
+ | `get_item` | Everything needed to work one item: thread, page, anchor, code. |
76
+ | `post_update` | Report back on the thread the feedback came from. |
77
+ | `create_item` | Raise a new item — an audit finding, something you noticed. |
78
+ | `set_status` | Move an item to open, deferred or resolved. |
79
+
80
+ `list_items` leads with a summary — totals, breakdown by type and by page — so
81
+ an agent can tell you the shape of the work before pulling any of it. Rows are
82
+ stubs; `get_item` is where the thread and the anchor live.
88
83
 
89
84
  ## What the agent sees
90
85
 
91
86
  ```
92
- Alpha: 12 items total — 9 open, 3 resolved, 7 unassigned.
93
- By type: bug (7), idea (4), feedback (1).
87
+ Alpha: 21 items total — 15 open, 3 deferred, 3 resolved, 19 unassigned.
88
+ By type: bug (7), idea (4), feedback (10).
94
89
  Busiest pages: /checkout (8), /settings (4).
95
90
 
96
91
  2 matches:
@@ -98,23 +93,44 @@ Busiest pages: /checkout (8), /settings (4).
98
93
  bug · open · /checkout · unassigned · 2 replies — id i1
99
94
  ```
100
95
 
101
- Deliberately prose rather than JSON. A tool that returns a bare array invites
102
- a model to read the array out; this one invites it to summarise.
96
+ Deliberately prose rather than JSON. A tool that returns a bare array invites a
97
+ model to read the array out; this one invites it to summarise.
103
98
 
104
- ## Permissions
99
+ ### Where the code is
105
100
 
106
- The key's role decides what the agent can do, and the API enforces it —
107
- nothing here is client-side. A reviewer-role key can read but not write. A
108
- project-bound key 404s on anything outside its project rather than reporting
109
- that it exists but is forbidden.
101
+ If the app was built with [`@skyelight/build`](https://www.npmjs.com/package/@skyelight/build),
102
+ `get_item` ends with the line that changes what an agent does next:
103
+
104
+ ```
105
+ Written by components/Card.tsx, line 88, in build a1b2c3d on branch feat/checkout.
106
+ ```
110
107
 
111
- ## Supersedes
108
+ The file saves a grep. The commit and branch are how an agent tells "still
109
+ broken" from "already fixed, this pin is stale" — and, on a preview
110
+ deployment, which branch the code it wants is actually on.
111
+
112
+ ## Who a write belongs to
113
+
114
+ Every write is **a person's**. A token carries your access, so a reply the
115
+ agent posts is yours, with the tool it came through shown as a mark beside the
116
+ timestamp rather than as the author.
117
+
118
+ There is no service-account mode. Synthetic agent identities existed and were
119
+ removed: a workspace should not grow a member for every tool somebody plugs in,
120
+ and a reply nobody is accountable for is worse than one attributed plainly.
121
+
122
+ A consequence worth knowing: a **workspace API key cannot write.** It stands
123
+ for a role, not a person, so there is nobody to attribute a reply to, and the
124
+ write tools refuse it with a message saying so. Keys still read, and still
125
+ respect a project binding — they are for scripts and CI, not for agents.
126
+
127
+ ## Permissions
112
128
 
113
- `integrations/skyelight-skill/`, the Python Claude Code skill — **removed** in
114
- SKY-291 along with the `/api/v1/brief` and `/api/v1/feedback/ship` endpoints
115
- it called.
129
+ The server enforces nothing; the API does. Whatever your account can do in the
130
+ web app, the agent can do through your token, and nothing more:
116
131
 
117
- That skill was brief-shaped: pull a synthesized decision brief, mark decisions
118
- shipped. This is item-shaped, which is what an agent working a specific piece
119
- of feedback actually needs, and it works across clients rather than Claude
120
- Code alone.
132
+ - A **reviewer** reads and cannot write.
133
+ - A **project-bound** credential answers 404 outside its project rather than
134
+ reporting that something exists but is forbidden.
135
+ - Resolving stays a person's call in the web app for a thread you do not own;
136
+ `set_status` obeys the same rule.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skyelight/mcp",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "MCP server for Skyelight \u2014 read feedback items from your project as an agent",
5
5
  "type": "module",
6
6
  "bin": {