Vertex AI MCP Server

Interaja com os modelos Gemini do Vertex AI do Google Cloud para assistência em codificação e respostas a consultas gerais.

GitHub
88
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge

Vertex AI MCP Server

smithery badge

Este projeto implementa um servidor Model Context Protocol (MCP) que fornece um conjunto abrangente de ferramentas para interagir com os modelos Gemini do Google Cloud Vertex AI, com foco em assistência de codificação e resposta a perguntas gerais.

Vertex AI Server MCP server

Limite de segurança

Este servidor inclui ferramentas de gravação no sistema de arquivos e execução de terminal, além de ferramentas de modelo e pesquisa. Execute-o com uma identidade dedicada de baixo privilégio, limite seu acesso ao sistema de arquivos e à rede e mantenha ferramentas consequentes atrás de aprovação explícita. Não trate um prompt de confirmação do cliente MCP como autorização no lado do servidor.

Para os tradeoffs de implementação que este projeto expôs, juntamente com outros seis codebases MCP públicos, consulte O que construir sete servidores MCP me ensinou sobre MCP em produção. O artigo usa este repositório como evidência pública de engenharia; ele não afirma que todos os controles de produção discutidos lá já estão implementados aqui.

Recursos

  • Fornece acesso aos modelos Vertex AI Gemini por meio de inúmeras ferramentas MCP.
  • Suporta fundamentação de pesquisa na web (answer_query_websearch) e resposta direta com conhecimento (answer_query_direct).
  • ID do modelo, temperatura, comportamento de streaming, tokens máximos de saída e configurações de repetição configuráveis por meio de variáveis de ambiente.
  • Usa API de streaming por padrão para melhor responsividade potencial.
  • Inclui lógica básica de repetição para erros transitórios de API.
  • Filtros de segurança mínimos aplicados (BLOCK_NONE) para reduzir bloqueios potenciais (use com cautela).

Ferramentas fornecidas

Consulta e geração (foco em IA)

  • answer_query_websearch: Responde a uma consulta em linguagem natural usando o modelo Vertex AI configurado, aprimorado com resultados do Google Search.
  • answer_query_direct: Responde a uma consulta em linguagem natural usando apenas o conhecimento interno do modelo Vertex AI configurado.
  • explain_topic_with_docs: Fornece uma explicação detalhada para uma consulta sobre um tópico específico de software, sintetizando informações principalmente de documentação oficial encontrada via pesquisa na web.
  • get_doc_snippets: Fornece trechos de código precisos e autoritativos ou respostas concisas para consultas técnicas, pesquisando documentação oficial.
  • generate_project_guidelines: Gera um documento estruturado de diretrizes de projeto (Markdown) com base em uma lista especificada de tecnologias (opcionalmente com versões), usando pesquisa na web para melhores práticas.

Ferramentas de pesquisa e análise

  • code_analysis_with_docs: Analisa trechos de código comparando-os com as melhores práticas da documentação oficial, identificando possíveis bugs, problemas de desempenho e vulnerabilidades de segurança.
  • technical_comparison: Compara várias tecnologias, frameworks ou bibliotecas com base em critérios específicos, fornecendo tabelas de comparação detalhadas com prós/contras e casos de uso.
  • architecture_pattern_recommendation: Sugere padrões de arquitetura para casos de uso específicos com base nas melhores práticas do setor, com exemplos de implementação e considerações.
  • dependency_vulnerability_scan: Analisa dependências do projeto em busca de vulnerabilidades de segurança conhecidas, fornecendo informações detalhadas e estratégias de mitigação.
  • database_schema_analyzer: Revisa esquemas de banco de dados quanto a normalização, indexação e problemas de desempenho, sugerindo melhorias com base nas melhores práticas específicas do banco de dados.
  • security_best_practices_advisor: Fornece recomendações de segurança para tecnologias ou cenários específicos, com exemplos de código para implementar práticas seguras.
  • testing_strategy_generator: Cria estratégias abrangentes de teste para aplicativos ou recursos, sugerindo tipos de teste apropriados com metas de cobertura.
  • regulatory_compliance_advisor: Fornece orientação sobre requisitos regulatórios para setores específicos (GDPR, HIPAA, etc.), com abordagens de implementação para conformidade.
  • microservice_design_assistant: Ajuda a projetar arquiteturas de microsserviços para domínios específicos, com recomendações de limites de serviço e padrões de comunicação.
  • documentation_generator: Cria documentação abrangente para código, APIs ou sistemas, seguindo as melhores práticas do setor para documentação técnica.

