MCP Fusion/Core concepts/Exposición de tools

Exposición de tools

Pregunta a la IA sobre Vinkius

Define las acciones una vez y elige cómo llegan al protocolo: una tool agrupada con discriminador o una tool atómica por acción, además de visibilidad por tags y esquemas por acción.

La forma en que creas un conector y la forma en que el agente lo ve son dos decisiones distintas en MCP Fusion. La capa de exposición se sitúa entre ambas: toma tus builders y compila la superficie tools/list que recibe el cliente. Cambia la estrategia sin tocar un solo handler.

Namespaces: una tool, muchas acciones

La creación usa nombres con puntos, y el primer punto separa el namespace de la acción:

Escribes	Tool MCP	Acción
`f.query('billing.get_invoice')`	`billing`	`get_invoice`
`f.mutation('billing.refund')`	`billing`	`refund`
`f.action('support.tickets.search')`	`support.tickets`	`search`

Los nombres de tools tienen como máximo un punto; los prefijos anidados usan f.router('support.tickets'). El registry fusiona los builders que comparten namespace, así que tres archivos que exportan compliance.scan, compliance.report y compliance.status producen una tool compliance con tres acciones. El agente ve una superficie coherente; tú conservas la organización de un archivo por acción.

Dos estrategias

attachToServer(server, { toolExposition }) elige la forma en el protocolo:

Agrupada es la opción predeterminada para namespaces con varias acciones: una tool MCP por namespace con un campo discriminador, action de forma predeterminada y renombrable con .discriminator('operation'). El agente elige la acción como argumento, exactamente como en una API orientada a recursos.

Plana es una tool MCP atómica por acción, llamada billing_get_invoice, con separador configurable. Cada tool recibe su propio esquema depurado, con campos comunes combinados solo con los de esa acción, el discriminador eliminado y sus propias anotaciones. Usa el modo plano cuando la selección de tools del cliente sea débil o cuando las acciones casi no compartan nada.

Las tools planas también convierten las affordances HATEOAS en algo directo: un .suggest('billing.remind') en una superficie plana es una tool que el cliente ya enumera.

Veracidad de las anotaciones

Los verbos semánticos establecen anotaciones MCP, y la exposición las conserva por acción:

Builder	Anotación
`f.query()`	`readOnlyHint: true`
`f.mutation()`	`destructiveHint: true`
`f.action()`	neutral
`.idempotent()`	`idempotentHint: true`

En modo plano cada tool atómica lleva sus propias indicaciones. En modo agrupado la tool lleva el agregado más seguro, y las indicaciones por acción viajan en las descripciones de los esquemas de cada acción. Una mutación destructiva que se presenta como de solo lectura es una mentira sobre la que los clientes actúan, así que el framework nunca infiere una seguridad que tú no hayas declarado.

Las anotaciones de parámetros enseñan

Los esquemas agrupados combinan parámetros comunes y específicos de cada acción, y la descripción de cada campo recibe una anotación de obligatoriedad generada a partir de las propias acciones:

Anotación	Significado
`(always required)`	obligatoria para todas las acciones de la tool
`Required for: refund, void`	obligatoria para todas las acciones indicadas
`Required for: refund. For: get`	obligatoria en algunas y opcional en otras
`For: get, list`	nunca obligatoria, pero usada por esas acciones

El agente no tiene que aprender la matriz a partir de errores: el esquema la declara. Combinada con el enum del discriminador, una tool agrupada es una API que se describe a sí misma.

Visibilidad por tag

.tags('billing', 'finance') marca una tool, y attachToServer(server, { filter }) decide qué expone:

typescript

attachToServer(server, {
  filter: {
    tags: ['finance'],          // AND: must carry every tag
    anyTag: ['public'],         // OR: at least one
    exclude: ['internal'],      // NOT
  },
});

Los tags permiten que una misma base de código sirva a varios productos: el nivel gratuito expone tools públicas, la implementación empresarial expone las internas y el código de handlers permanece idéntico. Consulta Conectores multi-tenant para la versión por solicitud de la misma idea.

Agrupar como estrategia de tokens

Cada nombre de tool, descripción y esquema cuesta contexto en cada turno. Cien tools planas son cien descripciones que el modelo lee antes de planificar. Agrupar diez acciones en una tool con un enum discriminador intercambia tamaño de esquema por tamaño de prompt, normalmente con una gran ventaja por encima de unas diez acciones. .toonDescription() comprime aún más la descripción y compactDescription() proporciona la forma corta para la divulgación progresiva de FSM. La economía se explica en Economía de tokens.

Siguientes pasos

Economía de tokens: pagar menos contexto por la misma superficie
Gating de estado FSM: eliminar tools que el estado prohíbe
Enrutamiento: dónde viven los builders en el disco