Vertex AI MCP Server

Vertex AI MCP 服务

本项目实现了一个模型上下文协议（MCP）服务，提供一套全面的工具，用于与 Google Cloud 的 Vertex AI Gemini 模型交互，重点支持编码辅助和通用问题解答。

安全边界

除了模型和研究工具外，此服务还包含文件系统写入和终端执行工具。请使用专用的低权限身份运行它，限制其文件系统和网络访问，并要求对具有重大影响的工具进行明确审批。不要将 MCP 客户端的确认提示视为服务端授权。

关于本项目以及另外六个公开 MCP 代码库所揭示的实现权衡，请参阅构建七个 MCP 服务的经验教训：生产环境中的 MCP。该文章将此代码库作为公开的工程实践证据；但并未声称文中讨论的每项生产控制措施都已在此实现。

功能

• 通过众多 MCP 工具访问 Vertex AI Gemini 模型。
• 支持网页搜索 grounding（answer_query_websearch）和直接知识问答（answer_query_direct）。
• 可通过环境变量配置模型 ID、温度、流式传输行为、最大输出令牌数和重试设置。
• 默认使用流式 API，以获得更好的响应速度。
• 包含针对临时 API 错误的基本重试逻辑。
• 采用最低限度的安全过滤器（BLOCK_NONE）以减少潜在拦截（请谨慎使用）。

提供的工具

查询与生成（面向 AI）

• answer_query_websearch：使用配置的 Vertex AI 模型并结合 Google 搜索结果回答自然语言查询。
• answer_query_direct：仅使用配置的 Vertex AI 模型的内部知识回答自然语言查询。
• explain_topic_with_docs：通过综合主要来自网页搜索找到的官方文档的信息，详细解释有关特定软件主题的查询。
• get_doc_snippets：通过搜索官方文档，为技术查询提供准确、权威的代码片段或简洁回答。
• generate_project_guidelines：根据指定的技术列表（可选包含版本），利用网页搜索查找最佳实践并生成结构化的项目指南文档（Markdown）。

研究与分析工具

• code_analysis_with_docs：通过将代码片段与官方文档中的最佳实践进行比较，分析代码，找出潜在的错误、性能问题和安全漏洞。
• technical_comparison：根据特定标准比较多种技术、框架或库，并提供包含优缺点和适用场景的详细对比表。
• architecture_pattern_recommendation：根据行业最佳实践，为特定使用场景推荐架构模式，并提供实现示例和注意事项。
• dependency_vulnerability_scan：分析项目依赖项中的已知安全漏洞，并提供详细信息和缓解策略。
• database_schema_analyzer：检查数据库架构的规范化、索引和性能问题，并根据特定数据库的最佳实践提出改进建议。
• security_best_practices_advisor：针对特定技术或场景提供安全建议，并提供实现安全实践的代码示例。
• testing_strategy_generator：为应用或功能制定全面的测试策略，并推荐合适的测试类型和覆盖率目标。
• regulatory_compliance_advisor：为特定行业提供法规要求（GDPR、HIPAA 等）方面的指导，并介绍合规实现方案。
• microservice_design_assistant：帮助为特定领域设计微服务架构，并提供服务边界建议和通信模式。
• documentation_generator：按照行业技术文档最佳实践，为代码、API 或系统创建全面的文档。

文件系统操作

• read_file_content：读取一个或多个文件的完整内容。提供单个路径字符串或路径字符串数组。
• write_file_content：创建新文件或完全覆盖现有文件。writes 参数接受单个对象（{path, content}）或此类对象的数组。
• edit_file_content：按行编辑文本文件，返回差异预览或应用更改。
• list_directory_contents：列出指定路径下的文件和目录（不递归）。
• get_directory_tree：以 JSON 格式获取文件和目录的递归树状视图。
• move_file_or_directory：移动或重命名文件和目录。
• search_filesystem：递归搜索与名称模式匹配的文件/目录，并可选择排除项。
• get_filesystem_info：获取文件或目录的详细元数据（大小、日期、类型、权限）。
• execute_terminal_command：执行 shell 命令，可选择指定 cwd 和 timeout。返回 stdout/stderr。

AI + 文件系统组合操作

• save_generate_project_guidelines：根据技术栈生成项目指南，并将结果保存到指定文件路径。
• save_doc_snippet：从文档中查找代码片段，并将结果保存到指定文件路径。
• save_topic_explanation：根据文档生成主题的详细说明，并将结果保存到指定文件路径。
• save_answer_query_direct：仅使用内部知识回答问题，并将答案保存到指定文件路径。
• save_answer_query_websearch：使用网络搜索结果回答问题，并将答案保存到指定文件路径。

（注意：每个工具的输入/输出架构定义在 src/tools/ 中对应的文件内，并通过 MCP 服务公开。）

前提条件

• Node.js（v18+）
• Bun（npm install -g bun）
• 已启用 Billing 的 Google Cloud Project。
• 已在 GCP 项目中启用 Vertex AI API。
• 已在环境中配置 Google Cloud Authentication（推荐通过 gcloud auth application-default login 使用 Application Default Credentials，或使用 Service Account Key）。

设置与安装

1. 克隆/放置项目： 确保项目文件位于所需位置。
2. 安装依赖：

   bun install
   

