converse-mcp-server 2.4.2 → 2.5.0

package/docs/API.md

@@ -331,16 +331,16 @@ MCP_TRANSPORT=stdio npm start
 | `gpt-4o` | 128K | 16K | Multimodal | Vision, general chat |
 | `gpt-4o-mini` | 128K | 16K | Fast multimodal | Quick responses, images |
 
-### Google/Gemini Models
+### Google/Gemini Models (API-based)
 
 | Model | Alias | Context | Tokens | Features | Use Cases |
 |-------|-------|---------|--------|----------|-----------|
-| `gemini-3-pro-preview` | `pro`, `gemini` | 1M | 64K | Thinking levels, enhanced reasoning | Complex problems, deep analysis |
+| `gemini-3-pro-preview` | `pro` | 1M | 64K | Thinking levels, enhanced reasoning | Complex problems, deep analysis |
 | `gemini-2.5-flash` | `flash` | 1M | 65K | Ultra-fast | Quick analysis, simple queries |
 | `gemini-2.5-pro` | `pro 2.5` | 1M | 65K | Thinking mode | Deep reasoning, architecture |
 | `gemini-2.0-flash` | `flash2` | 1M | 65K | Latest | Experimental thinking |
 
-**Note:** Default aliases `gemini`, `pro`, and `gemini-pro` now point to Gemini 3.0 Pro. Use `gemini-2.5-pro` explicitly if you need the 2.5 version.
+**Note:** The short model name `gemini` now routes to **Gemini CLI** (OAuth-based). For Google API access, use specific model names like `gemini-2.5-pro` or `gemini-2.0-flash`.
 
 ### X.AI/Grok Models
 
@@ -398,6 +398,42 @@ MCP_TRANSPORT=stdio npm start
 - **Response times**: 6-20 seconds typical (complex tasks may take minutes)
 - **Authentication**: Requires ChatGPT login OR `CODEX_API_KEY` environment variable
 
+### Gemini CLI Models (OAuth-based)
+
+**Gemini CLI** provides subscription-based access to Gemini models through OAuth:
+
+- **Model**: `gemini` (routes to gemini-3-pro-preview)
+- **Authentication**: OAuth via Gemini CLI (requires one-time setup)
+- **Setup**: Install `@google/gemini-cli` globally and run `gemini` to authenticate
+- **Billing**: Uses Google subscription (Google One AI Premium or Gemini Advanced) instead of API credits
+- **Credentials**: Stored in `~/.gemini/oauth_creds.json`
+- **Features**: Access to enhanced agentic features available through CLI
+- **Context**: 1M tokens (inherited from gemini-3-pro-preview)
+- **Output**: 64K tokens
+
+**Authentication Setup:**
+```bash
+# Install Gemini CLI globally
+npm install -g @google/gemini-cli
+
+# Run interactive authentication
+gemini
+
+# Follow prompts to authenticate via browser
+# Credentials are saved to ~/.gemini/oauth_creds.json
+```
+
+**Usage Example:**
+```json
+{
+  "name": "chat",
+  "arguments": {
+    "prompt": "Explain the event loop in JavaScript",
+    "model": "gemini"
+  }
+}
+```
+
 **Codex-Specific Behavior:**
 - `continuation_id` - Required for thread continuation (maintains full conversation history)
 - `files` parameter - Files accessed directly from working directory, not passed as message content

package/docs/PROVIDERS.md