Operações de sistema de arquivos

  • read_file_content: Lê o conteúdo completo de um ou mais arquivos. Forneça uma única string de caminho ou uma matriz de strings de caminho.
  • write_file_content: Cria novos arquivos ou sobrescreve completamente arquivos existentes. O argumento 'writes' aceita um único objeto ({path, content}) ou uma matriz de tais objetos.
  • edit_file_content: Faz edições baseadas em linhas em um arquivo de texto, retornando uma prévia do diff ou aplicando alterações.
  • list_directory_contents: Lista arquivos e diretórios diretamente dentro de um caminho especificado (não recursivo).
  • get_directory_tree: Obtém uma visualização recursiva em árvore de arquivos e diretórios como JSON.
  • move_file_or_directory: Move ou renomeia arquivos e diretórios.
  • search_filesystem: Pesquisa recursivamente arquivos/diretórios que correspondem a um padrão de nome, com exclusões opcionais.
  • get_filesystem_info: Recupera metadados detalhados (tamanho, datas, tipo, permissões) sobre um arquivo ou diretório.
  • execute_terminal_command: Executa um comando de shell, opcionalmente especificando cwd e timeout. Retorna stdout/stderr.

Operações combinadas de IA + sistema de arquivos

  • save_generate_project_guidelines: Gera diretrizes de projeto com base em uma pilha de tecnologia e salva o resultado em um caminho de arquivo especificado.
  • save_doc_snippet: Encontra trechos de código da documentação e salva o resultado em um caminho de arquivo especificado.
  • save_topic_explanation: Gera uma explicação detalhada de um tópico com base na documentação e salva o resultado em um caminho de arquivo especificado.
  • save_answer_query_direct: Responde a uma consulta usando apenas conhecimento interno e salva a resposta em um caminho de arquivo especificado.
  • save_answer_query_websearch: Responde a uma consulta usando resultados de pesquisa na web e salva a resposta em um caminho de arquivo especificado.

(Nota: Os esquemas de entrada/saída para cada ferramenta são definidos em seus respectivos arquivos dentro de src/tools/ e expostos por meio do servidor MCP.)

Pré-requisitos

  • Node.js (v18+)
  • Bun (npm install -g bun)
  • Projeto do Google Cloud com faturamento habilitado.
  • API Vertex AI habilitada no projeto GCP.
  • Autenticação do Google Cloud configurada em seu ambiente (Application Default Credentials via gcloud auth application-default login é recomendado, ou uma chave de conta de serviço).

Configuração e instalação

  1. Clonar/Colocar projeto: Certifique-se de que os arquivos do projeto estejam no local desejado.
  2. Instalar dependências: 
    bun install
  3. Configurar ambiente:
    • Crie um arquivo .env na raiz do projeto (copie .env.example).
    • Defina as variáveis de ambiente obrigatórias e opcionais conforme descrito em .env.example.
      • Defina AI_PROVIDER como "vertex" ou "gemini".
      • Se AI_PROVIDER="vertex", GOOGLE_CLOUD_PROJECT é obrigatório.
      • Se AI_PROVIDER="gemini", GEMINI_API_KEY é obrigatório.
  4. Compilar o servidor: 
    bun run build
    Isso compila o código TypeScript para build/index.js.

Uso (autônomo / NPX)

Uma vez publicado no npm, você pode executar este servidor diretamente usando npx:

# Ensure required environment variables are set (e.g., GOOGLE_CLOUD_PROJECT)
bunx vertex-ai-mcp-server

Alternativamente, instale-o globalmente:

bun install -g vertex-ai-mcp-server
# Then run:
vertex-ai-mcp-server

Nota: Executar de forma autônoma requer definir as variáveis de ambiente necessárias (como GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, credenciais de autenticação se não estiver usando ADC) em seu ambiente de shell antes de executar o comando.

Instalação via Smithery

Para instalar o Vertex AI Server para Claude Desktop automaticamente via Smithery:

bunx -y @smithery/cli install @shariqriazz/vertex-ai-mcp-server --client claude