3. 配置环境：
   • 在项目根目录中创建 .env 文件（复制 .env.example）。
   • 按照 .env.example 中的说明设置必需和可选的环境变量。
     • 将 AI_PROVIDER 设置为 "vertex" 或 "gemini"。
     • 如果 AI_PROVIDER="vertex"，则必须设置 GOOGLE_CLOUD_PROJECT。
     • 如果 AI_PROVIDER="gemini"，则必须设置 GEMINI_API_KEY。
4. 构建服务：

   bun run build
   

   这会将 TypeScript 代码编译为 build/index.js。

用法（独立运行 / NPX）

发布到 npm 后，你可以使用 npx 直接运行此服务：

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

或者，将其全局安装：

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

注意： 独立运行需要在执行命令前，在 shell 环境中设置必要的环境变量（例如 GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION，以及未使用 ADC 时所需的身份验证凭据）。

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Vertex AI Server：

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

在 Cline 中运行

1. 配置 MCP 设置： 在 Cline 的 MCP 设置文件（例如 .roo/mcp.json）中添加/更新配置。配置命令有两种主要方式：

   选项 A：使用 Node（直接路径——推荐用于开发）

   此方法使用 node 直接运行编译后的脚本。如果你已在本地克隆代码，此方法在开发期间很有用。

   {
     "mcpServers": {
       "vertex-ai-mcp-server": {
         "command": "node",
         "args": [
           "/full/path/to/your/vertex-ai-mcp-server/build/index.js" // 使用绝对路径，或确保该路径相对于 Cline 运行 node 的位置
         ],
         "env": {
           // --- 通用 AI 配置 ---
           "AI_PROVIDER": "vertex", // "vertex" 或 "gemini"
           // --- 必需（视情况而定）---
           "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", // 当 AI_PROVIDER="vertex" 时必需
           // "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY", // 当 AI_PROVIDER="gemini" 时必需
           // --- 可选模型选择 ---
           "VERTEX_MODEL_ID": "gemini-2.5-pro-exp-03-25", // 当 AI_PROVIDER="vertex" 时（覆盖设置示例）
           "GEMINI_MODEL_ID": "gemini-2.5-pro-exp-03-25", // 当 AI_PROVIDER="gemini" 时
           // --- 可选 AI 参数 ---
           "GOOGLE_CLOUD_LOCATION": "us-central1", // 仅适用于 Vertex AI
           "AI_TEMPERATURE": "0.0",
           "AI_USE_STREAMING": "true",
           "AI_MAX_OUTPUT_TOKENS": "65536", // 默认值来自 .env.example
           "AI_MAX_RETRIES": "3",
           "AI_RETRY_DELAY_MS": "1000",
           // --- 可选 Vertex 身份验证 ---
           // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json" // 使用 Vertex 服务账号密钥时设置
         },
         "disabled": false,
         "alwaysAllow": [
            // 如果不想看到确认提示，请在此处添加工具名称
            // 例如："answer_query_websearch"
         ],
         "timeout": 3600 // 可选：超时时间，单位为秒
       }
       // 在此处添加其他服务……
     }
   }
   

   • 重要： 确保 args 路径正确指向 build/index.js 文件。使用绝对路径可能更可靠。

   选项 B：使用 NPX（要求软件包已发布到 npm）

   此方法使用 npx 从 npm 注册表自动下载并运行服务软件包。如果你不想克隆代码仓库，此方法会很方便。

   {
     "mcpServers": {
       "vertex-ai-mcp-server": {
         "command": "bunx", // 使用 bunx
         "args": [
           "-y", // 自动确认安装
           "vertex-ai-mcp-server" // npm 包名称
         ],
         "env": {
           // --- 通用 AI 配置 ---
           "AI_PROVIDER": "vertex", // "vertex" 或 "gemini"
           // --- 必填（条件性） ---
           "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", // 当 AI_PROVIDER="vertex" 时必填
           // "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY", // 当 AI_PROVIDER="gemini" 时必填
           // --- 可选模型选择 ---
           "VERTEX_MODEL_ID": "gemini-2.5-pro-exp-03-25", // 当 AI_PROVIDER="vertex" 时（覆盖示例）
           "GEMINI_MODEL_ID": "gemini-2.5-pro-exp-03-25", // 当 AI_PROVIDER="gemini" 时
           // --- 可选 AI 参数 ---
           "GOOGLE_CLOUD_LOCATION": "us-central1", // 仅适用于 Vertex AI
           "AI_TEMPERATURE": "0.0",
           "AI_USE_STREAMING": "true",
           "AI_MAX_OUTPUT_TOKENS": "65536", // 默认值来自 .env.example
           "AI_MAX_RETRIES": "3",
           "AI_RETRY_DELAY_MS": "1000",
           // --- 可选 Vertex 身份验证 ---
           // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json" // 使用 Vertex 服务账号密钥时
         },
         "disabled": false,
         "alwaysAllow": [
            // 如果不想看到确认提示，请在此处添加工具名称
            // 例如："answer_query_websearch"
         ],
         "timeout": 3600 // 可选：超时时间（秒）
       }
       // 在此处添加其他服务……
     }
   }
   

   • 确保正确设置 env 块中的环境变量，使其与 .env 中的设置一致，或在此处显式定义。在实际的 JSON 文件中移除注释。

2. **重启/重新加载 Cline：**Cline 应能检测到配置更改并启动服务。

3. **使用工具：**现在可以通过 Cline 使用丰富的工具列表。

开发

• 监视模式：bun run watch
• Lint：bun run lint
• 格式化：bun run format

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。