MCP Fusion/Core concepts/Exposição de tools

Exposição de tools

Pergunte à IA sobre a Vinkius

Crie ações uma vez e escolha como chegam ao protocolo: uma tool agrupada com discriminador ou uma tool atômica por ação, além de visibilidade por tags e schemas por ação.

A forma como você cria um conector e a forma como o agente o vê são duas decisões diferentes no MCP Fusion. A camada de exposição fica entre elas: recebe seus builders e compila a superfície tools/list que o cliente recebe. Troque a estratégia sem tocar em um único handler.

Namespaces: uma tool, muitas ações

A criação usa nomes com pontos, e o primeiro ponto separa o namespace da ação:

Você escreve	Tool MCP	Ação
`f.query('billing.get_invoice')`	`billing`	`get_invoice`
`f.mutation('billing.refund')`	`billing`	`refund`
`f.action('support.tickets.search')`	`support.tickets`	`search`

Nomes de tools têm no máximo um ponto; prefixos aninhados usam f.router('support.tickets'). Builders que compartilham um namespace são mesclados pelo registry, então três arquivos exportando compliance.scan, compliance.report e compliance.status produzem uma tool compliance com três ações. O agente vê uma superfície coerente; você mantém a organização de um arquivo por ação.

Duas estratégias

attachToServer(server, { toolExposition }) escolhe a forma no protocolo:

Agrupada é o padrão para namespaces com várias ações: uma tool MCP por namespace com um campo discriminador, action por padrão e renomeável com .discriminator('operation'). O agente escolhe a ação como argumento, exatamente como em uma API orientada a recursos.

Plana é uma tool MCP atômica por ação, nomeada billing_get_invoice, com o separador configurável. Cada tool recebe seu próprio schema purificado, com campos comuns mesclados apenas com os da ação, o discriminador removido e suas próprias anotações. Use o modo plano quando a seleção de tools do cliente for fraca ou quando as ações compartilharem quase nada.

Tools planas também são onde as affordances HATEOAS se tornam diretas: um .suggest('billing.remind') em uma superfície plana é uma tool que o cliente já lista.

Verdade das anotações

Verbos semânticos definem anotações MCP, e a exposição as preserva por ação:

Builder	Anotação
`f.query()`	`readOnlyHint: true`
`f.mutation()`	`destructiveHint: true`
`f.action()`	neutra
`.idempotent()`	`idempotentHint: true`

No modo plano, cada tool atômica carrega suas próprias dicas. No modo agrupado, a tool carrega o agregado mais seguro, e as dicas por ação seguem nas descrições do schema de cada ação. Uma mutação destrutiva que se declara somente leitura é uma mentira sobre a qual os clientes agem, então o framework nunca infere segurança que você não declarou.

Anotações de parâmetros ensinam

Schemas agrupados mesclam parâmetros comuns e específicos da ação, e a descrição de cada campo recebe uma anotação de obrigatoriedade gerada a partir das próprias ações:

Anotação	Significado
`(always required)`	obrigatória em todas as ações da tool
`Required for: refund, void`	obrigatória em todas as ações listadas
`Required for: refund. For: get`	obrigatória em algumas e opcional em outras
`For: get, list`	nunca obrigatória, mas usada por essas ações

O agente não precisa aprender a matriz pelos erros; o schema a declara. Combinada com o enum do discriminador, uma tool agrupada é uma API que se descreve sozinha.

Visibilidade por tag

.tags('billing', 'finance') marca uma tool, e attachToServer(server, { filter }) decide o que ela expõe:

typescript

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

Tags são como uma base de código serve a vários produtos: o plano gratuito expõe tools públicas, a implantação empresarial expõe as internas e a base de handlers permanece idêntica. Consulte Conectores multi-tenant para a versão por requisição da mesma ideia.

Agrupamento como estratégia de tokens

Cada nome de tool, descrição e schema custa contexto em cada turno. Cem tools planas significam cem descrições que o modelo lê antes de planejar. Agrupar dez ações em uma tool com um enum discriminador troca tamanho do schema por tamanho do prompt, geralmente uma grande vantagem acima de aproximadamente dez ações. .toonDescription() comprime ainda mais a descrição, e compactDescription() fornece a forma curta para divulgação progressiva de FSM. A economia é explicada em Economia de tokens.

Próximos passos

Economia de tokens: pagar menos contexto pela mesma superfície
Gating de estado FSM: remover tools que o estado proíbe
Roteamento: onde os builders vivem no disco