@@ -20,11 +20,11 @@ This guide documents all supported AI providers in the Converse MCP Server and t
 - **Get Key**: [makersuite.google.com/app/apikey](https://makersuite.google.com/app/apikey)
 - **Environment Variable**: `GOOGLE_API_KEY`
 - **Supported Models**:
-  - `gemini-3-pro-preview` (aliases: `pro`, `gemini`) - Enhanced reasoning with thinking levels (1M context, 64K output)
+  - `gemini-3-pro-preview` (alias: `pro`) - Enhanced reasoning with thinking levels (1M context, 64K output)
   - `gemini-2.5-pro` (alias: `pro 2.5`) - Deep reasoning with thinking budget (1M context, 65K output)
   - `gemini-2.5-flash` (alias: `flash`) - Ultra-fast model with thinking budget (1M context, 65K output)
   - `gemini-2.0-flash`, `gemini-2.0-flash-lite` - Latest generation (1M context, 65K output)
-- **Note**: Default aliases (`gemini`, `pro`, `gemini-pro`) now point to Gemini 3.0 Pro. Use `gemini-2.5-pro` explicitly if you need version 2.5.
+- **Note**: The short model name `gemini` now routes to **Gemini CLI** (OAuth-based access). For Google API access, use specific model names like `gemini-2.5-pro` or `gemini-2.0-flash`.
 
 ### X.AI (Grok)
 - **API Key Format**: `xai-...` (starts with `xai-`)
@@ -114,6 +114,73 @@ This guide documents all supported AI providers in the Converse MCP Server and t
 - Use `CODEX_APPROVAL_POLICY=never` for headless server deployments
 - Always use `continuation_id` for thread continuation
 
+### Gemini CLI
+- **Authentication**: OAuth via Gemini CLI (no API key needed)
+- **Setup Required**:
+  1. Install Gemini CLI globally: `npm install -g @google/gemini-cli`
+  2. Authenticate: Run `gemini` command and follow interactive prompts
+  3. Credentials stored in `~/.gemini/oauth_creds.json`
+- **Environment Variables**: None (uses OAuth credentials file)
+- **Supported Models**:
+  - `gemini` - Routes to gemini-3-pro-preview via CLI
+  - Provides access to Gemini 3.0 Pro Preview through Google subscription (Google One AI Premium or Gemini Advanced)
+
+**Key Features:**
+- **OAuth Authentication**: Uses Google account login instead of API keys
+- **Subscription Access**: Leverage Google subscription instead of paying per API call
+- **Enhanced Features**: Access to agentic features available through CLI that aren't in standard API
+- **Model Support**: Currently supports gemini-3-pro-preview only
+
+**Authentication Setup:**
+```bash
+# Install Gemini CLI globally
+npm install -g @google/gemini-cli
+
+# Run interactive authentication (one-time setup)
+gemini
+
+# Follow prompts to:
+# 1. Select authentication method (Personal OAuth recommended)
+# 2. Authorize via browser
+# 3. Credentials are saved to ~/.gemini/oauth_creds.json
+```
+
+**Usage Examples:**
+
+*Chat Tool:*
+```json
+{
+  "name": "chat",
+  "arguments": {
+    "prompt": "Explain async/await in JavaScript",
+    "model": "gemini"
+  }
+}
+```
+
+*Consensus Tool:*
+```json
+{
+  "name": "consensus",
+  "arguments": {
+    "prompt": "Should we use TypeScript for this component?",
+    "models": ["gemini", "gpt-5", "claude-sonnet-4"]
+  }
+}
+```
+
+**Best Practices:**
+- Authenticate before first use (run `gemini` CLI command)
+- Use specific model names for Google API access (e.g., `gemini-2.5-pro`)
+- Model name `gemini` is reserved for CLI-based access
+- Check credentials file exists at `~/.gemini/oauth_creds.json` if authentication fails
+
+**Differences from Google API Provider:**
+- **Authentication**: OAuth (CLI) vs API Key (Google API)
+- **Billing**: Google subscription vs pay-per-use API
+- **Model Routing**: `gemini` → CLI provider, specific names (e.g., `gemini-2.5-pro`) → API provider
+- **Models**: Only gemini-3-pro-preview vs full Gemini model family
+
 ## Configuration Examples
 
 ### Basic Configuration (.env file)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "converse-mcp-server",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "Converse MCP Server - Converse with other LLMs with chat and consensus tools",
   "type": "module",
   "main": "src/index.js",
@@ -45,6 +45,8 @@
     "@mistralai/mistralai": "^1.10.0",
     "@modelcontextprotocol/sdk": "^1.22.0",
     "@openai/codex-sdk": "^0.58.0",
+    "ai": "^5.0.101",
+    "ai-sdk-provider-gemini-cli": "^1.4.0",
     "cors": "^2.8.5",
     "dotenv": "^17.2.3",
     "express": "^5.1.0",

package/src/providers/gemini-cli.js

@@ -0,0 +1,388 @@
+/**
+ * Gemini CLI Provider
+ *
+ * Provider implementation for Google's Gemini models using the ai-sdk-provider-gemini-cli package.
+ * Implements the unified interface: async invoke(messages, options) => { content, stop_reason, rawResponse }
+ *
+ * Key features:
+ * - Uses OAuth authentication from Gemini CLI (no API keys needed)
+ * - Supports gemini-3-pro-preview model via Google Cloud Code endpoints
+ * - Uses AI SDK v5 standard interfaces (generateText/streamText)
+ * - Compatible with both chat and consensus tools
+ *
+ * Authentication:
+ * - Requires global Gemini CLI installation: npm install -g @google/gemini-cli
+ * - User must authenticate once via: gemini (interactive CLI)
+ * - Credentials stored in ~/.gemini/oauth_creds.json
+ */
+
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { debugLog, debugError } from '../utils/console.js';
+import { ProviderError, ErrorCodes, StopReasons } from './interface.js';
+
+// Supported Gemini CLI models with their configurations
+const SUPPORTED_MODELS = {
+  'gemini-3-pro-preview': {
+    modelName: 'gemini-3-pro-preview',
+    friendlyName: 'Gemini 3.0 Pro Preview (via CLI)',
+    contextWindow: 1048576, // 1M tokens
+    maxOutputTokens: 64000,
+    supportsStreaming: true,
+    supportsImages: true, // Base64 only (no URLs)
+    supportsTemperature: true,
+    supportsThinking: true,
+    supportsWebSearch: true,
+    timeout: 300000, // 5 minutes
+    description:
+			'Gemini 3.0 Pro Preview via OAuth - requires Gemini CLI authentication',
+  },
+};
+
+/**
+ * Custom error class for Gemini CLI provider errors
+ */
+class GeminiCliProviderError extends ProviderError {
+  constructor(message, code, originalError = null) {
+    super(message, code, originalError);
+    this.name = 'GeminiCliProviderError';
+  }
+}
+
+/**
+ * Check if OAuth credentials file exists
+ * @returns {boolean} True if credentials file exists
+ */
+function hasOAuthCredentials() {
+  try {
+    const credsPath = join(homedir(), '.gemini', 'oauth_creds.json');
+    return existsSync(credsPath);
+  } catch (error) {
+    debugError('[Gemini CLI] Error checking OAuth credentials', error);
+    return false;
+  }
+}
+
+/**
+ * Dynamically import Gemini CLI SDK (lazy loading)
+ * This keeps the SDK as an optional dependency
+ */
+async function getGeminiCliSDK() {
+  try {
+    // Use dynamic import to load SDK only when needed
+    const { createGeminiProvider } = await import('ai-sdk-provider-gemini-cli');
+    return createGeminiProvider;
+  } catch (error) {
+    throw new GeminiCliProviderError(
+      'Gemini CLI SDK not installed. Install with: npm install ai-sdk-provider-gemini-cli',
+      'GEMINI_CLI_NOT_INSTALLED',
+      error,
+    );
+  }
+}
+
+/**
+ * Dynamically import AI SDK (lazy loading)
+ */
+async function getAISDK() {
+  try {
+    const { generateText, streamText } = await import('ai');
+    return { generateText, streamText };
+  } catch (error) {
+    throw new GeminiCliProviderError(
+      'AI SDK not installed. Install with: npm install ai',
+      'AI_SDK_NOT_INSTALLED',
+      error,
+    );
+  }
+}
+
+/**
+ * Create stream generator for Gemini CLI streaming responses
+ * Yields normalized events compatible with ProviderStreamNormalizer
+ */
+async function* createStreamingGenerator(
+  model,
+  messages,
+  options,
+  signal,
+) {
+  const { streamText } = await getAISDK();
+
+  try {
+    const streamOptions = {
+      model,
+      messages,
+      ...options,
+    };
+
+    if (signal) {
+      streamOptions.abortSignal = signal;
+    }
+
+    const result = await streamText(streamOptions);
+
+    // Yield start event
+    yield {
+      type: 'start',
+      provider: 'gemini-cli',
+      model: options.model || 'gemini-3-pro-preview',
+    };
+
+    // Stream text chunks
+    for await (const chunk of result.textStream) {
+      // Check for cancellation
+      if (signal?.aborted) {
+        throw new GeminiCliProviderError('Request cancelled', 'CANCELLED');
+      }
+
+      // Yield delta event with content chunk
+      yield {
+        type: 'delta',
+        content: chunk,
+      };
+    }
+
+    // Get final usage stats and metadata
+    const usage = await result.usage;
+    const finishReason = await result.finishReason;
+
+    // Yield usage event
+    if (usage) {
+      yield {
+        type: 'usage',
+        usage: {
+          input_tokens: usage.promptTokens || 0,
+          output_tokens: usage.completionTokens || 0,
+          total_tokens: usage.totalTokens || 0,
+          cached_input_tokens: 0,
+        },
+      };
+    }
+
+    // Yield end event
+    yield {
+      type: 'end',
+      stop_reason: mapFinishReason(finishReason),
+      finish_reason: finishReason,
+    };
+  } catch (error) {
+    if (signal?.aborted) {
+      throw new GeminiCliProviderError('Request cancelled', 'CANCELLED');
+    }
+    throw error;
+  }
+}
+
+/**
+ * Map AI SDK finish reasons to our StopReasons enum
+ */
+function mapFinishReason(finishReason) {
+  switch (finishReason) {
+  case 'stop':
+    return StopReasons.STOP;
+  case 'length':
+  case 'max-tokens':
+    return StopReasons.LENGTH;
+  case 'content-filter':
+    return StopReasons.CONTENT_FILTER;
+  case 'tool-calls':
+    return StopReasons.TOOL_USE;
+  case 'error':
+    return StopReasons.ERROR;
+  default:
+    return StopReasons.OTHER;
+  }
+}
+
+/**
+ * Gemini CLI Provider Implementation
+ */
+export const geminiCliProvider = {
+  /**
+	 * Invoke Gemini CLI with messages and options
+	 * @param {Array} messages - Message array (Converse format)
+	 * @param {Object} options - Invocation options
+	 * @returns {Promise<Object>|AsyncGenerator} Response or stream generator
+	 */
+  async invoke(messages, options = {}) {
+    const {
+      model = 'gemini-3-pro-preview',
+      config,
+      stream = false,
+      signal,
+      reasoning_effort,
+      temperature,
+      use_websearch,
+    } = options;
+
+    // Validate configuration
+    if (!config) {
+      throw new GeminiCliProviderError(
+        'Configuration is required',
+        ErrorCodes.MISSING_API_KEY,
+      );
+    }
+
+    // Check OAuth credentials
+    if (!hasOAuthCredentials()) {
+      throw new GeminiCliProviderError(
+        'Gemini CLI authentication required. Run: gemini (interactive CLI) to authenticate',
+        ErrorCodes.INVALID_API_KEY,
+      );
+    }
+
+    try {
+      // Get SDKs
+      const createGeminiProvider = await getGeminiCliSDK();
+      const { generateText } = await getAISDK();
+
+      // Create provider instance with OAuth authentication
+      const gemini = createGeminiProvider({
+        authType: 'oauth-personal',
+      });
+
+      // Create model instance
+      const modelInstance = gemini(model);
+
+      // Build AI SDK options
+      const aiOptions = {
+        messages,
+      };
+
+      // Add optional parameters
+      if (temperature !== undefined) {
+        aiOptions.temperature = temperature;
+      }
+
+      // Note: reasoning_effort and use_websearch are not directly supported by AI SDK
+      // These would need to be handled at the API level if the provider supports them
+      if (reasoning_effort !== undefined) {
+        debugLog(
+          '[Gemini CLI] Parameter "reasoning_effort" not directly supported (ignored)',
+        );
+      }
+      if (use_websearch) {
+        debugLog(
+          '[Gemini CLI] Parameter "use_websearch" not directly supported (ignored)',
+        );
+      }
+
+      // Streaming mode
+      if (stream) {
+        return createStreamingGenerator(modelInstance, messages, aiOptions, signal);
+      }
+
+      // Synchronous mode
+      const startTime = Date.now();
+
+      const result = await generateText({
+        model: modelInstance,
+        ...aiOptions,
+        ...(signal && { abortSignal: signal }),
+      });
+
+      const responseTime = Date.now() - startTime;
+
+      // Extract content from AI SDK v5 response format
+      const content = result.content?.[0]?.text || result.text || '';
+
+      return {
+        content,
+        stop_reason: mapFinishReason(result.finishReason),
+        rawResponse: result,
+        metadata: {
+          provider: 'gemini-cli',
+          model,
+          usage: result.usage
+            ? {
+              input_tokens: result.usage.promptTokens || 0,
+              output_tokens: result.usage.completionTokens || 0,
+              total_tokens: result.usage.totalTokens || 0,
+              cached_input_tokens: 0,
+            }
+            : null,
+          response_time_ms: responseTime,
+          finish_reason: result.finishReason || 'stop',
+        },
+      };
+    } catch (error) {
+      debugError('[Gemini CLI] Execution error', error);
+
+      // Map common errors to standard error codes
+      if (
+        error.message?.includes('authentication') ||
+				error.message?.includes('oauth') ||
+				error.message?.includes('credentials')
+      ) {
+        throw new GeminiCliProviderError(
+          'Gemini CLI authentication failed. Run: gemini (interactive CLI) to authenticate',
+          ErrorCodes.INVALID_API_KEY,
+          error,
+        );
+      }
+
+      if (error.message?.includes('rate limit')) {
+        throw new GeminiCliProviderError(
+          'Rate limit exceeded',
+          ErrorCodes.RATE_LIMIT_EXCEEDED,
+          error,
+        );
+      }
+
+      if (error.message?.includes('timeout')) {
+        throw new GeminiCliProviderError(
+          'Request timeout',
+          ErrorCodes.TIMEOUT_ERROR,
+          error,
+        );
+      }
+
+      // Re-throw as Gemini CLI error
+      throw new GeminiCliProviderError(
+        error.message || 'Gemini CLI execution failed',
+        ErrorCodes.API_ERROR,
+        error,
+      );
+    }
+  },
+
+  /**
+	 * Validate Gemini CLI configuration
+	 * Gemini CLI uses OAuth authentication (no API keys needed)
+	 */
+  validateConfig(_config) {
+    // Check if OAuth credentials file exists
+    return hasOAuthCredentials();
+  },
+
+  /**
+	 * Check if Gemini CLI provider is available
+	 */
+  isAvailable(config) {
+    return this.validateConfig(config);
+  },
+
+  /**
+	 * Get supported Gemini CLI models
+	 */
+  getSupportedModels() {
+    return SUPPORTED_MODELS;
+  },
+
+  /**
+	 * Get model configuration for specific model
+	 */
+  getModelConfig(modelName) {
+    const modelNameLower = modelName.toLowerCase();
+
+    // Check exact match
+    if (SUPPORTED_MODELS[modelNameLower]) {
+      return SUPPORTED_MODELS[modelNameLower];
+    }
+
+    // No aliases for Gemini CLI models currently
+    return null;
+  },
+};

package/src/providers/index.js

@@ -14,6 +14,7 @@ import { mistralProvider } from './mistral.js';
 import { deepseekProvider } from './deepseek.js';
 import { openrouterProvider } from './openrouter.js';
 import { codexProvider } from './codex.js';
+import { geminiCliProvider } from './gemini-cli.js';
 
 /**
  * Provider registry map
@@ -31,6 +32,7 @@ const providers = {
   deepseek: deepseekProvider,
   openrouter: openrouterProvider,
   codex: codexProvider,
+  'gemini-cli': geminiCliProvider,
 };
 
 /**

package/src/tools/chat.js

@@ -441,6 +441,11 @@ export function mapModelToProvider(model, providers) {
     return 'codex';
   }
 
+  // Check Gemini CLI (exact match only - routes to CLI provider instead of Google API)
+  if (modelLower === 'gemini') {
+    return 'gemini-cli';
+  }
+
   // Check OpenRouter-specific patterns first
   if (
     modelLower === 'openrouter auto' ||

package/src/tools/consensus.js

@@ -684,6 +684,16 @@ function mapModelToProvider(model, providers) {
     return 'openai';
   }
 
+  // Check Codex (exact match only - don't route "gpt-5-codex" etc to Codex provider)
+  if (modelLower === 'codex') {
+    return 'codex';
+  }
+
+  // Check Gemini CLI (exact match only - routes to CLI provider instead of Google API)
+  if (modelLower === 'gemini') {
+    return 'gemini-cli';
+  }
+
   // Check OpenRouter-specific patterns first
   if (
     modelLower === 'openrouter auto' ||