@derive-to/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,105 @@
+# 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.

package/SKILL.md

@@ -0,0 +1,65 @@
+# Derive — agent skill
+
+Derive hosts an artifact (HTML, Markdown, or a static bundle) at a permanent,
+versioned URL with inline comments. An agent connects to Derive's **remote MCP
+server** over Streamable HTTP (OAuth-authenticated — no static token) and drives
+the **read → revise → publish** loop. The agent acts at **its own role**: what it
+can do is exactly what that role can do.
+
+Connect (Claude Code / claude.ai / Claude Desktop):
+
+```
+claude mcp add --transport http derive <your-derive-server>/mcp
+```
+
+The first call triggers an OAuth consent in the browser; you grant the agent a
+scope, and that scope maps to a role (read-only, propose, or publish).
+
+Your identity (agent name, workspace, role) is in the server instructions — there is no `whoami` tool.
+
+## Tools
+
+| Tool | Use |
+|---|---|
+| `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. |
+
+## Role decides: live publish vs proposal
+
+`publish` is one tool. Whether it goes live or files a proposal is decided by **your role** (the scope you were granted), with `for_review:true` to force review:
+
+- **Admin / Creator** → `publish` goes live immediately, or pass `for_review:true` to file a proposal instead.
+- **Commenter** → `publish` files a proposal a human approves before it goes live.
+- **Viewer** → read-only.
+
+So an agent you authorize with a publish scope publishes exactly as you would; a
+lower-scoped agent can still read and publish, but its revisions become proposals a
+human approves rather than live content.
+
+## The loop
+
+1. **`catch_up`** → what changed since you last looked, plus the open feedback to address.
+2. **`read`** → the content (a page of a bundle, or a past version) in context.
+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.
+
+## Keep comments anchorable
+
+Anchors are text quotes with surrounding context, matched in the rendered
+document. They survive edits when the text stays recognizable: make local edits,
+keep headings and distinctive phrases stable, and prefer real text over images of
+text. A comment whose text is gone is shown as "text changed", never moved to the
+wrong place.
+
+## Notes
+
+- Versions are immutable; `@vN` URLs never change. The viewer groups rapid
+  same-author revisions into time-based sessions, but every revision is addressable.
+- Multi-page bundles are readable (`read` with a `section`, `catch_up`) and revisable
+  over the remote `/mcp` server via `publish` with a `files` map. Over the stdio
+  `@derive-to/mcp` server, bundles are publish-via-remote/web only, and `comment` set_state
+  takes a `comment_id`. Both servers expose the same 5 tools.

package/bin/derive-mcp.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// `npx @derive-to/mcp`: start the Derive MCP stdio server. Derive ships TypeScript with no
+// build step, so register tsx's loader and import the TS entry. The server talks
+// to a Derive instance over HTTP (DERIVE_SERVER) with an optional bearer (DERIVE_TOKEN).
+import { register } from "tsx/esm/api"
+
+register()
+await import(new URL("../src/index.ts", import.meta.url).href)

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@derive-to/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Stdio MCP server for Derive — list, read, catch up on, comment on, and publish artifacts on a Derive instance.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "derive",
+    "artifacts"
+  ],
+  "license": "FSL-1.1-ALv2",
+  "homepage": "https://derive.to",
+  "bugs": {
+    "url": "https://github.com/derive-to/derive/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/derive-to/derive.git",
+    "directory": "packages/mcp"
+  },
+  "bin": {
+    "derive-mcp": "./bin/derive-mcp.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "SKILL.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "tsx": "^4.19.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@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"
+  }
+}

package/src/client.ts

@@ -0,0 +1,263 @@
+/** HTTP client for a Derive server. Shared by the MCP server and any tooling. */
+
+export interface PublishArgs {
+  content: string | Uint8Array
+  filename: string
+  title?: string
+  slug?: string
+  spa?: boolean
+  message?: string
+  visibility?: "public" | "link" | "org" | "password" | "private"
+  /** Unlock password, required when visibility is "password". */
+  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[]
+}
+
+export type CommentState = "open" | "addressed" | "resolved" | "outdated"
+
+export interface CommentJson {
+  id: string
+  thread_id: string
+  base_version: number
+  path: string | null
+  anchor: string | null
+  body_md: string
+  author: string
+  state: CommentState
+  created_at: string
+}
+
+export interface ArtifactSummaryJson {
+  short_id: string
+  title: string | null
+  kind: "file" | "bundle"
+  current_version: number
+  visibility: string
+}
+
+/** A revision submitted for human review instead of published live. */
+export interface ProposeArgs {
+  content: string
+  filename?: string
+  message: string
+  /** Thread ids this revision addresses (flip to `addressed`, resolve on approval). */
+  addresses?: string[]
+}
+export interface ProposalJson {
+  id: string
+  base_version: number
+  addressed?: string[]
+}
+
+export interface NewCommentArgs {
+  body_md: string
+  thread_id?: string
+  author?: string
+  base_version?: number
+  path?: string
+  anchor?: unknown
+}
+
+export interface VersionJson {
+  n: number
+  author: string
+  message: string | null
+  name: string | null
+  created_at: string
+}
+export interface SessionJson {
+  n: number
+  from_n: number
+  count: number
+  author: string
+  name: string | null
+  created_at: string
+}
+export interface ArtifactJson {
+  short_id: string
+  url: string
+  title: string | null
+  kind: "file" | "bundle"
+  visibility: string
+  current_version: number
+  versions: VersionJson[]
+  /** Time-grouped version view (newest-first); present on the detail endpoint. */
+  sessions?: SessionJson[]
+}
+
+export interface DiffOpJson {
+  t: "ctx" | "add" | "del"
+  line: string
+}
+export interface DiffJson {
+  from: number
+  to: number
+  ops: DiffOpJson[]
+}
+
+export interface ViewStatsJson {
+  total: number
+  unique: number
+  perVersion: { version: number; count: number }[]
+  daily: { day: string; count: number }[]
+  recent: { viewer: string; kind: "user" | "anon"; at: string }[]
+}
+
+export interface DeriveClient {
+  /** List the workspace's artifacts (optionally filtered by a title query). */
+  list(query?: string): Promise<ArtifactSummaryJson[]>
+  publish(args: PublishArgs): Promise<ArtifactJson>
+  /** Submit a single-file revision for human review (does not go live). */
+  propose(shortId: string, args: ProposeArgs): Promise<ProposalJson>
+  get(shortId: string): Promise<ArtifactJson>
+  getContent(shortId: string, version?: number): Promise<string>
+  listComments(shortId: string, state?: CommentState): Promise<CommentJson[]>
+  createComment(shortId: string, args: NewCommentArgs): Promise<CommentJson>
+  /** Resolve or reopen the thread a comment belongs to. */
+  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>
+  /** Restore a past version as a new current revision. */
+  restore(shortId: string, version: number): Promise<ArtifactJson>
+  /** Aggregated view analytics. */
+  viewStats(shortId: string): Promise<ViewStatsJson>
+}
+
+export interface ClientOptions {
+  baseUrl: string
+  token?: string
+  /** Override fetch (used in tests to target an in-process server). */
+  fetchImpl?: typeof fetch
+}
+
+export function createClient(opts: ClientOptions): DeriveClient {
+  const base = opts.baseUrl.replace(/\/$/, "")
+  const f = opts.fetchImpl ?? fetch
+  const authHeaders: Record<string, string> = opts.token
+    ? { Authorization: `Bearer ${opts.token}` }
+    : {}
+
+  async function ok(res: Response): Promise<unknown> {
+    if (res.ok) return res.json()
+    const body = (await res.json().catch(() => ({}))) as { error?: string }
+    throw new Error(`derive ${res.status}: ${body.error ?? res.statusText}`)
+  }
+
+  return {
+    async list(query) {
+      const q = query ? `?query=${encodeURIComponent(query)}` : ""
+      const r = (await ok(await f(`${base}/v1/artifacts${q}`, { headers: authHeaders }))) as {
+        artifacts: ArtifactSummaryJson[]
+      }
+      return r.artifacts
+    },
+
+    async publish(args) {
+      const bytes =
+        typeof args.content === "string" ? new TextEncoder().encode(args.content) : args.content
+      const form = new FormData()
+      form.append("file", new Blob([bytes as BlobPart]), args.filename)
+      if (args.title) form.append("title", args.title)
+      if (args.slug) form.append("slug", args.slug)
+      if (args.message) form.append("message", args.message)
+      if (args.visibility) form.append("visibility", args.visibility)
+      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(","))
+      const url = args.id ? `${base}/v1/artifacts/${args.id}/versions` : `${base}/v1/artifacts`
+      return ok(
+        await f(url, { method: "POST", body: form, headers: authHeaders }),
+      ) as Promise<ArtifactJson>
+    },
+
+    async propose(shortId, args) {
+      const form = new FormData()
+      form.append(
+        "file",
+        new Blob([new TextEncoder().encode(args.content)]),
+        args.filename ?? "index.html",
+      )
+      form.append("message", args.message)
+      if (args.addresses?.length) form.append("addresses", args.addresses.join(","))
+      return ok(
+        await f(`${base}/v1/artifacts/${shortId}/proposals`, {
+          method: "POST",
+          body: form,
+          headers: authHeaders,
+        }),
+      ) as Promise<ProposalJson>
+    },
+
+    async get(shortId) {
+      return ok(
+        await f(`${base}/v1/artifacts/${shortId}`, { headers: authHeaders }),
+      ) as Promise<ArtifactJson>
+    },
+
+    async getContent(shortId, version) {
+      const q = version ? `?v=${version}` : ""
+      const res = await f(`${base}/v1/artifacts/${shortId}/content${q}`, { headers: authHeaders })
+      if (!res.ok) {
+        const body = (await res.json().catch(() => ({}))) as { error?: string }
+        throw new Error(`derive ${res.status}: ${body.error ?? res.statusText}`)
+      }
+      return res.text()
+    },
+
+    async listComments(shortId, state) {
+      const q = state ? `?state=${state}` : ""
+      const r = (await ok(
+        await f(`${base}/v1/artifacts/${shortId}/comments${q}`, { headers: authHeaders }),
+      )) as { comments: CommentJson[] }
+      return r.comments
+    },
+
+    async createComment(shortId, args) {
+      return ok(
+        await f(`${base}/v1/artifacts/${shortId}/comments`, {
+          method: "POST",
+          headers: { ...authHeaders, "content-type": "application/json" },
+          body: JSON.stringify(args),
+        }),
+      ) as Promise<CommentJson>
+    },
+
+    async setThreadState(shortId, commentId, state) {
+      await ok(
+        await f(`${base}/v1/artifacts/${shortId}/comments/${commentId}/resolve`, {
+          method: "POST",
+          headers: { ...authHeaders, "content-type": "application/json" },
+          body: JSON.stringify({ state }),
+        }),
+      )
+    },
+
+    async diff(shortId, from, to) {
+      const q = new URLSearchParams({ format: "json" })
+      if (from != null) q.set("from", String(from))
+      if (to != null) q.set("to", String(to))
+      return ok(
+        await f(`${base}/v1/artifacts/${shortId}/diff?${q}`, { headers: authHeaders }),
+      ) as Promise<DiffJson>
+    },
+
+    async restore(shortId, version) {
+      return ok(
+        await f(`${base}/v1/artifacts/${shortId}/restore`, {
+          method: "POST",
+          headers: { ...authHeaders, "content-type": "application/json" },
+          body: JSON.stringify({ version }),
+        }),
+      ) as Promise<ArtifactJson>
+    },
+
+    async viewStats(shortId) {
+      return ok(
+        await f(`${base}/v1/artifacts/${shortId}/analytics`, { headers: authHeaders }),
+      ) as Promise<ViewStatsJson>
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,307 @@
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { z } from "zod"
+import { createClient } from "./client"
+
+// Stdio MCP server for self-hosters: `npx @derive-to/mcp` talks to a Derive instance over
+// the /v1 HTTP API (DERIVE_SERVER) with a bearer (DERIVE_TOKEN). It exposes the SAME five
+// tools as the remote /mcp server — list_artifacts, read, catch_up, comment, publish —
+// so the vocabulary is identical whether an agent connects over OAuth or a static
+// token. (A static token already has publish rights, so publish here goes live unless
+// you pass for_review; bundle publishing is remote-only.)
+
+const client = createClient({
+  baseUrl: process.env.DERIVE_SERVER ?? "http://localhost:8080",
+  token: process.env.DERIVE_TOKEN,
+})
+
+// The agent guide, served as an MCP resource (single source: SKILL.md).
+const GUIDE = (() => {
+  try {
+    return readFileSync(fileURLToPath(new URL("../SKILL.md", import.meta.url)), "utf8")
+  } catch {
+    return "# Derive\nFind, read, catch_up, comment, and publish via the derive tools."
+  }
+})()
+
+const server = new McpServer({ name: "derive", version: "1.0.0" })
+
+const text = (s: string) => ({ content: [{ type: "text" as const, text: s }] })
+const json = (v: unknown) => text(JSON.stringify(v, null, 2))
+
+// FIND ------------------------------------------------------------------------
+server.registerTool(
+  "list_artifacts",
+  {
+    description:
+      "List the artifacts in your workspace — short id, title, kind, current version, visibility. Start here to find what to work on, then catch_up or read it.",
+    inputSchema: { query: z.string().optional().describe("Optional title search filter.") },
+  },
+  async ({ query }) => {
+    const arts = await client.list(query)
+    return json({ count: arts.length, artifacts: arts })
+  },
+)
+
+// READ CONTENT ----------------------------------------------------------------
+server.registerTool(
+  "read",
+  {
+    description:
+      "Read an artifact's CONTENT by short id (a past `version` defaults to current). For what CHANGED or the comment threads, use catch_up instead.",
+    inputSchema: {
+      short_id: z.string(),
+      version: z.number().int().optional().describe("Defaults to the current version."),
+    },
+  },
+  async ({ short_id, version }) => {
+    const a = await client.get(short_id)
+    const body = await client.getContent(short_id, version)
+    const v = version ?? a.current_version
+    return json({ short_id, title: a.title, kind: a.kind, version: v, content: body })
+  },
+)
+
+// CATCH UP — state, feedback, history, and diffs all in one -------------------
+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. " +
+      "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.",
+    inputSchema: {
+      short_id: z.string(),
+      since_version: z
+        .number()
+        .int()
+        .optional()
+        .describe("The version you last saw (diff base). Defaults to to_version − 1."),
+      to_version: z
+        .number()
+        .int()
+        .optional()
+        .describe("Compare up to this version instead of the current one."),
+      comments: z
+        .enum(["open", "addressed", "resolved", "outdated"])
+        .optional()
+        .describe(
+          "Return ONLY this state's comment threads (the feedback queue) instead of the delta.",
+        ),
+      response_format: z
+        .enum(["summary", "detailed"])
+        .optional()
+        .describe("'summary' (default) omits the line diff; 'detailed' includes it."),
+    },
+  },
+  async ({ short_id, since_version, to_version, comments, response_format }) => {
+    const summarizeComment = (c: {
+      thread_id: string
+      author: string
+      state: string
+      anchor: string | null
+      body_md: string
+    }) => ({
+      thread: c.thread_id,
+      author: c.author,
+      state: c.state,
+      quote: c.anchor,
+      body: c.body_md,
+    })
+
+    if (comments) {
+      const list = await client.listComments(short_id, comments)
+      return json({
+        short_id,
+        comments_state: comments,
+        count: list.length,
+        comments: list.map(summarizeComment),
+      })
+    }
+
+    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([
+      client.listComments(short_id, "open"),
+      client.listComments(short_id, "outdated"),
+      client.listComments(short_id, "addressed"),
+    ])
+    let entryDiff: string | undefined
+    if (response_format === "detailed" && since < to) {
+      const d = await client.diff(short_id, since, to)
+      entryDiff = d.ops
+        .map((o) => `${o.t === "add" ? "+" : o.t === "del" ? "-" : " "} ${o.line}`)
+        .join("\n")
+    }
+    const outdatedBit = outdated.length ? ` ${outdated.length} now outdated.` : ""
+    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}`
+    return json({
+      summary,
+      short_id,
+      since,
+      to,
+      head,
+      caught_up: since >= to,
+      versions: history,
+      new_versions: newVersions,
+      ...(entryDiff
+        ? { entry_diff: entryDiff }
+        : {
+            entry_diff: "(omitted) — call again with response_format='detailed' for the line diff.",
+          }),
+      open_comments: open.map(summarizeComment),
+      ...(outdated.length ? { outdated_comments: outdated.map(summarizeComment) } : {}),
+    })
+  },
+)
+
+// COMMENT — leave / reply / resolve feedback ----------------------------------
+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).",
+    inputSchema: {
+      short_id: z.string(),
+      body: z
+        .string()
+        .optional()
+        .describe("The comment text. Omit when only changing thread state."),
+      reply_to: z
+        .string()
+        .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."),
+      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)."),
+    },
+  },
+  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).")
+    let posted: Awaited<ReturnType<typeof client.createComment>> | undefined
+    if (body) {
+      const anchor = quote ? { type: "TextQuoteSelector", exact: quote } : undefined
+      posted = await client.createComment(short_id, {
+        thread_id: reply_to,
+        body_md: body,
+        anchor,
+        author: "agent",
+      })
+    }
+    let stateNote = ""
+    if (set_state) {
+      const ref = posted?.id ?? comment_id
+      if (!ref)
+        return text(
+          "`set_state` needs a `comment_id` (a comment in the thread) or a `body` to post and resolve.",
+        )
+      await client.setThreadState(short_id, ref, set_state)
+      stateNote = ` · thread ${set_state === "resolved" ? "resolved" : "reopened"}`
+    }
+    if (posted) {
+      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(`Thread ${set_state === "resolved" ? "resolved" : "reopened"}.`)
+  },
+)
+
+// WRITE — publish live, or file a proposal for review -------------------------
+server.registerTool(
+  "publish",
+  {
+    description:
+      "Publish a single-file artifact and get a permanent URL. OMIT short_id to create a NEW artifact (title recommended); PASS short_id to publish a new version (same URL). Pass for_review:true to file it as a PROPOSAL a human approves instead of going live. Pass `addresses` with the thread ids this revision resolves. (Multi-page bundles are published via the web app or the remote /mcp server.)",
+    inputSchema: {
+      content: z.string().describe("The artifact's text content (HTML or Markdown)."),
+      filename: z
+        .string()
+        .optional()
+        .describe("Filename, e.g. report.html or notes.md. Defaults to index.html."),
+      short_id: z
+        .string()
+        .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(),
+      message: z.string().optional().describe("What changed in this version."),
+      for_review: z
+        .boolean()
+        .optional()
+        .describe("File as a proposal for human review instead of publishing live."),
+      addresses: z
+        .array(z.string())
+        .optional()
+        .describe("Thread ids this revision resolves (live publish) or addresses (proposal)."),
+    },
+  },
+  async ({ content, filename, short_id, title, visibility, message, for_review, addresses }) => {
+    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, {
+        content,
+        filename,
+        message: message ?? "Proposed revision",
+        addresses,
+      })
+      const note = p.addressed?.length ? ` · addressed ${p.addressed.length} thread(s)` : ""
+      return json({
+        proposed: true,
+        proposal_id: p.id,
+        base_version: p.base_version,
+        note: `Submitted for review (not live)${note}.`,
+      })
+    }
+    const a = await client.publish({
+      id: short_id,
+      content,
+      filename: filename ?? "index.html",
+      title,
+      visibility,
+      message,
+      resolves: addresses,
+    })
+    const note = addresses?.length ? ` · resolved ${addresses.length} thread(s)` : ""
+    return json({
+      published: true,
+      short_id: a.short_id,
+      version: a.current_version,
+      url: a.url,
+      title: a.title,
+      note: short_id ? `Live — new version${note}.` : `Live — created "${a.title}"${note}.`,
+    })
+  },
+)
+
+// Expose the agent loop as an MCP resource so any client can read the conventions.
+server.registerResource(
+  "derive-guide",
+  "derive://guide",
+  {
+    title: "Derive agent guide",
+    description: "How to run the publish → review → revise loop.",
+    mimeType: "text/markdown",
+  },
+  async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: GUIDE }] }),
+)
+
+await server.connect(new StdioServerTransport())