# Conduire Homotope depuis un agent IA

> Un agent branché sur le serveur MCP de Homotope (https://homotope.app/mcp) mène une image jusqu'au fichier d'impression ou de découpe en 3 calculs au plus : suggérer le préréglage, calculer, regarder l'aperçu et lancer le contrôle de découpe, puis corriger par le conseil que rend le contrôle, et s'arrêter quand le contrôle passe et que l'aperçu zoomé ne montre plus le défaut nommé par l'utilisateur.

## Pour qui

Cette page est le mode d'emploi d'un agent IA (Claude Code, Claude, ChatGPT, Gemini CLI ou un script) qui utilise Homotope par son serveur MCP, à l'adresse `https://homotope.app/mcp`. Le texte brut est sur [/agents.md](https://homotope.app/agents.md). Chaque appel à `vectorize_image` est un calcul décompté du compte de l'utilisateur ; tous les autres outils sont gratuits. Donc : regarder avant de recalculer.

## La boucle en quatre temps

1. **Suggérer.** Appeler `suggest_preset` sur l'image (`image_base64`, `image_url` ou `source_job_id`). C'est gratuit, rien n'est calculé. Ou passer `"preset":"auto"` à `vectorize_image`.
2. **Calculer.** Appeler `vectorize_image` avec ce préréglage. Pour un sticker, une vitrophanie ou une impression découpée, ajouter `cut_contour` avec la largeur réelle `width_mm` (ses marges sont en mm à cette taille). La réponse est immédiate, avec un `job_id` : sonder `get_job` jusqu'à `done` (ou `failed`). C'est la seule étape décomptée.
3. **Voir et contrôler.** Appeler `get_preview` (`"side":"both"` compare avec l'original ; `zoom` cadre une boîte du contrôle ou la partie dont l'utilisateur se plaint), puis `check_cut` avec la largeur réelle `width_mm` (et `safety_mm`, `spacing_mm` de l'imprimeur s'il les a donnés). Lire `report.blocking`, `printer.status` et `advice`.
4. **Corriger par le conseil.** Prendre le premier conseil de `advice` et recalculer depuis la même source (`source_job_id` : aucun nouvel envoi), puis revenir au temps 3. La façon d'appliquer chaque conseil est ci-dessous.

## Appliquer un conseil

- `setting` est un réglage du moteur (`tolerance`, `smoothing`, `noise`, `colors`…) : le passer dans `options` avec sa `value` (ou d'un cran dans sa `direction`), avec le préréglage concret (`preset_suggested.preset` de `get_job` après `"auto"`, qui ne prend pas d'options).
- `setting` vaut `contour` : un nombre est la nouvelle `cut_contour.margin_mm`, un mot le nouveau `cut_contour.mode`.
- `setting` vaut `width_mm` : l'échelle est inconnue. Demander la largeur réelle à l'utilisateur et relancer `check_cut` : aucun nouveau calcul.
- `setting` vaut `none` : rien dans Homotope ne le corrige (la source, la mise en page ou le fichier de l'imprimeur doit changer). Dire à l'utilisateur le texte `why` et ne plus recalculer.

## Quand s'arrêter

- S'arrêter quand `check_cut` passe (`report.blocking` vaut 0 et `printer.status` vaut `ok` ; `warn` seulement si l'utilisateur l'accepte) ET que `get_preview` zoomé ne montre plus le défaut nommé par l'utilisateur.
- 3 calculs au plus par image. Après le dernier, montrer le meilleur résultat et les conseils restants au lieu de recalculer.
- S'arrêter aussitôt sur un conseil `none`, sur un 402 ou sur un 429 `too_many_variants`.

## Les bornes

- Chaque `vectorize_image` est un calcul : un des 2 essais du mois du plan Gratuit (les mêmes qu'à l'atelier), puis le quota Pro (100 calculs par mois), puis un crédit. Un calcul échoué est rendu.
- 402 `payment_required` : le compte n'a plus de droit. L'erreur porte `purchaseUrl` : la donner à l'utilisateur, ne pas réessayer, ne jamais citer de prix (ils sont sur la page Tarifs).
- 429 `too_many_variants` : plus de 8 calculs de la même image en une heure glissante. `retryAfterSeconds` dit quand ; en attendant, regarder (`get_preview`, `check_cut`) plutôt que calculer.
- 429 `rate_limited` (`suggest_preset` 30 par minute et par clé ou connexion, `get_preview` 30 par minute et par compte) ou `too_many_jobs` (file pleine) : attendre `retryAfterSeconds`.
- L'image d'origine est gardée 7 jours. Ensuite, `source_job_id`, le côté `source` de `get_preview` et `suggest_preset` par calcul répondent 410 `source_expired` : redemander l'image à l'utilisateur.
- `get_preview` : `width` jusqu'à 1024 px, 1 Mpx au plus ; `zoom` est en pixels de l'image, le repère des boîtes de `check_cut`.

## Ce que chaque outil coûte au compte

- `vectorize_image` : un calcul (essai, quota Pro ou crédit).
- `suggest_preset`, `get_preview`, `check_cut` et ses conseils `advice`, `read_printer_template` : gratuits, rien d'écrit.
- `get_job`, `get_svg`, `get_result`, `list_vectorizations` : gratuits ; les formats d'un calcul terminé sont compris dans le calcul.

## Fichiers de fabrication et contrôle imprimeur

- `get_result` avec `"format":"pdf"`, la largeur réelle `width_mm` (fichier à l'échelle 1:1, ce que demandent les imprimeurs) et `bleed_mm` (souvent 2 mm). Un calcul soumis avec `cut_contour` porte un calque CutContour en ton direct ; `white_underprint` et `finish_layers` ajoutent le blanc et les calques de finition de l'imprimeur.
- DXF pour une découpeuse : `"format":"dxf"` (une couche par couleur), `cut_only` pour le CutContour seul ; `layers` donne les séparations.
- L'imprimeur a envoyé un gabarit PDF ? `read_printer_template` (`pdf_url` ou base64, gratuit, rien n'est gardé) en rend le format fini, le fond perdu et la zone de sécurité : les recopier dans `get_result` en `page_width_mm`, `page_height_mm`, `bleed_mm` et `safe_mm` (`same_pages` à 2 : recto-verso, `verso_job_id`). L'utilisateur a dessiné son tracé de découpe ? Le passer à `vectorize_image` en `cut_contour_image_url` (ou en base64) à la place de `cut_contour`. `get_preview` prend `white_underprint` et `finish_layers` pour montrer ces calques sur le résultat.
- La partie imprimeur de `check_cut` exige `width_mm` : formes à moins de `safety_mm` du trait de coupe (3 mm par défaut), stickers plus proches que `spacing_mm` (4 mm par défaut), traits sous 0,25 pt, un seul CutContour fermé en mode `single`. Sans `width_mm`, ces contrôles sont « indisponibles », jamais réussis.

## Exemple : une vitrophanie de 140 × 40 cm

L'utilisateur veut une vitrophanie de 1 400 mm de large, avec contour de découpe et 2 mm de fond perdu. Deux calculs ici ; un troisième seulement si le second contrôle échoue encore.

```
suggest_preset    {"image_url":"https://…/vitrine.png"}
vectorize_image   {"image_url":"https://…/vitrine.png","preset":"auto",
                   "cut_contour":{"width_mm":1400}}
get_job           {"job_id":"<id>"}            (until "done")
get_preview       {"job_id":"<id>","side":"both","width":1024}
check_cut         {"job_id":"<id>","width_mm":1400}
vectorize_image   {"source_job_id":"<id>","preset":"<preset_suggested.preset>",
                   "cut_contour":{"width_mm":1400,"margin_mm":<advice value>}}
check_cut         {"job_id":"<id2>","width_mm":1400}
get_result        {"job_id":"<id2>","format":"pdf","width_mm":1400,"bleed_mm":2}
```

## Se brancher

Claude Code : ajouter le serveur, puis se connecter depuis `/mcp` (OAuth, le compte Homotope de l'utilisateur). Un script utilise une clé d'API dans l'en-tête `Authorization: Bearer` ; ne jamais écrire une clé dans une invite, un fichier ou un dépôt.

```
claude mcp add --transport http homotope https://homotope.app/mcp
```