Gemini 服务器工具文档

概述

本指南详细介绍了如何与 Gemini 服务器交互，包括各种可用工具、参数、错误处理以及开发结构。

可用工具

1. 内容生成

gemini_generateContent

• 描述: 根据提示生成内容。
• 参数:
  • prompt (字符串, 必填): 输入的提示。
  • modelName (字符串, 可选): 指定 Gemini 模型（例如：gemini-1.0-pro）。
  • generationConfig (对象, 可选):
    • temperature (数字, 可选): 控制输出的随机性（范围 0 到 1）。
    • maxOutputTokens (整数, 可选): 设置生成内容的最大长度。

示例

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Write a short poem about a rubber duck."
    }
  </arguments>
</use_mcp_tool>

2. 聊天功能

gemini_startChat

• 描述: 初始化一个新的聊天会话。
• 参数:
  • 无。

gemini_sendMessage

• 描述: 向现有聊天会话发送消息并获取响应。
• 参数:
  • sessionId (字符串, 必填): 聊天会话的唯一标识符。
  • message (字符串, 必填): 要发送的消息。

3. 文件上传

gemini_uploadFile

• 描述: 将文件上传到服务器。
• 参数:
  • filePath (字符串, 必填): 文件的绝对路径。
  • displayName (字符串, 可选): 文件的显示名称。

错误处理

服务器在工具执行失败时使用 MCP 标准 McpError 类型返回结构化错误。此对象通常包含：

• code: 表示错误类型的 ErrorCode 枚举值（例如：InvalidParams, InternalError, PermissionDenied, NotFound）。
• message: 人类可读的错误描述。
• details: （可选）包含底层 Gemini SDK 错误的具体信息的对象，用于故障排除。

常见错误场景

• 无效 API 密钥: 通常导致 InternalError，带有身份验证失败的消息。
• 无效参数: 结果为 InvalidParams（例如，缺少必填字段或数据类型错误）。
• 安全阻止: 可能导致 InternalError，带有详细信息指示 SAFETY 作为阻止原因或完成原因。
• 文件/缓存未找到: 可能导致 NotFound 或 InternalError，具体取决于 SDK 如何呈现错误。
• 速率限制: 可能导致 ResourceExhausted 或 InternalError。

检查返回的 message 和 details 字段以获取特定线索进行故障排除。

开发

该服务器遵循项目 .clinerules 和内部文档中概述的标准 MCP 服务器结构。关键模式包括：

• 服务层 (src/services): 封装与 @google/genai SDK 的交互，使其与 MCP 特定内容解耦。
• 工具层 (src/tools): 将服务层功能适配为 MCP 工具，处理参数映射和错误转换。
• Zod 模式 (src/tools/*Params.ts): 广泛用于定义工具参数、提供验证并生成与 LLM 交互至关重要的详细描述。
• 配置 (src/config): 通过 ConfigurationManager 实现集中化管理。
• 类型 (src/types): 清楚的 TypeScript 定义。

已知问题

• gemini_generateContentStream 使用了一个变通方法，收集所有分块后返回完整文本。MCP 客户端的真正流尚未实现。
• gemini_listFiles 和 gemini_listCaches 由于迭代 SDK 的Pager对象的限制，可能无法可靠地返回 nextPageToken。
• gemini_uploadFile 在服务器环境中需要绝对文件路径。
• 文件处理和缓存 API 在 Vertex AI 上不支持，仅限 Google AI Studio API 密钥使用。