Vertex AI MCP Server

Interactúa con los modelos Gemini de Vertex AI de Google Cloud para asistencia en codificación y respuesta a consultas generales.

GitHub
88
Prueba este MCPPatrocinado

Documentación

MseeP.ai Security Assessment Badge

Vertex AI MCP Server

smithery badge

Este proyecto implementa un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona un conjunto completo de herramientas para interactuar con los modelos Gemini de Vertex AI de Google Cloud, centrándose en la asistencia de codificación y la respuesta a consultas generales.

Vertex AI Server MCP server

Límite de seguridad

Este servidor incluye herramientas de escritura en el sistema de archivos y ejecución de terminal, además de herramientas de modelo e investigación. Ejecútelo con una identidad dedicada de bajos privilegios, limite su acceso al sistema de archivos y a la red, y mantenga las herramientas de consecuencias importantes detrás de una aprobación explícita. No trate un mensaje de confirmación del cliente MCP como autorización del lado del servidor.

Para conocer las compensaciones de implementación que este proyecto expuso junto con otros seis códigos base MCP públicos, consulte Lo que construir siete servidores MCP me enseñó sobre MCP en producción. El artículo utiliza este repositorio como evidencia pública de ingeniería; no afirma que todos los controles de producción discutidos allí ya estén implementados aquí.

Características

  • Proporciona acceso a los modelos Gemini de Vertex AI a través de numerosas herramientas MCP.
  • Admite la fundamentación de búsqueda web (answer_query_websearch) y la respuesta directa basada en conocimiento (answer_query_direct).
  • ID de modelo, temperatura, comportamiento de transmisión, tokens de salida máximos y configuraciones de reintento configurables mediante variables de entorno.
  • Utiliza la API de transmisión por defecto para una mejor capacidad de respuesta potencial.
  • Incluye lógica básica de reintento para errores transitorios de la API.
  • Se aplican filtros de seguridad mínimos (BLOCK_NONE) para reducir el bloqueo potencial (usar con precaución).

Herramientas proporcionadas

Consulta y generación (enfocadas en IA)

  • answer_query_websearch: Responde una consulta en lenguaje natural utilizando el modelo Vertex AI configurado mejorado con resultados de Búsqueda de Google.
  • answer_query_direct: Responde una consulta en lenguaje natural utilizando solo el conocimiento interno del modelo Vertex AI configurado.
  • explain_topic_with_docs: Proporciona una explicación detallada para una consulta sobre un tema de software específico, sintetizando información principalmente de documentación oficial encontrada mediante búsqueda web.
  • get_doc_snippets: Proporciona fragmentos de código precisos y autorizados o respuestas concisas para consultas técnicas mediante la búsqueda en documentación oficial.
  • generate_project_guidelines: Genera un documento estructurado de pautas de proyecto (Markdown) basado en una lista especificada de tecnologías (opcionalmente con versiones), utilizando búsqueda web para mejores prácticas.

Herramientas de investigación y análisis

  • code_analysis_with_docs: Analiza fragmentos de código comparándolos con las mejores prácticas de la documentación oficial, identificando posibles errores, problemas de rendimiento y vulnerabilidades de seguridad.
  • technical_comparison: Compara múltiples tecnologías, marcos de trabajo o bibliotecas según criterios específicos, proporcionando tablas de comparación detalladas con pros/contras y casos de uso.
  • architecture_pattern_recommendation: Sugiere patrones de arquitectura para casos de uso específicos basados en las mejores prácticas de la industria, con ejemplos de implementación y consideraciones.
  • dependency_vulnerability_scan: Analiza las dependencias del proyecto en busca de vulnerabilidades de seguridad conocidas, proporcionando información detallada y estrategias de mitigación.
  • database_schema_analyzer: Revisa esquemas de bases de datos para problemas de normalización, indexación y rendimiento, sugiriendo mejoras basadas en las mejores prácticas específicas de la base de datos.
  • security_best_practices_advisor: Proporciona recomendaciones de seguridad para tecnologías o escenarios específicos, con ejemplos de código para implementar prácticas seguras.
  • testing_strategy_generator: Crea estrategias integrales de prueba para aplicaciones o funciones, sugiriendo tipos de prueba apropiados con objetivos de cobertura.
  • regulatory_compliance_advisor: Proporciona orientación sobre requisitos regulatorios para industrias específicas (GDPR, HIPAA, etc.), con enfoques de implementación para el cumplimiento.
  • microservice_design_assistant: Ayuda a diseñar arquitecturas de microservicios para dominios específicos, con recomendaciones de límites de servicio y patrones de comunicación.
  • documentation_generator: Crea documentación integral para código, API o sistemas, siguiendo las mejores prácticas de la industria para documentación técnica.

