@derive-to/mcp 0.2.0 → 0.4.0

package/SKILL.md

@@ -22,10 +22,10 @@ Your identity (agent name, workspace, role) is in the server instructions — th
 | 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, 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. |
+| `read` | Read an artifact's content by short id, as **Markdown by default** (HTML is converted — headings, lists, tables, code fences; the styling noise is dropped). Omit `section` and a small doc/bundle returns whole; a **large one returns its outline first** (heading slugs for a single-file doc, page paths for a bundle) — call again with a `section` (a slug, a bundle page, `page.html#slug`, or `"*"` for the full clipped document). Pass `format:'html'` for the exact stored source (needed before publish `edits`) or `format:'text'` for flat visible text (what comment `quote`s anchor against). Pass `version` to read history. An image page in a bundle comes back as a real image, not garbage text. |
+| `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 a line diff — of the **readable Markdown form**, not raw HTML, so it shows what changed instead of tag noise. 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. |
+| `publish` | Save a revision. `content` for a single file, `files` (path→content map) for a multi-page bundle, or **`edits`** (`[{old_str, new_str}]`) to revise part of a single-file artifact without resending it. 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
 
@@ -54,6 +54,54 @@ human approves rather than live content.
    `addresses` + `request_review:true` for the next round. The human never
    resolves threads — you settle thread state.
 
+## Reading big documents
+
+`read` never hands you a wall of JSON-escaped HTML. A content-bearing response is
+a small frontmatter header (short id, title, version, format, section, size, url)
+followed by a blank line and the raw body — real newlines, greppable if a client
+spills it to a file. When a document is large, `read` (no `section`) returns its
+heading outline instead of the full text:
+
+```
+{ "sections": [
+    { "slug": "why-one-engine", "level": 2, "text": "Why: one engine", "chars": 2210 },
+    { "slug": "pr-6-the-fix",   "level": 2, "text": "PR-6: the fix",   "chars": 4812 }
+  ], "next": "Call read again with a section slug…" }
+```
+
+Pull just the part you need: `read(short_id, { section: "pr-6-the-fix" })`. Pass
+`section: "*"` to force the full (clipped) document when you genuinely need it all.
+
+## Edit, don't resend
+
+Once you've read a section, revise it with `publish`'s `edits` instead of
+resending the whole artifact:
+
+```
+publish(short_id, { edits: [{ old_str: "exact text from the source", new_str: "replacement" }] })
+```
+
+Each `old_str` must match **exactly once** in the current stored source — the
+same contract as a coding Edit tool. If it doesn't match (or matches more than
+once), nothing is applied and the error names which edit failed, so you add more
+surrounding context and retry. For an HTML artifact, read with `format:'html'`
+first — the Markdown view won't match raw source. Pass `base_version` (the
+version you read) to fail fast instead of silently editing a version you never saw.
+
+## Mockups & screens
+
+Reading Markdown by default doesn't flatten design work:
+
+- **See it rendered**: every `read` response's frontmatter carries the artifact's
+  `url` — open it in a real browser (or a browser-automation tool) to view or
+  screenshot the live page.
+- **See its structure/copy**: the default Markdown read.
+- **See a screenshot inline**: reading an image page of a bundle (`section:
+  "shot.png"`) returns a real image content block, not decoded bytes as text.
+- **Edit it**: `read(section, format:'html')` for the exact markup, then
+  `publish({ edits })` for a surgical change — a label, a color token — without
+  resending the whole design.
+
 ## Keep comments anchorable
 
 Anchors are text quotes with surrounding context, matched in the rendered
@@ -66,7 +114,18 @@ wrong place.
 
 - 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
+- Multi-page bundles are readable on both servers (`read` with a `section` — a page
+  path, or `page.html#slug` for one heading's part; `catch_up`) but revisable only
   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.
