Cliente tipado

MCP Fusion es útil a ambos lados de la frontera. El servidor se encarga del pipeline de seguridad; el cliente tipado proporciona a la aplicación que lo llama un contrato comprobado por el compilador. No hay SDK generado ni interfaces de argumentos duplicadas.

Exporta el router una vez

En el servidor, envuelve los builders en el registro tipado currificado y exporta su tipo de router inferido:

import { createTypedRegistry } from '@mcpfusion/core';
import type { InferRouter } from '@mcpfusion/core';

const registry = createTypedRegistry<AppContext>()(
  listProjects,
  createProject,
);

registry.registry.attachToServer(server, { contextFactory });
export type AppRouter = InferRouter<typeof registry>;

El valor de ejecución es registry.registry; _builders y _context son campos que transportan tipos. InferRouter intersecta los mapas de router fantasma acumulados por cada builder, por lo que cambiar un parámetro .withString() cambia el contrato de compilación del cliente sin un paso de generación de código.

Ejecuta con el contrato

import { createMCPFusionClient } from '@mcpfusion/core/client';
import type { AppRouter } from './server.js';

const client = createMCPFusionClient<AppRouter>(transport, {
  throwOnError: true,
});

await client.execute('projects.create', {
  workspace_id: 'ws_1',
  name: 'V2',
});

Una acción con puntos se asigna al espacio de nombres de la red: projects.create se convierte en callTool('projects', { ...args, action: 'create' }). Un solo segmento pasa sin cambios. La clave discriminadora predeterminada es action y se puede configurar con discriminatorKey.

Lotes y proxy

executeBatch(calls) usa Promise.all y devuelve los resultados en el orden de las llamadas. Pasa { sequential: true } cuando la segunda llamada depende de la primera. El proxy fluido es un Proxy JavaScript recursivo:

await client.proxy.projects.create({
  workspace_id: 'ws_1',
  name: 'V2',
});

await client.proxy.platform.users.list({ limit: 10 });

La inspección de DevTools y la búsqueda de then de Promise están protegidas, por lo que el proxy no se ejecuta accidentalmente mientras un depurador o un ejecutor de pruebas lo examina.

Middleware del cliente

El middleware del cliente se compila una vez al crear el cliente:

const client = createMCPFusionClient<AppRouter>(transport, {
  middleware: [async (action, args, next) => {
    const started = Date.now();
    const result = await next(action, args);
    metrics.record(action, Date.now() - started, result.isError);
    return result;
  }],
});

La firma es (action, args, next) => Promise<ToolResponse>. Úsalo para trazas del lado del cliente, reintentos con una política explícita o para añadir un encabezado de correlación. El servidor sigue siendo responsable de la autenticación, la validación y la redacción.

Análisis de errores

Con throwOnError: false, el cliente siempre devuelve ToolResponse; inspecciona isError. Con true, una respuesta con isError: true se convierte en MCPFusionClientError con code, recovery, availableActions congelado, severity y la respuesta sin procesar. Analiza el XML <tool_error> del framework, incluidas las listas de acciones heredadas separadas por comas.

Clientes de IA externos

No existen adaptadores de MCP Fusion para frameworks de modelos. Usa sus clientes MCP oficiales:

El framework del servidor sigue siendo responsable del Presenter MVA, DLP y límite del tenant. El runtime del modelo solo consume la superficie MCP resultante.

Próximos pasos

• Errors: el XML que analiza tu cliente
• Tool exposition: cómo las acciones con puntos se convierten en herramientas
• Runtime architecture: cómo las distribuye el servidor