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