@web-remarq/mcp 0.4.0 → 0.5.0
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.
- package/README.md +101 -14
- package/dist/server.js +548 -235
- package/dist/server.js.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -39,11 +39,6 @@ automatically:
|
|
|
39
39
|
Annotations are stored in a JSON file on disk and served to the widget over a
|
|
40
40
|
small HTTP endpoint on `127.0.0.1`. No Supabase project, no project key.
|
|
41
41
|
|
|
42
|
-
Trust model: the endpoint binds to `127.0.0.1` with permissive CORS, so any
|
|
43
|
-
page open in the local browser can reach it for as long as the server runs -
|
|
44
|
-
this is meant for dev-time use with low-sensitivity data, not a hardened
|
|
45
|
-
local API.
|
|
46
|
-
|
|
47
42
|
| Env var | Default | Purpose |
|
|
48
43
|
|---------|---------|---------|
|
|
49
44
|
| `REMARQ_PORT` | `1817` | Port for the widget-facing HTTP endpoint |
|
|
@@ -59,6 +54,95 @@ import { WebRemarq, HttpStorageAdapter } from 'web-remarq'
|
|
|
59
54
|
WebRemarq.init({ submitFlow: true, storage: new HttpStorageAdapter() })
|
|
60
55
|
```
|
|
61
56
|
|
|
57
|
+
### Access model (mcp 0.5.0, protocol 2)
|
|
58
|
+
|
|
59
|
+
On first start the server writes `.remarq/config.json`:
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"projectId": "prj_…", // stable identity of this store
|
|
64
|
+
"token": "…", // random bearer credential for the HTTP endpoint
|
|
65
|
+
"allowedOrigins": ["http://localhost:*", "http://127.0.0.1:*", "http://[::1]:*"]
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`npx @web-remarq/cli init` creates the same file up front. It is owner-only
|
|
70
|
+
and gitignored; the token never appears in source, URLs, ticket files, logs or
|
|
71
|
+
`doctor` output.
|
|
72
|
+
|
|
73
|
+
Every request except `GET /health` needs `Authorization: Bearer <token>` -
|
|
74
|
+
reads included. Browser requests must also come from an origin in
|
|
75
|
+
`allowedOrigins` (exact scheme + host; `:*` means any port). Foreign, `null`
|
|
76
|
+
and look-alike origins (`localhost.evil.com`) are refused on preflight, read
|
|
77
|
+
and write; a `Host` header that does not name this loopback listener is
|
|
78
|
+
refused too (DNS rebinding). Remote/staging origins are never allowed unless
|
|
79
|
+
you list them on purpose.
|
|
80
|
+
|
|
81
|
+
How the widget gets the token, in development only:
|
|
82
|
+
|
|
83
|
+
- **Vite**: `@web-remarq/unplugin` serves it at `/__web-remarq/config.json`
|
|
84
|
+
on your dev server; `HttpStorageAdapter` fetches it same-origin.
|
|
85
|
+
- **Next.js**: `withRemarq()` exposes it as `NEXT_PUBLIC_WEB_REMARQ_TOKEN`;
|
|
86
|
+
the `RemarqDevTools` snippet passes it as `new HttpStorageAdapter({ token })`.
|
|
87
|
+
- **Plain HTML / other bundlers**: paste it once in the browser console -
|
|
88
|
+
`WebRemarq.pair('<token>')` - it is kept in localStorage for that endpoint.
|
|
89
|
+
|
|
90
|
+
Rotating the token (edit the file, restart the server) does not change
|
|
91
|
+
`projectId` and does not touch annotations; widgets show "not paired" until
|
|
92
|
+
they get the new token. Changing `projectId` is a different project: widgets
|
|
93
|
+
keep their queued changes for the old one.
|
|
94
|
+
|
|
95
|
+
What this protects: the HTTP boundary, against other pages in your browser
|
|
96
|
+
and against rebinding attacks. What it does not protect: a process on your
|
|
97
|
+
machine with file access (it can read `.remarq/config.json`), and it is not a
|
|
98
|
+
cryptographic "human approval" - the lifecycle records who acted, it does not
|
|
99
|
+
authenticate them.
|
|
100
|
+
|
|
101
|
+
### Protocol 2 endpoints
|
|
102
|
+
|
|
103
|
+
| Route | Auth | Purpose |
|
|
104
|
+
|-------|------|---------|
|
|
105
|
+
| `GET /health` | none, any origin | `{ ok, protocol: 2 }` - liveness only, no data |
|
|
106
|
+
| `GET /store` | token | `{ rev, protocol, projectId, store }`; every annotation carries its own `rev` |
|
|
107
|
+
| `PUT /annotations/:id` | token | Create (no `If-Match`) or update (`If-Match: <rev>` required). Body is validated (types, enums, sizes, filename-safe id, unknown top-level fields rejected). Wrong revision → `409 { code: "conflict", details: { current } }`; missing → `428` |
|
|
108
|
+
| `DELETE /annotations/:id` | token | Optional `If-Match`; mismatch → 409 |
|
|
109
|
+
| `DELETE /annotations` | token | Clear |
|
|
110
|
+
|
|
111
|
+
Limits: 512 KB body, 10 000-character comments, 500 lifecycle events,
|
|
112
|
+
`application/json` only. An invalid request is a 4xx and changes neither the
|
|
113
|
+
store nor `.remarq/tasks/`.
|
|
114
|
+
|
|
115
|
+
**Upgrading from mcp 0.4.x**: widgets older than `web-remarq` 0.9.0 get 401
|
|
116
|
+
from a 0.5.0 server and go into their offline buffer instead of losing data;
|
|
117
|
+
upgrade the widget and the buffer is migrated (see "Offline and durability" in
|
|
118
|
+
the core README). A 0.9.0 widget refuses to talk to a 0.4.x server
|
|
119
|
+
("incompatible") rather than writing without revisions.
|
|
120
|
+
|
|
121
|
+
Only one server may serve a store: `.remarq/server.lock` names the owning
|
|
122
|
+
process, and a second start against the same store exits with an error. The
|
|
123
|
+
atomic transition guarantee below depends on this.
|
|
124
|
+
|
|
125
|
+
### Atomic transitions
|
|
126
|
+
|
|
127
|
+
`acknowledge`, `claim_fix` and `dismiss` are atomic per annotation: the read,
|
|
128
|
+
the lifecycle check and the write happen inside one critical section (local
|
|
129
|
+
file store) or as one conditional `UPDATE … WHERE id = ? AND rev = ?` (cloud,
|
|
130
|
+
needs `004_rev.sql`). Of several concurrent callers exactly one wins; the
|
|
131
|
+
others get `invalid_transition` with `details.conflict: true`, the current
|
|
132
|
+
status/revision and the last event - do not start work, re-read the annotation.
|
|
133
|
+
|
|
134
|
+
Pass `operationId` (any unique string you keep) to make a call idempotent: a
|
|
135
|
+
retry after a lost response finds the event already recorded and returns
|
|
136
|
+
`{ ok: true, replayed: true }` instead of appending a second one. A different
|
|
137
|
+
`operationId` never impersonates the earlier winner.
|
|
138
|
+
|
|
139
|
+
The guarantee is "one winner per transition", not "an authenticated owner":
|
|
140
|
+
nothing identifies which agent won, the lifecycle records `actor: 'agent'`.
|
|
141
|
+
Cloud mode has the same contract through the conditional update; the
|
|
142
|
+
disposable-database run that proves it against real Postgres is still an open
|
|
143
|
+
verification step (the adapter tests assert the exact statement, not SQL
|
|
144
|
+
atomicity).
|
|
145
|
+
|
|
62
146
|
### Watching for new feedback
|
|
63
147
|
|
|
64
148
|
`watch_annotations` returns immediately if pending annotations already exist;
|
|
@@ -135,14 +219,17 @@ There is no mode switch:
|
|
|
135
219
|
> Work through the tickets in .remarq/tasks/, one background subagent per
|
|
136
220
|
> file, in parallel. Follow the instructions inside each file.
|
|
137
221
|
|
|
138
|
-
Duplicate work is prevented by the lifecycle
|
|
139
|
-
thing any executor does is `acknowledge`
|
|
140
|
-
|
|
222
|
+
Duplicate work is prevented by the atomic lifecycle transition, not by file
|
|
223
|
+
locks: the first thing any executor does is `acknowledge` with a fresh
|
|
224
|
+
`operationId` - if it answers `invalid_transition`, someone else already moved
|
|
225
|
+
the annotation and the file should be skipped; if the call fails without an
|
|
226
|
+
answer, retry with the same `operationId`.
|
|
141
227
|
|
|
142
228
|
## Cloud mode prerequisites
|
|
143
229
|
|
|
144
|
-
1. A Supabase project provisioned with `@web-remarq/cloud` (≥0.
|
|
145
|
-
`001_init.sql
|
|
230
|
+
1. A Supabase project provisioned with `@web-remarq/cloud` (≥0.4.0). Run
|
|
231
|
+
`001_init.sql`, `002_lifecycle.sql`, `003_quality.sql` and `004_rev.sql`
|
|
232
|
+
from the cloud package (all additive).
|
|
146
233
|
2. A project key generated via `npx @web-remarq/cloud gen-key --name "..."`.
|
|
147
234
|
|
|
148
235
|
## Configuration
|
|
@@ -178,9 +265,9 @@ if any are missing or malformed. Leave all three unset for local mode.
|
|
|
178
265
|
|------|-------|---------|
|
|
179
266
|
| `list_annotations` | `{ route?, status?, viewportBucket?, file?, limit? }` | `{ annotations[], total }` - `status` accepts `draft`, `pending`, `in_progress`, `fixed_unverified`, `verified`, `dismissed`; each item carries `quality` (`clear` \| `ambiguous` \| `unactionable`) when an AI pre-flight check ran |
|
|
180
267
|
| `get_annotation` | `{ id }` | Full `AgentAnnotation` shape (source + searchHints + lifecycle + `qualityCheck` when present) |
|
|
181
|
-
| `acknowledge` | `{ id }` | `{ ok, status }` after `pending → in_progress` |
|
|
182
|
-
| `claim_fix` | `{ id }` | `{ ok, status }` after `pending\|in_progress → fixed_unverified` |
|
|
183
|
-
| `dismiss` | `{ id, reason? }` | `{ ok, status }` after non-terminal → `dismissed` |
|
|
268
|
+
| `acknowledge` | `{ id, operationId? }` | `{ ok, status, rev, replayed? }` after `pending → in_progress` (atomic, one winner) |
|
|
269
|
+
| `claim_fix` | `{ id, operationId? }` | `{ ok, status, rev, replayed? }` after `pending\|in_progress → fixed_unverified` |
|
|
270
|
+
| `dismiss` | `{ id, reason?, operationId? }` | `{ ok, status, rev, replayed? }` after non-terminal → `dismissed` |
|
|
184
271
|
| `watch_annotations` | `{ timeoutSeconds? }` (1-120, default 25) | `{ annotations[], total, timedOut }` - long-polls for new pending annotations |
|
|
185
272
|
|
|
186
273
|
When `qualityCheck.score` is `ambiguous` or `unactionable`, the comment likely needs designer clarification — prefer `dismiss` with a reason over guessing at intent.
|
|
@@ -188,7 +275,7 @@ When `qualityCheck.score` is `ambiguous` or `unactionable`, the comment likely n
|
|
|
188
275
|
### Error codes
|
|
189
276
|
|
|
190
277
|
- `annotation_not_found` — id absent in project (also returned if RLS hides it)
|
|
191
|
-
- `invalid_transition` — lifecycle action not allowed from current status
|
|
278
|
+
- `invalid_transition` — lifecycle action not allowed from current status. `details` carries `conflict: true`, `currentStatus`, `currentRev`, `lastEvent` and `requestedTransition`: treat it as "someone else got there first" - do not start work, re-read the annotation. Storage adapters without `mutate()` (custom ones) answer `atomic: false` on success
|
|
192
279
|
- `storage_error` - Supabase / network failure in cloud mode, or a local
|
|
193
280
|
file-store error (e.g. corrupted store) in local mode; payload includes root
|
|
194
281
|
cause
|