MCP Gemini Server

🚀 Gemini Server Tool Documentation

This guide details how to interact with the Gemini server, including available tools, parameters, error handling, and the development structure.

🚀 Quick Start

This documentation provides a comprehensive guide on interacting with the Gemini server. It covers available tools, parameter details, error handling, and the server's development structure.

✨ Features

Available Tools

1. Content Generation

gemini_generateContent

• Description: Generate content based on a prompt.
• Parameters:
  • prompt (string, required): The input prompt.
  • modelName (string, optional): Specify the Gemini model (e.g., gemini-1.0-pro).
  • generationConfig (object, optional):
    • temperature (number, optional): Control the randomness of the output (range 0 to 1).
    • maxOutputTokens (integer, optional): Set the maximum length of the generated content.

Example

<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. Chat Functionality

gemini_startChat

• Description: Initialize a new chat session.
• Parameters: None.

gemini_sendMessage

• Description: Send a message to an existing chat session and get a response.
• Parameters:
  • sessionId (string, required): The unique identifier of the chat session.
  • message (string, required): The message to send.

3. File Upload

gemini_uploadFile

• Description: Upload a file to the server.
• Parameters:
  • filePath (string, required): The absolute path of the file.
  • displayName (string, optional): The display name of the file.

🔧 Technical Details

Error Handling

The server returns structured errors using the MCP standard McpError type when tool execution fails. This object typically contains:

• code: An ErrorCode enum value representing the error type (e.g., InvalidParams, InternalError, PermissionDenied, NotFound).
• message: A human-readable error description.
• details (optional): An object containing specific information about the underlying Gemini SDK error for troubleshooting.

Common Error Scenarios

• Invalid API Key: Usually results in InternalError with an authentication failure message.
• Invalid Parameters: Results in InvalidParams (e.g., missing required fields or incorrect data types).
• Safety Block: May result in InternalError with details indicating SAFETY as the blocking or completion reason.
• File/Cache Not Found: May result in NotFound or InternalError, depending on how the SDK presents the error.
• Rate Limiting: May result in ResourceExhausted or InternalError.

Check the returned message and details fields for specific clues for troubleshooting.

Development

The server follows the standard MCP server structure outlined in the project .clinerules and internal documentation. Key patterns include:

• Service Layer (src/services): Encapsulates interactions with the @google/genai SDK, decoupling it from MCP-specific content.
• Tool Layer (src/tools): Adapts service layer functionality to MCP tools, handling parameter mapping and error conversion.
• Zod Schemas (src/tools/*Params.ts): Widely used to define tool parameters, provide validation, and generate detailed descriptions crucial for interacting with LLMs.
• Configuration (src/config): Centralized management through the ConfigurationManager.
• Types (src/types): Clear TypeScript definitions.

📄 Known Issues

• gemini_generateContentStream uses a workaround to collect all chunks and return the full text. True streaming for MCP clients is not yet implemented.
• gemini_listFiles and gemini_listCaches may not reliably return nextPageToken due to limitations in iterating over the SDK's Pager object.
• gemini_uploadFile requires an absolute file path in the server environment.
• File handling and cache APIs are not supported on Vertex AI and are only available for Google AI Studio API keys.