story-theme-mcp 1.0.0

package/src/server.js

@@ -0,0 +1,1350 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+import { loadTheme } from './theme/loader.js';
+import { Catalog, normalizeText, templateTypeOf, isInternalTemplate } from './theme/catalog.js';
+import { validateFile, fileKind } from './validate/template.js';
+import { lintTemplate, lintSettings, sampleTexts } from './validate/design.js';
+import { plainText } from './validate/richtext.js';
+import { collectTexts } from './build/texts.js';
+import { contrast, parseColor, round2, auditSchemes } from './validate/color.js';
+import { sectionFromPreset, blockFromPreset } from './build/scaffold.js';
+import { applyOperations, outline } from './build/edit.js';
+import { buildFromRecipe } from './build/recipe.js';
+import { localizeData } from './build/localize.js';
+import { generateColorSchemes } from './build/palette.js';
+import { buildStore, STYLES, BRAND_PAGES } from './build/quick.js';
+import { composeSections } from './build/compose.js';
+import { DIRECTIONS } from './knowledge/directions.js';
+import { ProjectStore, checkRelativePath } from './project/store.js';
+import { localSource } from './theme/source.js';
+import { reviewProject, formatReview, findSchemeReferences } from './project/review.js';
+import { exportTheme, importTheme, migrateProject } from './project/export.js';
+import { GUIDES, GUIDE_TOPICS } from './knowledge/guides.js';
+import { RECIPES, findRecipe } from './knowledge/recipes.js';
+import { FONT_PAIRINGS, searchFonts, checkFontHandle, fontInfo, FONT_LIBRARY } from './knowledge/fonts.js';
+import { ok, fail, parseContent, formatSettings, formatValidation, formatFindings } from './format.js';
+
+export { VERSION } from './version.js';
+import { VERSION } from './version.js';
+
+const INSTRUCTIONS = `Serveur MCP du Story Thème (thème Shopify premium de New Story). Il connaît chaque section, bloc, preset et réglage du thème, et fabrique des boutiques propres et professionnelles sous forme de thème à importer dans Shopify.
+
+Règle n°1 : AGIR D'ABORD, DEMANDER ENSUITE.
+- Dès la première demande, si vous savez de quelle boutique il s'agit (un nom, ou ce qu'elle vend), appelez build_store IMMÉDIATEMENT, sans poser de question avant. Déduisez le reste (style, ton) et rédigez les textes clés de la marque dans le paramètre copy. build_store livre une V1 complète en un seul appel : couleurs, polices, accueil, fiche produit, collection, pages, traduction, zip prêt à importer.
+- Une boutique qui claque a des PHOTOS. Si un connecteur Shopify est disponible, juste avant build_store : lisez les collections (image) et les produits (images), choisissez 3 à 6 belles photos (une large et lumineuse pour le héro, des photos en situation plutôt que des packshots ; notez leur largeur : celles de 1600 px ou plus vont dans images.large), copiez-les dans Contenu > Fichiers avec la mutation fileCreate (read_guide images donne la requête), puis passez leurs noms de fichiers dans images, et les handles des collections dans collections. Sans connecteur, build_store fait un héro typographique propre et n'affiche jamais de carré vide.
+- Une boutique BRANDÉE : choisissez une direction artistique (build_store direction : editorial, minimal, organique, artisan, douceur, pop, energie, tech) et remplissez copy au maximum : manifesto (s'illumine au défilement), rotating_words (mots qui tournent dans le titre), benefits (cartes empilées), process (étapes), story_steps et values (page Notre histoire), usage_steps, tips et usage_faq (page Comment utiliser, adaptée au produit). Titres avec **mot fort** en gras.
+- Pour aller au-delà des recettes (page ingrédients, lookbook, guide cadeau, comparatif, landing), utilisez compose_page : toutes les sections du thème sont disponibles (read_guide signatures).
+- Ne retirez jamais une section sans la remplacer par une section honnête (bénéfices, FAQ, liste de produits, bandeau défilant, collections) : l'accueil garde 8 à 10 sections.
+- La seule question autorisée avant d'agir : « Pour quelle boutique ? », si la demande ne donne ni nom ni activité.
+- Après la V1 : résumez en quelques lignes ce qui a été fait et les choix supposés, donnez le chemin du zip, puis posez 3 à 5 questions pour affiner (celles que renvoie build_store).
+- Ensuite, chaque demande du marchand s'applique au projet en cours (inutile de préciser project) : edit_template, update_theme_settings, apply_recipe, puis export_theme pour un nouveau zip.
+
+Honnêteté : n'inventez ni avis, ni note, ni chiffres, ni presse, ni labels. Pour les conditions (livraison, retours), restez général ou reprenez celles données par le marchand ; la revue signale ce qui reste à confirmer.
+
+Le thème vient de l'espace membre Story Thème : toujours la dernière version publiée. Si le marchand parle d'une nouvelle version, ou si une section semble manquer, appelez theme_source (update: true).
+
+Garde-fous : aucun type de section/bloc ni identifiant de réglage inventé (get_section, get_block, search_theme donnent les vrais) ; tout fichier est validé contre les schémas du thème et un fichier invalide n'est jamais enregistré ; undo annule la dernière modification. Le MCP ne touche ni au code du thème ni à une boutique en ligne. Si un connecteur Shopify est disponible, servez-vous-en pour lire le nom de la boutique, ses collections et ses produits réels, et passez leurs handles à build_store.
+
+Répondez au marchand dans sa langue, en vouvoyant en français, brièvement.`;
+
+function createContext(config) {
+  // La source dit OÙ est le thème : un dossier local en développement, la dernière version
+  // publiée sur le dashboard chez un client (src/theme/source.js). Elle peut changer de dossier
+  // en cours de route (mise à jour du thème) : on relit `source.dir` à chaque appel.
+  const source = config.source || localSource(config.themeDir);
+  let catalog = null;
+  let store = null;
+  let loadedFrom = null;
+  let loadedAt = 0;
+  let checkedAt = 0;
+
+  const newestSchemaChange = (dir) => {
+    let newest = 0;
+    for (const folder of ['sections', 'blocks', 'config', 'locales', 'templates']) {
+      const full = path.join(dir, folder);
+      if (!fs.existsSync(full)) continue;
+      for (const name of fs.readdirSync(full)) {
+        const stat = fs.statSync(path.join(full, name));
+        if (stat.mtimeMs > newest) newest = stat.mtimeMs;
+      }
+    }
+    return newest;
+  };
+
+  return {
+    config,
+    source,
+    get() {
+      const dir = source.dir || config.themeDir;
+      const now = Date.now();
+      if (catalog && dir !== loadedFrom) catalog = null;
+      if (catalog && now - checkedAt > 10000) {
+        checkedAt = now;
+        if (newestSchemaChange(dir) > loadedAt) catalog = null;
+      }
+      if (!catalog) {
+        loadedAt = Date.now();
+        checkedAt = loadedAt;
+        loadedFrom = dir;
+        catalog = new Catalog(loadTheme(dir));
+        store = new ProjectStore({ homeDir: config.homeDir, catalog });
+      }
+      return { catalog, store };
+    },
+  };
+}
+
+const run = (handler) => async (args) => {
+  try {
+    return await handler(args || {});
+  } catch (error) {
+    return fail(error.message);
+  }
+};
+
+const languageOf = (ctx, args, project = null) => args.language || project?.language || ctx.config.defaultLanguage;
+
+function presetOutlines(catalog, kind, type, language) {
+  const entry = kind === 'section' ? catalog.section(type) : catalog.block(type);
+  return (entry?.schema?.presets || []).map((preset, index) => {
+    const name = catalog.t(preset.name, language);
+    try {
+      if (kind === 'section') {
+        const { id, section } = sectionFromPreset(catalog, type, { preset: index, language });
+        return `### Preset « ${name} » (${catalog.t(preset.name, 'en')})\n${outline(catalog, { sections: { [id]: section }, order: [id] }, { language }).split('\n').slice(1).join('\n')}`;
+      }
+      const { id, block } = blockFromPreset(catalog, type, { preset: index, language });
+      return `### Preset « ${name} »\n${outline(catalog, { sections: { s: { type: 'advanced-custom-section', blocks: { [id]: block }, block_order: [id] } }, order: ['s'] }, { language }).split('\n').slice(2).join('\n')}`;
+    } catch (error) {
+      return `### Preset « ${name} » : ${error.message}`;
+    }
+  });
+}
+
+function schemeIdsFor(store, slug) {
+  const settings = store.read(slug, 'config/settings_data.json').data;
+  const current = typeof settings?.current === 'string' ? settings.presets?.[settings.current] : settings?.current;
+  return Object.keys(current?.color_schemes || {});
+}
+
+function fileReport(catalog, store, slug, file, data, language) {
+  const validation = validateFile(catalog, file, data, { schemeIds: schemeIdsFor(store, slug) });
+  const design = file === 'config/settings_data.json' ? lintSettings(catalog, data) : lintTemplate(catalog, file, data, { language });
+  return { validation, design };
+}
+
+const BRIEF = z
+  .object({
+    brand: z.string().optional().describe('Nom de la marque'),
+    activity: z.string().optional().describe('Ce que la boutique vend'),
+    audience: z.string().optional().describe('Clients visés'),
+    positioning: z.string().optional().describe('Gamme de prix, positionnement (premium, accessible…)'),
+    tone: z.string().optional().describe('Ton : vouvoiement/tutoiement, 3 adjectifs'),
+    brand_colors: z.array(z.string()).optional().describe('Couleurs de marque en #RRGGBB'),
+    fonts: z.string().optional().describe('Polices imposées ou style souhaité'),
+    inspirations: z.string().optional().describe('Boutiques ou marques d’inspiration'),
+    collections: z.array(z.string()).optional().describe('Handles des collections existantes ou prévues'),
+    key_products: z.array(z.string()).optional().describe('Handles des produits phares'),
+    proofs: z.string().optional().describe('Preuves réelles disponibles : note moyenne, nombre d’avis, presse, labels, chiffres'),
+    shipping_returns: z.string().optional().describe('Conditions réelles : délais, seuil de livraison offerte, retours'),
+    offers: z.string().optional().describe('Offres réelles (paliers, lots, code de bienvenue)'),
+    pages: z.array(z.string()).optional().describe('Pages voulues (à propos, contact, FAQ, suivi…)'),
+    notes: z.string().optional(),
+  })
+  .passthrough();
+
+const PROJECT = z.string().optional().describe('Projet (par défaut : le projet en cours)');
+
+const COPY = z
+  .object({
+    tagline: z.string().optional().describe('Promesse du héro, 3 à 8 mots (devient le <h1> de l’accueil)'),
+    hero_text: z.string().optional().describe('Une phrase sous la promesse'),
+    hero_button: z.string().optional().describe('Bouton du héro, 2 à 4 mots'),
+    announcements: z.array(z.string()).optional().describe('1 à 3 messages courts de la barre d’annonce'),
+    reassurance: z.array(z.string()).optional().describe('3 ou 4 arguments courts (livraison, retours, fabrication…), repris dans le bandeau défilant et les listes à puces'),
+    brand_story_title: z.string().optional(),
+    brand_story_text: z.string().optional().describe('2 ou 3 phrases vraies sur la marque'),
+    benefits: z.array(z.object({ title: z.string(), text: z.string().optional() })).optional().describe('3 ou 4 bénéfices produits'),
+    faq: z.array(z.object({ question: z.string(), answer: z.string() })).optional().describe('4 à 6 questions/réponses ; conditions données par le marchand ou formulations générales'),
+    newsletter_title: z.string().optional(),
+    newsletter_text: z.string().optional(),
+    manifesto: z.string().optional().describe('Manifeste de marque en 1 ou 2 phrases fortes : s’illumine mot à mot au défilement (accueil et Notre histoire)'),
+    rotating_words: z.array(z.string()).optional().describe('3 à 5 mots qui tournent dans le titre du héro, placés à la fin du titre (ex. tenue, humeur, occasion)'),
+    benefits_title: z.string().optional().describe('Titre au-dessus des bénéfices (cartes empilées)'),
+    process: z.array(z.object({ title: z.string(), text: z.string().optional(), icon: z.string().optional() })).optional().describe('3 à 5 étapes de fabrication ou de préparation (direction organique / artisanale)'),
+    process_title: z.string().optional(),
+    story_title: z.string().optional().describe('Titre de la page Notre histoire'),
+    story_intro: z.string().optional(),
+    story_steps: z.array(z.object({ label: z.string().optional(), title: z.string(), text: z.string().optional() })).optional().describe('Étapes réelles de l’histoire (dates ou moments) : frise de la page Notre histoire'),
+    values: z.array(z.object({ title: z.string(), text: z.string().optional(), icon: z.string().optional() })).optional().describe('3 ou 4 valeurs ou engagements réels'),
+    usage_title: z.string().optional().describe('Titre de la page Comment utiliser, ex. « Comment porter votre chouchou »'),
+    usage_intro: z.string().optional(),
+    usage_steps: z.array(z.object({ title: z.string(), text: z.string().optional(), icon: z.string().optional() })).optional().describe('3 à 5 étapes d’utilisation du produit, concrètes'),
+    tips: z.array(z.object({ title: z.string(), text: z.string().optional() })).optional().describe('3 ou 4 astuces ou idées d’usage (cartes colorées)'),
+    usage_faq: z.array(z.object({ question: z.string(), answer: z.string() })).optional().describe('Questions sur l’utilisation, l’entretien, la taille'),
+    showcase_title: z.string().optional().describe('Phrase forte du grand visuel (zoom au défilement)'),
+    showcase_text: z.string().optional(),
+    details: z.array(z.object({ title: z.string(), text: z.string() })).optional().describe('Détails produit réels : matières, utilisation, entretien (accordéons)'),
+    faq_intro: z.string().optional().describe('Une phrase sous le titre de la FAQ'),
+  })
+  .describe('Textes clés rédigés pour la marque, placés directement dans les pages');
+
+const POSITION = z
+  .union([z.number().int(), z.enum(['start', 'end']), z.object({ before: z.string() }), z.object({ after: z.string() })])
+  .optional()
+  .describe('Position : index, "start", "end", { before: id } ou { after: id }');
+
+const OPERATION = z
+  .object({
+    op: z.enum(['add_section', 'remove_section', 'move_section', 'duplicate_section', 'replace_section', 'update_settings', 'add_block', 'remove_block', 'move_block', 'set_disabled']),
+    type: z.string().optional().describe('add_section / add_block : type de section ou de bloc'),
+    preset: z.union([z.string(), z.number()]).optional().describe('Nom (français ou anglais) ou index du preset'),
+    id: z.string().optional().describe('Identifiant souhaité pour la nouvelle section / le nouveau bloc'),
+    section: z.string().optional().describe('remove/move/duplicate/replace_section : id de la section'),
+    target: z.string().optional().describe('update_settings, remove_block, move_block, set_disabled : "idSection" ou "idSection/idBloc/idSousBloc"'),
+    parent: z.string().optional().describe('add_block : "idSection" ou "idSection/idBloc" du conteneur'),
+    settings: z.record(z.string(), z.any()).optional().describe('Réglages { id: valeur } ; null supprime un réglage'),
+    mode: z.enum(['merge', 'replace']).optional().describe('update_settings : merge (défaut) ou replace'),
+    position: POSITION,
+    disabled: z.boolean().optional(),
+    data: z.record(z.string(), z.any()).optional().describe('replace_section : section complète'),
+  })
+  .passthrough();
+
+export function createServer(config) {
+  const ctx = createContext(config);
+  const server = new McpServer({ name: 'story-theme', version: VERSION }, { instructions: INSTRUCTIONS });
+  const readOnly = { readOnlyHint: true, openWorldHint: false };
+  const writes = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+
+  // ---------------------------------------------------------------- knowledge
+
+  server.registerTool(
+    'get_started',
+    {
+      title: 'Démarrer',
+      description: 'START HERE. Theme version, method to build a professional store with Story Theme, the tools in order, and existing projects.',
+      annotations: readOnly,
+    },
+    run(() => {
+      const { catalog, store } = ctx.get();
+      const sections = catalog.sectionTypes.filter((type) => catalog.section(type).schema);
+      const publicBlocks = catalog.blockTypes.filter((type) => !catalog.isPrivate(type));
+      const projects = store.list();
+      const current = store.current();
+      return ok(
+        [
+          `# ${catalog.name} ${catalog.version}`,
+          current ? `Projet en cours : ${current} (les outils l'utilisent par défaut).` : 'Aucun projet en cours : build_store crée la boutique dès la première demande.',
+          ctx.source.info?.origin === 'dashboard'
+            ? `Thème : dernière version publiée sur l'espace membre${ctx.source.info.canal === 'test' ? ' (canal test)' : ''}. theme_source pour vérifier les mises à jour.`
+            : ctx.source.info?.origin === 'cache'
+              ? `Thème : cache local (${ctx.source.info.message || 'espace membre injoignable'}).`
+              : `Thème lu dans ${catalog.theme.dir}`,
+          `${sections.length} sections, ${publicBlocks.length} blocs publics et ${catalog.blockTypes.length - publicBlocks.length} blocs privés, ${RECIPES.length} recettes de pages, langues de l'éditeur : ${catalog.languages.join(', ')}.`,
+          '',
+          'Pour une nouvelle boutique : build_store tout de suite (V1 complète en un appel), questions ensuite.',
+          '',
+          GUIDES.demarrage.body,
+          '',
+          '## Outils',
+          '- Connaître le thème : search_theme, list_sections, get_section, list_blocks, get_block, get_theme_settings, get_theme_template, read_guide',
+          '- Concevoir : recipes, generate_color_schemes, check_contrast, find_fonts',
+          '- Construire vite : build_store (V1 complète en un appel), compose_page (pages originales avec toutes les sections), read_guide signatures',
+          '- Construire : create_project, update_brief, apply_recipe, localize_template, list_texts, edit_template, write_file, update_theme_settings, read_file, exclude_template',
+          '- Contrôler : validate_json, review_project, undo, revert_file',
+          '- Livrer : export_theme (zip + check-list) ; import_theme pour auditer un thème exporté d’une boutique',
+          `Guides : ${GUIDE_TOPICS.join(', ')}`,
+          '',
+          `## Projets (${projects.length})`,
+          projects.length ? projects.map((project) => `- ${project.slug} — ${project.name} (${project.language}, modifié ${project.updated_at?.slice(0, 10)})`).join('\n') : 'Aucun projet pour le moment.',
+        ].join('\n'),
+      );
+    }),
+  );
+
+  server.registerTool(
+    'theme_source',
+    {
+      title: 'Source du thème',
+      description:
+        'Which Story Theme version the MCP is working on and where it comes from (member area dashboard, local cache, or local folder). `update: true` asks the member area for the latest published version and downloads it if it changed. Use it when the merchant mentions a new theme version, or when a section seems missing.',
+      inputSchema: {
+        update: z.boolean().optional().describe('Interroger l’espace membre maintenant et télécharger la dernière version publiée si elle a changé'),
+        force: z.boolean().optional().describe('Retélécharger la version même si elle est déjà en cache (cache abîmé)'),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    run(async ({ update = false, force = false }) => {
+      const source = ctx.source;
+      let changed = false;
+      let erreur = null;
+      if (update || force) {
+        try {
+          const resultat = await source.ensure({ force, timeoutMs: 15000 });
+          changed = Boolean(resultat.changed);
+        } catch (error) {
+          erreur = error.message;
+        }
+      }
+      const { catalog } = ctx.get();
+      const info = source.info || {};
+      const origine = {
+        dashboard: 'dernière version publiée sur l’espace membre Story Thème',
+        cache: 'cache local (espace membre injoignable)',
+        local: 'dossier local (STORY_THEME_DIR)',
+      }[info.origin] || 'dossier local';
+
+      return ok(
+        [
+          `# ${catalog.name} ${catalog.version}`,
+          `Origine : ${origine}`,
+          info.version && info.version !== catalog.version ? `Version annoncée par l’espace membre : ${info.version}` : null,
+          info.canal === 'test' ? 'Canal : version EN TEST (compte testeur).' : null,
+          `Dossier : ${info.dir || config.themeDir}`,
+          info.message,
+          changed ? `✅ Thème mis à jour en ${info.version} : les sections et réglages connus du MCP viennent de cette version.` : null,
+          // Une vérification qui retombe sur le cache n'est pas une vérification : dire « déjà
+          // à jour » alors que l'espace membre n'a pas répondu ferait chercher ailleurs.
+          update && !changed && !erreur && info.origin === 'cache'
+            ? '⚠️ Impossible de vérifier : le MCP travaille sur le thème en cache. Réessayez connecté.'
+            : null,
+          update && !changed && !erreur && info.origin !== 'cache' ? 'Déjà à jour : aucune version plus récente publiée.' : null,
+          erreur ? `⚠️ Mise à jour impossible : ${erreur}` : null,
+          !config.token && !config.themeDirExplicit
+            ? '\nAucun jeton configuré : ajoutez STORY_MCP_TOKEN (espace membre Story Thème > MCP & Appli) pour suivre automatiquement les versions publiées.'
+            : null,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+      );
+    }),
+  );
+
+  server.registerTool(
+    'read_guide',
+    {
+      title: 'Lire un guide',
+      description: `Read a Story Theme guide (French). Topics: ${GUIDE_TOPICS.join(', ')}.`,
+      inputSchema: { topic: z.enum(GUIDE_TOPICS) },
+      annotations: readOnly,
+    },
+    run(({ topic }) => ok(`# ${GUIDES[topic].title}\n\n${GUIDES[topic].body}`)),
+  );
+
+  server.registerTool(
+    'search_theme',
+    {
+      title: 'Chercher dans le thème',
+      description: 'Full-text search (French or English, accents optional) across sections, blocks, presets, settings, global settings, guides and recipes. Use it to find how the theme does something ("compte à rebours", "livraison offerte", "avant après").',
+      inputSchema: {
+        query: z.string().min(2),
+        kind: z.enum(['any', 'section', 'block', 'setting', 'global_setting', 'guide', 'recipe']).optional(),
+        limit: z.number().int().min(1).max(60).optional(),
+      },
+      annotations: readOnly,
+    },
+    run(({ query, kind = 'any', limit = 20 }) => {
+      const { catalog } = ctx.get();
+      const extra = [
+        ...GUIDE_TOPICS.map((topic) => ({ kind: 'guide', key: topic, title: GUIDES[topic].title, titleText: normalizeText(GUIDES[topic].title), text: normalizeText(GUIDES[topic].body) })),
+        ...RECIPES.map((recipe) => ({ kind: 'recipe', key: recipe.id, title: recipe.title, titleText: normalizeText(recipe.title), text: normalizeText(`${recipe.for} ${recipe.why} ${recipe.steps.map((step) => `${step.type} ${step.preset} ${step.role}`).join(' ')}`) })),
+      ];
+      const results = catalog.search(query, { kinds: kind === 'any' ? null : [kind], limit, extra });
+      if (!results.length) return ok(`Aucun résultat pour « ${query} ». Essayez un synonyme, ou list_sections / list_blocks.`);
+      return ok(results.map((result) => `- [${result.kind}] ${result.key} — ${result.title}`).join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'list_sections',
+    {
+      title: 'Lister les sections',
+      description: 'List the sections you can place, with their presets and what they are for. Filter by template type (index, product, collection, page…) or section group (header, footer).',
+      inputSchema: {
+        template: z.string().optional().describe('Type de modèle : index, product, collection, page, cart, search, blog, article, 404, password, list-collections, customers/account…'),
+        group: z.string().optional().describe('Groupe de sections : header, footer'),
+        language: z.string().optional(),
+      },
+      annotations: readOnly,
+    },
+    run(({ template, group, language }) => {
+      const { catalog } = ctx.get();
+      const lang = languageOf(ctx, { language });
+      const placement = template ? { template } : group ? { group } : null;
+      const byCategory = new Map();
+      for (const type of catalog.sectionTypes) {
+        const entry = catalog.section(type);
+        if (!entry.schema) continue;
+        if (placement && !catalog.sectionAllowedIn(entry.schema, placement)) continue;
+        const summary = catalog.sectionSummary(type, lang);
+        const category = summary.presets[0]?.category || (type.startsWith('main-') ? 'Pages principales' : 'Autres');
+        if (!byCategory.has(category)) byCategory.set(category, []);
+        const presets = summary.presets.map((preset) => preset.name).join(' ; ');
+        byCategory.get(category).push(`- ${type} — ${summary.name}${presets ? ` · presets : ${presets}` : ' · sans preset'}${summary.use_for ? ` · ${summary.use_for}` : ''}`);
+      }
+      const lines = [`Sections${placement ? ` autorisées (${template ? `modèle ${template}` : `groupe ${group}`})` : ''} :`];
+      for (const [category, items] of byCategory) lines.push(`\n## ${category}\n${items.join('\n')}`);
+      lines.push('\nDétail, réglages et contenu des presets : get_section.');
+      return ok(lines.join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'get_section',
+    {
+      title: 'Détail d’une section',
+      description: 'Everything about one section: purpose, where it is allowed, accepted blocks, static blocks, every preset as a block tree (in the chosen language), and its settings (ids, types, options, ranges, defaults). Read this before adding or editing a section.',
+      inputSchema: {
+        type: z.string(),
+        detail: z.enum(['summary', 'presets', 'settings', 'full']).optional().describe('summary, presets, settings, ou full (défaut)'),
+        language: z.string().optional(),
+      },
+      annotations: readOnly,
+    },
+    run(({ type, detail = 'full', language }) => {
+      const { catalog } = ctx.get();
+      const lang = languageOf(ctx, { language });
+      const summary = catalog.sectionSummary(type, lang);
+      if (!summary) {
+        const hint = catalog.search(type, { kinds: ['section'], limit: 5 }).map((result) => result.key);
+        throw new Error(`section « ${type} » inconnue${hint.length ? ` (proches : ${hint.join(', ')})` : ''}. list_sections donne la liste.`);
+      }
+      const lines = [`# ${summary.name} (${type})`];
+      if (summary.description) lines.push(summary.description);
+      if (summary.use_for) lines.push(`Quand l’utiliser : ${summary.use_for}`);
+      lines.push(`Placement : ${summary.placement}${summary.limit ? ` · ${summary.limit} par page maximum` : ''}`);
+      lines.push(`Blocs acceptés : ${summary.children}`);
+      if (summary.static_blocks.length) lines.push(`Blocs statiques (id imposé) : ${summary.static_blocks.map((entry) => `${entry.type}#${entry.id}`).join(', ')}`);
+      if (detail === 'summary') {
+        lines.push(`Presets : ${summary.presets.map((preset) => `${preset.name} (${preset.name_en})`).join(' ; ') || 'aucun'}`);
+        return ok(lines.join('\n'));
+      }
+      if (detail === 'full' || detail === 'presets') {
+        const outlines = presetOutlines(catalog, 'section', type, lang);
+        lines.push('', outlines.length ? outlines.join('\n\n') : 'Aucun preset : partez d’un modèle du thème (get_theme_template) ou composez les blocs.');
+      }
+      if (detail === 'full' || detail === 'settings') {
+        lines.push('', `## Réglages de la section (${summary.settings_count})`, formatSettings(catalog.normalizeSettings(catalog.section(type).schema.settings, lang)));
+      }
+      return ok(lines.join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'list_blocks',
+    {
+      title: 'Lister les blocs',
+      description: 'List theme blocks. With `parent` (a section or block type), lists exactly what that parent accepts (public @theme blocks and its private blocks).',
+      inputSchema: {
+        parent: z.string().optional().describe('Type de section ou de bloc parent'),
+        include_private: z.boolean().optional().describe('Inclure les blocs privés (préfixe _) sans parent donné'),
+        language: z.string().optional(),
+      },
+      annotations: readOnly,
+    },
+    run(({ parent, include_private = false, language }) => {
+      const { catalog } = ctx.get();
+      const lang = languageOf(ctx, { language });
+      let types;
+      let heading;
+      if (parent) {
+        const entry = catalog.section(parent) || catalog.block(parent);
+        if (!entry?.schema) throw new Error(`« ${parent} » n'est ni une section ni un bloc du thème`);
+        const policy = catalog.childPolicy(entry.schema);
+        types = catalog.acceptedChildTypes(entry.schema);
+        heading = `Blocs acceptés par « ${parent} »${policy.app ? ' (+ blocs d’applications)' : ''}${entry.statics.length ? ` · statiques : ${entry.statics.map((item) => `${item.type}#${item.id}`).join(', ')}` : ''}`;
+      } else {
+        types = catalog.blockTypes.filter((type) => include_private || !catalog.isPrivate(type));
+        heading = include_private ? 'Tous les blocs' : 'Blocs publics (utilisables dans toute section qui accepte @theme)';
+      }
+      const byCategory = new Map();
+      for (const type of types) {
+        const summary = catalog.blockSummary(type, lang);
+        if (!summary) continue;
+        const category = summary.private ? 'Blocs privés' : summary.category || 'Autres';
+        if (!byCategory.has(category)) byCategory.set(category, []);
+        byCategory.get(category).push(`- ${type} — ${summary.name}${summary.presets.length > 1 ? ` · presets : ${summary.presets.join(' ; ')}` : ''}${summary.children ? ' · contient des blocs' : ''}${summary.description ? ` · ${summary.description}` : ''}`);
+      }
+      const lines = [heading];
+      for (const [category, items] of byCategory) lines.push(`\n## ${category}\n${items.join('\n')}`);
+      return ok(lines.join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'get_block',
+    {
+      title: 'Détail d’un bloc',
+      description: 'Everything about one block: purpose, which parents accept it, its children, presets as trees, and every setting (ids, types, options, ranges, defaults).',
+      inputSchema: { type: z.string(), detail: z.enum(['summary', 'settings', 'full']).optional(), language: z.string().optional() },
+      annotations: readOnly,
+    },
+    run(({ type, detail = 'full', language }) => {
+      const { catalog } = ctx.get();
+      const lang = languageOf(ctx, { language });
+      const summary = catalog.blockSummary(type, lang);
+      if (!summary) {
+        const hint = catalog.search(type, { kinds: ['block'], limit: 5 }).map((result) => result.key);
+        throw new Error(`bloc « ${type} » inconnu${hint.length ? ` (proches : ${hint.join(', ')})` : ''}`);
+      }
+      const parents = catalog.parentsOf(type);
+      const explicit = parents.filter((parent) => parent.via === 'explicit').map((parent) => `${parent.kind === 'section' ? 'section' : 'bloc'} ${parent.type}`);
+      const lines = [`# ${summary.name} (${type})${summary.private ? ' — bloc privé' : ''}`];
+      if (summary.description) lines.push(summary.description);
+      lines.push(summary.private ? `Parents : ${explicit.join(', ') || 'aucun (bloc statique rendu par le code)'}` : `Parents : toute section ou tout bloc qui accepte @theme (${parents.length} au total)${explicit.length ? ` ; déclaré explicitement par ${explicit.join(', ')}` : ''}`);
+      if (summary.children) lines.push(`Blocs enfants : ${summary.children}`);
+      if (summary.static_blocks.length) lines.push(`Blocs statiques : ${summary.static_blocks.map((entry) => `${entry.type}#${entry.id}`).join(', ')}`);
+      if (detail !== 'settings') {
+        const outlines = presetOutlines(catalog, 'block', type, lang);
+        if (outlines.length) lines.push('', outlines.join('\n\n'));
+      }
+      if (detail !== 'summary') lines.push('', `## Réglages (${summary.settings_count})`, formatSettings(catalog.normalizeSettings(catalog.block(type).schema.settings, lang)));
+      return ok(lines.join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'get_theme_settings',
+    {
+      title: 'Réglages du thème',
+      description: 'Global theme settings (config/settings_schema.json): colours, typography, buttons, radius, cards, cart, social links… With `project`, also shows that project’s current values.',
+      inputSchema: {
+        group: z.string().optional().describe('Filtrer un groupe (ex. Typographie, Boutons, Panier)'),
+        project: z.string().optional(),
+        language: z.string().optional(),
+      },
+      annotations: readOnly,
+    },
+    run(({ group, project, language }) => {
+      const { catalog, store } = ctx.get();
+      const lang = languageOf(ctx, { language });
+      if (project) store.meta(project);
+      const current = project ? store.read(project, 'config/settings_data.json').data?.current : catalog.theme.settingsData?.current;
+      const lines = [];
+      for (const entry of catalog.theme.settingsSchema) {
+        if (entry.name === 'theme_info') continue;
+        const name = catalog.t(entry.name, lang);
+        if (group && !normalizeText(name).includes(normalizeText(group)) && !normalizeText(catalog.t(entry.name, 'en')).includes(normalizeText(group))) continue;
+        lines.push(`\n## ${name}`);
+        const settings = catalog.normalizeSettings(entry.settings, lang).map((setting) => {
+          if (setting.type === 'color_scheme_group') return { ...setting, definition: undefined, info: `palettes : ${Object.keys(current?.color_schemes || {}).join(', ')} — rôles : ${setting.definition.map((item) => item.id).join(', ')}` };
+          return setting;
+        });
+        lines.push(formatSettings(settings));
+        if (current) {
+          const values = settings.filter((setting) => current[setting.id] !== undefined && typeof current[setting.id] !== 'object').map((setting) => `${setting.id}=${JSON.stringify(current[setting.id])}`);
+          if (values.length) lines.push(`  valeurs ${project ? 'du projet' : 'du thème'} : ${values.join(', ')}`);
+        }
+      }
+      if (!lines.length) throw new Error(`aucun groupe ne correspond à « ${group} »`);
+      return ok(lines.join('\n').trim());
+    }),
+  );
+
+  server.registerTool(
+    'get_theme_template',
+    {
+      title: 'Modèle du thème',
+      description: 'A template or section group as shipped with the theme (reference compositions). Without `file`, lists them.',
+      inputSchema: { file: z.string().optional().describe('ex. templates/product.json, sections/footer-group.json'), format: z.enum(['outline', 'json']).optional(), language: z.string().optional() },
+      annotations: readOnly,
+    },
+    run(({ file, format = 'outline', language }) => {
+      const { catalog } = ctx.get();
+      const all = [...catalog.theme.templates.keys(), ...catalog.theme.groups.keys()].filter((rel) => !isInternalTemplate(rel));
+      if (!file) return ok(`Modèles du thème :\n${all.map((rel) => `- ${rel}`).join('\n')}`);
+      const data = catalog.theme.templates.get(file) || catalog.theme.groups.get(file);
+      if (!data) throw new Error(`« ${file} » n'existe pas dans le thème. Modèles : ${all.join(', ')}`);
+      if (format === 'json') return ok(JSON.stringify(data, null, 1));
+      return ok(`${outline(catalog, data, { language: languageOf(ctx, { language }), file })}\n\n(textes en anglais : ce sont les exemples livrés avec le thème)`);
+    }),
+  );
+
+  // ---------------------------------------------------------------- design
+
+  server.registerTool(
+    'recipes',
+    {
+      title: 'Recettes de pages',
+      description: 'Ready-made page compositions (home pages by business type, product pages, collection, about, contact, FAQ, tracking, landing) built only from theme presets. Without `id`: the list. With `id`: the steps and what each section must say.',
+      inputSchema: { id: z.string().optional(), template: z.string().optional().describe('Filtrer par fichier ou type (index, product, page…)') },
+      annotations: readOnly,
+    },
+    run(({ id, template }) => {
+      if (id) {
+        const recipe = findRecipe(id);
+        if (!recipe) throw new Error(`recette « ${id} » inconnue (recettes : ${RECIPES.map((item) => item.id).join(', ')})`);
+        return ok([
+          `# ${recipe.title} (${recipe.id}) → ${recipe.template}`,
+          `Pour : ${recipe.for}`,
+          `Pourquoi : ${recipe.why}`,
+          recipe.base ? `Base : ${recipe.base} du thème, sections ajoutées ensuite.` : '',
+          '',
+          ...recipe.steps.map((step, index) => `${index + 1}. ${step.type} · preset « ${step.preset} »${step.settings ? ` · ${JSON.stringify(step.settings)}` : ''}${step.blocks ? ` · + ${step.blocks.map((block) => block.type).join(', ')}` : ''}\n   → ${step.role}`),
+          '',
+          'apply_recipe construit ce modèle dans un projet ; réécrivez ensuite chaque texte pour la marque.',
+        ].filter((line) => line !== '').join('\n'));
+      }
+      const list = RECIPES.filter((recipe) => !template || recipe.template.includes(template));
+      return ok(list.map((recipe) => `- ${recipe.id} → ${recipe.template} · ${recipe.title} : ${recipe.for}`).join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'generate_color_schemes',
+    {
+      title: 'Générer les palettes',
+      description: 'Builds the four colour schemes the theme uses (background-1, background-2, inverse, scheme), the global palette and button palettes from 1–2 brand colours. Every text/button pair is pushed to WCAG AA; brand colour adjustments are reported. Pass the result to update_theme_settings.',
+      inputSchema: {
+        primary: z.string().describe('Couleur principale #RRGGBB'),
+        secondary: z.string().optional().describe('Couleur secondaire #RRGGBB'),
+        background: z.string().optional().describe('Fond clair imposé #RRGGBB (ex. crème)'),
+        neutral: z.enum(['tinted', 'warm', 'cool', 'pure']).optional().describe('Teinte des neutres : tinted (teintée par la marque, défaut), warm (crème), cool, pure (gris neutres)'),
+        mood: z.enum(['light', 'dark']).optional().describe('light (défaut) ou dark (boutique sombre)'),
+      },
+      annotations: readOnly,
+    },
+    run((args) => {
+      const result = generateColorSchemes(args);
+      return ok([
+        `Palettes générées${result.adjustments.length ? ' avec ajustements :\n' + result.adjustments.map((item) => `- ${item}`).join('\n') : ' (aucun ajustement nécessaire)'}`,
+        result.audit.length ? `Points de vigilance :\n${result.audit.map((item) => `- ${item.scheme} : ${item.message}`).join('\n')}` : 'Tous les contrastes passent AA.',
+        `Usage :\n${Object.entries(result.usage).map(([id, usage]) => `- ${id} : ${usage}`).join('\n')}`,
+        '',
+        'À appliquer avec update_theme_settings :',
+        JSON.stringify({ color_schemes: result.color_schemes, palette: result.palette, settings: result.button_palettes }, null, 1),
+      ].join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'check_contrast',
+    {
+      title: 'Vérifier un contraste',
+      description: 'WCAG contrast ratio between two colours, with AA/AAA verdicts for body text and large text.',
+      inputSchema: { foreground: z.string(), background: z.string() },
+      annotations: readOnly,
+    },
+    run(({ foreground, background }) => {
+      if (!parseColor(foreground) || !parseColor(background)) throw new Error('couleurs attendues au format #RRGGBB');
+      const ratio = contrast(foreground, background);
+      const verdict = (value, target) => (value >= target ? '✅' : '❌');
+      return ok(`${foreground} sur ${background} : ${round2(ratio)}:1\n- Texte courant AA (4,5) ${verdict(ratio, 4.5)} · AAA (7) ${verdict(ratio, 7)}\n- Grands titres AA (3) ${verdict(ratio, 3)} · AAA (4,5) ${verdict(ratio, 4.5)}`);
+    }),
+  );
+
+  server.registerTool(
+    'find_fonts',
+    {
+      title: 'Polices',
+      description: 'Fonts from the Shopify font library (the only ones a font_picker accepts). No args: tested pairings by style. `query`: search families. `handle`: check one handle (unknown or deprecated).',
+      inputSchema: { query: z.string().optional(), handle: z.string().optional() },
+      annotations: readOnly,
+    },
+    run(({ query, handle }) => {
+      if (handle) {
+        const problems = checkFontHandle(handle);
+        const info = fontInfo(handle);
+        return ok(problems.length ? problems.map((problem) => `${problem.level === 'error' ? '❌' : '⚠️'} ${problem.message}`).join('\n') : `✅ ${handle} : ${info.family}${info.alternative ? ` (police sous licence Monotype ; alternative libre : ${info.alternative})` : ''}`);
+      }
+      if (query) {
+        const found = searchFonts(query);
+        if (!found.length) return ok(`Aucune famille « ${query} » dans la bibliothèque Shopify (${FONT_LIBRARY.available.length} familles). Si c'est une police dépréciée, find_fonts avec handle donne sa remplaçante.`);
+        return ok(found.map((family) => `- ${family.family} : ${family.handles.join(' ')}${family.licensed ? ` (sous licence ; alternative libre ${family.free_alternative})` : ''}`).join('\n') + '\nSuffixe : n = normal, i = italique, chiffre = graisse (4 = regular, 6 = semi-bold, 7 = bold).');
+      }
+      return ok(['Paires vérifiées dans la bibliothèque Shopify (headings_font / body_font) :', ...FONT_PAIRINGS.map((pair) => `- ${pair.id} — ${pair.style} : ${pair.heading} / ${pair.body}. ${pair.note}`), '', 'Autre famille : find_fonts avec query.'].join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'validate_json',
+    {
+      title: 'Valider un JSON',
+      description: 'Validates a template, section group or settings_data against the real theme schemas (types, blocks allowed, setting ids and values, limits, rich text), plus a design review. No project needed.',
+      inputSchema: {
+        file: z.string().describe('Chemin du fichier dans le thème, ex. templates/index.json, templates/page.contact.json, sections/header-group.json, config/settings_data.json'),
+        content: z.union([z.string(), z.record(z.string(), z.any())]).describe('Le JSON (objet ou texte)'),
+        language: z.string().optional(),
+      },
+      annotations: readOnly,
+    },
+    run(({ file, content, language }) => {
+      const { catalog } = ctx.get();
+      const rel = checkRelativePath(file);
+      const data = parseContent(content);
+      const validation = validateFile(catalog, rel, data);
+      const design = rel === 'config/settings_data.json' ? lintSettings(catalog, data) : lintTemplate(catalog, rel, data, { language: languageOf(ctx, { language }) });
+      return ok(`${formatValidation(validation)}\n\n${formatFindings(design)}`);
+    }),
+  );
+
+  // ---------------------------------------------------------------- projects
+
+  server.registerTool(
+    'build_store',
+    {
+      title: 'Construire la V1 d’une boutique',
+      description: `FIRST CALL for a new store, without asking questions first. Builds a complete first version in one call and exports the zip: colour schemes from the brand colour (or the style), font pairing, home page (recipe picked from the style), product page, collection page, about/contact/FAQ/tracking pages, the rest of the theme translated, demo templates removed, and the brand copy you pass in \`copy\` placed in the pages. Reuses the project if it already exists (undo restores). Returns the choices made and the questions to ask the merchant next. Styles: ${Object.entries(STYLES).map(([id, style]) => `${id} (${style.label})`).join(', ')}.`,
+      inputSchema: {
+        name: z.string().min(2).describe('Nom de la boutique ou de la marque'),
+        activity: z.string().optional().describe('Ce qu’elle vend, en une phrase'),
+        style: z.enum(Object.keys(STYLES)).optional().describe('Déduit de l’activité si absent'),
+        primary_color: z.string().optional().describe('Couleur de marque #RRGGBB'),
+        secondary_color: z.string().optional(),
+        background_color: z.string().optional().describe('Fond clair imposé (ex. crème)'),
+        dark: z.boolean().optional().describe('Boutique sur fond sombre'),
+        fonts: z.enum(FONT_PAIRINGS.map((pair) => pair.id)).optional().describe('Paire de polices (sinon celle du style)'),
+        home: z.enum(RECIPES.filter((recipe) => recipe.template === 'templates/index.json').map((recipe) => recipe.id)).optional().describe('Recette d’accueil (sinon celle du style)'),
+        pages: z.array(z.enum(['a-propos', 'utilisation', 'contact', 'faq', 'suivi'])).optional().describe('Pages à créer (toutes par défaut) : a-propos = Notre histoire, utilisation = Comment utiliser'),
+        direction: z.enum(Object.keys(DIRECTIONS)).optional().describe(`Direction artistique : ${Object.entries(DIRECTIONS).map(([id, direction]) => `${id} (${direction.label} : ${direction.for})`).join(' ; ')}. Déduite du style si absente`),
+        offers: z.boolean().optional().describe('Fiche produit avec offres par paliers'),
+        collection: z.string().optional().describe('Handle de la collection principale (bouton du héro, meilleures ventes)'),
+        collections: z.array(z.string()).optional().describe('Handles des collections à montrer (la première = principale). Sans eux, les listes montrent toutes les collections'),
+        images: z
+          .object({
+            hero: z.string().optional().describe('Photo du héro, large et nette (1600 px de large ou plus ; nom du fichier dans Contenu > Fichiers, ex. darly-hero.jpg)'),
+            hero_mobile: z.string().optional().describe('Photo du héro en format portrait pour le mobile'),
+            story: z.array(z.string()).optional().describe('1 à 3 photos pour l’histoire de la marque'),
+            lifestyle: z.array(z.string()).optional().describe('Photos d’ambiance (visuels des sections)'),
+            large: z.array(z.string()).optional().describe('Parmi ces photos, celles qui font 1600 px de large ou plus : seules elles vont en plein écran (zoom au défilement, héro des pages de marque). Sans elles, pas de zoom et héro typographique sur les pages de marque, plutôt qu’une photo floue'),
+          })
+          .optional()
+          .describe('Photos déjà présentes dans Contenu > Fichiers. Sans photo : héro typographique, aucun carré vide'),
+        proofs: z
+          .object({
+            rating: z.number().optional().describe('Note moyenne réelle sur 5'),
+            testimonials: z.array(z.object({ name: z.string(), text: z.string(), role: z.string().optional() })).optional().describe('Vrais avis clients'),
+            figures: z.array(z.object({ value: z.string(), label: z.string() })).optional().describe('Chiffres réels et vérifiables, ex. {120}K+'),
+          })
+          .optional()
+          .describe('Uniquement des preuves réelles. Sans elles, les sections d’avis et de chiffres sont remplacées par des sections factuelles'),
+        shop_domain: z.string().optional().describe('Boutique Shopify (xxx.myshopify.com), pour mémoire'),
+        language: z.string().optional(),
+        copy: COPY.optional(),
+      },
+      annotations: writes,
+    },
+    run((input) => {
+      const { catalog, store } = ctx.get();
+      const result = buildStore({ catalog, store }, input);
+      const exported = exportTheme({ catalog, store, slug: result.slug });
+      const review = reviewProject(catalog, store, result.slug);
+      const own = review.perFile.filter((entry) => entry.origin === 'project');
+      const toWrite = own.reduce((total, entry) => total + entry.design.filter((finding) => finding.level === 'important').length, 0);
+      const placed = Object.values(result.written).reduce((total, count) => total + count, 0);
+      const questions = [];
+      if (!result.hasImages) questions.push('Je récupère les photos de votre boutique (collections, produits) pour le héro et les grandes sections ? C’est ce qui fera la différence visuelle.');
+      if (!input.collection && !input.collections?.length) questions.push('Quelle est votre collection principale (ou vos meilleures ventes) ? Je relie le bouton d’accueil et la liste de produits.');
+      if (!input.proofs?.testimonials?.length) questions.push('Avez-vous des avis clients réels (note, quelques citations) ? J’ajouterai une section d’avis.');
+      questions.push('Vos conditions exactes : délais de livraison, livraison offerte à partir de combien, retours sous combien de jours ?');
+      if (!input.primary_color) questions.push('Avez-vous une couleur de marque et un logo ?');
+      if (!input.offers) questions.push('Proposez-vous des lots ou des remises par quantité ?');
+      return ok([
+        `✅ V1 de « ${input.name} » ${result.existed ? 'reconstruite' : 'construite'} — projet ${result.slug} (projet en cours).`,
+        `Choix faits (à confirmer) : style ${result.style} ; ${result.choices.join(' ; ')}.`,
+        result.signatures.length ? `Moments signature de l’accueil : ${result.signatures.join(', ')}.` : 'Aucun moment signature : donnez manifesto, rotating_words, benefits (3+) ou process dans copy.',
+        result.brandPages.length ? `Pages de marque : ${result.brandPages.map((file) => file.replace('templates/', '')).join(', ')} (à attribuer à une page Shopify via « Modèle de thème »).` : '',
+        ...result.notes.map((note) => `- ${note}`),
+        `Accueil : ${result.sectionsPerFile['templates/index.json']} sections${result.hasImages ? '' : ' (sans photo : héro typographique, aucun carré vide)'}.`,
+        `Textes de la marque placés : ${placed}${result.translated ? ` · textes du thème traduits : ${result.translated}` : ''} · textes d’exemple encore à personnaliser : ${toWrite} (list_texts puis edit_template).`,
+        exported.ok ? `Zip : ${exported.zip}\nÀ importer dans Shopify : Boutique en ligne > Thèmes > Ajouter un thème > Importer un fichier zip (sans publier), puis Personnaliser pour voir le rendu.` : `Export impossible : ${exported.message}`,
+        '',
+        'Questions à poser maintenant pour affiner (pas plus de 5) :',
+        ...questions.slice(0, 5).map((question) => `- ${question}`),
+      ].join('\n'));
+    }),
+  );
+
+  const SECTION_SPEC = z
+    .object({
+      type: z.string().describe('Type de section (list_sections)'),
+      preset: z.union([z.string(), z.number()]).optional().describe('Preset de départ (get_section)'),
+      id: z.string().optional(),
+      palette: z.string().optional().describe('Palette du fond : background-1, background-2, inverse, scheme'),
+      separator: z.object({ top: z.string().optional(), bottom: z.string().optional(), animation: z.string().optional(), flip: z.boolean().optional() }).optional().describe('Formes : curve, slope, wave, waves, organic, tilt, peak, zigzag, scallop, clouds, mountains, torn, drip, fade, line ; animation : flow, swell, grow, parallax'),
+      image: z.string().optional().describe('Photo de la section (héro, zoom) : nom du fichier dans Contenu > Fichiers'),
+      image_mobile: z.string().optional(),
+      images: z.array(z.string()).optional().describe('Photos des blocs image de la section, dans l’ordre (les blocs image sans photo sont retirés)'),
+      settings: z.record(z.string(), z.any()).optional().describe('Réglages bruts de la section'),
+      content: z
+        .object({
+          eyebrow: z.string().optional().describe('Sur-titre'),
+          title: z.string().optional().describe('Titre ; **mot** = mot en gras (coloré par le style de titre)'),
+          title_tag: z.enum(['h1', 'h2', 'p']).optional(),
+          rotating_words: z.array(z.string()).optional(),
+          text: z.string().optional().describe('Texte ; ligne vide = nouveau paragraphe ; "" retire le texte d’exemple'),
+          buttons: z.array(z.object({ label: z.string(), link: z.string().optional(), style: z.string().optional() })).optional().describe('[] retire les boutons'),
+          manifesto: z.string().optional().describe('Remplace le contenu par un texte révélé au défilement'),
+          lines: z.array(z.string()).optional().describe('Lignes d’un bandeau défilant ou d’une liste à puces'),
+          items: z.array(z.union([z.string(), z.record(z.string(), z.any())])).optional().describe('Éléments répétés (étapes, cartes, questions, chiffres, caractéristiques, lignes de comparaison…) : { title, text, label, value, icon, image, button: {label, link}, palette, question, answer, name, role, values: [..] } ; le nombre d’éléments s’adapte'),
+        })
+        .optional(),
+    })
+    .passthrough();
+
+  server.registerTool(
+    'compose_page',
+    {
+      title: 'Composer une page',
+      description: 'Designs a page freely with ANY section of the theme: for each section, a preset to start from plus its content (title, text, buttons, repeated items such as steps, cards, questions, figures, specs, comparison rows), palette, shape separators and photos. The MCP places everything in the right blocks, adds or removes items, and saves only if the file is valid. Use it for original pages: our story, how to use, ingredients, lookbook, gift guide, landing page. mode append adds the sections to an existing page.',
+      inputSchema: {
+        project: PROJECT,
+        file: z.string().describe('ex. templates/page.utilisation.json, templates/page.ingredients.json, templates/index.json'),
+        sections: z.array(SECTION_SPEC).min(1),
+        mode: z.enum(['replace', 'append']).optional(),
+        summary: z.string().optional(),
+      },
+      annotations: writes,
+    },
+    run(({ project, file, sections, mode = 'replace', summary }) => {
+      const { store, catalog } = ctx.get();
+      project = store.resolve(project);
+      const meta = store.meta(project);
+      const rel = checkRelativePath(file);
+      if (fileKind(rel) !== 'template') throw new Error('compose_page écrit un modèle (templates/…)');
+      const base = mode === 'append' ? store.read(project, rel).data || { sections: {}, order: [] } : { sections: {}, order: [] };
+      const { data, notes } = composeSections(catalog, sections, { language: meta.language, data: base });
+      const report = fileReport(catalog, store, project, rel, data, meta.language);
+      if (!report.validation.ok) return fail(`Rien n'a été enregistré.\n${formatValidation(report.validation)}${notes.length ? `\nNotes : ${notes.join(' ; ')}` : ''}`);
+      store.write(project, rel, data, summary || `page composée (${sections.length} sections)`);
+      const pageHint = /^templates\/page\.[^.]+\.json$/.test(rel) ? `\nDans Shopify : créez la page puis choisissez le modèle « ${rel.replace('templates/', '').replace('.json', '')} ».` : '';
+      return ok(`Enregistré : ${rel}${pageHint}\n${notes.length ? `Notes : ${notes.join(' ; ')}\n` : ''}\n${outline(catalog, data, { language: meta.language, file: rel })}\n\n${formatFindings(report.design, { max: 12 })}`);
+    }),
+  );
+
+  server.registerTool(
+    'create_project',
+    {
+      title: 'Créer un projet',
+      description: 'Creates a store project: a workspace holding the store’s templates, section groups and theme settings, starting from the theme defaults. Fill the brief with facts from the merchant (never invent proofs).',
+      inputSchema: {
+        name: z.string().min(2).describe('Nom de la boutique ou du projet'),
+        language: z.string().optional().describe('Langue de la boutique (fr par défaut)'),
+        brief: BRIEF.optional(),
+      },
+      annotations: writes,
+    },
+    run(({ name, language, brief = {} }) => {
+      const { store, catalog } = ctx.get();
+      const lang = languageOf(ctx, { language });
+      if (!catalog.languages.includes(lang)) throw new Error(`langue « ${lang} » : le thème est traduit en ${catalog.languages.join(', ')}`);
+      const meta = store.create({ name, language: lang, brief });
+      const missing = ['activity', 'audience', 'positioning', 'tone', 'brand_colors', 'proofs', 'shipping_returns'].filter((key) => !brief[key] || (Array.isArray(brief[key]) && !brief[key].length));
+      return ok([
+        `Projet « ${meta.name} » créé : ${meta.slug} (Story Thème ${meta.theme.version}, langue ${meta.language}).`,
+        `Dossier : ${store.dir(meta.slug)}`,
+        missing.length ? `À préciser plus tard avec le marchand : ${missing.join(', ')} (update_brief). Ne bloquez pas dessus : construisez d'abord.` : 'Brief complet.',
+        'Plus rapide : build_store construit toute la V1 en un appel.',
+      ].join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'list_projects',
+    { title: 'Projets', description: 'Lists store projects.', annotations: readOnly },
+    run(() => {
+      const { store } = ctx.get();
+      const projects = store.list();
+      return ok(projects.length ? projects.map((project) => `- ${project.slug} — ${project.name} (${project.language}, thème ${project.theme?.version}, modifié ${project.updated_at?.slice(0, 16)})`).join('\n') : 'Aucun projet.');
+    }),
+  );
+
+  server.registerTool(
+    'get_project',
+    {
+      title: 'Projet',
+      description: 'A project’s brief, which files it customises (vs theme defaults), the outline of its home page, and recent changes.',
+      inputSchema: { project: PROJECT },
+      annotations: readOnly,
+    },
+    run(({ project }) => {
+      const { store, catalog } = ctx.get();
+      project = store.resolve(project);
+      const meta = store.meta(project);
+      const files = store.projectFiles(project);
+      const index = store.read(project, 'templates/index.json');
+      return ok([
+        `# ${meta.name} (${meta.slug}) — Story Thème ${meta.theme?.version}, langue ${meta.language}`,
+        meta.theme?.version !== catalog.version ? `⚠️ Projet créé avec la version ${meta.theme?.version}, thème actuel ${catalog.version}.` : '',
+        `Brief : ${JSON.stringify(meta.brief || {}, null, 1)}`,
+        `Fichiers personnalisés : ${files.join(', ') || 'aucun'}`,
+        '',
+        outline(catalog, index.data, { language: meta.language, file: `templates/index.json (${index.origin === 'project' ? 'projet' : 'version du thème'})` }),
+        '',
+        `Dernières modifications :\n${(meta.log || []).slice(-10).map((entry) => `- ${entry.at.slice(0, 16)} ${entry.file} : ${entry.summary}`).join('\n') || '- aucune'}`,
+      ].filter(Boolean).join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'update_brief',
+    {
+      title: 'Compléter le brief',
+      description: 'Adds or changes facts in a project brief (merged).',
+      inputSchema: { project: PROJECT, brief: BRIEF },
+      annotations: writes,
+    },
+    run(({ project, brief }) => {
+      const { store } = ctx.get();
+      project = store.resolve(project);
+      const meta = store.updateBrief(project, brief);
+      return ok(`Brief mis à jour :\n${JSON.stringify(meta.brief, null, 1)}`);
+    }),
+  );
+
+  server.registerTool(
+    'read_file',
+    {
+      title: 'Lire un fichier du projet',
+      description: 'Reads a project file (or the theme default when the project has not customised it) as an outline with block ids (for edit_template targets) and/or full JSON.',
+      inputSchema: {
+        project: PROJECT,
+        file: z.string().describe('ex. templates/index.json, sections/header-group.json, config/settings_data.json'),
+        format: z.enum(['outline', 'json', 'both']).optional(),
+      },
+      annotations: readOnly,
+    },
+    run(({ project, file, format = 'outline' }) => {
+      const { store, catalog } = ctx.get();
+      project = store.resolve(project);
+      const meta = store.meta(project);
+      const rel = checkRelativePath(file);
+      const { data, origin } = store.read(project, rel);
+      if (!data) return ok(`${rel} n'existe ni dans le projet ni dans le thème : créez-le avec apply_recipe, edit_template (add_section) ou write_file.`);
+      const header = `${rel} — ${origin === 'project' ? 'version du projet' : 'version du thème (pas encore personnalisée)'}`;
+      if (rel === 'config/settings_data.json' && format === 'outline') {
+        const current = typeof data.current === 'string' ? data.presets?.[data.current] : data.current;
+        const simple = Object.entries(current || {}).filter(([, value]) => typeof value !== 'object').map(([key, value]) => `${key}=${JSON.stringify(value)}`);
+        return ok(`${header}\nPalettes : ${Object.keys(current?.color_schemes || {}).join(', ')}\n${simple.join('\n')}\n(format json pour les palettes et le tiroir panier)`);
+      }
+      const parts = [header];
+      if (format !== 'json') parts.push(outline(catalog, data, { language: meta.language, file: rel }));
+      if (format !== 'outline') parts.push(JSON.stringify(data, null, 1));
+      return ok(parts.join('\n\n'));
+    }),
+  );
+
+  server.registerTool(
+    'list_texts',
+    {
+      title: 'Textes et liens d’une page',
+      description: 'Lists every text, rich text and link of a project file with its exact target ("section/block/…") and setting id, flagged [à réécrire] when the review would flag it (sample copy, English, unverified claims) or [exemple générique] for short theme labels that may stay. Use it to rewrite a whole page in one edit_template call of update_settings operations.',
+      inputSchema: { project: PROJECT, file: z.string(), only_to_fix: z.boolean().optional().describe('Seulement les textes signalés') },
+      annotations: readOnly,
+    },
+    run(({ project, file, only_to_fix = false }) => {
+      const { store, catalog } = ctx.get();
+      project = store.resolve(project);
+      const meta = store.meta(project);
+      const rel = checkRelativePath(file);
+      const { data, origin } = store.read(project, rel);
+      if (!data?.sections) throw new Error(`${rel} n'a pas de sections`);
+      const lines = [`${rel} (${origin === 'project' ? 'projet' : 'version du thème'}) — cibles pour edit_template / update_settings :`];
+      for (const entry of collectTexts(catalog, rel, data, { language: meta.language })) {
+        if (only_to_fix && entry.flag !== 'fix') continue;
+        const flags = [];
+        if (entry.flag === 'fix') flags.push(/anglais/.test(entry.issue) ? '[à réécrire, EN]' : /témoignage|chiffre|réponse|promesses|annonce|messages/.test(entry.issue) ? '[à réécrire, fait à vérifier]' : '[à réécrire]');
+        else if (entry.flag === 'sample') flags.push('[exemple générique]');
+        const shown = String(entry.value).length > 400 ? `${String(entry.value).slice(0, 397)}…` : entry.value;
+        lines.push(`- ${entry.target} › ${entry.setting} (${entry.type})${flags.length ? ' ' + flags.join(' ') : ''} = ${JSON.stringify(shown)}`);
+      }
+      if (lines.length === 1) lines.push(only_to_fix ? 'Aucun texte à corriger.' : 'Aucun texte renseigné (les valeurs par défaut du thème s’appliquent).');
+      lines.push('Rappel : un texte riche s’écrit <p>…</p> ; un texte riche en ligne sans <p>.');
+      return ok(lines.join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'write_file',
+    {
+      title: 'Écrire un fichier entier',
+      description: 'Saves a whole template, section group or settings_data in a project, after validation against the theme schemas. Refused (nothing saved) if any error. Prefer edit_template for changes.',
+      inputSchema: {
+        project: PROJECT,
+        file: z.string(),
+        content: z.union([z.string(), z.record(z.string(), z.any())]),
+        summary: z.string().optional().describe('Ce qui change, pour l’historique'),
+      },
+      annotations: writes,
+    },
+    run(({ project, file, content, summary }) => {
+      const { store, catalog } = ctx.get();
+      project = store.resolve(project);
+      const meta = store.meta(project);
+      const rel = checkRelativePath(file);
+      const data = parseContent(content);
+      const report = fileReport(catalog, store, project, rel, data, meta.language);
+      if (!report.validation.ok) return fail(`Rien n'a été enregistré.\n${formatValidation(report.validation)}`);
+      store.write(project, rel, data, summary || 'fichier écrit');
+      return ok(`Enregistré : ${rel}\n${formatValidation(report.validation)}\n\n${rel.startsWith('config/') ? '' : outline(catalog, data, { language: meta.language, file: rel }) + '\n\n'}${formatFindings(report.design)}`);
+    }),
+  );
+
+  server.registerTool(
+    'edit_template',
+    {
+      title: 'Modifier un modèle',
+      description: `Applies a list of operations to a template or section group of a project, validates the result, and saves it only if valid (all or nothing). Operations:
+- add_section {type, preset?, id?, position?, settings?} (sections come from their preset, texts in the project language)
+- remove_section {section} · move_section {section, position} · duplicate_section {section, position?} · replace_section {section, data}
+- update_settings {target, settings, mode?} (target "section" or "section/block/…"; null removes a setting)
+- add_block {parent, type, preset?, id?, position?, settings?} · remove_block {target} · move_block {target, position} · set_disabled {target, disabled}
+Read the file first (read_file) to get ids.`,
+      inputSchema: {
+        project: PROJECT,
+        file: z.string().describe('templates/<nom>.json ou sections/<groupe>.json'),
+        operations: z.array(OPERATION).min(1),
+        summary: z.string().optional(),
+      },
+      annotations: writes,
+    },
+    run(({ project, file, operations, summary }) => {
+      const { store, catalog } = ctx.get();
+      project = store.resolve(project);
+      const meta = store.meta(project);
+      const rel = checkRelativePath(file);
+      if (rel === 'config/settings_data.json') throw new Error('pour les réglages du thème, utilisez update_theme_settings');
+      const current = store.read(project, rel).data || (rel.startsWith('sections/') ? null : { sections: {}, order: [] });
+      if (!current) throw new Error(`${rel} n'existe pas : un groupe de sections se crée avec write_file ({ type, name, sections, order })`);
+      const { data, log } = applyOperations(catalog, current, operations, { language: meta.language });
+      const report = fileReport(catalog, store, project, rel, data, meta.language);
+      if (!report.validation.ok) return fail(`Rien n'a été enregistré : le résultat serait refusé par Shopify.\n${formatValidation(report.validation)}\n\nOpérations appliquées sur la copie :\n${log.join('\n')}`);
+      store.write(project, rel, data, summary || log.join(' ; '));
+      return ok(`Enregistré : ${rel}\n${log.map((line) => `- ${line}`).join('\n')}\n\n${outline(catalog, data, { language: meta.language, file: rel })}\n\n${formatValidation(report.validation)}\n${formatFindings(report.design, { max: 12 })}`);
+    }),
+  );
+
+  server.registerTool(
+    'apply_recipe',
+    {
+      title: 'Appliquer une recette',
+      description: 'Builds a page from a recipe (see `recipes`) into a project file, from theme presets with texts in the project language. Replaces the file by default (undo restores it). Then rewrite every sample text for the brand.',
+      inputSchema: {
+        project: PROJECT,
+        recipe: z.string(),
+        file: z.string().optional().describe('Fichier cible (par défaut celui de la recette)'),
+        mode: z.enum(['replace', 'append']).optional().describe('replace (défaut) ou append (ajoute les sections à la fin)'),
+      },
+      annotations: writes,
+    },
+    run(({ project, recipe: recipeId, file, mode = 'replace' }) => {
+      const { store, catalog } = ctx.get();
+      project = store.resolve(project);
+      const meta = store.meta(project);
+      const recipe = findRecipe(recipeId);
+      if (!recipe) throw new Error(`recette « ${recipeId} » inconnue (recettes : ${RECIPES.map((item) => item.id).join(', ')})`);
+      const rel = checkRelativePath(file || recipe.template);
+      if (fileKind(rel) !== 'template') throw new Error('une recette produit un modèle (templates/…)');
+      if (templateTypeOf(rel) !== templateTypeOf(recipe.template)) throw new Error(`la recette ${recipe.id} est faite pour un modèle ${templateTypeOf(recipe.template)}, pas ${templateTypeOf(rel)}`);
+      let base = recipe.base ? catalog.theme.templates.get(recipe.base) : null;
+      if (mode === 'append') base = store.read(project, rel).data || base;
+      const { data, roles } = buildFromRecipe(catalog, recipe, { language: meta.language, base });
+      const report = fileReport(catalog, store, project, rel, data, meta.language);
+      if (!report.validation.ok) return fail(`La recette produit un fichier invalide avec cette version du thème (rien n'a été enregistré) :\n${formatValidation(report.validation)}`);
+      store.write(project, rel, data, `recette ${recipe.id}`);
+      return ok([
+        `Recette « ${recipe.title} » appliquée à ${rel}.`,
+        '',
+        outline(catalog, data, { language: meta.language, file: rel }),
+        '',
+        'À faire maintenant, section par section (edit_template → update_settings) :',
+        ...roles.map((role) => `- ${role.section} : ${role.role}`),
+        '',
+        'Tous les textes sont ceux des presets du thème : réécrivez-les pour la marque, supprimez ce qui ne s’applique pas, renseignez les vrais liens (shopify://collections/<handle>).',
+        formatFindings(report.design.filter((finding) => finding.level !== 'important' || !/exemple du thème/.test(finding.message)), { max: 10 }),
+      ].join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'localize_template',
+    {
+      title: 'Traduire les modèles du thème',
+      description: 'Translates the English sample texts of the theme’s own templates and section groups into the project language, using the theme’s official translations (about 95 % of the default home page, half of the other pages). Saves the result in the project and lists the texts left to write (then list_texts + edit_template). Use it for pages kept close to the theme’s design; use apply_recipe for pages rebuilt from a recipe.',
+      inputSchema: {
+        project: PROJECT,
+        files: z.array(z.string()).optional().describe('Fichiers à traduire ; par défaut tous les modèles et groupes pas encore personnalisés par le projet'),
+      },
+      annotations: writes,
+    },
+    run(({ project, files }) => {
+      const { store, catalog } = ctx.get();
+      project = store.resolve(project);
+      const meta = store.meta(project);
+      if (meta.language === catalog.defaultLanguage) return ok(`Le projet est en ${meta.language}, la langue des textes du thème : rien à traduire.`);
+      const effective = store.effectiveFiles(project);
+      const targets = files?.length ? files.map((file) => checkRelativePath(file)) : [...effective.entries()].filter(([rel, entry]) => entry.origin === 'theme' && rel !== 'config/settings_data.json').map(([rel]) => rel);
+      const lines = [];
+      let left = 0;
+      for (const rel of targets) {
+        const source = store.read(project, rel).data;
+        if (!source?.sections) {
+          lines.push(`- ${rel} : introuvable`);
+          continue;
+        }
+        const { data, translated, remaining } = localizeData(catalog, source, meta.language);
+        if (!translated) {
+          lines.push(`- ${rel} : rien de traduisible${remaining.length ? `, ${remaining.length} texte(s) à écrire` : ''}`);
+          left += remaining.length;
+          continue;
+        }
+        const validation = validateFile(catalog, rel, data, { schemeIds: schemeIdsFor(store, project) });
+        if (!validation.ok) {
+          lines.push(`- ${rel} : non enregistré (${validation.errors[0].message})`);
+          continue;
+        }
+        store.write(project, rel, data, `traduction ${meta.language} (${translated} textes)`);
+        left += remaining.length;
+        lines.push(`- ${rel} : ${translated} texte(s) traduit(s)${remaining.length ? `, ${remaining.length} à écrire` : ' ✅'}`);
+      }
+      return ok(`${lines.join('\n')}\n\n${left ? `${left} texte(s) restent en anglais : list_texts (only_to_fix) sur chaque fichier, puis edit_template. Les modèles inutiles (démos d'offres, page d'aide…) peuvent être retirés avec exclude_template.` : 'Tous les textes sont traduits. Relisez-les : ce sont encore des exemples à adapter à la marque.'}`);
+    }),
+  );
+
+  server.registerTool(
+    'exclude_template',
+    {
+      title: 'Retirer un modèle inutile',
+      description: 'Leaves an unused alternate template (product.offers-*, page.help, page.wishlist…) out of the export and the review, so it never appears in the admin with sample content. Base templates cannot be removed. include=true puts it back.',
+      inputSchema: { project: PROJECT, file: z.string(), include: z.boolean().optional() },
+      annotations: writes,
+    },
+    run(({ project, file, include = false }) => {
+      const { store } = ctx.get();
+      project = store.resolve(project);
+      const excluded = store.setExcluded(project, file, !include);
+      return ok(`${file} ${include ? "remis dans l'export" : "retiré de l'export"}. Modèles retirés : ${excluded.join(', ') || 'aucun'}.`);
+    }),
+  );
+
+  server.registerTool(
+    'update_theme_settings',
+    {
+      title: 'Réglages du thème du projet',
+      description: 'Merges global theme settings into the project’s config/settings_data.json: `settings` (fonts, buttons, radius, cart type, social links…), `color_schemes` (replaces the listed schemes), `palette`. Validated and contrast-audited; refused on error.',
+      inputSchema: {
+        project: PROJECT,
+        settings: z.record(z.string(), z.any()).optional().describe('{ id_réglage: valeur } ; null supprime'),
+        color_schemes: z.record(z.string(), z.any()).optional().describe('{ "background-1": { settings: {…} }, … } (sortie de generate_color_schemes)'),
+        palette: z.record(z.string(), z.string()).optional(),
+        remove_schemes: z.array(z.string()).optional().describe('Palettes à supprimer (vérifiez qu’aucune section ne les utilise)'),
+      },
+      annotations: writes,
+    },
+    run(({ project, settings = {}, color_schemes, palette, remove_schemes = [] }) => {
+      const { store, catalog } = ctx.get();
+      project = store.resolve(project);
+      store.meta(project);
+      const rel = 'config/settings_data.json';
+      const data = JSON.parse(JSON.stringify(store.read(project, rel).data || { current: {} }));
+      if (typeof data.current === 'string') data.current = JSON.parse(JSON.stringify(data.presets?.[data.current] || {}));
+      const current = data.current;
+      for (const [key, value] of Object.entries(settings)) {
+        if (value === null) delete current[key];
+        else current[key] = value;
+      }
+      if (color_schemes) {
+        current.color_schemes = { ...(current.color_schemes || {}) };
+        for (const [id, scheme] of Object.entries(color_schemes)) current.color_schemes[id] = scheme?.settings ? scheme : { settings: scheme };
+      }
+      if (remove_schemes.length) {
+        const used = findSchemeReferences(catalog, store.effectiveFiles(project), remove_schemes);
+        if (used.length) return fail(`Rien n'a été enregistré : ${remove_schemes.join(', ')} ${used.length > 1 ? 'sont encore utilisées' : 'est encore utilisée'} (${used.length} réglage(s)) :\n${used.slice(0, 15).map((line) => `- ${line}`).join('\n')}${used.length > 15 ? '\n- …' : ''}\nChangez d'abord ces palettes (edit_template), puis supprimez.`);
+      }
+      for (const id of remove_schemes) delete current.color_schemes?.[id];
+      if (palette) current.palette = { ...(current.palette || {}), ...palette };
+      const validation = validateFile(catalog, rel, data);
+      if (!validation.ok) return fail(`Rien n'a été enregistré.\n${formatValidation(validation)}`);
+      store.write(project, rel, data, `réglages : ${[...Object.keys(settings), color_schemes ? 'palettes' : null, palette ? 'palette globale' : null].filter(Boolean).join(', ')}`);
+      const buttons = { 1: current.button_1_palette, 2: current.button_2_palette, 3: current.button_3_palette };
+      const contrastIssues = auditSchemes(current.color_schemes || {}, buttons).filter((finding) => finding.level !== 'ok');
+      return ok(`Réglages enregistrés.\n${formatValidation(validation)}\n${contrastIssues.length ? `Contrastes à surveiller :\n${contrastIssues.map((item) => `- ${item.level === 'error' ? '🔴' : '🟡'} ${item.scheme} : ${item.message}`).join('\n')}` : 'Contrastes : tout passe AA.'}\n${formatFindings(lintSettings(catalog, data).filter((finding) => !/contraste/.test(finding.message)))}`);
+    }),
+  );
+
+  server.registerTool(
+    'review_project',
+    {
+      title: 'Revue complète',
+      description: 'Full review of a project before export: blocking errors, design issues (sample or English texts left, missing links, several h1, contrast, fonts, fake urgency…), theme templates still untouched, and the go-live checklist.',
+      inputSchema: { project: PROJECT },
+      annotations: readOnly,
+    },
+    run(({ project }) => {
+      const { store, catalog } = ctx.get();
+      project = store.resolve(project);
+      return ok(formatReview(reviewProject(catalog, store, project)));
+    }),
+  );
+
+  server.registerTool(
+    'undo',
+    {
+      title: 'Annuler',
+      description: 'Restores a project file to its state before the last change (of that file, or of the whole project). Can be repeated.',
+      inputSchema: { project: PROJECT, file: z.string().optional() },
+      annotations: writes,
+    },
+    run(({ project, file }) => {
+      const { store } = ctx.get();
+      project = store.resolve(project);
+      const restored = store.undo(project, file || null);
+      if (restored.kind === 'exclusion') return ok(`Annulé : retour à la liste des modèles retirés du ${restored.at.slice(0, 19).replace('T', ' ')} (${restored.excluded.join(', ') || 'aucun'}).`);
+      return ok(`Annulé : ${restored.rel} revient à son état du ${restored.at.slice(0, 19).replace('T', ' ')}${restored.existed ? '' : ' (version du thème)'}.`);
+    }),
+  );
+
+  server.registerTool(
+    'revert_file',
+    {
+      title: 'Revenir à la version du thème',
+      description: 'Drops the project’s version of a file so the theme default applies again (undo can bring it back).',
+      inputSchema: { project: PROJECT, file: z.string() },
+      annotations: writes,
+    },
+    run(({ project, file }) => {
+      const { store } = ctx.get();
+      project = store.resolve(project);
+      return ok(store.revert(project, file) ? `${file} : retour à la version du thème.` : `${file} n'était pas personnalisé.`);
+    }),
+  );
+
+  server.registerTool(
+    'export_theme',
+    {
+      title: 'Exporter le thème',
+      description: 'Builds the theme zip to upload in Shopify (Online Store > Themes > Add theme > Upload zip), with the project files on top of the theme, plus the go-live checklist. Refused while any blocking error remains. Nothing is sent to a store.',
+      inputSchema: { project: PROJECT },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    },
+    run(({ project }) => {
+      const { store, catalog } = ctx.get();
+      project = store.resolve(project);
+      const result = exportTheme({ catalog, store, slug: project });
+      if (!result.ok) return fail(`${result.message}\n${(result.errors || []).map((entry) => `${entry.file} :\n${entry.errors.map((error) => `  - ${error.path} : ${error.message}`).join('\n')}`).join('\n')}`);
+      const notReady = /pas prêt à publier/.test(result.report);
+      const migratedFiles = Object.keys(result.migrated || {});
+      return ok(`${migratedFiles.length ? `Projet mis à jour vers le thème ${catalog.version} : ${migratedFiles.map((file) => `${file} (${result.migrated[file].length})`).join(', ')} — réglages que le thème n'a plus, sans effet sur le rendu (undo possible).\n` : ''}${notReady ? '⚠️ Exporté, mais PAS PRÊT À PUBLIER : des points 🔴 restent (voir la revue ci-dessous). Importez-le sans le publier.\n' : ''}✅ Thème exporté : ${result.zip} (${result.size_mb} Mo, ${result.files} fichiers, personnalisés : ${result.overlays.join(', ') || 'aucun'})\nCheck-list : ${result.checklist}\n\n${result.report}`);
+    }),
+  );
+
+  server.registerTool(
+    'migrate_project',
+    {
+      title: 'Mettre le projet à jour avec le thème',
+      description: 'After a theme update: removes settings the theme no longer has and resets values it no longer accepts (default value, nearest valid step), in every project file, without changing what renders. Unknown section or block types are reported, not removed. export_theme runs it automatically.',
+      inputSchema: { project: PROJECT },
+      annotations: writes,
+    },
+    run(({ project }) => {
+      const { store, catalog } = ctx.get();
+      project = store.resolve(project);
+      const report = migrateProject({ catalog, store, slug: project });
+      const files = Object.entries(report);
+      const remaining = reviewProject(catalog, store, project).errorCount;
+      return ok([
+        files.length ? `Mis à jour vers le thème ${catalog.version} :` : `Rien à mettre à jour : le projet correspond déjà au thème ${catalog.version}.`,
+        ...files.map(([file, changes]) => `- ${file} : ${changes.length} changement(s) — ${changes.slice(0, 4).join(' ; ')}${changes.length > 4 ? ' ; …' : ''}`),
+        remaining ? `⚠️ ${remaining} erreur(s) restent (sections ou blocs disparus du thème) : review_project les détaille.` : '✅ Aucune erreur bloquante.',
+      ].join('\n'));
+    }),
+  );
+
+  server.registerTool(
+    'import_theme',
+    {
+      title: 'Importer un thème',
+      description: 'Creates a project from a theme exported from a store (folder or .zip from Online Store > Themes > Download), to audit or rework it. Reports files that do not match this theme version.',
+      inputSchema: { source: z.string().describe('Chemin du dossier ou du .zip'), name: z.string(), language: z.string().optional() },
+      annotations: writes,
+    },
+    run(({ source, name, language }) => {
+      const { store, catalog } = ctx.get();
+      const result = importTheme({ catalog, store, source, name, language: languageOf(ctx, { language }) });
+      const withErrors = result.results.filter((entry) => entry.errors);
+      return ok([
+        `Projet ${result.project} créé depuis ${source} (version importée ${result.version}, thème du MCP ${result.themeVersion}).`,
+        result.version !== result.themeVersion ? `⚠️ Versions différentes : les sections qui n'existent plus en ${result.themeVersion} apparaissent en erreur.` : '',
+        ...result.results.map((entry) => `- ${entry.file} : ${entry.imported ? (entry.errors ? `❌ ${entry.errors} erreur(s)` : '✅') : `non importé (${entry.errors.join(', ')})`}${entry.warnings ? `, ${entry.warnings} avertissement(s)` : ''}`),
+        withErrors.length ? 'review_project détaille chaque problème.' : '',
+      ].filter(Boolean).join('\n'));
+    }),
+  );
+
+  // ---------------------------------------------------------------- prompts & resources
+
+  server.registerPrompt(
+    'creer-boutique',
+    {
+      title: 'Créer une boutique avec le Story Thème',
+      description: 'Guide pas à pas : brief, identité, pages, revue, export.',
+      argsSchema: { marque: z.string(), activite: z.string().optional(), langue: z.string().optional() },
+    },
+    ({ marque, activite, langue }) => ({
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Crée la boutique « ${marque} »${activite ? ` (${activite})` : ''} avec le Story Thème, en ${langue || 'français'}. Construis tout de suite une V1 complète avec build_store (sans me poser de question avant), en rédigeant les textes clés de la marque. Ensuite, résume ce que tu as fait, donne-moi le zip et pose-moi quelques questions pour affiner.`,
+          },
+        },
+      ],
+    }),
+  );
+
+  server.registerPrompt(
+    'refaire-une-page',
+    {
+      title: 'Refaire une page',
+      description: 'Refondre une page d’un projet existant.',
+      argsSchema: { projet: z.string(), page: z.string().describe('ex. accueil, fiche produit, à propos') },
+    },
+    ({ projet, page }) => ({
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Dans le projet ${projet}, refais la page « ${page} ». Lis d'abord le brief (get_project) et la page actuelle (read_file), propose-moi une structure (recipes, list_sections) avant de modifier, puis applique-la et réécris les textes pour la marque. Termine par review_project.`,
+          },
+        },
+      ],
+    }),
+  );
+
+  server.registerPrompt(
+    'auditer-un-theme',
+    {
+      title: 'Auditer un thème exporté',
+      description: 'Importer un thème téléchargé depuis une boutique et lister ce qu’il faut corriger.',
+      argsSchema: { chemin: z.string(), nom: z.string() },
+    },
+    ({ chemin, nom }) => ({
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Importe le thème « ${chemin} » dans un projet nommé « ${nom} » (import_theme), lance review_project, puis donne-moi les corrections par ordre d'impact sur les ventes et l'image de marque, et propose de les appliquer.`,
+          },
+        },
+      ],
+    }),
+  );
+
+  for (const topic of GUIDE_TOPICS) {
+    server.registerResource(
+      `guide-${topic}`,
+      `storytheme://guides/${topic}`,
+      { title: GUIDES[topic].title, description: `Guide Story Thème : ${GUIDES[topic].title}`, mimeType: 'text/markdown' },
+      async (uri) => ({ contents: [{ uri: uri.href, mimeType: 'text/markdown', text: `# ${GUIDES[topic].title}\n\n${GUIDES[topic].body}` }] }),
+    );
+  }
+
+  return server;
+}