@prontosite/mcp 0.13.7 → 0.14.1

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 Alle nennenswerten Änderungen am MCP-Server für ProntoSite. Der Server ist ein dünner Client um die
 ProntoSite Deploy-API; die eigentliche Logik lebt serverseitig.
 
+## 0.14.1 – 2026-10-22
+
+- Instructions + `media_search`: Fotos nie per URL von Unsplash oder anderen Bilddiensten (images.unsplash.com, imgix …) ins
+  HTML/CSS schreiben – sonst lädt jeder Besucher das Bild beim Dienst (Besucher-IPs in die USA, Einwilligungspflicht); immer
+  `media_import`, ProntoSite liefert das Foto selbst aus.
+
+## 0.14.0 – 2026-10-22
+
+Enthält 0.13.8 (nie einzeln veröffentlicht).
+- Neu: `media_search {site, query, orientation?, count≤6}` – Unsplash-Fotos suchen; je Treffer eine kleine Vorschau als Bild,
+  Fotograf, Lizenz-Hinweis und `resultId` (1 h gültig). Gleiche Suchen kommen 1 h aus dem Cache.
+- Neu: `media_import {site, resultId}` – Treffer übernehmen (Download-Trigger laut Unsplash-Richtlinie, Varianten, Kontingent,
+  Fotograf/Quelle in den Medien-Metadaten) → `mediaId` + vorbelegter alt-Text; danach `site_image_set`.
+- Instructions: „Bei ‚passendes Bild für Abschnitt X': site_page_texts → media_search → 2–3 Vorschauen zur Wahl → media_import
+  + site_image_set + Screenshot."
+
+## 0.13.8 – 2026-10-21
+
+- Neu: `site_edit_html {find, replace, region?, scope?, pages?}` – Markup-Fragment (z. B. Footer) über alle Seiten in EINEM
+  Aufruf ersetzen, ein Rückgängig-Schritt; mehrere Fundstellen ohne `scope:"all"` → nur Liste. Rechtstext-Bereich, Skript-Regeln
+  und das ProntoSite-Badge geschützt (`skipped`).
+- Badge-Sperre: `site_edit_text`, `site_edit_html` und `site_file_put` ändern, entfernen oder bauen das Badge (`data-ps="badge"`)
+  nicht nach – es wird beim Ausliefern erzeugt; Änderungen daneben und das Wiederherstellen des Original-Markers bleiben erlaubt.
+- Rate-Limit (429): Meldung nennt die Rest-Wartezeit und den richtigen Weg (statt allgemeinem Text). Schreib-Limit je Token/Grant
+  und Konto: Betreuer 200, Kunden 30 Aufrufe je 10 Minuten.
+- Instructions: Markup über alle Seiten per `site_edit_html`, nie Seite für Seite per `site_file_put`; Badge nie im HTML ändern.
+
 ## 0.13.7 – 2026-10-20
 
 - Neu: `site_forms_get` – Konto-Empfänger, je Formular Art (verwaltetes ProntoSite-Formular oder eigenes `<form>` aus dem

package/api.mjs

@@ -115,8 +115,8 @@ export function friendlyApiError(status, serverError = "") {
     return "Dein API-Token ist ungültig oder abgelaufen. Token im Dashboard → API-Zugang neu erstellen und in ~/.prontosite.json eintragen.";
   if (status === 403 && /API-Zugang nicht im Tarif|Starter-Plan/i.test(raw))
     return "Dein ProntoSite-Tarif enthält keinen API-Zugang. Wähle im Dashboard → Zahlung einen Tarif oder bitte deinen Betreuer um eine API-Freigabe.";
-  if (status === 429)
-    return "Zu viele Anfragen in kurzer Zeit (Rate-Limit). Bitte einen Moment warten und erneut versuchen.";
+  if (status === 429)   // Server nennt Wartezeit + richtigen Weg → durchreichen; sonst allgemeiner Hinweis
+    return /wieder möglich in/.test(raw) ? raw : "Zu viele Anfragen in kurzer Zeit (Rate-Limit). Bitte einen Moment warten und erneut versuchen.";
   return raw || `HTTP ${status}`;
 }
 
@@ -402,6 +402,15 @@ export async function apiEditText(cfg, { site, find, replace, scope = null, regi
     method: "POST", headers: { ...authHeaders(token, cfg), "content-type": "application/json" }, body: JSON.stringify(body) }));
 }
 
