@derive-to/mcp 0.1.0 → 0.2.0

package/SKILL.md

@@ -23,9 +23,9 @@ Your identity (agent name, workspace, role) is in the server instructions — th
 |---|---|
 | `list_artifacts` | Find: the artifacts in your workspace (short id, title, kind, version, visibility). Optional `query` filters by title. |
 | `read` | Read an artifact's content by short id. For a bundle, omit `section` for the outline or pass a `section` (page path) for one page; pass `version` to read history. |
-| `catch_up` | Start here on an artifact: its state in one call — what changed since `since_version`, the open/outdated comment threads, and version history. Pass `comments` (open/addressed/resolved/outdated) for that filtered feedback queue, or `response_format='detailed'` (with optional `since_version`/`to_version`) to fold in the exact line diff. |
-| `comment` | Leave feedback, reply (`reply_to` a thread id), anchor to a `quote`, and/or resolve/reopen (`set_state`). |
-| `publish` | Save a revision. `content` for a single file, `files` (path→content map) for a multi-page bundle. Omit `short_id` to create new (title required); pass it to add a version. `addresses` lists thread ids this revision resolves. |
+| `catch_up` | Start here on an artifact: its state in one call — what changed since `since_version`, the open/outdated comment threads, the `review` round state, and version history. Pass `comments` (open/addressed/resolved/outdated) for that filtered feedback queue, or `response_format='detailed'` (with optional `since_version`/`to_version`) to fold in the exact line diff. Waiting on a review? Pass `wait` (seconds, max 50) to long-poll: the call blocks until the human sends back / approves / comments — chain these instead of sleeping. |
+| `comment` | Leave feedback, reply (`reply_to` a thread id), anchor to a `quote`, react (`react: "👍"` with `reply_to` — the loop's lightweight ack, landing on the thread's latest human comment), and/or resolve/reopen (`set_state`). |
+| `publish` | Save a revision. `content` for a single file, `files` (path→content map) for a multi-page bundle. Omit `short_id` to create new (title required); pass it to add a version. `addresses` lists thread ids this revision resolves; `request_review:true` opens a review round for your human. New artifacts land **private** by default (the human you act for owns the draft) — they promote via the share dialog, so don't pass a wider `visibility` unasked. The result's `opened_in_tab` says whether an open Derive tab caught the push; when false, open the `url` for the user if they should see it now. |
 
 ## Role decides: live publish vs proposal
 
@@ -46,6 +46,13 @@ human approves rather than live content.
 3. **Revise**, then **`comment`** (reply/resolve) and/or **`publish`** (pass `addresses`
    to resolve the threads this revision fixes) — same URL, a new version. Comment
    highlights re-anchor to the moved text.
+4. **Review rounds** (the /derive loop): publish with `request_review:true`, then
+   chain `catch_up(short_id, wait: 50)` — each call returns the moment the human
+   hits Send back / Approve (or ~50s pass). On `sent_back`, sweep ALL threads (any
+   author, anchored or not), ack every human comment FIRST
+   (`comment(reply_to, react:"👍")` at minimum), then revise and publish with
+   `addresses` + `request_review:true` for the next round. The human never
+   resolves threads — you settle thread state.
 
 ## Keep comments anchorable
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@derive-to/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Stdio MCP server for Derive — list, read, catch up on, comment on, and publish artifacts on a Derive instance.",
   "keywords": [
@@ -37,24 +37,24 @@
     ".": "./src/index.ts",
     "./client": "./src/client.ts"
   },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "tsx": "^4.19.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@derive/api": "workspace:*",
+    "@derive/db": "workspace:*",
+    "@derive/storage": "workspace:*",
     "@hono/node-server": "^2.0.5",
     "@types/node": "^25.9.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.9",
-    "@derive/api": "0.1.0",
-    "@derive/db": "0.1.0",
-    "@derive/storage": "0.1.0"
-  },
-  "scripts": {
-    "start": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
+    "vitest": "^4.1.9"
   }
-}
+}

package/src/client.ts

@@ -7,13 +7,15 @@ export interface PublishArgs {
   slug?: string
   spa?: boolean
   message?: string
-  visibility?: "public" | "link" | "org" | "password" | "private"
-  /** Unlock password, required when visibility is "password". */
+  visibility?: "public" | "org" | "private"
+  /** A lock on a public link (optional). */
   password?: string
   /** When set, publishes a new version of this artifact instead of a new one. */
   id?: string
   /** Comment ids whose threads to resolve as part of this (re)publish. */
   resolves?: string[]
+  /** Open a review round for this version (the /derive loop's ask). */
+  requestReview?: boolean
 }
 
 export type CommentState = "open" | "addressed" | "resolved" | "outdated"
