Documentación

MCP Fusion/Protocol and runtime/Motor de prompts

Motor de prompts

Pregunta a la IA sobre Vinkius

Los prompts son ciudadanos de primera clase junto a las tools: esquemas de argumentos tipados, ejecución de tools en loopback desde los handlers de prompt, paginación con cursores firmados, interceptores y plazos de hidratación.

Las tools se ejecutan; los prompts siembran. Un prompt es una plantilla reutilizable, del lado del servidor, para una conversación: el cliente los lista, el usuario elige uno y el servidor devuelve el conjunto de mensajes. MCP Fusion los trata con la misma ingeniería que las tools: entradas tipadas, middleware, paginación y un loopback hacia tu propia pipeline de tools.

Definir un prompt

typescript
import { z } from 'zod';

export default f.prompt('issue.review')
  .describe('Review a pull request with the team checklist')
  .input(z.object({
    repo: z.string().describe('Repository slug'),
    pr: z.number().describe('Pull request number'),
  }))
  .handler(async (ctx, args) => ({
    description: 'Review acme/product#42 against the checklist',
    messages: [
      { role: 'user', content: `Review PR ${args.pr} in ${args.repo}. Use the checklist.` },
      { role: 'assistant', content: 'Sharing the checklist first, then the diff.' },
    ],
  }));

La forma fluent refleja la de las tools: .describe(), .input() (un objeto Zod, o un mapa plano de descriptores de argumentos primitivos), .use(middleware), .title(), .icons(), .tags() y el terminal .handler((ctx, args) => PromptResult). El resultado es { description?, messages } con los roles user y assistant, se permiten varios turnos, y hay bloques de contenido más allá del texto: image, audio, resource_link, resource y los helpers de fábrica de PromptMessage (.system() se codifica como user: MCP no tiene rol system).

La forma declarativa, definePrompt, y la forma f.prompt(name, config) al estilo de f.presenter() existen para layouts de config-as-code. Los argumentos se compilan a Zod con validación plana y estricta: solo primitivos, sin arrays ni objetos anidados. Esa es una restricción de MCP, que se aplica en el momento de la definición con un error claro y no en el momento del wire.

Loopback: prompts que llaman a tools

El contexto del handler de un prompt incluye invokeTool(name, args), un dispatcher hacia la misma pipeline de tools, con middleware, validación y Presenters. Un prompt no es, por tanto, un string estático: puede obtener el diff en vivo del PR con las propias tools del usuario, hidratar el checklist y solo entonces devolver los mensajes sembrados. El RBAC se aplica dentro del loopback (el contexto del llamador es el contexto del llamador), y el AbortSignal de la petición se propaga, de modo que un prompt cancelado cancela el trabajo de tools que disparó.

La hidratación está acotada: un plazo por registry (.timeout(ms) en el builder o setDefaultHydrationTimeout) limita cuánto tiempo puede gastar un prompt llamando tools antes de devolver. Pasado el plazo, la respuesta se envía con un bloque de alerta de hidratación en lugar de dejar colgado al cliente.

Paginación y ciclo de vida

prompts/list se pagina en el servidor: CursorCodec convierte el nombre "after" en un cursor que está firmado con HMAC-SHA256 o cifrado con AES-GCM (configurado con un secreto de 32 bytes; sin uno, una clave efímera por proceso). El tamaño de página por defecto es 50 y se admite el filtrado por tags. Un cursor es opaco para los clientes por diseño.

notifyPromptListChanged() (o la ruta del evento list_changed en las mutaciones de f.prompt en tiempo de ejecución) envía notifications/prompts/list_changed, con un debounce de 100ms, de modo que un registry que crece durante una sesión no envíe spam al cliente.

Interceptores

registry.useInterceptor(fn) se ejecuta después de que un handler devuelve y antes de que el cliente vea el resultado: añadir un <compliance_notice>, anteponer un turno de usuario o inyectar bloques de contexto envueltos en una tag. Interceptar es la forma segura de añadir orientación para toda la organización sin editar cada prompt.

Por qué importa

El impuesto de integración para los equipos que construyen sobre MCP suele ser "el cliente solo tiene tools". Los prompts cierran la otra mitad: envías el workflow, no solo la capacidad. Combinados con Tools, Resources y el Wire format, un solo conector puede entregar a un agente la forma completa de trabajar con tus datos, en el protocolo nativo del agente.

Próximos pasos