Executando com Cline

  1. Configurar configurações MCP: Adicione/atualize a configuração no arquivo de configurações MCP do Cline (por exemplo, .roo/mcp.json). Você tem duas maneiras principais de configurar o comando:

    Opção A: Usando Node (caminho direto - recomendado para desenvolvimento)

    Este método usa node para executar o script compilado diretamente. É útil durante o desenvolvimento quando você tem o código clonado localmente.

    {
  "mcpServers": {
    "vertex-ai-mcp-server": {
      "command": "node",
      "args": [
        "/full/path/to/your/vertex-ai-mcp-server/build/index.js" // Use absolute path or ensure it's relative to where Cline runs node
      ],
      "env": {
        // --- General AI Configuration ---
        "AI_PROVIDER": "vertex", // "vertex" or "gemini"
        // --- Required (Conditional) ---
        "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", // Required if AI_PROVIDER="vertex"
        // "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY", // Required if AI_PROVIDER="gemini"
        // --- Optional Model Selection ---
        "VERTEX_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="vertex" (Example override)
        "GEMINI_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="gemini"
        // --- Optional AI Parameters ---
        "GOOGLE_CLOUD_LOCATION": "us-central1", // Specific to Vertex AI
        "AI_TEMPERATURE": "0.0",
        "AI_USE_STREAMING": "true",
        "AI_MAX_OUTPUT_TOKENS": "65536", // Default from .env.example
        "AI_MAX_RETRIES": "3",
        "AI_RETRY_DELAY_MS": "1000",
        // --- Optional Vertex Authentication ---
        // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json" // If using Service Account Key for Vertex
      },
      "disabled": false,
      "alwaysAllow": [
         // Add tool names here if you don't want confirmation prompts
         // e.g., "answer_query_websearch"
      ],
      "timeout": 3600 // Optional: Timeout in seconds
    }
    // Add other servers here...
  }
}
    • Importante: Certifique-se de que o caminho args aponte corretamente para o arquivo build/index.js. Usar um caminho absoluto pode ser mais confiável.

    Opção B: Usando NPX (requer pacote publicado no npm)

    Este método usa npx para baixar e executar automaticamente o pacote do servidor do registro npm. Isso é conveniente se você não quiser clonar o repositório.

    {
  "mcpServers": {
    "vertex-ai-mcp-server": {
      "command": "bunx", // Use bunx
      "args": [
        "-y", // Auto-confirm installation
        "vertex-ai-mcp-server" // The npm package name
      ],
      "env": {
        // --- General AI Configuration ---
        "AI_PROVIDER": "vertex", // "vertex" or "gemini"
        // --- Required (Conditional) ---
        "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", // Required if AI_PROVIDER="vertex"
        // "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY", // Required if AI_PROVIDER="gemini"
        // --- Optional Model Selection ---
        "VERTEX_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="vertex" (Example override)
        "GEMINI_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="gemini"
        // --- Optional AI Parameters ---
        "GOOGLE_CLOUD_LOCATION": "us-central1", // Specific to Vertex AI
        "AI_TEMPERATURE": "0.0",
        "AI_USE_STREAMING": "true",
        "AI_MAX_OUTPUT_TOKENS": "65536", // Default from .env.example
        "AI_MAX_RETRIES": "3",
        "AI_RETRY_DELAY_MS": "1000",
        // --- Optional Vertex Authentication ---
        // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json" // If using Service Account Key for Vertex
      },
      "disabled": false,
      "alwaysAllow": [
         // Add tool names here if you don't want confirmation prompts
         // e.g., "answer_query_websearch"
      ],
      "timeout": 3600 // Optional: Timeout in seconds
    }
    // Add other servers here...
  }
}
    • Certifique-se de que as variáveis de ambiente no bloco env estejam definidas corretamente, seja correspondendo a .env ou definidas explicitamente aqui. Remova comentários do arquivo JSON real.

  2. Reiniciar/recarregar o Cline: O Cline deve detectar a alteração de configuração e iniciar o servidor.

  3. Usar ferramentas: Agora você pode usar a extensa lista de ferramentas por meio do Cline.

Desenvolvimento

  • Modo de observação: bun run watch
  • Linting: bun run lint
  • Formatação: bun run format

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.