@derive-to/mcp 0.4.0 → 0.5.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

@@ -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.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Stdio MCP server for Derive — list, read, catch up on, comment on, and publish artifacts on a Derive instance.",
   "keywords": [
@@ -37,25 +37,27 @@
     ".": "./src/index.ts",
     "./client": "./src/client.ts"
   },
-  "scripts": {
-    "start": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
-  },
   "dependencies": {
-    "@derive-to/cli": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "tsx": "^4.19.0",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@derive-to/cli": "0.4.0"
   },
   "devDependencies": {
-    "@derive/api": "workspace:*",
-    "@derive/db": "workspace:*",
-    "@derive/storage": "workspace:*",
     "@hono/node-server": "^2.0.5",
     "@types/node": "^25.9.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.9",
+    "@derive/core": "0.1.0",
+    "@derive/db": "0.1.0",
+    "@derive/storage": "0.1.0",
+    "@derive/api": "0.1.0"
+  },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "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). */
@@ -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,
@@ -550,12 +552,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 +622,7 @@ server.registerTool(
   },
   async ({
     content,
+    content_path,
     edits,
     base_version,
     filename,
@@ -627,15 +638,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 +682,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 +699,30 @@ 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 } : {}),
+      ...(pathSha && echoedSha ? { content_verified: true } : {}),
       version: a.current_version,
       url: a.url,
       title: a.title,
@@ -687,7 +731,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,
     })
   },
 )