+/** POST /api/edit-html/<site> – Markup-Fragment über alle Seiten ersetzen (z. B. Footer), EIN Undo-Eintrag. 409 als Objekt. */
+export async function apiEditHtml(cfg, { site, find, replace, scope = null, region = null, pages = null, baseRev = null } = {}, fetchImpl = fetch) {
+  const { token, slug } = resolveTarget(cfg, site);
+  const body = { find, replace, ...(scope ? { scope } : {}), ...(region ? { region } : {}),
+    ...(Array.isArray(pages) && pages.length ? { pages } : {}), ...(Number.isInteger(baseRev) ? { baseRev } : {}) };
+  return asJsonOr409(await fetchImpl(`${baseUrl(cfg)}/edit-html/${encodeURIComponent(slug)}`, {
+    method: "POST", headers: { ...authHeaders(token, cfg), "content-type": "application/json" }, body: JSON.stringify(body) }));
+}
+
 /** GET /api/page-texts/<site>?page= – alle Texte einer Seite (Textknoten, reine Text-Links, Attribute, Titel/Beschreibung). */
 export async function apiPageTexts(cfg, { site, page } = {}, fetchImpl = fetch) {
   const { token, slug } = resolveTarget(cfg, site);
@@ -551,6 +560,18 @@ export async function apiMediaRestore(cfg, { site, trashId } = {}, fetchImpl = f
   return asJson(await fetchImpl(`${baseUrl(cfg)}/media-restore/${encodeURIComponent(slug)}`, {
     method: "POST", headers: { ...authHeaders(token, cfg), "content-type": "application/json" }, body: JSON.stringify({ trashId }) }));
 }
+/** GET /api/media-search/<site>?query=&orientation=&count= – Unsplash-Treffer (Vorschau base64, Fotograf, resultId). */
+export async function apiMediaSearch(cfg, { site, query, orientation = null, count = 3 } = {}, fetchImpl = fetch) {
+  const { token, slug } = resolveTarget(cfg, site);
+  const q = new URLSearchParams({ query: String(query ?? ""), count: String(count ?? 3), ...(orientation ? { orientation } : {}) });
+  return asJson(await fetchImpl(`${baseUrl(cfg)}/media-search/${encodeURIComponent(slug)}?${q}`, { headers: authHeaders(token, cfg) }));
+}
+/** POST /api/media-import/<site> – Unsplash-Treffer übernehmen (Download-Trigger, Varianten, Attribution) → mediaId. */
+export async function apiMediaImport(cfg, { site, resultId } = {}, fetchImpl = fetch) {
+  const { token, slug } = resolveTarget(cfg, site);
+  return asJson(await fetchImpl(`${baseUrl(cfg)}/media-import/${encodeURIComponent(slug)}`, {
+    method: "POST", headers: { ...authHeaders(token, cfg), "content-type": "application/json" }, body: JSON.stringify({ resultId }) }));
+}
 /** GET /api/preview-screenshot/<site>?page=&width= – PNG des Entwurfs (Base64 + Maße). */
 export async function apiPreviewScreenshot(cfg, { site, page = "index.html", width = 1280 } = {}, fetchImpl = fetch) {
   const { token, slug } = resolveTarget(cfg, site);

package/index.mjs

@@ -21,7 +21,7 @@ const cfg = loadConfig();
 // es im MCP-Log/Terminal auffällt; die endgültige Auflösung (Betreuer-Token-Vorrang vs. Map) klärt sites_list.
 for (const w of (cfg.warnings || [])) process.stderr.write("[prontosite-mcp] ⚠ " + w + "\n");
 // instructions: Arbeitsweise (Weg B = Standard) – gleicher Text wie am Remote-Endpunkt.
-const server = new McpServer({ name: "prontosite", version: "0.13.7" }, { instructions: instructionsFor("local") });
+const server = new McpServer({ name: "prontosite", version: "0.14.1" }, { instructions: instructionsFor("local") });
 // Tool-Definitionen: gemeinsame Quelle mit dem Remote-Endpunkt (tools.mjs, Konzept KI-Anbindung §4.2).
 registerTools(server, { z, cfg, mode: "local" });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prontosite/mcp",
-  "version": "0.13.7",
+  "version": "0.14.1",
   "description": "MCP-Server für ProntoSite – Website-Status, Export, Deploy und Veröffentlichen direkt aus einem KI-Assistenten (Claude Desktop). Dünner Client um die ProntoSite Deploy-API.",
   "type": "module",
   "bin": {

package/tools.mjs

@@ -9,7 +9,7 @@
  *                site_domain_connect nur mit Betreuer-Token (Entscheidung 9a).
  * `z` wird vom Aufrufer übergeben (dieselbe zod-Instanz wie sein MCP-SDK).
  */
-import { apiEditText, apiPageTexts, apiPageTextsSet, apiPageCopy, apiMediaUploadBegin, apiMediaUploadFile, apiMediaCommit, apiMediaList, apiImageSet, apiUndo, apiMediaDelete, apiMediaRestore, apiFormsGet, apiFormsSet, apiPreviewScreenshot, apiStatus, apiExport, apiExportFetch, apiDeploy, apiPublish, sitesList, apiAccountCreate, apiCompanyGet, apiCompanySet, apiLegalOptions, apiDomainStatus, apiDomainConnect, apiEmbeds, apiEmbedConsent, apiWidgets, apiWidgetSet, apiFiles, apiFileGet, apiFilePut, apiFileDelete, apiFileRename, apiLock } from "./api.mjs";
+import { apiEditText, apiEditHtml, apiPageTexts, apiPageTextsSet, apiPageCopy, apiMediaUploadBegin, apiMediaUploadFile, apiMediaCommit, apiMediaList, apiImageSet, apiUndo, apiMediaDelete, apiMediaRestore, apiFormsGet, apiFormsSet, apiMediaSearch, apiMediaImport, apiPreviewScreenshot, apiStatus, apiExport, apiExportFetch, apiDeploy, apiPublish, sitesList, apiAccountCreate, apiCompanyGet, apiCompanySet, apiLegalOptions, apiDomainStatus, apiDomainConnect, apiEmbeds, apiEmbedConsent, apiWidgets, apiWidgetSet, apiFiles, apiFileGet, apiFilePut, apiFileDelete, apiFileRename, apiLock } from "./api.mjs";
 
 /**
  * Arbeitsweise (MCP-`instructions` beim Initialize – lokal UND /mcp): Weg B ist der Standard (Nick 19.10.).
@@ -29,6 +29,9 @@ const instructionLines = mode => [
   "2a. Für Text-, Link- und Kontaktdaten-Änderungen (Telefonnummer, E-Mail, Adresse, Öffnungszeiten) IMMER site_edit_text mit "
     + "scope:\"all\" (bei Bedarf region:\"footer\"/\"header\") – EIN Aufruf für alle Seiten, inkl. tel:/mailto:-Links. NIE Seite für Seite per "
     + "site_file_put. Meldet die Antwort company, zusätzlich site_company_set für die Firmendaten (Impressum/Datenschutz/Kontakt).",
+  "2c. Für Markup über alle Seiten (z. B. Footer-HTML) site_edit_html mit scope:\"all\" (ggf. region:\"footer\"), nie Seite für Seite per site_file_put. "
+    + "Schreib-Limit je 10 Minuten: Kunden 30, Betreuer 200 Aufrufe – dieselbe Änderung auf vielen Seiten ist EIN Aufruf (site_edit_text scope:\"all\" bzw. site_edit_html).",
+  "2d. Badge nie im HTML ändern, nachbauen oder entfernen – es wird beim Ausliefern erzeugt (data-ps=\"badge\"; site_edit_text/site_edit_html/site_file_put lehnen das ab, erlaubt ist nur das Wiederherstellen des Original-Markers).",
   "2b. Für Übersetzungen und Textüberarbeitung: site_page_texts → Texte übersetzen/überarbeiten → site_page_texts_set, JE SEITE ein Aufruf "
     + "(neue Sprachfassung vorher mit site_page_copy, z. B. index.html → en/index.html). NIE HTML über site_file_put umschreiben. "
     + "Rechtstext-Seiten (Impressum/Datenschutz) sind ausgenommen.",
@@ -40,6 +43,9 @@ const instructionLines = mode => [
     + "media_upload_commit und mit site_image_set einsetzen. Nie Varianten selbst bauen, nie ZIP für Medien.",
   ...(mode === "local" ? ["5a-lokal. Wenn du einen lokalen Dateipfad hast, nutze media_upload_file; sonst Upload-Link (media_upload_begin). "
     + "media_upload_file prüft, lädt hoch und übernimmt in einem Schritt und liefert die mediaId."] : []),
+  "5e. Bei „passendes Bild für Abschnitt X\": Abschnittstext lesen (site_page_texts), Suchbegriff bilden, media_search, dem Nutzer 2–3 "
+    + "Vorschauen zeigen und wählen lassen, dann media_import + site_image_set + site_preview_screenshot. Fotos NIE per URL von Unsplash "
+    + "oder anderen Bilddiensten (images.unsplash.com, imgix …) ins HTML/CSS schreiben – sonst lädt jeder Besucher beim Dienst; immer media_import.",
   "5b. Design = CSS-Datei ändern (site_file_get/site_file_put), nicht HTML umschreiben. Nach Design- oder Bild-Änderungen "
     + "site_preview_screenshot (1280 bzw. 390) prüfen, BEVOR du dem Nutzer antwortest.",
   "5c. Bei „rückgängig“ site_undo (bzw. „doch wieder“ site_redo), nie Dateien manuell zurückbauen. Medien löschen nur mit site_media_delete "
@@ -54,10 +60,10 @@ export const SERVER_INSTRUCTIONS = instructionsFor("remote");
 // Tool-Annotationen (MCP ToolAnnotations): ChatGPT & Co. fragen sonst bei JEDEM Aufruf nach. readOnly = ändert nichts;
 // destructive = live/kundenwirksam, ersetzt Bestand oder nimmt zurück (Bestätigung sinnvoll). Entwurfs-Änderungen sind
 // rückgängig machbar und daher nicht destruktiv. openWorld = wirkt nach außen (öffentliche Website/DNS).
-const READ_ONLY = new Set(["sites_list", "site_status", "site_forms_get", "site_page_texts", "site_media_list", "site_preview_screenshot", "site_company_get",
+const READ_ONLY = new Set(["sites_list", "site_status", "site_forms_get", "media_search", "site_page_texts", "site_media_list", "site_preview_screenshot", "site_company_get",
   "site_domain_status", "site_embeds", "site_widgets", "site_files", "site_file_get"]);
 const DESTRUCTIVE = new Set(["site_publish", "site_deploy", "deploy_commit", "site_file_delete", "site_media_delete", "site_undo", "site_redo", "site_domain_connect"]);
-const OPEN_WORLD = new Set(["site_publish", "site_deploy", "deploy_commit", "site_domain_connect"]);
+const OPEN_WORLD = new Set(["site_publish", "site_deploy", "deploy_commit", "site_domain_connect", "media_search", "media_import"]);
 export function toolAnnotations(name, mode = "local") {
   // site_export: remote nur ein Download-Link (lesend), lokal schreibt es eine ZIP auf die Platte.
   const ro = READ_ONLY.has(name) || (name === "site_export" && mode === "remote");
@@ -165,6 +171,22 @@ export function registerTools(server0, { z, cfg, mode = "local", remote = null }
     async ({ site, find, replace, scope, region, attributes, pages, baseRev }) => { try { return asText(await apiEditText(cfg, { site, find, replace, scope, region, attributes, pages, baseRev })); } catch (e) { return asError(e); } }
   );
 
+  server.tool(
+    "site_edit_html",
+    "SCHREIBEND (Entwurf, nicht live) – Markup-Fragment über ALLE Seiten in EINEM Aufruf ersetzen (z. B. Footer-HTML: neuer Link, "
+      + "Social-Icons, Zeile ergänzen). Sucht `find` wörtlich im Quelltext (wie site_file_get) innerhalb von region (footer | header | "
+      + "main | all) und ersetzt durch `replace` – EIN Rückgängig-Schritt für alle Seiten. scope:\"all\" = alle Fundstellen ersetzen; ohne "
+      + "scope ändert der Server bei mehr als einer Fundstelle NICHTS und liefert die Liste (oder pages:[…]). Für reinen Text nimm "
+      + "site_edit_text. Rechtstext-Bereich, Skripte (Regeln wie site_file_put) und das ProntoSite-Badge sind geschützt (skipped).",
+    { site: z.string().optional().describe(SITE_DESC),
+      find: z.string().describe("Exaktes Markup, wie es im Quelltext steht (aus site_file_get kopieren)."),
+      replace: z.string().describe("Neues Markup."),
+      region: z.enum(["all", "header", "main", "footer"]).optional().describe("Nur in diesem Bereich suchen (erstes <footer>/<header>/<main> je Seite)."),
+      scope: z.enum(["all"]).optional().describe("\"all\" = alle Fundstellen auf allen (bzw. den gewählten) Seiten ersetzen."),
+      pages: z.array(z.string()).optional().describe("Nur diese Seiten (ID, Datei oder Slug)."),
+      baseRev: z.number().int().optional().describe("Optional: draftRev aus site_status (Konfliktschutz).") },
+    async (a) => { try { return asText(await apiEditHtml(cfg, a)); } catch (e) { return asError(e); } }
+  );
   server.tool(
     "site_page_texts",
     "LESEND – STANDARDWEG für Übersetzung/Umformulierung: liefert ALLE Texte einer Seite ohne HTML: [{id, role, text, markdown?}] – "
@@ -232,6 +254,32 @@ export function registerTools(server0, { z, cfg, mode = "local", remote = null }
     { site: z.string().optional().describe(SITE_DESC), uploadId: z.string().describe("uploadId aus media_upload_begin.") },
     async ({ site, uploadId }) => { try { return asText(await apiMediaCommit(cfg, { site, uploadId })); } catch (e) { return asError(e); } }
   );
+  server.tool(
+    "media_search",
+    "Kostenlose Fotos von Unsplash suchen (verbraucht ein gemeinsames Stunden-Kontingent; gleiche Suchen kommen 1 h aus dem Cache). "
+      + "Liefert je Treffer eine kleine Vorschau als Bild, Fotograf, Lizenz-Hinweis und eine resultId (1 h gültig). Suchbegriff am besten "
+      + "englisch und konkret (z. B. 'bakery counter bread'). Dem Nutzer 2–3 Vorschauen zeigen und wählen lassen, dann media_import "
+      + "(nie die Unsplash-URL direkt einbinden).",
+    { site: z.string().optional().describe(SITE_DESC), query: z.string().describe("Suchbegriff (2–120 Zeichen)."),
+      orientation: z.enum(["landscape", "portrait", "squarish"]).optional().describe("Ausrichtung: landscape (Hero/Banner), portrait, squarish."),
+      count: z.number().int().min(1).max(6).default(3).describe("Anzahl Treffer (max. 6).") },
+    async ({ site, query, orientation, count }) => {
+      try {
+        const r = await apiMediaSearch(cfg, { site, query, orientation, count });
+        const images = (r.results || []).filter(x => x.preview?.data).map(x => ({ type: "image", data: x.preview.data, mimeType: x.preview.mimeType || "image/jpeg" }));
+        const text = { ...r, results: (r.results || []).map((x, i) => ({ nr: i + 1, ...x, preview: x.preview ? "(Bild unten)" : null })) };
+        return { content: [{ type: "text", text: JSON.stringify(text, null, 2) }, ...images] };
+      } catch (e) { return asError(e); }
+    }
+  );
+  server.tool(
+    "media_import",
+    "SCHREIBEND: einen Unsplash-Treffer aus media_search übernehmen – der Server lädt das Foto (Download-Trigger laut Unsplash-Richtlinie), "
+      + "erzeugt Varianten, speichert Fotograf/Quelle in den Medien-Metadaten und liefert mediaId + vorbelegten alt-Text. Zählt aufs "
+      + "Medien-Kontingent. Danach site_image_set {mediaId, alt} und site_preview_screenshot.",
+    { site: z.string().optional().describe(SITE_DESC), resultId: z.string().describe("resultId aus media_search (1 h gültig).") },
+    async ({ site, resultId }) => { try { return asText(await apiMediaImport(cfg, { site, resultId })); } catch (e) { return asError(e); } }
+  );
   server.tool(
     "site_media_list",
     "LESEND: Medien der Website (mediaId, Name, Typ, Größe, Maße; Uploads und Bilder der importierten Website) und das Medien-Kontingent; trash = Papierkorb (trashId für site_media_restore).",