Référence des outils MCP

Cette page s’adresse à ceux qui travaillent avec un agent externe, comme Codex, Cursor ou Claude Desktop, connecté à Genie par Local MCP. Pour connecter d’abord un client, consultez Local MCP Bridge.

Outils

Genie expose jusqu’à neuf outils.

Outil	Forfait	Usage
`fm_session`	Gratuit	Statut, fichiers ouverts, fichier actif, contexte du projet et actualisation des métadonnées. Activer un autre fichier demande un forfait payant.
`fm_search`	Gratuit	Recherche dans les guides, schémas et catalogues d’étapes et de fonctions de Genie. `query` requise.
`fm_read`	Gratuit	Lecture d’un script ou d’une cible de métadonnées précise dans le fichier en direct.
`fm_query`	Gratuit	Requêtes SELECT en lecture seule.
`fm_evaluate`	Payant	Évaluation d’un calcul FileMaker. Le fichier n’est jamais modifié.
`fm_stage`	Payant	Validation, aperçu, préparation ou exécution d’une modification. Voir Fonctionnement de la préparation.
`fm_workbench`	Payant	Liste et vérification des éléments Workbench, retrait d’un élément en attente, et préparation d’un groupe de modifications ensemble. Retirer un élément ne modifie jamais votre fichier.
`fm_run`	Payant	`action:start` exécute un script existant du fichier courant. `action:status` lit son résultat optionnel. Chaque lancement demande votre confirmation.
`report_issue`	Gratuit	Optionnel. Envoie un court rapport de diagnostic lorsque Genie ou l’agent rencontre un problème. Indisponible lorsque Product issue reports est désactivé dans Settings ou que le Privacy Mode de Local MCP est actif.

La lecture est gratuite. La préparation et l’exécution demandent un forfait payant. Après un changement de forfait, reconnectez le client pour actualiser ses outils.

Fonctionnement de la préparation

Chaque appel à fm_stage traite une seule modification d’un seul type. action:validate et action:compile_preview vérifient ou prévisualisent la modification. Ils ne modifient jamais votre fichier.

Sans le mode Application automatique : action:stage envoie la modification dans Workbench. Vous la révisez là avant que quoi que ce soit change dans votre fichier.
Avec le mode Application automatique activé : une demande explicite action:execute applique la modification directement. Elle apparaît dans Workbench › Submitted avec son résultat réel.

Le mode Application automatique est désactivé par défaut et s’active dans les réglages de Genie. Les contrôles d’accès, de fichier et de confidentialité s’appliquent dans les deux cas. fm_run demande votre confirmation pour chaque exécution de script, même avec le mode Application automatique activé. Voir Révision, mode Application automatique et annulation.

Quand Claude Code ou Codex appelle les outils

Claude Code et Codex exécutés dans Genie (Claude Code et Codex) utilisent ces mêmes neuf outils par le serveur d’outils local de Genie. Leurs appels se comportent comme ceux de tout autre client MCP, avec les mêmes règles du mode Application automatique :

Sans ce mode, action:stage met la modification en attente de votre révision. Dans Genie, elle apparaît sous forme de carte avec Apply, Review et Copy dans la conversation du programme, et dans Workbench si la carte ne peut pas être remise.
Avec ce mode, action:stage et un action:execute explicite appliquent directement la modification, avec les vérifications natives de Genie et une relecture. Cela inclut les dossiers de scripts, les renommages et les installations de HookSet (kind:script_folders), ainsi que les écritures de modèles là où votre version de FileMaker les permet.
Le forfait payant, les vérifications de fichier et de confidentialité, et le Privacy Mode de Local MCP s’appliquent toujours. fm_run demande toujours votre confirmation à chaque lancement.
Contrairement à l’Agent de Genie, rien ne vérifie la modification d’un moteur par rapport à votre demande.

La lecture reste gratuite, la préparation et l’exécution demandent un forfait payant.

Ce que fm_stage accepte

Type	Usage
`script`	Un nouveau script (`result_type: "new_script"`) ou une modification d’un script nommé (`result_type: "delta_edit"`).
`script_folders`	Créer des dossiers de scripts et y déplacer des scripts. Fonctionne seulement avec le mode Application automatique activé.
`layout`	Créer un modèle, y ajouter des objets ou modifier ses objets, décrits en Layout Schema. Avec le mode Application automatique activé, un `action:execute` explicite l’écrit dans votre fichier sous macOS. Sans le mode Application automatique, il attend dans Workbench, où vous l’appliquez après une confirmation ou copiez les objets pour les coller vous-même. Sous Windows, les objets du modèle sont copiés.
`data`	Une modification de données ou de schéma en SQL FileMaker.
`table_occurrence`	Ajouter une occurrence de table au graphe des liens.
`relationship_graph`	Créer ou modifier des liens, et organiser le graphe.

Les requêtes en lecture seule restent avec fm_query, hors Workbench. Les questions et la planification restent dans l’agent ou dans le chat de Genie.

Préparer des scripts

Préparez un nouveau script ou une modification d’un script nommé par appel. Pour plusieurs scripts, faites un appel à fm_stage par script.
Avant une modification, lisez le script avec fm_read target:script. Il renvoie le script en lignes numérotées. Ancrez chaque modification sur ces numéros de ligne, qui commencent à 1.
Trouvez le Script Schema et les fiches exactes des étapes et fonctions avec fm_search avant d’écrire les étapes.
Quand les noms de métadonnées comptent, lisez-les avec fm_read target:selection et joignez le metadata_selection renvoyé à l’élément préparé.
Préparez les scripts et les modifications de données comme des éléments séparés.
Validez avec action:validate avant de préparer.

