Roteamento

O MCP Fusion descobre tools na sua árvore de arquivos do mesmo jeito que o Next.js descobre páginas. Um arquivo, uma tool, o caminho é o nome.

Tools baseadas em arquivos

src/tools/
  billing/
    get-invoice.ts    →  billing.get_invoice
    refund.ts         →  billing.refund
  support/
    tickets/
      search.ts       →  support.tickets.search

Registre-as uma vez na inicialização:

import { initMCPFusion, autoDiscover } from '@mcpfusion/core';

const f = initMCPFusion();
await autoDiscover(f, './src/tools');

Cada arquivo faz default export do seu builder, e a cascata de resolução de exports aceita um default export, um export nomeado tool, ou qualquer builder exportado que reporte o próprio nome.

Tools agrupadas

Uma API com centenas de endpoints não mapeia para centenas de tools. Cada nome, schema e descrição de tool custa janela de contexto, e a precisão do agente cai conforme a lista cresce. O GroupedToolBuilder consolida ações relacionadas em uma única tool com um discriminador:

f.group('billing')
  .describe('Invoice operations')
  .action('get', (a) => a
    .withString('id', 'Invoice ID')
    .requiredFor('get', ['id']))
  .action('refund', (a) => a
    .withString('id', 'Invoice ID')
    .withNumber('amount_cents', 'Amount in CENTS')
    .requiredFor('refund', ['id', 'amount_cents']))
  .returns(InvoicePresenter);

O agente chama billing com um argumento discriminador, e as anotações de "Required for" dizem a ele quais parâmetros cada ação precisa. Uma superfície plana de 500 endpoints se torna um punhado de tools inteligentes, o que é a maior economia de tokens disponível em conectores grandes. Veja Tools para o builder por tool e Governance para saber como superfícies agrupadas continuam auditáveis.

Cadeias de middleware

O middleware é aplicado globalmente por árvore de diretórios e por tool:

// A middleware derives context; its return object merges into ctx.
const withTenant = f.middleware(async (ctx) => ({
  tenantId: resolveTenant(ctx.request),
}));

f.query('billing.get_invoice').use(withTenant);

• O f.middleware() global roda para toda tool
• .use() em um builder adiciona middleware específico da tool
• As cadeias são pré-compiladas em tempo de build em um pipeline O(1), então adicionar middleware não torna o caminho da requisição mais lento

O contexto retornado pelo middleware é mesclado em ctx, tipado pelo genérico initMCPFusion<AppContext>(). Todo handler, middleware e Presenter a jusante vê o mesmo contexto tipado, e é assim que o isolamento de tenant permanece consistente em todo o conector.

Inicialização e contexto

f.registry.attachToServer(server, {
  contextFactory: async (extra) => ({
    db: await pool.acquire(),
    tenantId: resolveTenant(extra),
  }),
});

O contextFactory roda por requisição, então recursos por requisição, como conexões de banco e identidade de tenant, são novos e isolados. Tudo o que ele retorna é o ctx que seus handlers recebem.

Próximos passos

• Tools: o builder em si, parâmetros e state gating
• Quickstart: um conector mínimo funcional
• Deploy: implante a árvore inteira na Vinkius Cloud