Referencia de herramientas MCP

Esta página es para quienes trabajan con un agente externo, como Codex, Cursor o Claude Desktop, conectado a Genie por Local MCP. Para conectar primero un cliente, consulta Puente MCP local.

Herramientas

Genie expone hasta nueve herramientas.

Herramienta	Plan	Uso
`fm_session`	Gratis	Estado, archivos abiertos, archivo activo, contexto del proyecto y actualización de metadatos. Activar otro archivo requiere un plan de pago.
`fm_search`	Gratis	Buscar en las guías, esquemas y catálogos de pasos y funciones de Genie. Requiere `query`.
`fm_read`	Gratis	Leer un script o un destino de metadatos exacto del archivo en vivo.
`fm_query`	Gratis	Consultas SELECT de solo lectura.
`fm_evaluate`	De pago	Evaluar un cálculo de FileMaker. Nunca cambia el archivo.
`fm_stage`	De pago	Validar, previsualizar, preparar o ejecutar un cambio. Consulta Cómo funciona la preparación.
`fm_workbench`	De pago	Listar y revisar elementos de Workbench, quitar un elemento en cola y preparar un grupo de cambios juntos. Quitar un elemento nunca cambia tu archivo.
`fm_run`	De pago	`action:start` ejecuta un script existente del archivo actual. `action:status` lee su resultado opcional. Cada inicio pide tu confirmación.
`report_issue`	Gratis	Opcional. Envía un breve informe de diagnóstico cuando Genie o el agente encuentran un problema. No está disponible cuando Product issue reports está desactivado en Settings o el Privacy Mode de Local MCP está activo.

La lectura es gratis. La preparación y la ejecución requieren un plan de pago. Después de cambiar de plan, vuelve a conectar el cliente para que actualice sus herramientas.

Cómo funciona la preparación

Cada llamada a fm_stage trata un solo cambio de un solo tipo. action:validate y action:compile_preview comprueban o previsualizan el cambio. Nunca cambian tu archivo.

Sin el modo Aplicación automática: action:stage envía el cambio a Workbench. Lo revisas allí antes de que cambie nada en tu archivo.
Con el modo Aplicación automática activado: una petición explícita action:execute aplica el cambio directamente. Aparece en Workbench › Submitted con su resultado real.

El modo Aplicación automática está desactivado por defecto y se activa en los ajustes de Genie. Los controles de acceso, de archivo y de privacidad se aplican en ambos casos. fm_run pide tu confirmación en cada ejecución de script, incluso con el modo Aplicación automática activado. Consulta Revisión, modo Aplicación automática y deshacer.

Cuando Claude Code o Codex llaman a las herramientas

Claude Code y Codex ejecutados dentro de Genie (Claude Code y Codex) usan estas mismas nueve herramientas mediante el servidor local de herramientas de Genie. Sus llamadas se comportan como las de cualquier otro cliente MCP, con las mismas reglas del modo Aplicación automática:

Sin ese modo, action:stage deja el cambio en espera de tu revisión. En Genie aparece como una tarjeta con Apply, Review y Copy en la conversación del programa, y en Workbench si no se puede entregar la tarjeta.
Con ese modo, action:stage y un action:execute explícito aplican el cambio directamente, con las comprobaciones nativas de Genie y una relectura. Esto incluye las carpetas de scripts, los cambios de nombre y las instalaciones de HookSet (kind:script_folders), y las escrituras de layouts donde tu versión de FileMaker las permite.
El plan de pago, las comprobaciones de archivo y de privacidad, y el Privacy Mode de Local MCP siguen vigentes. fm_run sigue pidiendo tu confirmación en cada inicio.
A diferencia del Agent de Genie, nada comprueba el cambio de un motor frente a lo que pediste.

Las lecturas siguen siendo gratuitas, y la preparación y la ejecución requieren un plan de pago.

Qué acepta fm_stage

Tipo	Uso
`script`	Un script nuevo (`result_type: "new_script"`) o una edición de un script con nombre (`result_type: "delta_edit"`).
`script_folders`	Crear carpetas de scripts y mover scripts a ellas. Solo funciona con el modo Aplicación automática activado.
`layout`	Crear un layout, añadirle objetos o editar sus objetos, descritos en Layout Schema. Con el modo Aplicación automática activado, un `action:execute` explícito lo escribe en tu archivo en macOS. Sin el modo Aplicación automática, espera en Workbench, donde lo aplicas tras una confirmación o copias los objetos para pegarlos tú mismo. En Windows, los objetos del layout se copian.
`data`	Un cambio de datos o de esquema en SQL de FileMaker.
`table_occurrence`	Añadir una ocurrencia de tabla al gráfico de relaciones.
`relationship_graph`	Crear o editar relaciones y ordenar el gráfico.

