Tools

Las tools son lo que el agente llama. En términos de Vinkius son las AI Capabilities de tu conector. MCP Fusion te da un builder fluido con tres puntos de entrada semánticos, y la semántica se mapea a las anotaciones MCP que el agente ve.

Una tool completa

export default f.mutation('billing.refund')
  .describe('Refund an invoice by ID')
  .withString('id', 'Invoice ID')
  .withNumber('amount_cents', 'Amount to refund in CENTS')
  .withOptionalEnum('reason', ['duplicate', 'customer_request', 'fraud'],
    'Why the refund is happening')
  .returns(InvoicePresenter)
  .use(requireAuth)
  .handle(async (input, ctx) => {
    const result = await refunds.create(input, ctx.tenantId);
    if (!result.ok) return result.response;
    return result.value;
  });

Parámetros

• .withString(name, description), .withNumber, .withBoolean, .withEnum y las variantes .withOptional construyen el schema de entrada de Zod
• Las tools guiadas por models pueden usar .fromModel() y reutilizar los campos fillable de un Model como parámetros
• .toonDescription() comprime la descripción de la tool en un formato de pipe que cuesta aproximadamente la mitad de los tokens
• .bindState('approved', 'DISCHARGE') conecta la tool a un estado de FSM, cubierto más abajo

Middleware

.use() añade middleware a una tool. El middleware se compone al estilo Express y cada middleware devuelve un contexto parcial que se fusiona en ctx, y así es como auth, la resolución de tenant y el rate limiting se mantienen fuera de tus handlers:

// A middleware derives context: the returned object merges into ctx,
// typed through the whole fluent chain.
const withUser = f.middleware(async (ctx) => {
  const user = await auth.verify(ctx.request);
  return { user };
});

f.query('billing.get_profile').use(withUser);

Consulta Routing para el middleware global aplicado a cada tool de un directorio.

La mónada Result

Los handlers que pueden fallar devuelven un Result en lugar de lanzar excepciones, y el framework convierte un Failure en una respuesta de tool estructurada sobre la que el agente puede actuar:

import { succeed, fail, toolError } from '@mcpfusion/core';

.handle(async (input) => {
  const invoice = await db.invoices.findUnique({ where: { id: input.id } });
  if (!invoice) {
    return fail(toolError('NOT_FOUND', {
      message: 'No invoice with that ID',
      availableActions: ['billing.list_invoices'],
    }));
  }
  return succeed(invoice);
});

La lista availableActions es contexto autorreparable: cuando el agente eligió un ID equivocado, el error le enseña qué puede hacer en su lugar. Consulta Governance para ver cómo la misma idea funciona ante cambios de contrato.

FSM state gating

Algunas tools no deben existir en ciertos estados. Una tool de discharge no tiene sentido visible antes de que una factura sea aprobada. .bindState() conecta la tool a un estado de flujo de trabajo y MCP Fusion la elimina físicamente de tools/list mientras el estado lo prohíbe:

export default f.action('billing.discharge')
  .describe('Discharge an approved invoice')
  .bindState('approved', 'DISCHARGE')
  .handle(async (input, ctx) => { /* ... */ });

El cliente recibe notifications/tools/list_changed a medida que el estado cambia, así que el menú del agente refleja la realidad. Esto mata la alucinación clásica en la que el model llama a un paso fuera de orden. El state store es conectable, con opciones de Redis y edge KV, así que el gating también funciona en serverless.

Próximos pasos

• Routing: organiza las tools por archivo, agrupa muchas acciones en una tool
• Models and Presenters: moldea lo que devuelve cada tool
• Testing: prueba el pipeline completo en memoria