🚀 Gemini 服务器工具文档

本指南详细介绍了如何与 Gemini 服务器进行交互，涵盖了各种可用工具、参数设置、错误处理方式以及开发结构，帮助你高效使用 Gemini 服务器。

🚀 快速开始

本指南将带你了解如何与 Gemini 服务器交互，包括使用可用工具、处理错误以及遵循开发结构。

✨ 主要特性

丰富的工具集：提供内容生成、聊天功能和文件上传等多种工具。
结构化错误处理：使用 MCP 标准 McpError 类型返回错误信息，便于故障排除。
遵循 MCP 服务器结构：确保代码的可维护性和可扩展性。

📦 安装指南

文档未提及安装步骤，暂不提供。

💻 使用示例

基础用法

内容生成

<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>

高级用法

文档未提及高级用法代码示例，暂不提供。

📚 详细文档

🔍 可用工具

1. 内容生成

`gemini_generateContent`

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

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 密钥使用。