@derive-to/mcp 0.5.0 → 0.6.0

package/src/client.ts

@@ -17,6 +17,9 @@ export interface PublishArgs {
   slug?: string
   spa?: boolean
   message?: string
+  /** Browse tags to set on the artifact at publish time. Given ⇒ replaces the set;
+   *  omitted ⇒ leaves existing tags untouched on a republish. */
+  tags?: string[]
   /** The v2 access triple for a NEW artifact (see access-model.md); ignored on a
    *  republish. */
   workspaceAccess?: WorkspaceAccess
@@ -61,27 +64,36 @@ export interface ArtifactSummaryJson {
   workspace_access?: string
   link_role?: string
   listed?: string
+  /** Browse tags on the artifact — present when the server returns them (newer servers). */
+  tags?: string[]
+  current_content_type?: string | null
+  is_linked_bundle?: boolean
 }
 
-/** 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 | Uint8Array
-  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 TagCountJson {
+  tag: string
+  count: number
+}
+export interface TagSuggestionsJson {
+  current: string[]
+  suggested: TagCountJson[]
+  vocabulary: TagCountJson[]
 }
-export interface ProposalJson {
+/** The result of adding/removing/replacing tags across one or many artifacts. */
+export interface TagResultJson {
+  updated: number
+  skipped: number
+  failed: number
+  results: { short_id: string; tags: string[] }[]
+}
+export interface CollectionSummaryJson {
   id: string
-  base_version: number
-  addressed?: string[]
+  title: string
+  count: number
 }
 
+/** A revision submitted for human review instead of published live. */
+
 export interface NewCommentArgs {
   body_md: string
   thread_id?: string
@@ -89,6 +101,7 @@ export interface NewCommentArgs {
   base_version?: number
   path?: string
   anchor?: unknown
+  visual_target?: string
 }
 
 export interface VersionJson {
@@ -118,17 +131,34 @@ export interface ArtifactJson {
   listed?: string
   current_version: number
   versions: VersionJson[]
+  /** Browse tags — present on the detail endpoint (newer servers). */
+  tags?: string[]
+  /** Collection ids this artifact belongs to — present on the detail endpoint. */
+  collections?: string[]
   /** Time-grouped version view (newest-first); present on the detail endpoint. */
   sessions?: SessionJson[]
   /** Publish-response extras (agent-credentialed publishes only). */
   review_requested?: boolean
   opened_in_tab?: boolean
+  linked_bundle?: {
+    schema: "derive.linked-bundle/v1"
+    purpose: string
+    members: {
+      id: string
+      ref: string
+      label: string
+      role?: string
+      note?: string
+      available: boolean
+    }[]
+    diagrams?: { id: string; title: string; type: "loop" | "graph" }[]
+  }
 }
 
 /** One review round: the human-ack primitive of the /derive loop. */
 export interface ReviewRoundJson {
   id: string
-  state: "pending" | "sent_back" | "approved"
+  state: "pending" | "sent_back"
   version: number
   note: string | null
   created_at: string
@@ -147,17 +177,55 @@ export interface DiffJson {
 
 export interface ViewStatsJson {
   total: number
+  last24h: number
   unique: number
   perVersion: { version: number; count: number }[]
   daily: { day: string; count: number }[]
   recent: { viewer: string; kind: "user" | "anon"; at: string }[]
 }
 
+/** A library is an access-scoped catalog of immutable template starters. */
+export interface TemplateLibraryEntryJson {
+  id: string
+  library_id: string
+  source_version: number
+  kind: "artifact" | "context"
+  category: string
+  format: "md" | "html"
+  title: string
+  description: string
+  outcome: string
+  sections: string[]
+  inputs: { name: string; description: string; required?: boolean }[]
+  tags: string[]
+  created_at: string
+}
+export interface TemplateLibraryJson {
+  id: string
+  title: string
+  description: string
+  scope: "private" | "workspace" | "public"
+  created_at: string
+  updated_at: string | null
+  entry_count: number
+  entries?: TemplateLibraryEntryJson[]
+}
+export interface TemplateLibraryPageJson {
+  libraries: TemplateLibraryJson[]
+  truncated: boolean
+  next_cursor: string | null
+}
+export interface TemplateStarterJson {
+  entry: TemplateLibraryEntryJson
+  source: string
+  mime_type: string
+}
+
 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
@@ -179,14 +247,48 @@ export interface OutlineSectionJson {
   chars: number
 }
 
+export interface SearchOpts {
+  caseSensitive?: boolean
+  /** source (default): the exact stored bytes. text: the visible text (tags stripped). */
+  in?: "source" | "text"
+  /** Lines of surrounding context per match (default 0, max 5, server-clamped). */
+  context?: number
+  /** Cap on matches returned per artifact (default 40, max 200, server-clamped). */
+  maxMatches?: number
+  /** Single-artifact search only; ignored in workspace-wide mode. */
+  version?: number
+}
+
 export interface DeriveClient {
-  /** List the workspace's artifacts (optionally filtered by a title query). */
-  list(query?: string): Promise<ArtifactSummaryJson[]>
+  /** List the workspace's artifacts (optionally filtered by a title query and/or a browse tag). */
+  list(query?: string, tag?: string, archived?: boolean): Promise<ArtifactSummaryJson[]>
+  /** Move an artifact onto or off the reversible archive shelf. */
+  archive(shortId: string, archived: boolean): Promise<{ archived: boolean }>
+  /** The workspace tag vocabulary (tag → count, most-used first). */
+  listTags(): Promise<TagCountJson[]>
+  /** Suggest tags for an artifact: its current tags, neighbors' tags, and the vocabulary. */
+  suggestTags(shortId: string): Promise<TagSuggestionsJson>
+  /** Add/remove/replace browse tags across one or more artifacts. `set` replaces the
+   *  whole set (overriding add/remove); otherwise add then remove. */
+  tag(
+    shortIds: string[],
+    ops: { add?: string[]; remove?: string[]; set?: string[] },
+  ): Promise<TagResultJson>
+  /** The workspace's team-visible collections with item counts. */
+  listCollections(): Promise<CollectionSummaryJson[]>
+  /** Add artifacts to a collection identified by id OR name (created if a new name). */
+  collect(
+    shortIds: string[],
+    ref: string,
+  ): Promise<{ collection: { id: string; title: string }; added: number; skipped: number }>
   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, opts?: ContentOpts): Promise<ContentResult>
+  /** Grep WITHIN one artifact (shortId set) or ACROSS the workspace (shortId
+   *  omitted) — the same engine and ripgrep-style text report the remote MCP
+   *  `search` tool returns, relayed here verbatim. */
+  search(shortId: string | undefined, query: string, opts?: SearchOpts): Promise<string>
   /** 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(
@@ -210,6 +312,10 @@ export interface DeriveClient {
   restore(shortId: string, version: number): Promise<ArtifactJson>
   /** Aggregated view analytics. */
   viewStats(shortId: string): Promise<ViewStatsJson>
+  /** Accessible public + workspace + personal libraries, for MCP resources only. */
+  listTemplateLibraries(cursor?: string): Promise<TemplateLibraryPageJson>
+  getTemplateLibrary(id: string): Promise<TemplateLibraryJson>
+  getTemplateStarter(libraryId: string, entryId: string): Promise<TemplateStarterJson>
 }
 
 export interface ClientOptions {
@@ -239,12 +345,151 @@ export function createClient(opts: ClientOptions): DeriveClient {
   }
 
   return {
-    async list(query) {
-      const q = query ? `?query=${encodeURIComponent(query)}` : ""
+    async list(query, tag, archived) {
+      const qs = new URLSearchParams()
+      if (query) qs.set("query", query)
+      if (tag) qs.set("tag", tag.trim().toLowerCase())
+      if (archived) qs.set("scope", "archived")
+      const q = qs.toString() ? `?${qs}` : ""
       const r = (await ok(await f(`${base}/v1/artifacts${q}`, { headers: authHeaders }))) as {
         artifacts: ArtifactSummaryJson[]
       }
-      return r.artifacts
+      return r.artifacts.map((artifact) => ({
+        ...artifact,
+        is_linked_bundle: artifact.current_content_type === "text/x-derive-linked-bundle",
+      }))
+    },
+
+    async archive(shortId, archived) {
+      return ok(
+        await f(`${base}/v1/artifacts/${shortId}/archive`, {
+          method: archived ? "PUT" : "DELETE",
+          headers: authHeaders,
+        }),
+      ) as Promise<{ archived: boolean }>
+    },
+
+    async listTags() {
+      const r = (await ok(await f(`${base}/v1/tags`, { headers: authHeaders }))) as {
+        tags: TagCountJson[]
+      }
+      return (r.tags ?? []).slice().sort((a, b) => b.count - a.count || a.tag.localeCompare(b.tag))
+    },
+
+    async suggestTags(shortId) {
+      return ok(
+        await f(`${base}/v1/artifacts/${shortId}/tag-suggestions`, { headers: authHeaders }),
+      ) as Promise<TagSuggestionsJson>
+    },
+
+    async tag(shortIds, ops) {
+      // `set` replaces the whole set in one bulk call. Otherwise apply the additive `add`
+      // (the bulk-add route merges per artifact) and/or `remove` — each a bulk call over
+      // the same id set, so the server does the per-artifact authorization + skip counting.
+      const post = (path: string, body: unknown) =>
+        f(`${base}${path}`, {
+          method: "POST",
+          headers: { ...authHeaders, "content-type": "application/json" },
+          body: JSON.stringify(body),
+        })
+      if (ops.set) {
+        // No bulk "set" route; set each artifact's tags directly (the union with nothing).
+        const results: { short_id: string; tags: string[] }[] = []
+        let updated = 0
+        let failed = 0
+        for (const id of shortIds) {
+          try {
+            const r = (await ok(
+              await f(`${base}/v1/artifacts/${id}/tags`, {
+                method: "PUT",
+                headers: { ...authHeaders, "content-type": "application/json" },
+                body: JSON.stringify({ tags: ops.set }),
+              }),
+            )) as { tags: string[] }
+            results.push({ short_id: id, tags: r.tags })
+            updated++
+          } catch {
+            failed++
+          }
+        }
+        return { updated, skipped: 0, failed, results }
+      }
+      let updated = 0
+      let skipped = 0
+      let failed = 0
+      if (ops.add?.length) {
+        const r = (await ok(await post("/v1/bulk/tags", { shortIds, add: ops.add }))) as {
+          ok: number
+          skipped: number
+          failed: number
+        }
+        updated = r.ok
+        skipped = r.skipped
+        failed = r.failed
+      }
+      if (ops.remove?.length) {
+        // No bulk-remove route: read-modify-write each artifact via the single tag route.
+        const removeSet = new Set(ops.remove.map((t) => t.trim().toLowerCase()))
+        for (const id of shortIds) {
+          try {
+            const a = await (ok(
+              await f(`${base}/v1/artifacts/${id}`, { headers: authHeaders }),
+            ) as Promise<{
+              tags?: string[]
+            }>)
+            const next = (a.tags ?? []).filter((t) => !removeSet.has(t))
+            await ok(
+              await f(`${base}/v1/artifacts/${id}/tags`, {
+                method: "PUT",
+                headers: { ...authHeaders, "content-type": "application/json" },
+                body: JSON.stringify({ tags: next }),
+              }),
+            )
+          } catch {
+            /* a remove miss (not editable) is reflected by the add pass's skipped, or ignored */
+          }
+        }
+      }
+      return { updated, skipped, failed, results: [] }
+    },
+
+    async listCollections() {
+      const r = (await ok(await f(`${base}/v1/collections`, { headers: authHeaders }))) as {
+        collections: { id: string; title: string; count: number }[]
+      }
+      return r.collections.map((c) => ({ id: c.id, title: c.title, count: c.count }))
+    },
+
+    async collect(shortIds, ref) {
+      // Resolve `ref` against the workspace's collections by id OR title, else create it.
+      const name = ref.trim()
+      const cols = (
+        (await ok(await f(`${base}/v1/collections`, { headers: authHeaders }))) as {
+          collections: { id: string; title: string }[]
+        }
+      ).collections
+      const match = cols.find((c) => c.id === name || c.title.toLowerCase() === name.toLowerCase())
+      let collectionId = match?.id
+      let title = match?.title ?? ""
+      if (!collectionId) {
+        const created = (await ok(
+          await f(`${base}/v1/collections`, {
+            method: "POST",
+            headers: { ...authHeaders, "content-type": "application/json" },
+            body: JSON.stringify({ title: name }),
+          }),
+        )) as { id: string; title: string }
+        collectionId = created.id
+        title = created.title
+      }
+      const r = (await ok(
+        await f(`${base}/v1/bulk/collections`, {
+          method: "POST",
+          headers: { ...authHeaders, "content-type": "application/json" },
+          body: JSON.stringify({ shortIds, collectionIds: [collectionId] }),
+        }),
+      )) as { ok: number; skipped: number }
+      return { collection: { id: collectionId, title }, added: r.ok, skipped: r.skipped }
     },
 
     async publish(args) {
@@ -264,6 +509,7 @@ export function createClient(opts: ClientOptions): DeriveClient {
         slug: args.slug,
         spa: args.spa,
         message: args.message,
+        tags: args.tags,
         workspaceAccess: args.workspaceAccess,
         linkRole: args.linkRole,
         listed: args.listed,
@@ -277,29 +523,6 @@ export function createClient(opts: ClientOptions): DeriveClient {
       ) as Promise<ArtifactJson>
     },
 
-    async propose(shortId, args) {
-      const form = new FormData()
-      if (args.edits) {
-        form.append("edits", JSON.stringify(args.edits))
-        if (args.baseVersion != null) form.append("base_version", String(args.baseVersion))
-      } else {
-        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(","))
-      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 }),
@@ -334,6 +557,24 @@ export function createClient(opts: ClientOptions): DeriveClient {
       }
     },
 
+    async search(shortId, query, opts) {
+      const q = new URLSearchParams({ query })
+      if (opts?.caseSensitive) q.set("case_sensitive", "true")
+      if (opts?.in) q.set("in", opts.in)
+      if (opts?.context != null) q.set("context", String(opts.context))
+      if (opts?.maxMatches != null) q.set("max_matches", String(opts.maxMatches))
+      if (opts?.version != null) q.set("v", String(opts.version))
+      const path = shortId
+        ? `${base}/v1/artifacts/${shortId}/search?${q}`
+        : `${base}/v1/artifacts/search?${q}`
+      const res = await f(path, { 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 getOutline(shortId, version) {
       const q = new URLSearchParams({ outline: "1" })
       if (version) q.set("v", String(version))
@@ -415,5 +656,30 @@ export function createClient(opts: ClientOptions): DeriveClient {
         await f(`${base}/v1/artifacts/${shortId}/analytics`, { headers: authHeaders }),
       ) as Promise<ViewStatsJson>
     },
+
+    async listTemplateLibraries(cursor) {
+      const query = new URLSearchParams({ limit: "100" })
+      if (cursor) query.set("cursor", cursor)
+      return ok(
+        await f(`${base}/v1/template-libraries?${query}`, { headers: authHeaders }),
+      ) as Promise<TemplateLibraryPageJson>
+    },
+
+    async getTemplateLibrary(id) {
+      return ok(
+        await f(`${base}/v1/template-libraries/${encodeURIComponent(id)}`, {
+          headers: authHeaders,
+        }),
+      ) as Promise<TemplateLibraryJson>
+    },
+
+    async getTemplateStarter(libraryId, entryId) {
+      return ok(
+        await f(
+          `${base}/v1/template-libraries/${encodeURIComponent(libraryId)}/entries/${encodeURIComponent(entryId)}/starter`,
+          { headers: authHeaders },
+        ),
+      ) as Promise<TemplateStarterJson>
+    },
   }
 }

package/src/filename.ts

@@ -0,0 +1,30 @@
+// Choosing the upload filename for an inline `content` publish when the caller gave
+// none. The Derive server types an artifact by its filename FIRST, so a blind
+// `index.html` default silently stores Markdown as text/html — the page then renders
+// the raw Markdown as markup and swallows tag-like text (the 2026-07 retype incident).
+//
+// These mirror the server's own sniff, inlined here because the stdio shim keeps NO
+// @derive/core dependency at runtime (it is a thin HTTP client).
+
+/** An HTML page opener: the doctype/`<html>` markers, plus the head/meta/style/
+ *  title/body openers a headless designed page starts with — matched after skipping
+ *  leading HTML comments (a comment alone never decides). A leading `<div>`/`<p>`/
+ *  custom tag is NOT one: that is how HTML-flavored Markdown (a centered README)
+ *  legitimately opens. Mirrors @derive/core's looksLikeHtmlDocument exactly. */
+export const looksLikeHtmlDocument = (s: string): boolean => {
+  let head = s.replace(/^/, "").trimStart()
+  for (let i = 0; i < 8 && head.startsWith("<!--"); i++) {
+    const end = head.indexOf("-->")
+    if (end === -1) return false
+    head = head.slice(end + 3).trimStart()
+  }
+  return /^<(!doctype\s+html|html|head|body|meta|style|title)[\s/>]/i.test(head.slice(0, 64))
+}
+
+/** The fallback filename for inline content with none given: an HTML page →
+ *  `index.html`, anything else → `index.md`. So Markdown is never stored as HTML.
+ *  Caveat: fragment HTML that opens with a `<div>` (indistinguishable from
+ *  HTML-flavored Markdown) still lands as `.md` — pass an explicit
+ *  `filename` (or use `edits`) to keep it HTML. */
+export const fallbackFilename = (content: string | undefined): string =>
+  looksLikeHtmlDocument(content ?? "") ? "index.html" : "index.md"