@derive-to/mcp 0.4.1 → 0.5.1

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, 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. |
+| `read` | Read an artifact's content by short id, as **Markdown by default** (HTML is converted — headings, lists, tables, code fences; a styled page still renders fully to viewers, only this reading view flattens it). 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, 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. |
+| `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. Fully-styled HTML renders as-authored in the sandboxed viewer: declare your own `<meta name="viewport">` (skips the mobile-reflow injection; `data-reflow-exempt` exempts a single element), upload images/woff2 fonts to `POST /v1/assets` instead of inlining base64, and check the echoed `content_sha256` against your local bytes. |
 
 ## Role decides: live publish vs proposal
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@derive-to/mcp",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "type": "module",
   "description": "Stdio MCP server for Derive — list, read, catch up on, comment on, and publish artifacts on a Derive instance.",
   "keywords": [
@@ -41,20 +41,22 @@
     "@modelcontextprotocol/sdk": "^1.12.0",
     "tsx": "^4.19.0",
     "zod": "^4.4.3",
-    "@derive-to/cli": "0.3.0"
+    "@derive-to/cli": "0.4.0"
   },
   "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/core": "0.1.0",
     "@derive/db": "0.1.0",
-    "@derive/storage": "0.1.0",
-    "@derive/api": "0.1.0"
+    "@derive/storage": "0.1.0"
   },
   "scripts": {
     "start": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
+    "typecheck:tsc": "tsc --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage"
   }

package/src/client.ts

@@ -1,5 +1,8 @@
 /** HTTP client for a Derive server. Shared by the MCP server and any tooling. */
 
+import type { LinkRole, Listed, WorkspaceAccess } from "@derive/core"
+import { buildPublishForm } from "@derive-to/cli/publish"
+
 /** One exact-match search/replace edit (the Edit-tool contract). */
 export interface DocEdit {
   old_str: string
@@ -16,9 +19,9 @@ export interface PublishArgs {
   message?: string
   /** 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"
+  workspaceAccess?: WorkspaceAccess
+  linkRole?: LinkRole
+  listed?: Listed
   /** A lock on the world link (optional). */
   password?: string
   /** When set, publishes a new version of this artifact instead of a new one. */
@@ -63,7 +66,7 @@ export interface ArtifactSummaryJson {
 /** A revision submitted for human review instead of published live. */
 export interface ProposeArgs {
   /** Full content for the proposal. Omit when using `edits` instead. */
-  content?: string
+  content?: string | Uint8Array
   filename?: string
   message: string
   /** Thread ids this revision addresses (flip to `addressed`, resolve on approval). */
@@ -154,7 +157,7 @@ export interface ContentOpts {
   version?: number
   /** A heading slug (single-file) or page path (bundle, optionally page#slug). */
   section?: string
-  format?: "markdown" | "text"
+  format?: "markdown" | "text" | "html"
 }
 
 /** A content read: the body plus the server's X-Derive-* capability headers, so a
@@ -245,28 +248,29 @@ export function createClient(opts: ClientOptions): DeriveClient {
     },
 
     async publish(args) {
-      const form = new FormData()
-      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.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(","))
-      if (args.requestReview) form.append("request_review", "true")
+      // Surgical revision (args.edits) needs no file upload — the server materializes
+      // it from the current stored source (requires an existing artifact, args.id).
+      const bytes = args.edits
+        ? undefined
+        : typeof args.content === "string"
+          ? new TextEncoder().encode(args.content)
+          : args.content
+      const form = buildPublishForm({
+        bytes: bytes as Uint8Array | undefined,
+        filename: args.filename,
+        edits: args.edits,
+        baseVersion: args.baseVersion,
+        title: args.title,
+        slug: args.slug,
+        spa: args.spa,
+        message: args.message,
+        workspaceAccess: args.workspaceAccess,
+        linkRole: args.linkRole,
+        listed: args.listed,
+        password: args.password,
+        resolves: args.resolves,
+        requestReview: args.requestReview,
+      })
       const url = args.id ? `${base}/v1/artifacts/${args.id}/versions` : `${base}/v1/artifacts`
       return ok(
         await f(url, { method: "POST", body: form, headers: authHeaders }),
@@ -279,11 +283,11 @@ export function createClient(opts: ClientOptions): DeriveClient {
         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",
-        )
+        const bytes =
+          typeof args.content === "string" || args.content === undefined
+            ? new TextEncoder().encode(args.content ?? "")
+            : args.content
+        form.append("file", new Blob([bytes as BlobPart]), args.filename ?? "index.html")
       }
       form.append("message", args.message)
       if (args.addresses?.length) form.append("addresses", args.addresses.join(","))

package/src/index.ts

@@ -1,4 +1,6 @@
+import { createHash } from "node:crypto"
 import { readFileSync } from "node:fs"
+import { basename } from "node:path"
 import { fileURLToPath } from "node:url"
 import {
   findAccountWorkspace,
@@ -212,9 +214,11 @@ server.registerTool(
           'A heading slug (single-file) or page path (bundle, optionally page#slug). Pass "*" for the full document.',
         ),
       format: z
-        .enum(["markdown", "text"])
+        .enum(["markdown", "text", "html"])
         .optional()
-        .describe("markdown (default, HTML converted) or text (flat visible text)."),
+        .describe(
+          "markdown (default, HTML converted), text (flat visible text), or html (the exact stored source — read it before revising with publish `edits`).",
+        ),
       version: z.number().int().optional().describe("Defaults to the current version."),
       workspace: wsArg,
     },
@@ -550,12 +554,20 @@ 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). 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.)",
+      "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). Provide the body as `content_path` (a local file this server reads and uploads — preferred, zero tokens) or `content` (inline text). To CHANGE PART of an existing artifact, prefer `edits` (exact-match search/replace against the stored source — read format:'html' first) over resending everything. 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.) FULLY-STYLED HTML renders as-authored (own <style>/scripts/fonts) in the sandboxed viewer — declare your own <meta name=\"viewport\"> to skip the mobile-reflow injection, and self-host binaries via POST /v1/assets (images and woff2 fonts) instead of inlining base64.",
     inputSchema: {
       content: z
         .string()
         .optional()
-        .describe("The artifact's full text content (HTML or Markdown). Use this OR `edits`."),
+        .describe(
+          "The artifact's full text content (HTML or Markdown). Use this OR `content_path` OR `edits`. For images or web fonts, upload the raw bytes to POST /v1/assets (no base64 — binaries carried through a tool call can be silently mistranscribed) and reference the returned URL.",
+        ),
+      content_path: z
+        .string()
+        .optional()
+        .describe(
+          "PREFERRED over `content` when the artifact exists as a local file: an absolute path this server reads and uploads as raw bytes — the content never rides through your context (no token cost, no transcription risk), and the stored bytes are verified against the file's sha256 automatically. Build and iterate on the file locally, then publish it by path. Filename defaults to the file's basename.",
+        ),
       edits: z
         .array(
           z.object({
@@ -612,6 +624,7 @@ server.registerTool(
   },
   async ({
     content,
+    content_path,
     edits,
     base_version,
     filename,
@@ -627,15 +640,31 @@ server.registerTool(
     workspace: ws,
   }) => {
     const client = clientFor(ws)
-    if (content !== undefined && edits) return text("Provide `content` OR `edits`, not both.")
+    if ([content, content_path, edits].filter((v) => v !== undefined).length > 1)
+      return text("Provide exactly one of `content`, `content_path`, or `edits`.")
+    // content_path: this server runs on the caller's machine, so it reads the file
+    // itself and uploads the bytes — the content never passes through the model. The
+    // local file's sha256 is checked against the response's content_sha256 echo below.
+    let pathBytes: Uint8Array | undefined
+    let pathSha: string | undefined
+    if (content_path !== undefined) {
+      try {
+        pathBytes = new Uint8Array(readFileSync(content_path))
+      } catch (e) {
+        return err(
+          `could not read content_path "${content_path}": ${e instanceof Error ? e.message : "unknown error"}`,
+        )
+      }
+      pathSha = createHash("sha256").update(pathBytes).digest("hex")
+    }
     if (for_review) {
       if (!short_id) return text("A proposal revises an EXISTING artifact — pass its short_id.")
       try {
         const p = await client.propose(short_id, {
-          content,
+          content: pathBytes ?? content,
           edits,
           baseVersion: base_version,
-          filename,
+          filename: filename ?? (content_path !== undefined ? basename(content_path) : undefined),
           message: message ?? "Proposed revision",
           addresses,
         })
@@ -655,10 +684,12 @@ server.registerTool(
     try {
       a = await client.publish({
         id: short_id,
-        content,
+        content: pathBytes ?? content,
         edits,
         baseVersion: base_version,
-        filename: filename ?? (edits ? undefined : "index.html"),
+        filename:
+          filename ??
+          (content_path !== undefined ? basename(content_path) : edits ? undefined : "index.html"),
         title,
         workspaceAccess: workspace_access,
         linkRole: link_role,
@@ -670,15 +701,31 @@ server.registerTool(
     } catch (e) {
       return err(e instanceof Error ? e.message : "publish failed")
     }
+    // The server echoes the sha256 of the stored bytes; for a by-path publish it
+    // must match the local file exactly.
+    const echoedSha = (a as { content_sha256?: string }).content_sha256
+    if (pathSha && echoedSha && echoedSha !== pathSha)
+      return err(
+        `content integrity mismatch: local file sha256 ${pathSha} but the server stored ${echoedSha} — the upload was corrupted; retry the publish.`,
+      )
     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."
         : ""
+    // Advisories (missing viewport, oversized inline base64) are computed server-side
+    // and carried on the REST response; this shim is an HTTP client with no @derive/core
+    // at runtime, so it only relays them.
+    const advisories = (a as { advisories?: string[] }).advisories
+    const advisoryNote = advisories?.length
+      ? advisories.map((advisory) => ` ${advisory}`).join("")
+      : ""
     return json({
       published: true,
       short_id: a.short_id,
       ...(a.review_requested ? { review_requested: true } : {}),
+      ...(echoedSha ? { content_sha256: echoedSha } : {}),
+      ...(pathSha && echoedSha ? { content_verified: true } : {}),
       version: a.current_version,
       url: a.url,
       title: a.title,
@@ -687,7 +734,8 @@ server.registerTool(
       ...(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,
+        openNote +
+        advisoryNote,
     })
   },
 )