web-comments 0.1.0 → 1.0.0

package/README.md

@@ -4,11 +4,12 @@ Figma-style comments for any web page. Press <kbd>C</kbd>, click an element, wri
 
 Every comment thread records the element (selector, text, HTML, position), the URL, a screenshot of the element and one of the page as the commenter saw it.
 
-Three parts are open interfaces, so it fits whatever you already run:
+Four parts are open interfaces, so it fits whatever you already run:
 
 - **Sign-in**: auth plugins answer "who is this?" from what already sits in front of your app: your own session endpoint, Cloudflare Access, a bearer token, or anything you write. The server never stores passwords or sessions.
 - **Database**: a `CommentsStore`. Built in: Drizzle over SQLite (D1, libSQL/Turso), Postgres (PlanetScale Postgres, Neon, Supabase, ...) and MySQL (PlanetScale, ...), plus an in-memory store. Or implement the interface over anything.
 - **Screenshots**: an `AssetStore`. Built in: R2 and S3 (and S3-compatible), plus in-memory. Or implement `put`/`get` over any storage or HTTP API.
+- **Connectors**: where comments go and what can act on them. Built in: **Linear** (every thread an issue, kept in step both ways) and **MCP** (agents read threads with their screenshots, reply and resolve, signed in with OAuth as the person who approved them). Or write your own.
 
 The **widget** is a toolbar docked on the right of the page, built with [React Spectrum 2](https://react-spectrum.adobe.com/) and kept in a shadow root, so neither your CSS nor Spectrum's leaks across. Only people the API accepts see it; for everyone else the page is untouched.
 
@@ -56,6 +57,8 @@ Mount it on the same origin as the pages being commented on, so the browser send
 | `allowedOrigins` | Other origins that may call the API with credentials. |
 | `widgetScript` | The contents of `dist/widget.global.js`, served at `{basePath}/widget.js`. |
 | `maxScreenshotBytes` | Default 5 MB per screenshot. |
+| `linkParam` | Query parameter of thread links, as the widget's. Default `comment`. |
+| `connectors` | Integrations: `linear(...)`, `mcp(...)`, or your own. See [Connectors](#connectors). |
 | `onEvent` | Called after every change (`thread.created`, `comment.created`, `thread.resolved`, `thread.moved`, ...), for integrations. `thread.created` already carries the screenshots. |
 
 ### Sign-in
@@ -130,6 +133,78 @@ assets: (env) =>
 
 Screenshots are drawn from the DOM in the browser (no screen-capture prompt). Cross-origin images that don't allow CORS can't be drawn and come out blank; a comment never waits more than a few seconds for its screenshots.
 
+## Connectors
+
+```ts
+import { linear } from "web-comments/connectors/linear";
+import { mcp } from "web-comments/connectors/mcp";
+
+connectors: [
+  mcp(),
+  linear((env) => ({ auth: { apiKey: env.LINEAR_API_KEY }, team: "ENG", webhookSecret: env.LINEAR_WEBHOOK_SECRET })),
+],
+```
+
+Connectors need a store that keeps links and values (`saveLink`, `findLink`, `listLinks`, `getValue`, `setValue`, `deleteValue`); the built-in stores do, and create the two extra tables (`wc_links`, `wc_values`) on first use.
+
+### MCP
+
+`mcp()` serves an [MCP](https://modelcontextprotocol.io) server at `{basePath}/mcp`:
+
+```sh
+claude mcp add --transport http comments https://app.example.com/__comments/mcp
+```
+
+| Tool | |
+| --- | --- |
+| `list_comment_threads` | Open threads (or resolved, or all), on one page or the whole site: what was said, where, by whom. |
+| `get_comment_thread` | One thread in full: every comment, the element's selector, HTML and box, and both screenshots as images. |
+| `reply_to_comment_thread` | Replies, as the agent. |
+| `resolve_comment_thread` | Resolves, optionally replying first with what was done. |
+| `reopen_comment_thread` | Opens a resolved thread again. |
+
+MCP clients sign in with OAuth 2.1, as the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) describes: protected resource and authorization server metadata, dynamic client registration and client ID metadata documents, authorization codes with PKCE, rotating refresh tokens. The person approving a client is whoever your auth plugins already recognise in their browser, so it works with whatever sign-in you plugged in; someone not signed in is sent to the plugins' `loginUrl`. The agent then acts as that person, under their name with the client's in brackets ("Ada (Claude Code)"). Tokens are opaque and kept hashed in the store.
+
+The metadata is served under `{basePath}/mcp`, which is all a host has to route. Hosts that also send `/.well-known/oauth-protected-resource{basePath}/mcp` and its siblings (`matches()` says yes to them) serve them at the origin's root too. Requests your auth plugins recognise directly, such as a `bearerToken` for a CI agent, are let in without OAuth.
+
+| Option | |
+| --- | --- |
+| `name` | What the server calls itself to clients and on the approval page. Default `web-comments`. |
+| `accessTokenTtl` | Seconds. Default an hour. |
+| `refreshTokenTtl` | Seconds. Default 30 days. |
+
+### Linear
+
+`linear(options)`: every thread becomes an issue in a team, with the comment, a link back to the thread, the element, and both screenshots uploaded to Linear. Replies become issue comments; resolving the thread completes the issue (the team's first "completed" state) and reopening it moves the issue back (its first "unstarted" state). With a webhook, Linear's side comes back too: comments there become replies, and completing or cancelling the issue resolves the thread. Threads show their issue ("Linear ENG-123") in the widget.
+
+| Option | |
+| --- | --- |
+| `auth` | `{ apiKey }` (a personal key: the issues are that person's, and say who commented), `{ accessToken }` (OAuth), or `{ clientId, clientSecret }` (an OAuth app with client credentials: the issues are the app's, under each commenter's name and picture). |
+| `team` | The team's key (`ENG`) or id. |
+| `webhookSecret` | Signing secret of a Linear webhook for Issues and Comments, pointed at `{basePath}/linear/webhook`. |
+| `labelIds`, `projectId` | Where new issues go. |
+| `filter` | `(thread) => boolean`: which threads become issues. |
+
+`options` can be a function of the environment; returning `null` leaves Linear out there (say, until its secrets are set).
+
+### Your own
+
+```ts
+interface Connector<Env> {
+  name: string; // lowercase; its routes live under {basePath}/{name}
+  onEvent?(event: CommentsEvent, context: ConnectorContext<Env>): void | Promise<void>;
+  fetch?(request: Request, context: ConnectorRequestContext<Env>): Response | Promise<Response>;
+  rootPaths?(basePath: string): string[];
+}
+```
+
+- `onEvent` hears every change once the response has gone out (`thread.created`, `comment.created`, `thread.resolved`, ...), except the ones it made itself.
+- `fetch` answers requests under `{basePath}/{name}`, e.g. a webhook. Nobody is signed in for them: verify the caller yourself, or ask `context.identify(request)` for the person the API would see.
+- `context.as(person)` acts on comments by the API's own rules (`listThreads`, `getThread`, `reply`, `setStatus`, `deleteComment`). Other connectors and `onEvent` hear about it, with the connector as the event's `source`.
+- `context.links` ties threads and comments to their counterparts elsewhere (`save`, `find(externalId)`, `forThread`); links with a URL show on the thread.
+- `context.storage` keeps the connector's own state (`get`, `set` with an optional TTL, `delete`), apart from other connectors'.
+- `context.screenshot(thread, kind)` reads a screenshot from the asset store; `context.threadUrl(thread)` is the page with the thread open.
+
 ## Widget
 
 The toolbar sits along the right edge: comment mode (<kbd>C</kbd>), this page's comments, and who you're signed in as. By default the page is moved over to make room for it (`margin-right` on `<html>`), so nothing is covered; `dock: "overlay"` draws it on top instead. The comments panel floats beside it. If the API answers 401 or 403, nothing is shown and the page is left alone.
@@ -187,7 +262,7 @@ pnpm dev:demo                              # 127.0.0.1:$PORT (default 8795), wit
 
 ```sh
 pnpm install
-pnpm test        # the server against the memory, D1 (Miniflare) and Postgres (PGlite) stores; auth; assets; anchoring
+pnpm test        # the server and connectors against the memory, D1 (Miniflare) and Postgres (PGlite) stores; MCP with the official SDK client; Linear against a stand-in API; auth; assets; anchoring
 pnpm typecheck
 pnpm check       # biome
 pnpm build

package/dist/chunks/{chunk-GHNSLFY2.js → chunk-644PTNSO.js}

@@ -7,10 +7,12 @@ var sqlite_exports = {};
 __export(sqlite_exports, {
   comments: () => comments,
   createTablesSql: () => createTablesSql,
+  links: () => links,
   threads: () => threads,
-  users: () => users
+  users: () => users,
+  values: () => values
 });
-import { index, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { index, primaryKey, sqliteTable, text } from "drizzle-orm/sqlite-core";
 var threads = sqliteTable(
   "wc_threads",
   {
@@ -55,18 +57,45 @@ var users = sqliteTable("wc_users", {
   kind: text("kind").notNull(),
   lastSeenAt: text("last_seen_at").notNull()
 });
+var links = sqliteTable(
+  "wc_links",
+  {
+    site: text("site").notNull(),
+    connector: text("connector").notNull(),
+    externalId: text("external_id").notNull(),
+    threadId: text("thread_id").notNull(),
+    commentId: text("comment_id"),
+    url: text("url"),
+    title: text("title"),
+    createdAt: text("created_at").notNull()
+  },
+  (t) => [
+    primaryKey({ columns: [t.site, t.connector, t.externalId] }),
+    index("wc_links_thread").on(t.site, t.threadId)
+  ]
+);
+var values = sqliteTable("wc_values", {
+  name: text("name").primaryKey(),
+  value: text("value").notNull(),
+  expiresAt: text("expires_at")
+});
 var createTablesSql = [
   `CREATE TABLE IF NOT EXISTS wc_threads (id TEXT PRIMARY KEY, site TEXT NOT NULL, page TEXT NOT NULL, url TEXT NOT NULL, anchor TEXT NOT NULL, context TEXT, screenshots TEXT NOT NULL, status TEXT NOT NULL, author_id TEXT NOT NULL, author_name TEXT NOT NULL, author_avatar TEXT, author_kind TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, resolved_at TEXT, resolved_by TEXT)`,
   `CREATE INDEX IF NOT EXISTS wc_threads_page ON wc_threads (site, page, created_at)`,
   `CREATE TABLE IF NOT EXISTS wc_comments (id TEXT PRIMARY KEY, thread_id TEXT NOT NULL, body TEXT NOT NULL, author_id TEXT NOT NULL, author_name TEXT NOT NULL, author_avatar TEXT, author_kind TEXT NOT NULL, created_at TEXT NOT NULL)`,
   `CREATE INDEX IF NOT EXISTS wc_comments_thread ON wc_comments (thread_id, created_at)`,
-  `CREATE TABLE IF NOT EXISTS wc_users (id TEXT PRIMARY KEY, name TEXT NOT NULL, email TEXT, avatar_url TEXT, kind TEXT NOT NULL, last_seen_at TEXT NOT NULL)`
+  `CREATE TABLE IF NOT EXISTS wc_users (id TEXT PRIMARY KEY, name TEXT NOT NULL, email TEXT, avatar_url TEXT, kind TEXT NOT NULL, last_seen_at TEXT NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS wc_links (site TEXT NOT NULL, connector TEXT NOT NULL, external_id TEXT NOT NULL, thread_id TEXT NOT NULL, comment_id TEXT, url TEXT, title TEXT, created_at TEXT NOT NULL, PRIMARY KEY (site, connector, external_id))`,
+  `CREATE INDEX IF NOT EXISTS wc_links_thread ON wc_links (site, thread_id)`,
+  `CREATE TABLE IF NOT EXISTS wc_values (name TEXT PRIMARY KEY, value TEXT NOT NULL, expires_at TEXT)`
 ];
 
 export {
   threads,
   comments,
   users,
+  links,
+  values,
   createTablesSql,
   sqlite_exports
 };

package/dist/chunks/{chunk-6VWNCJ3A.js → chunk-7K7K7M5O.js}

@@ -7,10 +7,12 @@ var pg_exports = {};
 __export(pg_exports, {
   comments: () => comments,
   createTablesSql: () => createTablesSql,
+  links: () => links,
   threads: () => threads,
-  users: () => users
+  users: () => users,
+  values: () => values
 });
-import { index, pgTable, text } from "drizzle-orm/pg-core";
+import { index, pgTable, primaryKey, text } from "drizzle-orm/pg-core";
 var threads = pgTable(
   "wc_threads",
   {
@@ -55,18 +57,45 @@ var users = pgTable("wc_users", {
   kind: text("kind").notNull(),
   lastSeenAt: text("last_seen_at").notNull()
 });
+var links = pgTable(
+  "wc_links",
+  {
+    site: text("site").notNull(),
+    connector: text("connector").notNull(),
+    externalId: text("external_id").notNull(),
+    threadId: text("thread_id").notNull(),
+    commentId: text("comment_id"),
+    url: text("url"),
+    title: text("title"),
+    createdAt: text("created_at").notNull()
+  },
+  (t) => [
+    primaryKey({ columns: [t.site, t.connector, t.externalId] }),
+    index("wc_links_thread").on(t.site, t.threadId)
+  ]
+);
+var values = pgTable("wc_values", {
+  name: text("name").primaryKey(),
+  value: text("value").notNull(),
+  expiresAt: text("expires_at")
+});
 var createTablesSql = [
   `CREATE TABLE IF NOT EXISTS wc_threads (id TEXT PRIMARY KEY, site TEXT NOT NULL, page TEXT NOT NULL, url TEXT NOT NULL, anchor TEXT NOT NULL, context TEXT, screenshots TEXT NOT NULL, status TEXT NOT NULL, author_id TEXT NOT NULL, author_name TEXT NOT NULL, author_avatar TEXT, author_kind TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, resolved_at TEXT, resolved_by TEXT)`,
   `CREATE INDEX IF NOT EXISTS wc_threads_page ON wc_threads (site, page, created_at)`,
   `CREATE TABLE IF NOT EXISTS wc_comments (id TEXT PRIMARY KEY, thread_id TEXT NOT NULL, body TEXT NOT NULL, author_id TEXT NOT NULL, author_name TEXT NOT NULL, author_avatar TEXT, author_kind TEXT NOT NULL, created_at TEXT NOT NULL)`,
   `CREATE INDEX IF NOT EXISTS wc_comments_thread ON wc_comments (thread_id, created_at)`,
-  `CREATE TABLE IF NOT EXISTS wc_users (id TEXT PRIMARY KEY, name TEXT NOT NULL, email TEXT, avatar_url TEXT, kind TEXT NOT NULL, last_seen_at TEXT NOT NULL)`
+  `CREATE TABLE IF NOT EXISTS wc_users (id TEXT PRIMARY KEY, name TEXT NOT NULL, email TEXT, avatar_url TEXT, kind TEXT NOT NULL, last_seen_at TEXT NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS wc_links (site TEXT NOT NULL, connector TEXT NOT NULL, external_id TEXT NOT NULL, thread_id TEXT NOT NULL, comment_id TEXT, url TEXT, title TEXT, created_at TEXT NOT NULL, PRIMARY KEY (site, connector, external_id))`,
+  `CREATE INDEX IF NOT EXISTS wc_links_thread ON wc_links (site, thread_id)`,
+  `CREATE TABLE IF NOT EXISTS wc_values (name TEXT PRIMARY KEY, value TEXT NOT NULL, expires_at TEXT)`
 ];
 
 export {
   threads,
   comments,
   users,
+  links,
+  values,
   createTablesSql,
   pg_exports
 };