Las consultas de solo lectura van por fm_query, fuera de Workbench. Las preguntas y la planificación se quedan en el agente o en el chat de Genie.

Preparar scripts

Prepara un script nuevo o una edición de un script con nombre por llamada. Para varios scripts, haz una llamada a fm_stage por script.
Antes de una edición, lee el script con fm_read target:script. Devuelve el script en líneas numeradas. Ancla cada edición a esos números de línea, que empiezan en 1.
Busca el Script Schema y los registros exactos de pasos y funciones con fm_search antes de escribir los pasos.
Cuando importan los nombres de metadatos, léelos con fm_read target:selection y pasa el metadata_selection devuelto con el elemento preparado.
Prepara los scripts y los cambios de datos como elementos separados.
Valida con action:validate antes de preparar.

Preparar datos y esquema

Lee primero las tablas, campos y relaciones exactos con fm_read y luego prepara una sola petición con fm_stage kind:data. Antes de que se ejecute un cambio de datos, FileMaker muestra una confirmación con el SQL y los valores exactos.

Resultados opcionales de scripts

Capturar el resultado es opcional. No hace falta un script intermedio, y Genie no sustituye ni envuelve el parámetro del script.

En el script de FileMaker, envuelve el resultado en el último paso Exit Script:

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

Genie_ReturnScriptResult ( result ) envía el valor a una ejecución pendiente de Genie y devuelve ese mismo valor sin cambios. Un script padre de FileMaker puede seguir leyendo Get ( ScriptResult ). Si un script tiene varias rutas Exit Script que deben devolver un resultado, usa la función en cada una.

El proceso:

Llama a fm_run con action:"start", el archivo y el script exactos, y capture_result:true. Genie te pide confirmar la ejecución.
Guarda el run_request_id devuelto.
Consulta fm_run con action:"status" y ese identificador. Estas consultas son de solo lectura y no piden otra confirmación.
Da la ejecución por terminada solo cuando el estado es "completed" y script_completion_observed es true. Un inicio en cola no basta.

Genie mantiene una sola ejecución con resultado a la vez para el mismo archivo y script. Las respuestas no solicitadas, de otro script, duplicadas o superpuestas se ignoran. Los resultados solo se guardan en la memoria del plug-in, tienen un límite de un millón de caracteres y caducan a los 15 minutos. Los scripts que no usan la función se ejecutan igualmente; comprueba su efecto con la herramienta de solo lectura más pequeña que sirva.

Ejemplos de enrutamiento

Petición	Qué debe hacer el agente
”Crea un script que exporte Customers como JSON.”	Buscar las guías y el esquema, leer los metadatos exactos con `fm_read`, validar con `fm_stage kind:script action:validate` y preparar con `fm_stage kind:script action:stage`.
”Actualiza el script seleccionado para registrar antes de la llamada a la API.”	Leer el contenido exacto con `fm_read target:script` y preparar un `delta_edit` concreto con `fm_stage kind:script`.
”Crea dos scripts: Export Customers y Export Orders.”	Hacer dos llamadas de preparación separadas.
”Crea la tabla Customers con los campos Email y Status.”	Inspeccionar los metadatos exactos y preparar una petición de datos con `fm_stage kind:data`.
”Muéstrame los clientes activos.”	Usar `fm_read` para el esquema y `fm_query` para las filas de solo lectura.
”Ejecuta GenieShowDialog y devuelve su resultado JSON.”	Identificar el archivo y el script exactos, llamar a `fm_run action:start` con `capture_result:true`, esperar tu confirmación y consultar el identificador devuelto con `action:status`. El script debe usar `Genie_ReturnScriptResult`.

Recursos principales

Puntos de entrada esenciales:

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 incluye el nombre del proyecto, la descripción, las reglas activas, las convenciones de nombres, los patrones reutilizables, la plantilla de script y guidance_sources, que indica si cada valor viene del Project o de Generic Personalization. Esta guía orienta nombres, comentarios, patrones y estructura de scripts. Nunca cambia lo que el agente puede hacer.

Guías importantes:

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

Con la integración Klai activa:

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

Los agentes centrados en presentaciones también pueden leer:

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

Usa fm_search con una query no vacía cuando un cliente expone las herramientas pero no los recursos. Los filtros exactos key o uri limitan una búsqueda al mismo contenido.