@@ -28,6 +30,8 @@ export interface CommentJson {
   author: string
   state: CommentState
   created_at: string
+  /** emoji → actor display names (the ack surface). */
+  reactions?: Record<string, string[]>
 }
 
 export interface ArtifactSummaryJson {
@@ -86,6 +90,19 @@ export interface ArtifactJson {
   versions: VersionJson[]
   /** Time-grouped version view (newest-first); present on the detail endpoint. */
   sessions?: SessionJson[]
+  /** Publish-response extras (agent-credentialed publishes only). */
+  review_requested?: boolean
+  opened_in_tab?: boolean
+}
+
+/** One review round: the human-ack primitive of the /derive loop. */
+export interface ReviewRoundJson {
+  id: string
+  state: "pending" | "sent_back" | "approved"
+  version: number
+  note: string | null
+  created_at: string
+  resolved_at: string | null
 }
 
 export interface DiffOpJson {
@@ -120,6 +137,12 @@ export interface DeriveClient {
   setThreadState(shortId: string, commentId: string, state: "resolved" | "open"): Promise<void>
   /** Line diff between two versions (defaults: current-1 → current). */
   diff(shortId: string, from?: number, to?: number): Promise<DiffJson>
+  /** The artifact's review rounds (newest first) + the pending one, if any. */
+  getReview(
+    shortId: string,
+  ): Promise<{ rounds: ReviewRoundJson[]; pending: ReviewRoundJson | null }>
+  /** Toggle an emoji reaction on a comment (the loop's lightweight ack). */
+  react(shortId: string, commentId: string, emoji: string): Promise<void>
   /** Restore a past version as a new current revision. */
   restore(shortId: string, version: number): Promise<ArtifactJson>
   /** Aggregated view analytics. */
@@ -167,6 +190,7 @@ export function createClient(opts: ClientOptions): DeriveClient {
       if (args.password) form.append("password", args.password)
       if (args.spa) form.append("spa", "true")
       if (args.resolves?.length) form.append("resolves", args.resolves.join(","))
+      if (args.requestReview) form.append("request_review", "true")
       const url = args.id ? `${base}/v1/artifacts/${args.id}/versions` : `${base}/v1/artifacts`
       return ok(
         await f(url, { method: "POST", body: form, headers: authHeaders }),
@@ -244,6 +268,22 @@ export function createClient(opts: ClientOptions): DeriveClient {
       ) as Promise<DiffJson>
     },
 
+    async getReview(shortId) {
+      return ok(
+        await f(`${base}/v1/artifacts/${shortId}/review`, { headers: authHeaders }),
+      ) as Promise<{ rounds: ReviewRoundJson[]; pending: ReviewRoundJson | null }>
+    },
+
+    async react(shortId, commentId, emoji) {
+      await ok(
+        await f(`${base}/v1/artifacts/${shortId}/comments/${commentId}/react`, {
+          method: "POST",
+          headers: { ...authHeaders, "content-type": "application/json" },
+          body: JSON.stringify({ emoji }),
+        }),
+      )
+    },
+
     async restore(shortId, version) {
       return ok(
         await f(`${base}/v1/artifacts/${shortId}/restore`, {

package/src/index.ts

@@ -69,9 +69,10 @@ server.registerTool(
   "catch_up",
   {
     description:
-      "START HERE on an artifact. Its state in one call: a summary, the versions since `since_version`, the open (and outdated) comment threads, and the full version history. " +
+      "START HERE on an artifact. Its state in one call: a summary, the review round, the versions since `since_version`, the open (and outdated) comment threads, and the full version history. " +
       "Pass `comments` (open / addressed / resolved / outdated) to instead get that filtered thread list — your feedback queue. " +
-      "Pass `response_format='detailed'` (optionally with `since_version`/`to_version`) to fold in the exact line diff between two versions.",
+      "Pass `response_format='detailed'` (optionally with `since_version`/`to_version`) to fold in the exact line diff between two versions. " +
+      "WAITING ON A REVIEW? Pass `wait` (seconds, max 50) to block until the human sends back or approves — chain these instead of sleeping between polls.",
     inputSchema: {
       short_id: z.string(),
       since_version: z
@@ -94,9 +95,18 @@ server.registerTool(
         .enum(["summary", "detailed"])
         .optional()
         .describe("'summary' (default) omits the line diff; 'detailed' includes it."),
+      wait: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe(
+          "Long-poll: block up to this many seconds for the human's next review action before returning. Returns immediately when something is already actionable.",
+        ),
     },
   },
-  async ({ short_id, since_version, to_version, comments, response_format }) => {
+  async ({ short_id, since_version, to_version, comments, response_format, wait }) => {
     const summarizeComment = (c: {
       thread_id: string
       author: string
@@ -121,17 +131,71 @@ server.registerTool(
       })
     }
 
+    // Long-poll (self-host shim flavor): the /v1 API has no blocking endpoint,
+    // so poll every 2.5s until the human acts or the wait runs out — the same
+    // contract as the remote server's wait on a coarser clock. "Acts" = the
+    // round changes OR the open-comment count moves (so waiting works with no
+    // round open, exactly like the server's comment.created wake). Transient
+    // errors retry; they never end the wait early. A settled round that still
+    // applies to the current head is already actionable and returns at once.
+    if (wait) {
+      const deadline = Date.now() + wait * 1000
+      const snap = () =>
+        Promise.all([
+          client.get(short_id),
+          client.getReview(short_id),
+          client.listComments(short_id, "open"),
+        ]).then(([art, rev, open]) => {
+          const round = rev.pending ?? rev.rounds[0] ?? null
+          return {
+            key: `${round?.id ?? "none"}:${round?.state ?? "none"}:${open.length}`,
+            actionable:
+              !!round && round.state !== "pending" && round.version >= art.current_version,
+          }
+        })
+      let baseline: string | null = null
+      for (;;) {
+        const cur = await snap().catch(() => null)
+        if (cur) {
+          if (baseline === null) {
+            baseline = cur.key
+            if (cur.actionable) break
+          } else if (cur.key !== baseline) break
+        }
+        if (Date.now() >= deadline) break
+        await new Promise((r) => setTimeout(r, 2500))
+      }
+    }
+
     const a = await client.get(short_id)
     const head = a.current_version
     const to = Math.min(head, Math.max(1, to_version ?? head))
     const since = Math.min(to, Math.max(1, since_version ?? to - 1))
     const history = a.versions.slice().sort((x, y) => y.n - x.n)
     const newVersions = history.filter((v) => v.n > since && v.n <= to)
-    const [open, outdated, addressed] = await Promise.all([
+    const [open, outdated, addressed, reviewState] = await Promise.all([
       client.listComments(short_id, "open"),
       client.listComments(short_id, "outdated"),
       client.listComments(short_id, "addressed"),
+      client.getReview(short_id).catch(() => ({ rounds: [], pending: null })),
     ])
+    const round = reviewState.pending ?? reviewState.rounds[0] ?? null
+    const review = round
+      ? {
+          state: round.state,
+          version: round.version,
+          requested_at: round.created_at,
+          resolved_at: round.resolved_at,
+          note: round.note,
+        }
+      : null
+    const reviewBit = review
+      ? review.state === "pending"
+        ? ` Review requested on v${review.version} — waiting for the human.`
+        : review.state === "sent_back"
+          ? ` The human sent back their review of v${review.version} — read the open threads, revise, and re-request.`
+          : ` The human approved v${review.version} — you're clear to proceed.`
+      : ""
     let entryDiff: string | undefined
     if (response_format === "detailed" && since < to) {
       const d = await client.diff(short_id, since, to)
@@ -143,10 +207,11 @@ server.registerTool(
     const addressedBit = addressed.length ? ` ${addressed.length} addressed (pending review).` : ""
     const summary =
       since >= to
-        ? `You're up to date on "${a.title}" (v${head}); ${open.length} open comment(s).${addressedBit}${outdatedBit}`
-        : `"${a.title}": ${newVersions.length} new version(s) since v${since} (now v${to}). ${open.length} open comment(s).${addressedBit}${outdatedBit}`
+        ? `You're up to date on "${a.title}" (v${head}); ${open.length} open comment(s).${addressedBit}${outdatedBit}${reviewBit}`
+        : `"${a.title}": ${newVersions.length} new version(s) since v${since} (now v${to}). ${open.length} open comment(s).${addressedBit}${outdatedBit}${reviewBit}`
     return json({
       summary,
+      review,
       short_id,
       since,
       to,
@@ -170,7 +235,7 @@ server.registerTool(
   "comment",
   {
     description:
-      "Leave feedback, reply in a thread, and/or resolve or reopen a thread. Anchor a NEW comment to a quoted span with `quote`. Reply by passing the thread id as `reply_to`. Resolve/reopen by passing `set_state` with a `comment_id` from the thread (or the comment you just left).",
+      "Leave feedback, reply in a thread, react, and/or resolve or reopen a thread. Anchor a NEW comment to a quoted span with `quote`. Reply by passing the thread id as `reply_to`. Pass `react` with a `comment_id` (or `reply_to` to hit the thread's latest comment) to acknowledge feedback without the noise of a reply — the loop's minimum ack. Resolve/reopen by passing `set_state` with a `comment_id` from the thread (or the comment you just left).",
     inputSchema: {
       short_id: z.string(),
       body: z
@@ -182,16 +247,22 @@ server.registerTool(
         .optional()
         .describe("A thread id to reply in; omit to start a new thread."),
       quote: z.string().optional().describe("Exact text to anchor a NEW comment to."),
+      react: z
+        .enum(["👍", "❤️", "🎉", "😄", "👀", "🙏", "🚀", "👎"])
+        .optional()
+        .describe("React to a comment (with `comment_id` or `reply_to`) — 👍 is the loop's ack."),
       set_state: z.enum(["resolved", "open"]).optional().describe("Resolve or reopen a thread."),
       comment_id: z
         .string()
         .optional()
-        .describe("A comment in the thread to set_state on (when not posting)."),
+        .describe("A comment in the thread to react to / set_state on (when not posting)."),
     },
   },
-  async ({ short_id, body, reply_to, quote, set_state, comment_id }) => {
-    if (!body && !set_state)
-      return text("Provide `body` (to comment) or `set_state` (to resolve/reopen).")
+  async ({ short_id, body, reply_to, quote, react, set_state, comment_id }) => {
+    if (!body && !set_state && !react)
+      return text(
+        "Provide `body` (to comment), `react` (to acknowledge), or `set_state` (to resolve/reopen).",
+      )
     let posted: Awaited<ReturnType<typeof client.createComment>> | undefined
     if (body) {
       const anchor = quote ? { type: "TextQuoteSelector", exact: quote } : undefined
@@ -202,6 +273,32 @@ server.registerTool(
         author: "agent",
       })
     }
+    let reactNote = ""
+    if (react) {
+      // The ack target: an explicit comment, else the newest comment in the
+      // thread by someone ELSE — never the agent's own just-posted reply. One
+      // unfiltered fetch covers every thread state (the human may have replied
+      // on a resolved thread).
+      const all = await client.listComments(short_id)
+      let target = comment_id
+      if (!target && reply_to) {
+        const thread = all
+          .filter((cm) => cm.thread_id === reply_to)
+          .sort((x, y) => x.created_at.localeCompare(y.created_at))
+        const other = [...thread].reverse().find((cm) => cm.author !== "agent")
+        target = (other ?? thread[thread.length - 1])?.id
+      }
+      if (!target)
+        return text("`react` needs a `comment_id` or a `reply_to` thread to acknowledge.")
+      // The /react route TOGGLES; skipping an already-present emoji keeps a
+      // retried ack from silently removing it.
+      if (all.find((cm) => cm.id === target)?.reactions?.[react]?.length) {
+        reactNote = ` · already acknowledged with ${react}`
+      } else {
+        await client.react(short_id, target, react)
+        reactNote = ` · acknowledged with ${react}`
+      }
+    }
     let stateNote = ""
     if (set_state) {
       const ref = posted?.id ?? comment_id
@@ -216,9 +313,12 @@ server.registerTool(
       const where = reply_to
         ? `replied in thread ${posted.thread_id}`
         : `new thread ${posted.thread_id}`
-      return text(`${where} (comment ${posted.id})${quote ? ` on “${quote}”` : ""}${stateNote}.`)
+      return text(
+        `${where} (comment ${posted.id})${quote ? ` on “${quote}”` : ""}${reactNote}${stateNote}.`,
+      )
     }
-    return text(`Thread ${set_state === "resolved" ? "resolved" : "reopened"}.`)
+    if (!set_state) return text(`Acknowledged${reactNote.replace(" · acknowledged", "")}.`)
+    return text(`Thread ${set_state === "resolved" ? "resolved" : "reopened"}${reactNote}.`)
   },
 )
 
@@ -239,10 +339,9 @@ server.registerTool(
         .optional()
         .describe("Omit to create a new artifact; pass it to add a version."),
       title: z.string().optional(),
-      // `password` stays CLI/web-only (it needs a password argument this tool
-      // doesn't take). Omitted ⇒ the server default, `private` (the publish is
-      // owned by the user the agent acts on behalf of).
-      visibility: z.enum(["public", "link", "org", "private"]).optional(),
+      // Omitted ⇒ the workspace's agent default (usually `private` — the
+      // human you act for owns the draft and promotes it when ready).
+      visibility: z.enum(["private", "org", "public"]).optional(),
       message: z.string().optional().describe("What changed in this version."),
       for_review: z
         .boolean()
@@ -252,9 +351,25 @@ server.registerTool(
         .array(z.string())
         .optional()
         .describe("Thread ids this revision resolves (live publish) or addresses (proposal)."),
+      request_review: z
+        .boolean()
+        .optional()
+        .describe(
+          "Open a review round asking your human to review this version — the /derive loop. Poll catch_up's `review` (or pass `wait`) for the state.",
+        ),
     },
   },
-  async ({ content, filename, short_id, title, visibility, message, for_review, addresses }) => {
+  async ({
+    content,
+    filename,
+    short_id,
+    title,
+    visibility,
+    message,
+    for_review,
+    addresses,
+    request_review,
+  }) => {
     if (for_review) {
       if (!short_id) return text("A proposal revises an EXISTING artifact — pass its short_id.")
       const p = await client.propose(short_id, {
@@ -279,15 +394,25 @@ server.registerTool(
       visibility,
       message,
       resolves: addresses,
+      requestReview: request_review,
     })
     const note = addresses?.length ? ` · resolved ${addresses.length} thread(s)` : ""
+    const openNote =
+      a.opened_in_tab === false
+        ? " No open Derive tab caught this push — open the url for the user if they should see it now."
+        : ""
     return json({
       published: true,
       short_id: a.short_id,
+      ...(a.review_requested ? { review_requested: true } : {}),
       version: a.current_version,
       url: a.url,
       title: a.title,
-      note: short_id ? `Live — new version${note}.` : `Live — created "${a.title}"${note}.`,
+      visibility: a.visibility,
+      ...(a.opened_in_tab !== undefined ? { opened_in_tab: a.opened_in_tab } : {}),
+      note:
+        (short_id ? `Live — new version${note}.` : `Live — created "${a.title}"${note}.`) +
+        openNote,
     })
   },
 )

package/LICENSE

@@ -1,105 +0,0 @@
-# Functional Source License, Version 1.1, ALv2 Future License
-
-## Abbreviation
-
-FSL-1.1-ALv2
-
-## Notice
-
-Copyright 2026 Anir Agarwal <Agarwal.anir@gmail.com>
-
-## Terms and Conditions
-
-### Licensor ("We")
-
-The party offering the Software under these Terms and Conditions.
-
-### The Software
-
-The "Software" is each version of the software that we make available under
-these Terms and Conditions, as indicated by our inclusion of these Terms and
-Conditions with the Software.
-
-### License Grant
-
-Subject to your compliance with this License Grant and the Patents,
-Redistribution and Trademark clauses below, we hereby grant you the right to
-use, copy, modify, create derivative works, publicly perform, publicly display
-and redistribute the Software for any Permitted Purpose identified below.
-
-### Permitted Purpose
-
-A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
-means making the Software available to others in a commercial product or
-service that:
-
-1. substitutes for the Software;
-
-2. substitutes for any other product or service we offer using the Software
-   that exists as of the date we make the Software available; or
-
-3. offers the same or substantially similar functionality as the Software.
-
-Permitted Purposes specifically include using the Software:
-
-1. for your internal use and access;
-
-2. for non-commercial education;
-
-3. for non-commercial research; and
-
-4. in connection with professional services that you provide to a licensee
-   using the Software in accordance with these Terms and Conditions.
-
-### Patents
-
-To the extent your use for a Permitted Purpose would necessarily infringe our
-patents, the license grant above includes a license under our patents. If you
-make a claim against any party that the Software infringes or contributes to
-the infringement of any patent, then your patent license to the Software ends
-immediately.
-
-### Redistribution
-
-The Terms and Conditions apply to all copies, modifications and derivatives of
-the Software.
-
-If you redistribute any copies, modifications or derivatives of the Software,
-you must include a copy of or a link to these Terms and Conditions and not
-remove any copyright notices provided in or with the Software.
-
-### Disclaimer
-
-THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
-PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
-
-IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
-SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
-EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
-
-### Trademarks
-
-Except for displaying the License Details and identifying us as the origin of
-the Software, you have no right under these Terms and Conditions to use our
-trademarks, trade names, service marks or product names.
-
-## Grant of Future License
-
-We hereby irrevocably grant you an additional license to use the Software under
-the Apache License, Version 2.0 that is effective on the second anniversary of
-the date we make the Software available. On or after that date, you may use the
-Software under the Apache License, Version 2.0, in which case the following
-will apply:
-
-Licensed under the Apache License, Version 2.0 (the "License"); you may not use
-this file except in compliance with the License.
-
-You may obtain a copy of the License at
-
-http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software distributed
-under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-CONDITIONS OF ANY KIND, either express or implied. See the License for the
-specific language governing permissions and limitations under the License.