@web-remarq/mcp 0.3.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 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;
@@ -97,7 +181,10 @@ loop:
97
181
  # do not wait for subagents - go straight back to watch_annotations
98
182
  ```
99
183
 
100
- Copy-paste prompt to put an agent on duty in this mode:
184
+ The server ships this recipe as an MCP prompt: in clients that support them
185
+ (Claude Code renders it as the `/mcp__web-remarq__watch` slash command) one
186
+ command puts the agent on duty - no copy-paste needed. For clients without
187
+ MCP-prompt support, paste this instead:
101
188
 
102
189
  > You are on annotation duty for this project. Designers drop feedback via
103
190
  > the web-remarq MCP server. Run this loop until I tell you to stop: call
@@ -119,6 +206,10 @@ via the MCP tools. Files appear when an annotation is submitted, update on
119
206
  status changes, and disappear once it is verified or dismissed. The folder is
120
207
  server-owned - never edit or commit it (`.remarq/` self-gitignores).
121
208
 
209
+ Caveat: with a custom `REMARQ_DATA_FILE` pointing outside `.remarq/`, the
210
+ `tasks/` folder is created next to your data file and is NOT auto-gitignored -
211
+ add it to your `.gitignore` yourself.
212
+
122
213
  There is no mode switch:
123
214
 
124
215
  - **Agent on duty** (watching via `watch_annotations`): the folder just mirrors
@@ -128,14 +219,17 @@ There is no mode switch:
128
219
  > Work through the tickets in .remarq/tasks/, one background subagent per
129
220
  > file, in parallel. Follow the instructions inside each file.
130
221
 
131
- Duplicate work is prevented by the lifecycle machine, not by locks: the first
132
- thing any executor does is `acknowledge` - if that fails, someone else owns
133
- the task and the file should be skipped.
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`.
134
227
 
135
228
  ## Cloud mode prerequisites
136
229
 
137
- 1. A Supabase project provisioned with `@web-remarq/cloud` (≥0.2.0). Run both
138
- `001_init.sql` and `002_lifecycle.sql` from the cloud package.
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).
139
233
  2. A project key generated via `npx @web-remarq/cloud gen-key --name "..."`.
140
234
 
141
235
  ## Configuration
@@ -171,9 +265,9 @@ if any are missing or malformed. Leave all three unset for local mode.
171
265
  |------|-------|---------|
172
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 |
173
267
  | `get_annotation` | `{ id }` | Full `AgentAnnotation` shape (source + searchHints + lifecycle + `qualityCheck` when present) |
174
- | `acknowledge` | `{ id }` | `{ ok, status }` after `pending → in_progress` |
175
- | `claim_fix` | `{ id }` | `{ ok, status }` after `pending\|in_progress → fixed_unverified` |
176
- | `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` |
177
271
  | `watch_annotations` | `{ timeoutSeconds? }` (1-120, default 25) | `{ annotations[], total, timedOut }` - long-polls for new pending annotations |
178
272
 
179
273
  When `qualityCheck.score` is `ambiguous` or `unactionable`, the comment likely needs designer clarification — prefer `dismiss` with a reason over guessing at intent.
@@ -181,7 +275,7 @@ When `qualityCheck.score` is `ambiguous` or `unactionable`, the comment likely n
181
275
  ### Error codes
182
276
 
183
277
  - `annotation_not_found` — id absent in project (also returned if RLS hides it)
184
- - `invalid_transition` — lifecycle action not allowed from current status; payload includes `currentStatus`
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
185
279
  - `storage_error` - Supabase / network failure in cloud mode, or a local
186
280
  file-store error (e.g. corrupted store) in local mode; payload includes root
187
281
  cause