Operaciones del sistema de archivos

  • read_file_content: Lee el contenido completo de uno o más archivos. Proporcione una sola cadena de ruta o una matriz de cadenas de ruta.
  • write_file_content: Crea archivos nuevos o sobrescribe completamente archivos existentes. El argumento 'writes' acepta un solo objeto ({path, content}) o una matriz de dichos objetos.
  • edit_file_content: Realiza ediciones basadas en líneas a un archivo de texto, devolviendo una vista previa del diff o aplicando los cambios.
  • list_directory_contents: Lista archivos y directorios directamente dentro de una ruta especificada (no recursivo).
  • get_directory_tree: Obtiene una vista de árbol recursiva de archivos y directorios como JSON.
  • move_file_or_directory: Mueve o renombra archivos y directorios.
  • search_filesystem: Busca recursivamente archivos/directorios que coincidan con un patrón de nombre, con exclusiones opcionales.
  • get_filesystem_info: Recupera metadatos detallados (tamaño, fechas, tipo, permisos) sobre un archivo o directorio.
  • execute_terminal_command: Ejecuta un comando de shell, especificando opcionalmente cwd y timeout. Devuelve stdout/stderr.

Operaciones combinadas de IA + sistema de archivos

  • save_generate_project_guidelines: Genera pautas de proyecto basadas en una pila tecnológica y guarda el resultado en una ruta de archivo especificada.
  • save_doc_snippet: Encuentra fragmentos de código de la documentación y guarda el resultado en una ruta de archivo especificada.
  • save_topic_explanation: Genera una explicación detallada de un tema basada en documentación y guarda el resultado en una ruta de archivo especificada.
  • save_answer_query_direct: Responde una consulta usando solo conocimiento interno y guarda la respuesta en una ruta de archivo especificada.
  • save_answer_query_websearch: Responde una consulta usando resultados de búsqueda web y guarda la respuesta en una ruta de archivo especificada.

(Nota: Los esquemas de entrada/salida para cada herramienta están definidos en sus respectivos archivos dentro de src/tools/ y se exponen a través del servidor MCP.)

Requisitos previos

  • Node.js (v18+)
  • Bun (npm install -g bun)
  • Proyecto de Google Cloud con facturación habilitada.
  • API de Vertex AI habilitada en el proyecto de GCP.
  • Autenticación de Google Cloud configurada en su entorno (se recomiendan Credenciales de Aplicación Predeterminadas mediante gcloud auth application-default login, o una Clave de Cuenta de Servicio).

Configuración e instalación

  1. Clonar/Colocar el proyecto: Asegúrese de que los archivos del proyecto estén en la ubicación deseada.
  2. Instalar dependencias: 
    bun install
  3. Configurar el entorno:
    • Cree un archivo .env en la raíz del proyecto (copie .env.example).
    • Establezca las variables de entorno requeridas y opcionales como se describe en .env.example.
      • Establezca AI_PROVIDER a "vertex" o "gemini".
      • Si AI_PROVIDER="vertex", GOOGLE_CLOUD_PROJECT es obligatorio.
      • Si AI_PROVIDER="gemini", GEMINI_API_KEY es obligatorio.
  4. Compilar el servidor: 
    bun run build
    Esto compila el código TypeScript a build/index.js.

Uso (independiente / NPX)

Una vez publicado en npm, puede ejecutar este servidor directamente usando npx:

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

Alternativamente, instálelo globalmente:

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

Nota: Ejecutar de forma independiente requiere establecer las variables de entorno necesarias (como GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, credenciales de autenticación si no se usa ADC) en su entorno de shell antes de ejecutar el comando.

Instalación mediante Smithery

Para instalar Vertex AI Server para Claude Desktop automáticamente mediante Smithery:

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

Ejecución con Cline

  1. Configurar ajustes de MCP: Agregue/actualice la configuración en su archivo de ajustes MCP de Cline (por ejemplo, .roo/mcp.json). Tiene dos formas principales de configurar el comando:

    Opción A: Usando Node (ruta directa - recomendada para desarrollo)

    Este método usa node para ejecutar el script compilado directamente. Es útil durante el desarrollo cuando tiene el 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: Asegúrese de que la ruta args apunte correctamente al archivo build/index.js. Usar una ruta absoluta podría ser más confiable.

    Opción B: Usando NPX (requiere paquete publicado en npm)

    Este método usa npx para descargar y ejecutar automáticamente el paquete del servidor desde el registro npm. Esto es conveniente si no desea clonar el repositorio.

    {
  "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...
  }
}
    • Asegúrese de que las variables de entorno en el bloque env estén configuradas correctamente, ya sea coincidiendo con .env o definidas explícitamente aquí. Elimine los comentarios del archivo JSON real.

  2. Reiniciar/Recargar Cline: Cline debería detectar el cambio de configuración e iniciar el servidor.

  3. Usar herramientas: Ahora puede usar la extensa lista de herramientas a través de Cline.

Desarrollo

  • Modo de observación: bun run watch
  • Linting: bun run lint
  • Formato: bun run format

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para más detalles.