+  `@derive-to/mcp` server, bundles are publish-via-remote/web only, and `comment`
+  set_state takes a `comment_id`. `edits` (single-file only) works on both. Both
+  servers expose the same 5 tools.
+- An older self-hosted Derive server that predates `format`/`section`/`outline`
+  responds to `read` with a note that it returned the full raw artifact instead —
+  the stdio client detects this from a missing response header and degrades rather
+  than silently misreading a section.
+- The stdio server shares the machine's `derive login` — no token to paste. It acts as
+  your stored default account/workspace unless `DERIVE_ACCOUNT`/`DERIVE_WORKSPACE`
+  pin the project to a specific one (id or name; set in `.mcp.json`'s `env`). Still no
+  `whoami` tool, but a wrong pin fails loudly at startup rather than silently
+  targeting the wrong workspace.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@derive-to/mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Stdio MCP server for Derive — list, read, catch up on, comment on, and publish artifacts on a Derive instance.",
   "keywords": [
@@ -44,6 +44,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
+    "@derive-to/cli": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "tsx": "^4.19.0",
     "zod": "^4.4.3"

package/src/client.ts

@@ -1,14 +1,25 @@
 /** HTTP client for a Derive server. Shared by the MCP server and any tooling. */
 
+/** One exact-match search/replace edit (the Edit-tool contract). */
+export interface DocEdit {
+  old_str: string
+  new_str: string
+}
+
 export interface PublishArgs {
-  content: string | Uint8Array
-  filename: string
+  /** Full content for a fresh publish/republish. Omit when using `edits` instead. */
+  content?: string | Uint8Array
+  filename?: string
   title?: string
   slug?: string
   spa?: boolean
   message?: string
-  visibility?: "public" | "org" | "private"
-  /** A lock on a public link (optional). */
+  /** The v2 access triple for a NEW artifact (see access-model.md); ignored on a
+   *  republish. */
+  workspaceAccess?: "none" | "member"
+  linkRole?: "none" | "viewer" | "commenter" | "editor"
+  listed?: "none" | "workspace" | "public"
+  /** A lock on the world link (optional). */
   password?: string
   /** When set, publishes a new version of this artifact instead of a new one. */
   id?: string
@@ -16,6 +27,11 @@ export interface PublishArgs {
   resolves?: string[]
   /** Open a review round for this version (the /derive loop's ask). */
   requestReview?: boolean
+  /** Exact-match search/replace against the current stored source, INSTEAD of
+   *  `content` — revises without resending the whole artifact. Requires `id`. */
+  edits?: DocEdit[]
+  /** Safety check for `edits`: reject if the artifact moved past this version. */
+  baseVersion?: number
 }
 
 export type CommentState = "open" | "addressed" | "resolved" | "outdated"
@@ -39,16 +55,23 @@ export interface ArtifactSummaryJson {
   title: string | null
   kind: "file" | "bundle"
   current_version: number
-  visibility: string
+  workspace_access?: string
+  link_role?: string
+  listed?: string
 }
 
 /** A revision submitted for human review instead of published live. */
 export interface ProposeArgs {
-  content: string
+  /** Full content for the proposal. Omit when using `edits` instead. */
+  content?: string
   filename?: string
   message: string
   /** Thread ids this revision addresses (flip to `addressed`, resolve on approval). */
   addresses?: string[]
+  /** Exact-match search/replace against the current stored source, INSTEAD of
+   *  `content`. */
+  edits?: DocEdit[]
+  baseVersion?: number
 }
 export interface ProposalJson {
   id: string
@@ -85,7 +108,11 @@ export interface ArtifactJson {
   url: string
   title: string | null
   kind: "file" | "bundle"
-  visibility: string
+  /** The v2 access triple (see access-model.md); optional so an older server that
+   *  still returns `visibility` doesn't fail the type. */
+  workspace_access?: string
+  link_role?: string
+  listed?: string
   current_version: number
   versions: VersionJson[]
   /** Time-grouped version view (newest-first); present on the detail endpoint. */
@@ -123,6 +150,32 @@ export interface ViewStatsJson {
   recent: { viewer: string; kind: "user" | "anon"; at: string }[]
 }
 
+export interface ContentOpts {
+  version?: number
+  /** A heading slug (single-file) or page path (bundle, optionally page#slug). */
+  section?: string
+  format?: "markdown" | "text"
+}
+
+/** A content read: the body plus the server's X-Derive-* capability headers, so a
+ *  caller can tell an older self-hosted server (no headers at all) from a real
+ *  raw-format response and degrade gracefully instead of misreading intent. */
+export interface ContentResult {
+  text: string
+  /** Null when the server predates these params (no X-Derive-Format header). */
+  format: string | null
+  section: string | null
+  sectionCount: number | null
+  supportsParams: boolean
+}
+
+export interface OutlineSectionJson {
+  level: number
+  text: string
+  slug: string
+  chars: number
+}
+
 export interface DeriveClient {
   /** List the workspace's artifacts (optionally filtered by a title query). */
   list(query?: string): Promise<ArtifactSummaryJson[]>
@@ -130,13 +183,20 @@ export interface DeriveClient {
   /** 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>
+  getContent(shortId: string, opts?: ContentOpts): Promise<ContentResult>
+  /** The heading (single-file) or page (bundle) outline. Empty `sections` on an
+   *  older server that doesn't understand `?outline=1` (it 400s or ignores it). */
+  getOutline(
+    shortId: string,
+    version?: number,
+  ): Promise<{ sections: OutlineSectionJson[]; pages: { path: string; type?: string }[] | null }>
   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>
+  /** Line diff between two versions (defaults: current-1 → current). `content:
+   *  "markdown"` diffs the readable Markdown form instead of raw source. */
+  diff(shortId: string, from?: number, to?: number, content?: "raw" | "markdown"): Promise<DiffJson>
   /** The artifact's review rounds (newest first) + the pending one, if any. */
   getReview(
     shortId: string,
@@ -152,6 +212,11 @@ export interface DeriveClient {
 export interface ClientOptions {
   baseUrl: string
   token?: string
+  /** Which workspace `token` acts in for this request — the token itself already
+   *  reaches every workspace its owner belongs to; this just tells the server
+   *  which one. Omit to fall back to the grant's own default (unchanged
+   *  behavior for a plain static DERIVE_TOKEN). */
+  workspace?: string
   /** Override fetch (used in tests to target an in-process server). */
   fetchImpl?: typeof fetch
 }
@@ -159,9 +224,10 @@ export interface ClientOptions {
 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}` }
-    : {}
+  const authHeaders: Record<string, string> = {
+    ...(opts.token ? { Authorization: `Bearer ${opts.token}` } : {}),
+    ...(opts.workspace ? { "X-Derive-Workspace": opts.workspace } : {}),
+  }
 
   async function ok(res: Response): Promise<unknown> {
     if (res.ok) return res.json()
@@ -179,14 +245,24 @@ export function createClient(opts: ClientOptions): DeriveClient {
     },
 
     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.edits) {
+        // Surgical revision: no file upload, the server materializes it from the
+        // current stored source. Requires an existing artifact (args.id).
+        form.append("edits", JSON.stringify(args.edits))
+        if (args.baseVersion != null) form.append("base_version", String(args.baseVersion))
+        if (args.filename) form.append("filename", args.filename)
+      } else {
+        const bytes =
+          typeof args.content === "string" ? new TextEncoder().encode(args.content) : args.content
+        form.append("file", new Blob([bytes as BlobPart]), args.filename ?? "index.html")
+      }
       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.workspaceAccess) form.append("workspace_access", args.workspaceAccess)
+      if (args.linkRole) form.append("link_role", args.linkRole)
+      if (args.listed) form.append("listed", args.listed)
       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(","))
@@ -199,11 +275,16 @@ export function createClient(opts: ClientOptions): DeriveClient {
 
     async propose(shortId, args) {
       const form = new FormData()
-      form.append(
-        "file",
-        new Blob([new TextEncoder().encode(args.content)]),
-        args.filename ?? "index.html",
-      )
+      if (args.edits) {
+        form.append("edits", JSON.stringify(args.edits))
+        if (args.baseVersion != null) form.append("base_version", String(args.baseVersion))
+      } else {
+        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(
@@ -221,14 +302,44 @@ export function createClient(opts: ClientOptions): DeriveClient {
       ) as Promise<ArtifactJson>
     },
 
-    async getContent(shortId, version) {
-      const q = version ? `?v=${version}` : ""
-      const res = await f(`${base}/v1/artifacts/${shortId}/content${q}`, { headers: authHeaders })
+    async getContent(shortId, opts) {
+      const q = new URLSearchParams()
+      if (opts?.version) q.set("v", String(opts.version))
+      if (opts?.section) q.set("section", opts.section)
+      if (opts?.format) q.set("format", opts.format)
+      const qs = q.toString()
+      const res = await f(`${base}/v1/artifacts/${shortId}/content${qs ? `?${qs}` : ""}`, {
+        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()
+      const format = res.headers.get("x-derive-format")
+      return {
+        text: await res.text(),
+        format,
+        section: res.headers.get("x-derive-section"),
+        sectionCount: res.headers.has("x-derive-sections")
+          ? Number(res.headers.get("x-derive-sections"))
+          : null,
+        // No X-Derive-Format header at all = a server that predates these params
+        // (an older self-hosted instance) — the caller should treat this as raw
+        // whole-artifact content and not assume format/section were honored.
+        supportsParams: format !== null,
+      }
+    },
+
+    async getOutline(shortId, version) {
+      const q = new URLSearchParams({ outline: "1" })
+      if (version) q.set("v", String(version))
+      const res = await f(`${base}/v1/artifacts/${shortId}/content?${q}`, { headers: authHeaders })
+      if (!res.ok) return { sections: [], pages: null }
+      const body = (await res.json()) as {
+        sections?: OutlineSectionJson[]
+        pages?: { path: string; type?: string }[]
+      }
+      return { sections: body.sections ?? [], pages: body.pages ?? null }
     },
 
     async listComments(shortId, state) {
@@ -259,10 +370,11 @@ export function createClient(opts: ClientOptions): DeriveClient {
       )
     },
 
-    async diff(shortId, from, to) {
+    async diff(shortId, from, to, content) {
       const q = new URLSearchParams({ format: "json" })
       if (from != null) q.set("from", String(from))
       if (to != null) q.set("to", String(to))
+      if (content === "markdown") q.set("content", "markdown")
       return ok(
         await f(`${base}/v1/artifacts/${shortId}/diff?${q}`, { headers: authHeaders }),
       ) as Promise<DiffJson>

package/src/index.ts

@@ -1,21 +1,96 @@
 import { readFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
+import {
+  findAccountWorkspace,
+  freshToken,
+  getAccount,
+  getDefault,
+  listAccounts,
+  resolveAccountRef,
+  resolveWorkspaceRef,
+} from "@derive-to/cli/config"
 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.)
+// the /v1 HTTP API (DERIVE_SERVER). It exposes the SAME tools as the remote /mcp
+// server — list_workspaces, list_artifacts, read, catch_up, comment, publish — so the
+// vocabulary is identical whether an agent connects over OAuth or a static token.
+//
+// No token to paste: by default this reads the SAME local store `derive login`
+// writes (~/.config/derive/credentials.json), refreshing silently — sign in once
+// on the machine and every project's MCP server just works. DERIVE_ACCOUNT /
+// DERIVE_WORKSPACE pin which signed-in account/workspace THIS project acts as by
+// DEFAULT (id or name); unset, it falls back to your stored default. Because one
+// login reaches every workspace the account belongs to, any tool also takes a
+// per-call `workspace` argument (see list_workspaces) to act in another one without
+// changing that pin. DERIVE_TOKEN remains an escape hatch for a static bearer (CI,
+// no local login) — DERIVE_WORKSPACE has no effect there, since a static token
+// already acts as every workspace's owner.
+const server_ = process.env.DERIVE_SERVER ?? "http://localhost:8080"
 
-const client = createClient({
-  baseUrl: process.env.DERIVE_SERVER ?? "http://localhost:8080",
-  token: process.env.DERIVE_TOKEN,
-})
+/** {token, workspace} for the client below — see the module doc comment for the
+ *  precedence. Kept out of `createClient` itself so a resolution failure fails
+ *  loudly at startup (a clear thrown message) instead of quietly targeting the
+ *  wrong workspace, or surfacing as an unexplained 401 mid-session. Not signed
+ *  in at all (no env override, nothing saved) degrades gracefully to anonymous,
+ *  same as today's unset DERIVE_TOKEN — only an env var naming something that
+ *  doesn't exist is an error. */
+async function resolveAuth(): Promise<{
+  token?: string
+  workspace?: string
+  accountId?: string
+}> {
+  if (process.env.DERIVE_TOKEN) return { token: process.env.DERIVE_TOKEN }
+
+  const accountEnv = process.env.DERIVE_ACCOUNT
+  const workspaceEnv = process.env.DERIVE_WORKSPACE
+  let accountId: string | null
+  let workspace: string | undefined
+
+  if (accountEnv) {
+    accountId = resolveAccountRef(server_, accountEnv)
+    if (!accountId)
+      throw new Error(
+        `DERIVE_ACCOUNT "${accountEnv}" isn't signed in on this machine — run \`derive login\`.`,
+      )
+    if (workspaceEnv) {
+      const found = findAccountWorkspace(server_, accountId, workspaceEnv)
+      if (!found)
+        throw new Error(
+          `DERIVE_WORKSPACE "${workspaceEnv}" isn't one of that account's workspaces — run \`derive workspaces --account ${accountEnv}\`.`,
+        )
+      workspace = found.id
+    } else {
+      workspace = getAccount(server_, accountId)?.defaultWorkspace ?? undefined
+    }
+  } else if (workspaceEnv) {
+    const resolved = resolveWorkspaceRef(server_, workspaceEnv)
+    if (!resolved)
+      throw new Error(
+        `DERIVE_WORKSPACE "${workspaceEnv}" isn't a workspace on any signed-in account.`,
+      )
+    if ("ambiguous" in resolved)
+      throw new Error(
+        `DERIVE_WORKSPACE "${workspaceEnv}" matches workspaces under more than one account — set DERIVE_ACCOUNT too.`,
+      )
+    accountId = resolved.accountId
+    workspace = resolved.workspaceId
+  } else {
+    const def = getDefault(server_)
+    accountId = def?.account ?? null
+    workspace = def?.workspace ?? undefined
+  }
+
+  if (!accountId) return {}
+  const token = (await freshToken(server_, accountId)) ?? undefined
+  return { token, workspace, accountId }
+}
+
+const { token, workspace, accountId } = await resolveAuth()
+const client = createClient({ baseUrl: server_, token, workspace })
 
 // The agent guide, served as an MCP resource (single source: SKILL.md).
 const GUIDE = (() => {
@@ -30,17 +105,94 @@ 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))
+const err = (s: string) => ({
+  content: [{ type: "text" as const, text: s }],
+  isError: true as const,
+})
+
+// A content-bearing response: a frontmatter-style header, a blank line, then the
+// RAW body — never JSON-escaped (parity with the remote server's envelope).
+const doc = (meta: Record<string, string | number | null | undefined>, body: string) => {
+  const head = Object.entries(meta)
+    .filter(([, v]) => v !== undefined && v !== null)
+    .map(([k, v]) => `${k}: ${v}`)
+    .join("\n")
+  return text(`---\n${head}\n---\n\n${body}`)
+}
+
+// A `workspace` arg (id or name) on any tool acts in THAT workspace for the one
+// call, without re-pinning the session: the token already reaches every workspace
+// the account belongs to, so we just build a throwaway client that sends the
+// matching X-Derive-Workspace header. Names resolve against the active account's
+// local roster; an unrecognized ref is passed through as a literal id (a static
+// DERIVE_TOKEN caller has no roster to match names against). Omit → the session's
+// resolved default client.
+const resolveWsId = (ref: string): string => {
+  if (accountId) {
+    const found = findAccountWorkspace(server_, accountId, ref)
+    if (found) return found.id
+  }
+  return ref
+}
+const clientFor = (ref?: string) =>
+  ref ? createClient({ baseUrl: server_, token, workspace: resolveWsId(ref) }) : client
+const wsArg = z
+  .string()
+  .optional()
+  .describe(
+    "Workspace to act in — its id or name from list_workspaces. Omit to use this session's default workspace.",
+  )
+
+// The signed-in roster on THIS machine (shared by the list_workspaces tool and the
+// derive://workspaces resource) — read fresh so a sibling `derive login`/`describe`
+// shows up mid-session.
+const buildRoster = () => {
+  const accounts = listAccounts(server_).map((a) => {
+    const account = getAccount(server_, a.id)
+    return {
+      account_id: a.id,
+      handle: a.handle,
+      is_default_account: a.isDefault,
+      workspaces: Object.entries(account?.workspaces ?? {}).map(([id, w]) => ({
+        workspace_id: id,
+        name: w.name,
+        role: w.role,
+        description: w.description ?? null,
+        is_default_workspace: id === account?.defaultWorkspace,
+        is_active: id === workspace,
+      })),
+    }
+  })
+  const active = accountId
+    ? { server: server_, account_id: accountId, workspace_id: workspace ?? null }
+    : { server: server_, note: "No signed-in account resolved for this session." }
+  return { active, accounts }
+}
+
+// WORKSPACES — the switcher: every workspace signed in on this machine ---------
+server.registerTool(
+  "list_workspaces",
+  {
+    description:
+      "List every workspace signed in on this machine you can act in — id, name, your role, local description, and which is active. One login reaches them all; pass a workspace's id or name as the `workspace` argument to list_artifacts / read / catch_up / comment / publish to act there for that call.",
+    inputSchema: {},
+  },
+  async () => json(buildRoster()),
+)
 
 // 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.") },
+      "List the artifacts in your workspace — short id, title, kind, current version, access. Defaults to this session's workspace; pass `workspace` (id or name from list_workspaces) to list another. Start here to find what to work on, then catch_up or read it.",
+    inputSchema: {
+      query: z.string().optional().describe("Optional title search filter."),
+      workspace: wsArg,
+    },
   },
-  async ({ query }) => {
-    const arts = await client.list(query)
+  async ({ query, workspace: ws }) => {
+    const arts = await clientFor(ws).list(query)
     return json({ count: arts.length, artifacts: arts })
   },
 )
@@ -50,17 +202,74 @@ 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.",
+      "Read an artifact's CONTENT by short id, as Markdown by default (HTML is converted). Omit `section` to see the outline first (heading slugs for a single-file doc, page paths for a bundle) — call again with a `section` (or \"*\" for the full document) once you know what you want. Pass `format:'html'` for the exact source (needed before publish `edits`), or a past `version` for history. For what CHANGED or the comment threads, use catch_up instead. (Older self-hosted servers that predate these params return the whole artifact regardless of section/format — noted in the response when that happens.)",
     inputSchema: {
       short_id: z.string(),
+      section: z
+        .string()
+        .optional()
+        .describe(
+          'A heading slug (single-file) or page path (bundle, optionally page#slug). Pass "*" for the full document.',
+        ),
+      format: z
+        .enum(["markdown", "text"])
+        .optional()
+        .describe("markdown (default, HTML converted) or text (flat visible text)."),
       version: z.number().int().optional().describe("Defaults to the current version."),
+      workspace: wsArg,
     },
   },
-  async ({ short_id, version }) => {
+  async ({ short_id, section, format, version, workspace: ws }) => {
+    const client = clientFor(ws)
     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 })
+
+    // No section: show the outline first (mirrors the remote server's
+    // outline-before-blind-dump behavior). Falls back to full content when the
+    // artifact has no headings/pages, or the server predates `?outline=1`.
+    if (!section) {
+      const outline = await client.getOutline(short_id, version)
+      if (outline.sections.length || outline.pages) {
+        return json({
+          short_id,
+          title: a.title,
+          kind: a.kind,
+          version: v,
+          ...(outline.sections.length ? { sections: outline.sections } : {}),
+          ...(outline.pages ? { pages: outline.pages } : {}),
+          next:
+            outline.sections.length || outline.pages?.length
+              ? 'Call read again with a `section` (a slug/page above), or section:"*" for the full document.'
+              : undefined,
+        })
+      }
+    }
+
+    try {
+      const result = await client.getContent(short_id, {
+        version,
+        section,
+        format: format ?? "markdown",
+      })
+      if (!result.supportsParams)
+        return doc(
+          { short_id, title: a.title, kind: a.kind, version: v },
+          `${result.text}\n\n[note: this server predates section/format params — returning the full raw artifact.]`,
+        )
+      return doc(
+        {
+          short_id,
+          title: a.title,
+          kind: a.kind,
+          version: v,
+          ...(result.format ? { format: result.format } : {}),
+          ...(result.section ? { section: result.section } : {}),
+        },
+        result.text,
+      )
+    } catch (e) {
+      return err(e instanceof Error ? e.message : "read failed")
+    }
   },
 )
 
@@ -71,7 +280,7 @@ server.registerTool(
     description:
       "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 a line diff between two versions — of their readable Markdown form, not raw HTML. " +
       "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(),
@@ -104,9 +313,19 @@ server.registerTool(
         .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.",
         ),
+      workspace: wsArg,
     },
   },
-  async ({ short_id, since_version, to_version, comments, response_format, wait }) => {
+  async ({
+    short_id,
+    since_version,
+    to_version,
+    comments,
+    response_format,
+    wait,
+    workspace: ws,
+  }) => {
+    const client = clientFor(ws)
     const summarizeComment = (c: {
       thread_id: string
       author: string
@@ -198,7 +417,9 @@ server.registerTool(
       : ""
     let entryDiff: string | undefined
     if (response_format === "detailed" && since < to) {
-      const d = await client.diff(short_id, since, to)
+      // Diff the readable Markdown form, not raw HTML — kills tag noise and
+      // avoids a minified one-line document producing one useless del/add pair.
+      const d = await client.diff(short_id, since, to, "markdown")
       entryDiff = d.ops
         .map((o) => `${o.t === "add" ? "+" : o.t === "del" ? "-" : " "} ${o.line}`)
         .join("\n")
@@ -256,9 +477,11 @@ server.registerTool(
         .string()
         .optional()
         .describe("A comment in the thread to react to / set_state on (when not posting)."),
+      workspace: wsArg,
     },
   },
-  async ({ short_id, body, reply_to, quote, react, set_state, comment_id }) => {
+  async ({ short_id, body, reply_to, quote, react, set_state, comment_id, workspace: ws }) => {
+    const client = clientFor(ws)
     if (!body && !set_state && !react)
       return text(
         "Provide `body` (to comment), `react` (to acknowledge), or `set_state` (to resolve/reopen).",
@@ -327,9 +550,33 @@ 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.)",
+      "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). To CHANGE PART of an existing artifact, prefer `edits` (exact-match search/replace against the stored source — read format:'html' first) over resending everything via `content`. 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)."),
+      content: z
+        .string()
+        .optional()
+        .describe("The artifact's full text content (HTML or Markdown). Use this OR `edits`."),
+      edits: z
+        .array(
+          z.object({
+            old_str: z
+              .string()
+              .describe(
+                "Exact text from the STORED SOURCE (read format:'html' first on an HTML artifact). Must occur exactly once.",
+              ),
+            new_str: z.string().describe("Replacement text. Empty string deletes."),
+          }),
+        )
+        .optional()
+        .describe(
+          "Surgical revision without resending the artifact: exact-match search/replace against the current stored source, applied in order. Errors (applying nothing) if any old_str matches zero or multiple times. Requires `short_id`; use INSTEAD of `content`.",
+        ),
+      base_version: z
+        .number()
+        .optional()
+        .describe(
+          "Safety check for `edits`: pass the version you read; errors instead of applying if the artifact moved past it.",
+        ),
       filename: z
         .string()
         .optional()
@@ -339,9 +586,12 @@ server.registerTool(
         .optional()
         .describe("Omit to create a new artifact; pass it to add a version."),
       title: z.string().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(),
+      // The v2 access triple for a NEW artifact (see access-model.md); omit any to
+      // take the workspace default (the team draft — the human you act for owns it
+      // and promotes it when ready). Ignored on a republish.
+      workspace_access: z.enum(["none", "member"]).optional(),
+      link_role: z.enum(["none", "viewer", "commenter", "editor"]).optional(),
+      listed: z.enum(["none", "workspace", "public"]).optional(),
       message: z.string().optional().describe("What changed in this version."),
       for_review: z
         .boolean()
@@ -357,45 +607,69 @@ server.registerTool(
         .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.",
         ),
+      workspace: wsArg,
     },
   },
   async ({
     content,
+    edits,
+    base_version,
     filename,
     short_id,
     title,
-    visibility,
+    workspace_access,
+    link_role,
+    listed,
     message,
     for_review,
     addresses,
     request_review,
+    workspace: ws,
   }) => {
+    const client = clientFor(ws)
+    if (content !== undefined && edits) return text("Provide `content` OR `edits`, not both.")
     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, {
+      try {
+        const p = await client.propose(short_id, {
+          content,
+          edits,
+          baseVersion: base_version,
+          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}.`,
+        })
+      } catch (e) {
+        return err(e instanceof Error ? e.message : "propose failed")
+      }
+    }
+    if (edits && !short_id) return text("`edits` revises an EXISTING artifact — pass its short_id.")
+    let a: Awaited<ReturnType<typeof client.publish>>
+    try {
+      a = await client.publish({
+        id: 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}.`,
+        edits,
+        baseVersion: base_version,
+        filename: filename ?? (edits ? undefined : "index.html"),
+        title,
+        workspaceAccess: workspace_access,
+        linkRole: link_role,
+        listed,
+        message,
+        resolves: addresses,
+        requestReview: request_review,
       })
+    } catch (e) {
+      return err(e instanceof Error ? e.message : "publish failed")
     }
-    const a = await client.publish({
-      id: short_id,
-      content,
-      filename: filename ?? "index.html",
-      title,
-      visibility,
-      message,
-      resolves: addresses,
-      requestReview: request_review,
-    })
     const note = addresses?.length ? ` · resolved ${addresses.length} thread(s)` : ""
     const openNote =
       a.opened_in_tab === false
@@ -408,7 +682,8 @@ server.registerTool(
       version: a.current_version,
       url: a.url,
       title: a.title,
-      visibility: a.visibility,
+      listed: a.listed,
+      link_role: a.link_role,
       ...(a.opened_in_tab !== undefined ? { opened_in_tab: a.opened_in_tab } : {}),
       note:
         (short_id ? `Live — new version${note}.` : `Live — created "${a.title}"${note}.`) +
@@ -429,4 +704,35 @@ server.registerResource(
   async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: GUIDE }] }),
 )
 
+// Every account/workspace signed in on THIS machine, with the local `description`
+// each was given via `derive workspace describe` — the context a bare name can't
+// carry. This tool's OWN live calls only ever act as `active` below (fixed at
+// startup by DERIVE_ACCOUNT/DERIVE_WORKSPACE or the stored default); the rest of
+// the roster is visibility only, for deciding whether that pin is still the right
+// one — e.g. before proposing a change to a project's .mcp.json. Read fresh (not
+// cached at startup) since `derive workspace describe` can run in a sibling
+// terminal mid-session.
+server.registerResource(
+  "derive-workspaces",
+  "derive://workspaces",
+  {
+    title: "Signed-in accounts & workspaces",
+    description:
+      "Every account and workspace signed in on this machine, each with its local `description` " +
+      "(what it's FOR, set via `derive workspace describe`) if one has been set. `active` is the " +
+      "one this session's tools actually publish to — read this before assuming a bare workspace " +
+      "name is enough context, or before touching a project's DERIVE_ACCOUNT/DERIVE_WORKSPACE pin.",
+    mimeType: "application/json",
+  },
+  async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(buildRoster(), null, 2),
+      },
+    ],
+  }),
+)
+
 await server.connect(new StdioServerTransport())