everymuseum-mcp 0.1.0 → 0.1.2

package/dist/api.js

@@ -116,7 +116,11 @@ function asArtwork(value) {
         updatedAt: str("updatedAt") ?? undefined,
     };
 }
-/** Search the archive. Always requests totals so callers get paging metadata. */
+/**
+ * Search the archive. `includeTotal` is off by default: requesting the grand
+ * total forces a COUNT over the whole (600k+) filtered archive, which is the
+ * slowest part of a search — skip it unless a caller genuinely needs it.
+ */
 export async function searchArtworks(query, options = {}) {
     const params = new URLSearchParams();
     const trimmed = query.trim();
@@ -125,7 +129,8 @@ export async function searchArtworks(query, options = {}) {
     params.set("limit", String(options.limit ?? 12));
     if (options.offset)
         params.set("offset", String(options.offset));
-    params.set("includeTotal", "1");
+    if (options.includeTotal)
+        params.set("includeTotal", "1");
     const body = await apiFetch(`/api/search?${params.toString()}`);
     // includeTotal=1 returns { items, total, limit, offset, nextCursor }.
     if (body && typeof body === "object" && "items" in body) {
@@ -140,13 +145,162 @@ export async function searchArtworks(query, options = {}) {
     const items = Array.isArray(body) ? body.map(asArtwork) : [];
     return { items, total: null, nextCursor: null };
 }
+// ─── Smart search: multi-word matching + client-side filters ─────────────────
+//
+// The backend `q` is a single substring match, so "hokusai wave" matches no
+// field literally and returns nothing. We tokenize the query, fetch each term
+// (the backend matches each one), then rank the union by how many query terms
+// each work's metadata actually covers. Filters the API doesn't support are
+// applied here over an over-fetched window.
+const STOPWORDS = new Set([
+    "the", "a", "an", "of", "and", "or", "in", "on", "at", "to",
+    "with", "by", "for", "from", "de", "la", "le",
+]);
+const OVERFETCH = 150;
+function queryTerms(query) {
+    const terms = query
+        .toLowerCase()
+        .split(/\s+/)
+        .map((term) => term.replace(/[^\p{L}\p{N}-]/gu, ""))
+        .filter((term) => term.length >= 2 && !STOPWORDS.has(term));
+    return Array.from(new Set(terms)).slice(0, 5);
+}
+function artworkText(artwork) {
+    return [
+        artwork.title,
+        artwork.artist,
+        artwork.medium,
+        artwork.culture,
+        artwork.department,
+        artwork.classification,
+        artwork.description,
+        artwork.tags.join(" "),
+        sourceLabel(artwork.source),
+        artwork.source,
+    ]
+        .filter(Boolean)
+        .join(" ")
+        .toLowerCase();
+}
+function termCoverage(text, terms) {
+    let covered = 0;
+    for (const term of terms)
+        if (text.includes(term))
+            covered += 1;
+    return covered;
+}
+function hasActiveFilters(filters) {
+    return (!!filters.source ||
+        !!filters.medium ||
+        !!filters.culture ||
+        !!filters.license ||
+        filters.hasImage === true ||
+        filters.yearFrom != null ||
+        filters.yearTo != null);
+}
+function matchesFilters(artwork, filters) {
+    if (filters.source) {
+        const needle = filters.source.toLowerCase();
+        const matches = artwork.source.toLowerCase().includes(needle) ||
+            sourceLabel(artwork.source).toLowerCase().includes(needle);
+        if (!matches)
+            return false;
+    }
+    if (filters.medium && !(artwork.medium ?? "").toLowerCase().includes(filters.medium.toLowerCase())) {
+        return false;
+    }
+    if (filters.culture && !(artwork.culture ?? "").toLowerCase().includes(filters.culture.toLowerCase())) {
+        return false;
+    }
+    if (filters.license && !(artwork.license ?? "").toLowerCase().includes(filters.license.toLowerCase())) {
+        return false;
+    }
+    if (filters.hasImage && !(artwork.imageUrl || artwork.thumbnailUrl || artwork.iiifUrl)) {
+        return false;
+    }
+    if (filters.yearFrom != null || filters.yearTo != null) {
+        const lo = filters.yearFrom ?? -Infinity;
+        const hi = filters.yearTo ?? Infinity;
+        const start = artwork.dateStart ?? artwork.dateEnd;
+        const end = artwork.dateEnd ?? artwork.dateStart;
+        if (start == null || end == null)
+            return false; // unknown date can't satisfy a year filter
+        if (end < lo || start > hi)
+            return false; // no overlap with [lo, hi]
+    }
+    return true;
+}
+/**
+ * Search with multi-word ranking and optional client-side filters. Falls back
+ * to the fast single-request path when the query is one term and no filters are
+ * set. Filters operate over an over-fetched window, so very rare combinations
+ * may miss matches beyond that window.
+ */
+export async function searchArtworksSmart(query, options = {}) {
+    const limit = options.limit ?? 12;
+    const offset = options.offset ?? 0;
+    const filters = options.filters ?? {};
+    const filtered = hasActiveFilters(filters);
+    const terms = queryTerms(query);
+    // Fast path: single meaningful term, no filters → one backend page. Search the
+    // extracted term (not the raw query) so "the wave" probes "wave", not the literal
+    // phrase the substring backend would never match. Over-fetch one to know hasMore.
+    if (terms.length <= 1 && !filtered) {
+        const probe = terms[0] ?? query.trim();
+        const page = await searchArtworks(probe, { limit: limit + 1, offset });
+        const items = page.items.slice(0, limit);
+        return { items, terms, filtered: false, hasMore: page.items.length > limit };
+    }
+    // Gather candidates: one over-fetched page per term (backend matches each),
+    // deduped by id. Empty term list (e.g. all stopwords) falls back to the raw query.
+    const probes = terms.length > 0 ? terms : [query.trim()].filter(Boolean);
+    const pages = await Promise.all(probes.map((probe) => searchArtworks(probe, { limit: OVERFETCH })
+        .then((result) => result.items)
+        .catch(() => [])));
+    const byId = new Map();
+    for (const page of pages) {
+        for (const artwork of page) {
+            if (artwork.id && !byId.has(artwork.id))
+                byId.set(artwork.id, artwork);
+        }
+    }
+    let candidates = Array.from(byId.values());
+    if (filtered)
+        candidates = candidates.filter((artwork) => matchesFilters(artwork, filters));
+    // Rank by how many query terms each work's metadata covers (desc). Stable for ties.
+    const ranked = candidates
+        .map((artwork, index) => ({ artwork, index, score: termCoverage(artworkText(artwork), terms) }))
+        .sort((a, b) => b.score - a.score || a.index - b.index)
+        .map((entry) => entry.artwork);
+    const items = ranked.slice(offset, offset + limit);
+    return { items, terms, filtered, hasMore: ranked.length > offset + items.length };
+}
+// Memoize artwork lookups for the life of the process: add_to_board, compare,
+// and board flows often re-request the same ids right after a search. Bounded
+// with FIFO eviction so a long browsing session can't grow the map unboundedly.
+const ARTWORK_CACHE_MAX = 500;
+const artworkCache = new Map();
 /** Fetch full detail for a single artwork. Throws ApiError(404) if missing. */
 export async function getArtwork(id) {
-    const body = await apiFetch(`/api/artworks/${encodeURIComponent(id)}`);
-    if (!body || typeof body !== "object" || !("id" in body)) {
-        throw new ApiError(`No artwork found for id "${id}".`, 404);
+    const cached = artworkCache.get(id);
+    if (cached)
+        return cached;
+    const pending = (async () => {
+        const body = await apiFetch(`/api/artworks/${encodeURIComponent(id)}`);
+        if (!body || typeof body !== "object" || !("id" in body)) {
+            throw new ApiError(`No artwork found for id "${id}".`, 404);
+        }
+        return asArtwork(body);
+    })();
+    if (artworkCache.size >= ARTWORK_CACHE_MAX) {
+        const oldest = artworkCache.keys().next().value;
+        if (oldest !== undefined)
+            artworkCache.delete(oldest);
     }
-    return asArtwork(body);
+    artworkCache.set(id, pending);
+    // Don't cache failures — let the next call retry.
+    pending.catch(() => artworkCache.delete(id));
+    return pending;
 }
 /** Works the archive considers similar to the given artwork (up to ~12). */
 export async function findSimilar(id) {

package/dist/board-html.js

@@ -47,6 +47,8 @@ function renderCard(item) {
     const attribution = [item.sourceLabel, item.license].filter(Boolean).map((part) => escapeHtml(part));
     if (attribution.length)
         metaLines.push(`<span class="attr">${attribution.join(" · ")}</span>`);
+    if (item.note)
+        metaLines.push(`<span class="note">${escapeHtml(item.note)}</span>`);
     const caption = `
       <figcaption>
         <span class="title">${title}</span>
@@ -182,6 +184,14 @@ export function renderBoardHtml(board) {
     color: var(--muted);
     margin-top: 4px;
   }
+  figcaption .note {
+    font-size: 13px;
+    font-style: italic;
+    color: #3a342d;
+    margin-top: 6px;
+    padding-left: 10px;
+    border-left: 2px solid var(--accent);
+  }
   .card a:hover figcaption .title { color: var(--accent); }
   .empty {
     max-width: 1280px;
@@ -224,3 +234,39 @@ export function renderBoardHtml(board) {
 </html>
 `;
 }
+const MARKDOWN_IMAGE_SIZE = 1000;
+/** Strip characters that would break a Markdown image alt / link text. */
+function escapeMd(value) {
+    return value.replace(/[\[\]]/g, "").replace(/\s+/g, " ").trim();
+}
+/** Render a board as a Markdown document — paste into docs, Notion, or a README. */
+export function renderBoardMarkdown(board) {
+    const lines = [];
+    lines.push(`# ${escapeMd(board.name)}`);
+    if (board.description)
+        lines.push("", escapeMd(board.description));
+    const count = board.items.length;
+    lines.push("", `_${count} ${count === 1 ? "work" : "works"} · curated via [EveryMuseum](https://everymuseum.org)_`, "");
+    board.items.forEach((item, index) => {
+        const title = item.title?.trim() || "Untitled";
+        const imageUrl = safeUrl(bestDisplayUrl(item, MARKDOWN_IMAGE_SIZE));
+        const link = safeUrl(item.sourceUrl) || `https://everymuseum.org/artworks/${item.id}`;
+        // Escape every interpolated field (collapses newlines, strips [] link/image
+        // syntax) so a note or metadata value can't inject Markdown structure. URLs
+        // go in angle brackets so a stray ')' can't truncate the link/image.
+        const facts = [item.artist, item.dateDisplay, item.medium, item.sourceLabel, item.license]
+            .filter((part) => Boolean(part))
+            .map(escapeMd)
+            .join(" · ");
+        lines.push(`### ${index + 1}. ${escapeMd(title)}`);
+        if (imageUrl)
+            lines.push("", `![${escapeMd(title)}](<${imageUrl}>)`);
+        if (facts)
+            lines.push("", facts);
+        if (item.note)
+            lines.push("", `> ${escapeMd(item.note)}`);
+        if (link)
+            lines.push("", `[View the work →](<${link}>)`, "");
+    });
+    return lines.join("\n");
+}

package/dist/boards.js

@@ -83,7 +83,7 @@ export function createBoard(boards, name, description) {
     boards.push(board);
     return board;
 }
-export function boardItemFromArtwork(artwork) {
+export function boardItemFromArtwork(artwork, note = null) {
     return {
         id: artwork.id,
         title: artwork.title,
@@ -98,17 +98,18 @@ export function boardItemFromArtwork(artwork) {
         iiifUrl: artwork.iiifUrl,
         sourceUrl: artwork.sourceUrl,
         license: artwork.license,
+        note,
         addedAt: new Date().toISOString(),
     };
 }
 /** Add artworks to a board, skipping ids already present. Returns count added. */
-export function addArtworksToBoard(board, artworks) {
+export function addArtworksToBoard(board, artworks, note = null) {
     const present = new Set(board.items.map((item) => item.id));
     let added = 0;
     for (const artwork of artworks) {
         if (present.has(artwork.id))
             continue;
-        board.items.push(boardItemFromArtwork(artwork));
+        board.items.push(boardItemFromArtwork(artwork, note));
         present.add(artwork.id);
         added += 1;
     }
@@ -116,6 +117,15 @@ export function addArtworksToBoard(board, artworks) {
         board.updatedAt = new Date().toISOString();
     return added;
 }
+/** Set (or clear) the note on a board item by artwork id. Returns true if found. */
+export function annotateBoardItem(board, artworkId, note) {
+    const item = board.items.find((entry) => entry.id === artworkId);
+    if (!item)
+        return false;
+    item.note = note;
+    board.updatedAt = new Date().toISOString();
+    return true;
+}
 /** Remove items by artwork id. Returns count removed. */
 export function removeItemsFromBoard(board, ids) {
     const remove = new Set(ids);

package/dist/images.js

@@ -1,5 +1,8 @@
 import { API_BASE } from "./api.js";
-const IMAGE_TIMEOUT_MS = 20_000;
+// Per-image cap. Images are fetched in parallel, so the tool waits for the
+// slowest one; a tight cap keeps a single stalled museum CDN from holding up
+// the whole result (slow images are simply dropped from the gallery).
+const IMAGE_TIMEOUT_MS = 10_000;
 const MAX_IMAGE_BYTES = 6 * 1024 * 1024; // 6 MB — generous for a sized JPEG.
 const USER_AGENT = "everymuseum-mcp/0.1 (+https://everymuseum.org)";
 // MIME types Claude can render as image content blocks.
@@ -67,8 +70,10 @@ export function bestDisplayUrl(artwork, size) {
     }
     return resolveUrl(artwork.imageUrl ?? artwork.thumbnailUrl);
 }
-/** Fetch an image and return it as a base64 MCP image content block, or null. */
-export async function fetchImageContent(url) {
+// High-res downloads can be much larger than inline previews.
+export const DOWNLOAD_MAX_BYTES = 40 * 1024 * 1024; // 40 MB
+/** Fetch image bytes with a hard size cap and content-type guard. Null on failure. */
+export async function fetchImageBytes(url, maxBytes = MAX_IMAGE_BYTES) {
     const resolved = resolveUrl(url);
     if (!resolved)
         return null;
@@ -89,9 +94,8 @@ export async function fetchImageContent(url) {
             return null;
         // Reject obviously oversized bodies up front…
         const declaredLength = Number(response.headers.get("content-length"));
-        if (Number.isFinite(declaredLength) && declaredLength > MAX_IMAGE_BYTES) {
+        if (Number.isFinite(declaredLength) && declaredLength > maxBytes)
             return null;
-        }
         // …then stream with a hard byte cap so a lying/missing content-length can't
         // make us buffer an unbounded body into memory.
         const reader = response.body?.getReader();
@@ -106,7 +110,7 @@ export async function fetchImageContent(url) {
             if (!value)
                 continue;
             total += value.byteLength;
-            if (total > MAX_IMAGE_BYTES) {
+            if (total > maxBytes) {
                 controller.abort();
                 return null;
             }
@@ -114,8 +118,7 @@ export async function fetchImageContent(url) {
         }
         if (total === 0)
             return null;
-        const buffer = Buffer.concat(chunks, total);
-        return { type: "image", data: buffer.toString("base64"), mimeType };
+        return { buffer: Buffer.concat(chunks, total), mimeType };
     }
     catch {
         return null;
@@ -124,7 +127,31 @@ export async function fetchImageContent(url) {
         clearTimeout(timeout);
     }
 }
+/** Fetch an image and return it as a base64 MCP image content block, or null. */
+export async function fetchImageContent(url) {
+    const bytes = await fetchImageBytes(url, MAX_IMAGE_BYTES);
+    if (!bytes)
+        return null;
+    return { type: "image", data: bytes.buffer.toString("base64"), mimeType: bytes.mimeType };
+}
 /** Convenience: fetch the best display image for an artwork as a content block. */
 export async function artworkImageContent(artwork, size) {
     return fetchImageContent(bestDisplayUrl(artwork, size));
 }
+/** A large, renderable URL suitable for saving a high-resolution copy. */
+export function downloadUrlFor(artwork) {
+    return bestDisplayUrl(artwork, 4096);
+}
+/** Map an image MIME type to a file extension. */
+export function extensionForMime(mimeType) {
+    switch (mimeType) {
+        case "image/png":
+            return "png";
+        case "image/webp":
+            return "webp";
+        case "image/gif":
+            return "gif";
+        default:
+            return "jpg";
+    }
+}

package/dist/index.js

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join, resolve, sep } from "node:path";
 import { platform } from "node:process";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { ApiError, API_BASE, findSimilar, getArtwork, getSuggestions, searchArtworks, sourceLabel, } from "./api.js";
-import { renderBoardHtml } from "./board-html.js";
-import { addArtworksToBoard, boardsExportDir, createBoard, deleteBoard, findBoard, loadBoards, removeItemsFromBoard, saveBoards, withBoards, } from "./boards.js";
-import { artworkImageContent } from "./images.js";
-const VERSION = "0.1.0";
+import { ApiError, API_BASE, findSimilar, getArtwork, getSuggestions, searchArtworksSmart, sourceLabel, } from "./api.js";
+import { renderBoardHtml, renderBoardMarkdown } from "./board-html.js";
+import { addArtworksToBoard, annotateBoardItem, boardsExportDir, createBoard, dataDir, deleteBoard, findBoard, loadBoards, removeItemsFromBoard, saveBoards, withBoards, } from "./boards.js";
+import { artworkImageContent, downloadUrlFor, extensionForMime, fetchImageBytes, DOWNLOAD_MAX_BYTES, } from "./images.js";
+const VERSION = "0.1.2";
 function text(value) {
     return { type: "text", text: value };
 }
@@ -39,8 +39,10 @@ function captionLine(art, index) {
     const date = art.dateDisplay?.trim() || "n.d.";
     const label = sourceLabel(art.source);
     const license = art.license?.trim();
-    const tail = license ? ` · ${license}` : "";
-    return `${index}. "${title}" — ${artist} (${date}) · ${label}${tail}\n   id: ${art.id}`;
+    const meta = [label, license].filter((part) => Boolean(part)).join(" · ");
+    // Link straight to the work: the source museum's record, or the EveryMuseum page.
+    const link = art.sourceUrl?.trim() || `${API_BASE}/artworks/${art.id}`;
+    return `${index}. "${title}" — ${artist} (${date}) · ${meta}\n   ${link}  ·  id: ${art.id}`;
 }
 /** Build a captioned gallery: one text line per item, each followed by its image. */
 async function galleryContent(items, options) {
@@ -65,6 +67,7 @@ function boardItemCaption(item, index) {
         dateDisplay: item.dateDisplay,
         source: item.source,
         license: item.license,
+        sourceUrl: item.sourceUrl,
     }, index);
 }
 function boardSummaryLine(board) {
@@ -80,13 +83,15 @@ const server = new McpServer({ name: "everymuseum", version: VERSION }, {
         "",
         "Use these tools to pull up images conversationally, learn about specific works,",
         "discover related pieces, and curate persistent local 'boards' (mood boards /",
-        "reading lists) that can be exported to a shareable HTML gallery.",
+        "reading lists) that can be exported to a shareable HTML or Markdown gallery.",
         "",
-        "Workflow tips: search_artworks → get_artwork (deep detail) → find_similar",
-        "(go deeper) → create_board / add_to_board (collect) → export_board (share).",
-        "Every artwork has a stable `id`; pass it to get_artwork, find_similar, and",
-        "add_to_board. Images are real artwork reproductions; always attribute the",
-        "source institution and respect the stated license.",
+        "Workflow tips: search_artworks (supports multi-word queries + filters by museum,",
+        "year range, medium, culture, license) → get_artwork (deep detail) → find_similar",
+        "or compare_artworks (explore) → create_board / add_to_board (collect, with notes)",
+        "→ download_artworks (save hi-res files) or export_board (share as HTML/Markdown).",
+        "Every artwork has a stable `id`; pass it to get_artwork, find_similar, compare,",
+        "add_to_board, and download_artworks. Images are real artwork reproductions;",
+        "always attribute the source institution and respect the stated license.",
     ].join("\n"),
 });
 // ─── Discovery & images ──────────────────────────────────────────────────────
@@ -94,9 +99,11 @@ server.registerTool("search_artworks", {
     title: "Search the EveryMuseum archive",
     description: "Search open-access museum artworks by free text (artist, title, culture, " +
         "medium, period, museum name, or theme — e.g. 'hokusai wave', 'art nouveau " +
-        "poster', 'egyptian bronze'). Returns captioned results with images so they " +
-        "can be shown directly in the conversation. Each result includes a stable id " +
-        "for use with get_artwork, find_similar, and add_to_board.",
+        "poster', 'egyptian bronze'). Multi-word queries are matched intelligently. " +
+        "Optionally filter by museum, year range, medium, culture, or license. " +
+        "Returns captioned results with images so they can be shown directly in the " +
+        "conversation; each includes a link to the work and a stable id for use with " +
+        "get_artwork, find_similar, and add_to_board.",
     inputSchema: {
         query: z
             .string()
@@ -117,6 +124,23 @@ server.registerTool("search_artworks", {
             .max(10000)
             .optional()
             .describe("Skip this many results for paging through more (default 0)."),
+        source: z
+            .string()
+            .optional()
+            .describe("Filter to a museum, by key or name (e.g. 'met', 'rijksmuseum', 'getty')."),
+        yearFrom: z
+            .number()
+            .int()
+            .optional()
+            .describe("Only works whose date overlaps on/after this year (e.g. 1800)."),
+        yearTo: z
+            .number()
+            .int()
+            .optional()
+            .describe("Only works whose date overlaps on/before this year (e.g. 1900)."),
+        medium: z.string().optional().describe("Filter by medium substring (e.g. 'woodblock', 'bronze')."),
+        culture: z.string().optional().describe("Filter by culture/origin substring (e.g. 'japan', 'france')."),
+        license: z.string().optional().describe("Filter by license substring (e.g. 'public domain', 'cc0')."),
         includeImages: z
             .boolean()
             .optional()
@@ -134,25 +158,30 @@ server.registerTool("search_artworks", {
     const limit = args.limit ?? 6;
     const includeImages = args.includeImages ?? true;
     const imageSize = args.imageSize ?? 512;
-    const result = await searchArtworks(args.query, {
-        limit,
-        offset: args.offset ?? 0,
-    });
+    const offset = args.offset ?? 0;
+    const filters = {
+        source: args.source,
+        yearFrom: args.yearFrom,
+        yearTo: args.yearTo,
+        medium: args.medium,
+        culture: args.culture,
+        license: args.license,
+    };
+    const result = await searchArtworksSmart(args.query, { limit, offset, filters });
     if (result.items.length === 0) {
+        const filterNote = result.filtered ? " (with your filters applied)" : "";
         return ok([
-            text(`No artworks matched "${args.query}". Try a broader term, an artist, ` +
-                `a culture, or call suggest_searches for ideas.`),
+            text(`No artworks matched "${args.query}"${filterNote}. Try a broader term, ` +
+                `fewer filters, or call suggest_searches for ideas.`),
         ]);
     }
-    const totalNote = result.total != null
-        ? ` of ~${result.total.toLocaleString()} matching works`
-        : "";
-    const offset = args.offset ?? 0;
-    const moreNote = result.total != null && offset + result.items.length < result.total
-        ? ` Call again with offset: ${offset + result.items.length} for more.`
+    const termNote = result.terms.length > 1 ? ` matched on: ${result.terms.join(", ")}` : "";
+    const filterNote = result.filtered ? " · filtered" : "";
+    const moreNote = result.hasMore
+        ? ` More available — call again with offset: ${offset + result.items.length}.`
         : "";
     const header = text(`Showing ${result.items.length} result${result.items.length === 1 ? "" : "s"}` +
-        `${totalNote} for "${args.query}".${moreNote}`);
+        ` for "${args.query}"${termNote}${filterNote}.${moreNote}`);
     const gallery = await galleryContent(result.items, {
         includeImages,
         imageSize,
@@ -267,6 +296,126 @@ server.registerTool("find_similar", {
         ...gallery,
     ]);
 }));
+server.registerTool("compare_artworks", {
+    title: "Compare several artworks side by side",
+    description: "Fetch multiple works by id and present them together with images and key " +
+        "facts — useful for contrasting style, period, medium, or treatment across pieces.",
+    inputSchema: {
+        ids: z
+            .array(z.string().min(1))
+            .min(2)
+            .max(8)
+            .describe("2–8 artwork ids to compare."),
+        imageSize: z
+            .number()
+            .int()
+            .min(200)
+            .max(2000)
+            .optional()
+            .describe("Long-edge pixel size for images (default 640)."),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async (args) => guard(async () => {
+    const unique = Array.from(new Set(args.ids));
+    const fetched = await Promise.all(unique.map((id) => getArtwork(id).catch(() => null)));
+    const items = fetched.filter((art) => art !== null);
+    const missing = unique.filter((id) => !items.some((art) => art.id === id));
+    if (items.length === 0) {
+        return fail(`None of those ids resolved: ${unique.join(", ")}.`);
+    }
+    const gallery = await galleryContent(items, {
+        includeImages: true,
+        imageSize: args.imageSize ?? 640,
+    });
+    const missingNote = missing.length ? ` (couldn't find: ${missing.join(", ")})` : "";
+    return ok([text(`Comparing ${items.length} works${missingNote}:`), ...gallery]);
+}));
+function slugForFile(value) {
+    return (value ?? "")
+        .normalize("NFKD")
+        .replace(/[^\w\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-")
+        .toLowerCase()
+        .slice(0, 60);
+}
+function downloadFilename(art, mimeType) {
+    // art.id comes straight from the API JSON and is NOT trusted to be a clean
+    // cuid — strip it to a safe segment so no path separators / '..' can reach
+    // the filename. (The caller also basenames + asserts containment.)
+    const safeId = art.id.replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 40) || "id";
+    const base = [slugForFile(art.title) || "artwork", slugForFile(sourceLabel(art.source)), safeId]
+        .filter(Boolean)
+        .join("-")
+        .slice(0, 120);
+    return `${base}.${extensionForMime(mimeType)}`;
+}
+function resolveDownloadDir(folder) {
+    const trimmed = folder?.trim();
+    return trimmed ? resolve(trimmed) : join(dataDir(), "downloads");
+}
+server.registerTool("download_artworks", {
+    title: "Download high-resolution images to disk",
+    description: "Save high-resolution image files for one or more works (by id) to a folder " +
+        "on this machine, returning the saved file paths. Use to collect the actual " +
+        "image files rather than inline previews.",
+    inputSchema: {
+        ids: z
+            .array(z.string().min(1))
+            .min(1)
+            .max(50)
+            .describe("Artwork ids to download."),
+        folder: z
+            .string()
+            .optional()
+            .describe("Destination folder (default ~/.everymuseum/downloads). Created if missing."),
+    },
+    annotations: { readOnlyHint: false, openWorldHint: true },
+}, async (args) => guard(async () => {
+    const dir = resolveDownloadDir(args.folder);
+    await mkdir(dir, { recursive: true });
+    const root = resolve(dir);
+    const unique = Array.from(new Set(args.ids));
+    const downloadOne = async (id) => {
+        try {
+            const art = await getArtwork(id);
+            const bytes = await fetchImageBytes(downloadUrlFor(art), DOWNLOAD_MAX_BYTES);
+            if (!bytes)
+                return { id, ok: false, reason: "no downloadable image" };
+            // basename + containment assertion: the write can never escape `dir`,
+            // even if a field slipped a separator past slugging.
+            const filePath = join(dir, basename(downloadFilename(art, bytes.mimeType)));
+            if (resolve(filePath) !== root && !resolve(filePath).startsWith(root + sep)) {
+                return { id, ok: false, reason: "unsafe path" };
+            }
+            await writeFile(filePath, bytes.buffer);
+            return { id, ok: true, path: filePath, kb: Math.round(bytes.buffer.byteLength / 1024) };
+        }
+        catch (error) {
+            return { id, ok: false, reason: error instanceof Error ? error.message : "failed" };
+        }
+    };
+    // Bounded concurrency so peak memory is pool×cap, not 50×40 MB.
+    const CONCURRENCY = 4;
+    const results = [];
+    for (let i = 0; i < unique.length; i += CONCURRENCY) {
+        const batch = unique.slice(i, i + CONCURRENCY);
+        results.push(...(await Promise.all(batch.map(downloadOne))));
+    }
+    const saved = results.filter((r) => r.ok);
+    const failed = results.filter((r) => !r.ok);
+    const lines = [
+        `Saved ${saved.length} of ${unique.length} image${unique.length === 1 ? "" : "s"} to ${dir}:`,
+    ];
+    for (const entry of saved)
+        lines.push(`• ${entry.path} (${entry.kb} KB)`);
+    if (failed.length) {
+        lines.push(`Could not download ${failed.length}:`);
+        for (const entry of failed)
+            lines.push(`• ${entry.id} — ${entry.reason}`);
+    }
+    return ok([text(lines.join("\n"))]);
+}));
 server.registerTool("suggest_searches", {
     title: "Suggest things to explore",
     description: "Return a curated list of popular search terms drawn from the archive's top " +
@@ -348,6 +497,11 @@ server.registerTool("add_to_board", {
             .min(1)
             .max(100)
             .describe("Artwork ids to add (from search/get/similar results)."),
+        note: z
+            .string()
+            .max(500)
+            .optional()
+            .describe("Optional note applied to each work added in this call (why it's here)."),
     },
     annotations: { readOnlyHint: false },
 }, async (args) => guard(async () => {
@@ -370,7 +524,7 @@ server.registerTool("add_to_board", {
             return fail(`No board matches "${args.board}". Use list_boards to see boards, or ` +
                 `create_board to make one.`);
         }
-        const added = addArtworksToBoard(board, found);
+        const added = addArtworksToBoard(board, found, args.note?.trim() || null);
         const skipped = found.length - added;
         await saveBoards(boards);
         const parts = [
@@ -386,6 +540,35 @@ server.registerTool("add_to_board", {
         return ok([text(parts.join(" "))]);
     });
 }));
+server.registerTool("annotate_board_item", {
+    title: "Add or edit a note on a board item",
+    description: "Set (or clear) the curator note on one work already on a board — e.g. why " +
+        "it was saved, or what to notice. Notes show in view_board and exports.",
+    inputSchema: {
+        board: z.string().min(1).describe("Board slug, name, or id."),
+        artworkId: z.string().min(1).describe("The artwork id on the board to annotate."),
+        note: z
+            .string()
+            .max(500)
+            .describe("The note text. Pass an empty string to clear the note."),
+    },
+    annotations: { readOnlyHint: false },
+}, async (args) => guard(() => withBoards(async (boards) => {
+    const board = findBoard(boards, args.board);
+    if (!board)
+        return fail(`No board matches "${args.board}".`);
+    const note = args.note.trim() || null;
+    const found = annotateBoardItem(board, args.artworkId, note);
+    if (!found) {
+        return fail(`Artwork ${args.artworkId} is not on "${board.name}".`);
+    }
+    await saveBoards(boards);
+    return ok([
+        text(note
+            ? `Noted on "${board.name}": ${args.artworkId} — "${note}".`
+            : `Cleared the note on ${args.artworkId} in "${board.name}".`),
+    ]);
+})));
 server.registerTool("view_board", {
     title: "View a board's contents",
     description: "Show the works on a board with captioned images, identified by slug, name, " +
@@ -468,16 +651,21 @@ server.registerTool("remove_from_board", {
     ]);
 })));
 server.registerTool("export_board", {
-    title: "Export a board to an HTML gallery",
-    description: "Render a board as a self-contained, shareable HTML gallery page (an editorial " +
-        "contact sheet with captions, attribution, and source links) and write it to " +
-        "disk. Optionally open it in the default browser. Returns the file path.",
+    title: "Export a board to a shareable gallery",
+    description: "Render a board and write it to disk. format 'html' (default) produces a " +
+        "self-contained editorial gallery page (captions, attribution, notes, source " +
+        "links) that can optionally open in the browser. format 'markdown' returns " +
+        "copy-pasteable Markdown (for docs/Notion/READMEs) and also writes a .md file.",
     inputSchema: {
         board: z.string().min(1).describe("Board slug, name, or id to export."),
+        format: z
+            .enum(["html", "markdown"])
+            .optional()
+            .describe("Output format (default 'html')."),
         open: z
             .boolean()
             .optional()
-            .describe("Open the exported page in the default browser (default false)."),
+            .describe("For HTML, open the page in the default browser (default false)."),
     },
     annotations: { readOnlyHint: false, openWorldHint: true },
 }, async (args) => guard(async () => {
@@ -487,6 +675,16 @@ server.registerTool("export_board", {
         return fail(`No board matches "${args.board}".`);
     const dir = boardsExportDir();
     await mkdir(dir, { recursive: true });
+    const countLabel = `${board.items.length} work${board.items.length === 1 ? "" : "s"}`;
+    if ((args.format ?? "html") === "markdown") {
+        const markdown = renderBoardMarkdown(board);
+        const filePath = join(dir, `${board.slug}-${board.id}.md`);
+        await writeFile(filePath, markdown, "utf8");
+        return ok([
+            text(`Exported "${board.name}" (${countLabel}) as Markdown to:\n${filePath}\n\n` +
+                `--- copy below ---\n\n${markdown}`),
+        ]);
+    }
     const filePath = join(dir, `${board.slug}-${board.id}.html`);
     await writeFile(filePath, renderBoardHtml(board), "utf8");
     let openNote = "";
@@ -510,7 +708,7 @@ server.registerTool("export_board", {
         }
     }
     return ok([
-        text(`Exported "${board.name}" (${board.items.length} works) to:\n${filePath}${openNote}`),
+        text(`Exported "${board.name}" (${countLabel}) to:\n${filePath}${openNote}`),
     ]);
 }));
 server.registerTool("delete_board", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "everymuseum-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for the EveryMuseum archive — search open-access museum artworks, pull up images, find similar works, and curate boards, all from a conversation with Claude.",
   "keywords": [
     "mcp",