use_mcp_tool

A ferramenta use_mcp_tool permite a interação com ferramentas externas fornecidas por servidores conectados do Protocolo de Contexto de Modelo (MCP). Ela estende as capacidades do AI Cockpit Reasoning com funcionalidades específicas de domínio através de um protocolo padronizado.

Parâmetros

A ferramenta aceita estes parâmetros:

• server_name (obrigatório): O nome do servidor MCP que fornece a ferramenta
• tool_name (obrigatório): O nome da ferramenta a ser executada
• arguments (obrigatório/opcional): Um objeto JSON contendo os parâmetros de entrada da ferramenta, seguindo o esquema de entrada da ferramenta. Pode ser opcional para ferramentas que não exigem entrada.

O Que Faz

Esta ferramenta permite que o AI Cockpit Reasoning acesse funcionalidades especializadas fornecidas por servidores MCP externos. Cada servidor MCP pode oferecer várias ferramentas com capacidades únicas, estendendo o AI Cockpit Reasoning além de sua funcionalidade integrada. O sistema valida os argumentos em relação a esquemas, gerencia as conexões do servidor e processa respostas de vários tipos de conteúdo (texto, imagem, recurso).

Quando é usada?

• Quando é necessária uma funcionalidade especializada não disponível nas ferramentas principais
• Quando são necessárias operações específicas de domínio
• Quando é necessária a integração com sistemas ou serviços externos
• Ao trabalhar com dados que exigem processamento ou análise específicos
• Ao acessar ferramentas proprietárias através de uma interface padronizada

Principais Características

• Usa o protocolo MCP padronizado através da biblioteca @modelcontextprotocol/sdk
• Suporta múltiplos mecanismos de transporte (StdioClientTransport e SSEClientTransport)
• Valida os argumentos usando a validação de esquema Zod tanto no lado do cliente quanto no do servidor
• Processa múltiplos tipos de conteúdo de resposta: texto, imagem e referências de recursos
• Gerencia o ciclo de vida do servidor com reinicializações automáticas quando o código do servidor muda
• Fornece um mecanismo "sempre permitir" para ignorar a aprovação de ferramentas confiáveis
• Funciona com a ferramenta complementar access_mcp_resource para recuperação de recursos
• Mantém o rastreamento e o tratamento adequados de erros para operações com falha
• Suporta tempos limite configuráveis (1-3600 segundos, padrão: 60 segundos)
• Permite que os observadores de arquivos detectem e recarreguem automaticamente as alterações do servidor

Limitações

• Depende de servidores MCP externos estarem disponíveis e conectados
• Limitado às ferramentas fornecidas pelos servidores conectados
• As capacidades da ferramenta variam entre diferentes servidores MCP
• Problemas de rede podem afetar a confiabilidade e o desempenho
• Requer a aprovação do usuário antes da execução (a menos que esteja na lista "sempre permitir")
• Não pode executar várias operações de ferramentas MCP simultaneamente

Configuração do Servidor

Os servidores MCP podem ser configurados globalmente ou no nível do projeto:

• Configuração Global: Gerenciada através das configurações da extensão AI Cockpit Reasoning no VS Code. Estas se aplicam a todos os projetos, a menos que sejam substituídas.
• Configuração no Nível do Projeto: Definida em um arquivo .AI Cockpitcode/mcp.json no diretório raiz do seu projeto.
• Isso permite configurações de servidor específicas do projeto.
• Os servidores no nível do projeto têm precedência sobre os servidores globais se compartilharem o mesmo nome.
• Como o .AI Cockpitcode/mcp.json pode ser versionado, ele simplifica o compartilhamento de configurações com sua equipe.

Como Funciona

Quando a ferramenta use_mcp_tool é invocada, ela segue este processo:

1. Inicialização e Validação:

   • O sistema verifica se o hub MCP está disponível
   • Confirma se o servidor especificado existe e está conectado
   • Valida se a ferramenta solicitada existe no servidor
   • Os argumentos são validados em relação à definição do esquema da ferramenta
   • As configurações de tempo limite são extraídas da configuração do servidor (padrão: 60 segundos)