Préparer des données et du schéma

Lisez d’abord les tables, rubriques et liens exacts avec fm_read, puis préparez une seule demande avec fm_stage kind:data. Avant qu’une modification de données s’exécute, FileMaker affiche une confirmation avec le SQL et les valeurs exacts.

Résultats de scripts optionnels

La capture du résultat est optionnelle. Aucun script intermédiaire n’est nécessaire, et Genie ne remplace ni n’enveloppe le paramètre du script.

Dans le script FileMaker, enveloppez le résultat dans la dernière étape Exit Script :

Exit Script [ Text Result: Genie_ReturnScriptResult ( $result ) ]

Genie_ReturnScriptResult ( result ) transmet la valeur à une exécution Genie en attente et renvoie cette même valeur sans la modifier. Un script FileMaker parent peut toujours lire Get ( ScriptResult ). Si un script a plusieurs chemins Exit Script qui doivent renvoyer un résultat, utilisez la fonction sur chacun.

Le déroulement :

Appelez fm_run avec action:"start", le fichier et le script exacts, et capture_result:true. Genie vous demande de confirmer l’exécution.
Conservez le run_request_id renvoyé.
Interrogez fm_run avec action:"status" et cet identifiant. Ces vérifications sont en lecture seule et ne demandent pas de nouvelle confirmation.
Considérez l’exécution terminée seulement lorsque le statut est "completed" et que script_completion_observed vaut true. Un lancement mis en file ne suffit pas.

Genie garde une seule exécution avec résultat à la fois pour un même fichier et un même script. Les rappels non demandés, d’un autre script, en double ou superposés sont ignorés. Les résultats restent uniquement dans la mémoire du plug-in, sont limités à un million de caractères et expirent après 15 minutes. Les scripts qui n’utilisent pas la fonction s’exécutent quand même ; vérifiez leur effet avec le plus petit outil en lecture seule utile.

Exemples d’orientation

Demande	Ce que l’agent doit faire
« Crée un script qui exporte Customers en JSON. »	Trouver les guides et le schéma, lire les métadonnées exactes avec `fm_read`, valider avec `fm_stage kind:script action:validate`, puis préparer avec `fm_stage kind:script action:stage`.
« Modifie le script sélectionné pour journaliser avant l’appel API. »	Lire le contenu exact avec `fm_read target:script`, puis préparer un `delta_edit` ciblé avec `fm_stage kind:script`.
« Crée deux scripts : Export Customers et Export Orders. »	Faire deux appels de préparation séparés.
« Crée la table Customers avec les champs Email et Status. »	Inspecter les métadonnées exactes, puis préparer une demande de données avec `fm_stage kind:data`.
« Montre-moi les clients actifs. »	Utiliser `fm_read` pour le schéma, puis `fm_query` pour les lignes en lecture seule.
« Exécute GenieShowDialog et renvoie son résultat JSON. »	Identifier le fichier et le script exacts, appeler `fm_run action:start` avec `capture_result:true`, attendre votre confirmation, puis interroger l’identifiant renvoyé avec `action:status`. Le script doit utiliser `Genie_ReturnScriptResult`.

Ressources principales

Points d’entrée essentiels :

genie://schemas/script-schema
genie://schemas/script-catalog
genie://schemas/layout-schema
genie://context/project
genie://context/scripts
genie://metadata/relationships
genie://metadata/relationship-graph
genie://metadata/selected
genie://metadata/all

genie://context/project inclut le nom du projet, la description, les règles activées, les conventions de nommage, les patterns réutilisables, le modèle de script et guidance_sources, qui indique si chaque valeur vient du Project ou de Generic Personalization. Ce guidage oriente les noms, commentaires, patterns et la structure des scripts. Il ne change jamais ce que l’agent a le droit de faire.

Guides importants :

genie://guides/script-delta-editing
genie://guides/metadata-selection
genie://guides/stage-contract
genie://guides/relationships
genie://guides/layout-design
genie://guides/filemaker-guide-manifest
genie://guides/filemaker-behavior-core
genie://guides/filemaker-script-review
genie://guides/filemaker-script-debug
genie://guides/filemaker-data-behavior
genie://guides/what-not-to-stage

Lorsque l’intégration Klai est activée :

genie://guides/klai-filemaker-business-hooks
genie://guides/klai-hook-execution-contract
genie://guides/klai-helper-inbox-diagnostics
genie://guides/klai-hook-async-data-cache-diagnostics
genie://guides/klai-hook-request-template
genie://guides/klai-resource-map

Les agents orientés modèles peuvent aussi lire :

genie://layout/schema
genie://layout/objects-dictionary
genie://layout/style-ast
genie://layout/stylesheet-contract
genie://layout/fm-attribute-model
genie://layout/design-to-fm-transform
genie://layout/asset-registry
genie://layout/roundtrip-fidelity
genie://layout/paste-survival
genie://layout/host-import-proof
genie://layout/visual-render-proof
genie://layout/completion-audit

Utilisez fm_search avec une query non vide lorsqu’un client expose les outils mais pas les ressources. Les filtres exacts key ou uri restreignent une recherche au même contenu.