2. Execução e Comunicação:

   • O sistema seleciona o mecanismo de transporte apropriado:
     • StdioClientTransport: Para comunicação com processos locais via E/S padrão
     • SSEClientTransport: Para comunicação com servidores HTTP via Eventos Enviados pelo Servidor
   • Uma solicitação é enviada com o nome do servidor, o nome da ferramenta e os argumentos validados
   • A comunicação usa a biblioteca @modelcontextprotocol/sdk para interações padronizadas
   • A execução da solicitação é rastreada com tratamento de tempo limite para evitar operações suspensas

3. Processamento da Resposta:

   • As respostas podem incluir múltiplos tipos de conteúdo:
     • Conteúdo de texto: Respostas de texto simples
     • Conteúdo de imagem: Dados de imagem binários com informações de tipo MIME
     • Referências de recursos: URIs para acessar recursos do servidor (funciona com access_mcp_resource)
   • O sistema verifica a flag isError para determinar se o tratamento de erros é necessário
   • Os resultados são formatados para exibição na interface do AI Cockpit Reasoning

4. Manuseio de Recursos e Erros:

   • O sistema usa padrões WeakRef para evitar vazamentos de memória
   • Um contador de erros consecutivos rastreia e gerencia os erros
   • Os observadores de arquivos monitoram as alterações no código do servidor e acionam reinicializações automáticas
   • O modelo de segurança requer aprovação para a execução da ferramenta, a menos que esteja na lista "sempre permitir"

Segurança e Permissões

A arquitetura MCP oferece vários recursos de segurança:

• Os usuários devem aprovar o uso da ferramenta antes da execução (por padrão)
• Ferramentas específicas podem ser marcadas para aprovação automática na lista "sempre permitir"
• As configurações do servidor são validadas com esquemas Zod para integridade
• Tempos limite configuráveis evitam operações suspensas (1-3600 segundos)
• As conexões do servidor podem ser ativadas ou desativadas através da interface do usuário

Exemplos de Quando Usado

• Análise de formatos de dados especializados usando ferramentas de processamento do lado do servidor
• Geração de imagens ou outras mídias através de modelos de IA hospedados em servidores externos
• Execução de cálculos complexos específicos de domínio sem implementação local
• Acesso a APIs ou serviços proprietários através de uma interface controlada
• Recuperação de dados de bancos de dados ou fontes de dados especializadas

Exemplos de Uso

Solicitando dados de previsão do tempo com resposta em texto:

<use_mcp_tool>
<server_name>weather-server</server_name>
<tool_name>get_forecast</tool_name>
<arguments>
{
  "city": "San Francisco",
  "days": 5,
  "format": "text"
}
</arguments>
</use_mcp_tool>

Analisando o código-fonte com uma ferramenta especializada que retorna JSON:

<use_mcp_tool>
<server_name>code-analysis</server_name>
<tool_name>complexity_metrics</tool_name>
<arguments>
{
  "language": "typescript",
  "file_path": "src/app.ts",
  "include_functions": true,
  "metrics": ["cyclomatic", "cognitive"]
}
</arguments>
</use_mcp_tool>

Gerando uma imagem com parâmetros específicos:

<use_mcp_tool>
<server_name>image-generation</server_name>
<tool_name>create_image</tool_name>
<arguments>
{
  "prompt": "Uma cidade futurista com carros voadores",
  "style": "photorealistic",
  "dimensions": {
    "width": 1024,
    "height": 768
  },
  "format": "webp"
}
</arguments>
</use_mcp_tool>

Acessando um recurso através de uma ferramenta que retorna uma referência de recurso:

<use_mcp_tool>
<server_name>database-connector</server_name>
<tool_name>query_and_store</tool_name>
<arguments>
{
  "database": "users",
  "type": "select",
  "fields": ["name", "email", "last_login"],
  "where": {
    "status": "active"
  },
  "store_as": "active_users"
}
</arguments>
</use_mcp_tool>

Ferramenta sem argumentos obrigatórios:

<use_mcp_tool>
<server_name>system-monitor</server_name>
<tool_name>get_current_status</tool_name>
<arguments>
{}
</arguments>
</use_mcp_tool>