@rlabs-inc/gemini-mcp 0.6.3 → 0.7.0

package/README.md

@@ -1,58 +1,49 @@
 # MCP Server Gemini
 
-A Model Context Protocol (MCP) server for integrating Google's Gemini 3 models with Claude Code, enabling powerful collaboration between both AI systems.
+A Model Context Protocol (MCP) server for integrating Google's Gemini 3 models with Claude Code, enabling powerful collaboration between both AI systems. Now with a beautiful CLI!
 
 [![npm version](https://badge.fury.io/js/@rlabs-inc%2Fgemini-mcp.svg)](https://www.npmjs.com/package/@rlabs-inc/gemini-mcp)
+[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)
 
-## What's New in v0.6.0
+## What's New in v0.7.0
 
-**35+ tools** for comprehensive Gemini 3 integration - the most complete Gemini MCP server available!
+**Beautiful CLI with Themes!** Use Gemini directly from your terminal:
 
-**Deep Research Agent (NEW!):**
-- **gemini-deep-research** - Autonomous multi-step research with web search
-- **gemini-check-research** - Poll research status and get results
-- **gemini-research-followup** - Ask follow-up questions on completed research
-
-**Token Management (NEW!):**
-- **gemini-count-tokens** - Count tokens before API calls with cost estimates
-
-**Text-to-Speech:**
-- **gemini-speak** - Convert text to speech with 30 unique voices
-- **gemini-dialogue** - Generate two-speaker conversations
-- **gemini-list-voices** - Browse all available voices
+```bash
+# Install globally
+npm install -g @rlabs-inc/gemini-mcp
 
-**URL Analysis:**
-- **gemini-analyze-url** - Analyze web pages with questions
-- **gemini-compare-urls** - Compare two URLs side by side
-- **gemini-extract-from-url** - Extract structured data from pages
+# Set your API key once
+gemini config set api-key YOUR_KEY
 
-**Context Caching:**
-- **gemini-create-cache** - Cache large documents for repeated queries
-- **gemini-query-cache** - Query cached content efficiently
-- **gemini-list-caches** / **gemini-delete-cache** - Manage caches
+# Generate images, videos, search, research, and more!
+gemini image "a cat astronaut" --size 4K
+gemini search "latest AI news"
+gemini research "quantum computing applications" --wait
+gemini speak "Hello world" --voice Puck
+```
 
-**Multimodal Analysis:**
-- **YouTube Analysis** - Analyze videos by URL with timestamps and clipping
-- **Document Analysis** - PDFs, DOCX, spreadsheets with table extraction
+**5 Beautiful Themes:** terminal, neon, ocean, forest, minimal
 
-**Generation & Editing:**
-- **4K Image Generation** - Up to 4K resolution with 10 aspect ratios
-- **Multi-Turn Image Editing** - Iteratively refine images through conversation
-- **Video Generation** - Create videos with Veo 2.0
+**CLI Commands:**
+- `gemini query` - Direct Gemini queries with thinking levels
+- `gemini search` - Real-time web search with citations
+- `gemini research` - Deep research agent
+- `gemini image` - Generate images (up to 4K)
+- `gemini video` - Generate videos with Veo
+- `gemini speak` - Text-to-speech with 30 voices
+- `gemini tokens` - Count tokens and estimate costs
+- `gemini config` - Manage settings
 
-**Advanced Tools:**
-- **Code Execution** - Gemini writes AND runs Python code
-- **Google Search** - Real-time web information with citations
-- **Structured Output** - JSON schema responses with validation
-- **Brainstorming** - Claude + Gemini collaborative problem-solving
+**MCP Registry Support:** Now discoverable in the official MCP ecosystem!
 
 ### Previous Versions
 
-**v0.5.1:** Documentation updates, code quality improvements
-**v0.5.0:** 30+ tools, TTS, URL analysis, caching
-**v0.4.0:** YouTube, documents, code execution, search
-**v0.3.0:** Thinking levels, structured output
-**v0.2.0:** Image/Video generation with Veo
+**v0.6.x:** Deep Research, Token Counting, TTS, URL analysis, Context Caching
+**v0.5.x:** 30+ tools, YouTube analysis, Document analysis
+**v0.4.x:** Code execution, Google Search
+**v0.3.x:** Thinking levels, Structured output, 4K images
+**v0.2.x:** Image/Video generation with Veo
 
 ---
 
@@ -84,16 +75,28 @@ A Model Context Protocol (MCP) server for integrating Google's Gemini 3 models w
 
 ## Quick Installation
 
-### Using npm (Recommended)
+### MCP Server for Claude Code
 
 ```bash
+# Using npm (Recommended)
 claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY npx -y @rlabs-inc/gemini-mcp
+
+# Using bun
+claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY bunx @rlabs-inc/gemini-mcp
 ```
 
-### Using bun
+### CLI (Global Install)
 
 ```bash
-claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY bunx @rlabs-inc/gemini-mcp
+# Install globally
+npm install -g @rlabs-inc/gemini-mcp
+
+# Set your API key once (stored securely)
+gemini config set api-key YOUR_KEY
+
+# Now use any command!
+gemini search "latest news"
+gemini image "sunset over mountains" --ratio 16:9
 ```
 
 **Get your API key:** Visit [Google AI Studio](https://aistudio.google.com/apikey) - it's free and takes seconds!

package/dist/cli/commands/config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Config Command
+ *
+ * Set and view CLI configuration.
+ * gemini config set api-key YOUR_KEY
+ * gemini config show
+ */
+export declare function configCommand(argv: string[]): Promise<void>;

package/dist/cli/commands/config.js

@@ -0,0 +1,147 @@
+/**
+ * Config Command
+ *
+ * Set and view CLI configuration.
+ * gemini config set api-key YOUR_KEY
+ * gemini config show
+ */
+import { parseArgs } from 'node:util';
+import { loadConfig, saveConfig, getConfigPath } from '../config.js';
+import { print, printError, printSuccess, printMuted, printWarning, t, header, box } from '../ui/index.js';
+function showHelp() {
+    const theme = t();
+    print(header('gemini config', 'CLI configuration'));
+    print('');
+    print(theme.colors.primary('Usage:'));
+    print(`  gemini config ${theme.colors.muted('<command>')} [options]`);
+    print('');
+    print(theme.colors.primary('Commands:'));
+    print(`  ${theme.colors.highlight('set')}    ${theme.colors.muted('Set a configuration value')}`);
+    print(`  ${theme.colors.highlight('show')}   ${theme.colors.muted('Show current configuration')}`);
+    print(`  ${theme.colors.highlight('path')}   ${theme.colors.muted('Show config file path')}`);
+    print('');
+    print(theme.colors.primary('Settings:'));
+    print(`  ${theme.colors.highlight('api-key')}         ${theme.colors.muted('Your Gemini API key')}`);
+    print(`  ${theme.colors.highlight('theme')}           ${theme.colors.muted('Default theme (terminal, neon, minimal, ocean, forest)')}`);
+    print(`  ${theme.colors.highlight('output-dir')}      ${theme.colors.muted('Directory for generated files')}`);
+    print(`  ${theme.colors.highlight('default-voice')}   ${theme.colors.muted('Default TTS voice')}`);
+    print(`  ${theme.colors.highlight('default-model')}   ${theme.colors.muted('Default model (pro or flash)')}`);
+    print('');
+    print(theme.colors.primary('Examples:'));
+    print(theme.colors.muted('  gemini config set api-key AIzaSy...'));
+    print(theme.colors.muted('  gemini config set theme neon'));
+    print(theme.colors.muted('  gemini config set output-dir ~/Documents/Gemini'));
+    print(theme.colors.muted('  gemini config show'));
+}
+async function showConfig() {
+    const theme = t();
+    const config = await loadConfig();
+    print(header('Current Configuration', getConfigPath()));
+    print('');
+    const lines = [
+        `${theme.colors.primary('API Key:')} ${config.apiKey ? theme.colors.success('Set (hidden)') : theme.colors.error('Not set')}`,
+        `${theme.colors.primary('Theme:')} ${config.theme}`,
+        `${theme.colors.primary('Output Dir:')} ${config.outputDir}`,
+        `${theme.colors.primary('Default Voice:')} ${config.defaultVoice}`,
+        `${theme.colors.primary('Image Size:')} ${config.defaultImageSize}`,
+        `${theme.colors.primary('Image Ratio:')} ${config.defaultImageRatio}`,
+        `${theme.colors.primary('Video Ratio:')} ${config.defaultVideoRatio}`,
+    ];
+    print(box(lines, { title: 'Settings' }));
+    print('');
+    if (!config.apiKey) {
+        printWarning('API key not set. Set it with:');
+        print(theme.colors.muted('  gemini config set api-key YOUR_API_KEY'));
+        print('');
+        print(theme.colors.muted('Or set the GEMINI_API_KEY environment variable.'));
+    }
+}
+async function setConfig(key, value) {
+    const theme = t();
+    // Map user-friendly keys to config keys
+    const keyMap = {
+        'api-key': 'apiKey',
+        'apikey': 'apiKey',
+        'theme': 'theme',
+        'output-dir': 'outputDir',
+        'outputdir': 'outputDir',
+        'default-voice': 'defaultVoice',
+        'voice': 'defaultVoice',
+        'default-model': 'defaultModel',
+        'model': 'defaultModel',
+        'image-size': 'defaultImageSize',
+        'image-ratio': 'defaultImageRatio',
+        'video-ratio': 'defaultVideoRatio',
+    };
+    const configKey = keyMap[key.toLowerCase()];
+    if (!configKey) {
+        printError(`Unknown setting: ${key}`);
+        printMuted('Valid settings: api-key, theme, output-dir, default-voice');
+        process.exit(1);
+    }
+    // Validate values
+    if (configKey === 'theme') {
+        const validThemes = ['terminal', 'neon', 'minimal', 'ocean', 'forest'];
+        if (!validThemes.includes(value)) {
+            printError(`Invalid theme: ${value}`);
+            printMuted(`Valid themes: ${validThemes.join(', ')}`);
+            process.exit(1);
+        }
+    }
+    if (configKey === 'defaultImageSize') {
+        const validSizes = ['1K', '2K', '4K'];
+        if (!validSizes.includes(value)) {
+            printError(`Invalid image size: ${value}`);
+            printMuted(`Valid sizes: ${validSizes.join(', ')}`);
+            process.exit(1);
+        }
+    }
+    // Save the config
+    await saveConfig({ [configKey]: value });
+    // Show confirmation
+    const displayValue = configKey === 'apiKey' ? '***' + value.slice(-4) : value;
+    printSuccess(`Set ${key} = ${displayValue}`);
+    if (configKey === 'apiKey') {
+        print('');
+        print(theme.colors.muted('Your API key is now stored in:'));
+        print(theme.colors.muted(`  ${getConfigPath()}`));
+        print('');
+        printWarning('Keep this file secure. Do not share it.');
+    }
+}
+export async function configCommand(argv) {
+    const { positionals } = parseArgs({
+        args: argv,
+        options: {
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+        allowPositionals: true,
+    });
+    const subCommand = positionals[0];
+    if (!subCommand || subCommand === 'help') {
+        showHelp();
+        return;
+    }
+    switch (subCommand) {
+        case 'show':
+            await showConfig();
+            break;
+        case 'path':
+            print(getConfigPath());
+            break;
+        case 'set':
+            const key = positionals[1];
+            const value = positionals.slice(2).join(' ');
+            if (!key || !value) {
+                printError('Usage: gemini config set <key> <value>');
+                printMuted('Example: gemini config set api-key YOUR_KEY');
+                process.exit(1);
+            }
+            await setConfig(key, value);
+            break;
+        default:
+            printError(`Unknown config command: ${subCommand}`);
+            printMuted('Valid commands: set, show, path');
+            process.exit(1);
+    }
+}

package/dist/cli/commands/image.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Image Command
+ *
+ * Generate images with Gemini's Imagen model.
+ * gemini image "a cat in space"
+ */
+export declare function imageCommand(argv: string[]): Promise<void>;

package/dist/cli/commands/image.js

@@ -0,0 +1,133 @@
+/**
+ * Image Command
+ *
+ * Generate images with Gemini's Imagen model.
+ * gemini image "a cat in space"
+ */
+import { parseArgs } from 'node:util';
+import { initGeminiClient, generateImage } from '../../gemini-client.js';
+import { setupLogger } from '../../utils/logger.js';
+import { spinner, print, printError, printSuccess, printMuted, t, header, box } from '../ui/index.js';
+// Valid options
+const VALID_SIZES = ['1K', '2K', '4K'];
+const VALID_RATIOS = ['1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9'];
+function showHelp() {
+    const theme = t();
+    print(header('gemini image', 'Generate images with AI'));
+    print('');
+    print(theme.colors.primary('Usage:'));
+    print(`  gemini image ${theme.colors.muted('"your prompt"')} [options]`);
+    print('');
+    print(theme.colors.primary('Options:'));
+    print(`  ${theme.colors.highlight('--size, -s')}     ${theme.colors.muted('Resolution: 1K, 2K, 4K (default: 2K)')}`);
+    print(`  ${theme.colors.highlight('--ratio, -r')}    ${theme.colors.muted('Aspect ratio (default: 1:1)')}`);
+    print(`  ${theme.colors.highlight('--output, -o')}   ${theme.colors.muted('Output file path')}`);
+    print(`  ${theme.colors.highlight('--style')}        ${theme.colors.muted('Art style (e.g., "watercolor", "cyberpunk")')}`);
+    print(`  ${theme.colors.highlight('--search')}       ${theme.colors.muted('Use Google Search for real-world accuracy')}`);
+    print(`  ${theme.colors.highlight('--help, -h')}     ${theme.colors.muted('Show this help')}`);
+    print('');
+    print(theme.colors.primary('Aspect Ratios:'));
+    print(theme.colors.muted('  1:1   - Square (default)'));
+    print(theme.colors.muted('  16:9  - Widescreen landscape'));
+    print(theme.colors.muted('  9:16  - Portrait/mobile'));
+    print(theme.colors.muted('  4:3   - Classic landscape'));
+    print(theme.colors.muted('  3:4   - Classic portrait'));
+    print(theme.colors.muted('  21:9  - Ultrawide cinematic'));
+    print('');
+    print(theme.colors.primary('Examples:'));
+    print(theme.colors.muted('  gemini image "a cat astronaut floating in space"'));
+    print(theme.colors.muted('  gemini image "sunset over mountains" --ratio 16:9 --size 4K'));
+    print(theme.colors.muted('  gemini image "portrait of a robot" -r 3:4 --style "oil painting"'));
+    print(theme.colors.muted('  gemini image "Eiffel Tower at night" --search'));
+}
+export async function imageCommand(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            help: { type: 'boolean', short: 'h', default: false },
+            size: { type: 'string', short: 's', default: '2K' },
+            ratio: { type: 'string', short: 'r', default: '1:1' },
+            output: { type: 'string', short: 'o' },
+            style: { type: 'string' },
+            search: { type: 'boolean', default: false },
+        },
+        allowPositionals: true,
+    });
+    if (values.help) {
+        showHelp();
+        return;
+    }
+    // Get prompt from positional args
+    const prompt = positionals.join(' ');
+    if (!prompt) {
+        printError('No image prompt provided');
+        printMuted('Usage: gemini image "your prompt"');
+        process.exit(1);
+    }
+    const theme = t();
+    const s = spinner();
+    const size = values.size;
+    const ratio = values.ratio;
+    const style = values.style;
+    const useSearch = values.search;
+    // Validate size
+    if (!VALID_SIZES.includes(size)) {
+        printError(`Invalid size: ${size}`);
+        printMuted(`Valid sizes: ${VALID_SIZES.join(', ')}`);
+        process.exit(1);
+    }
+    // Validate ratio
+    if (!VALID_RATIOS.includes(ratio)) {
+        printError(`Invalid ratio: ${ratio}`);
+        printMuted(`Valid ratios: ${VALID_RATIOS.join(', ')}`);
+        process.exit(1);
+    }
+    try {
+        // Suppress logger output for CLI
+        setupLogger('quiet');
+        // Initialize Gemini client
+        s.start('Connecting to Gemini...');
+        await initGeminiClient();
+        // Build full prompt with style if provided
+        let fullPrompt = prompt;
+        if (style) {
+            fullPrompt = `${prompt}, in ${style} style`;
+        }
+        // Generate image
+        s.update('Generating image...');
+        const result = await generateImage(fullPrompt, {
+            aspectRatio: ratio, // Type assertion for ratio string
+            imageSize: size,
+            useGoogleSearch: useSearch,
+        });
+        if (!result.filePath) {
+            throw new Error('Image generation failed - no file created');
+        }
+        s.success('Image generated!');
+        print('');
+        // Get file stats
+        const file = Bun.file(result.filePath);
+        const fileSize = file.size;
+        // Show info
+        const infoLines = [
+            `${theme.colors.primary('Prompt:')} ${prompt.substring(0, 50)}${prompt.length > 50 ? '...' : ''}`,
+            style ? `${theme.colors.primary('Style:')} ${style}` : null,
+            `${theme.colors.primary('Size:')} ${size}`,
+            `${theme.colors.primary('Ratio:')} ${ratio}`,
+            useSearch ? `${theme.colors.primary('Search:')} Enabled` : null,
+            `${theme.colors.primary('File:')} ${result.filePath}`,
+            `${theme.colors.primary('File Size:')} ${(fileSize / 1024).toFixed(1)} KB`,
+        ].filter(Boolean);
+        print(box(infoLines, { title: 'Image Generated' }));
+        print('');
+        printSuccess(`Image saved to: ${result.filePath}`);
+        // Hint about opening
+        print('');
+        print(theme.colors.muted(`Open with: open "${result.filePath}"`));
+    }
+    catch (error) {
+        s.error('Image generation failed');
+        printError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}

package/dist/cli/commands/query.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Query Command
+ *
+ * Direct queries to Gemini with thinking level control.
+ * gemini query "your prompt" [--thinking high]
+ */
+export declare function queryCommand(argv: string[]): Promise<void>;

package/dist/cli/commands/query.js

@@ -0,0 +1,94 @@
+/**
+ * Query Command
+ *
+ * Direct queries to Gemini with thinking level control.
+ * gemini query "your prompt" [--thinking high]
+ */
+import { parseArgs } from 'node:util';
+import { initGeminiClient, generateWithGeminiPro, generateWithGeminiFlash } from '../../gemini-client.js';
+import { setupLogger } from '../../utils/logger.js';
+import { spinner, print, printError, printMuted, t, header } from '../ui/index.js';
+function showHelp() {
+    const theme = t();
+    print(header('gemini query', 'Query Gemini directly'));
+    print('');
+    print(theme.colors.primary('Usage:'));
+    print(`  gemini query ${theme.colors.muted('"your prompt"')} [options]`);
+    print('');
+    print(theme.colors.primary('Options:'));
+    print(`  ${theme.colors.highlight('--thinking, -t')}  ${theme.colors.muted('Thinking level: minimal, low, medium, high (default: high)')}`);
+    print(`  ${theme.colors.highlight('--model, -m')}     ${theme.colors.muted('Model to use: pro, flash (default: pro)')}`);
+    print(`  ${theme.colors.highlight('--help, -h')}      ${theme.colors.muted('Show this help')}`);
+    print('');
+    print(theme.colors.primary('Examples:'));
+    print(theme.colors.muted('  gemini query "What is the meaning of life?"'));
+    print(theme.colors.muted('  gemini query "Explain quantum computing" --thinking high'));
+    print(theme.colors.muted('  gemini query "Quick fact check" -t minimal -m flash'));
+}
+export async function queryCommand(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            help: { type: 'boolean', short: 'h', default: false },
+            thinking: { type: 'string', short: 't', default: 'high' },
+            model: { type: 'string', short: 'm', default: 'pro' },
+        },
+        allowPositionals: true,
+    });
+    if (values.help) {
+        showHelp();
+        return;
+    }
+    // Get prompt from positional args
+    const prompt = positionals.join(' ');
+    if (!prompt) {
+        printError('No prompt provided');
+        printMuted('Usage: gemini query "your prompt"');
+        process.exit(1);
+    }
+    // Validate thinking level
+    const validThinking = ['minimal', 'low', 'medium', 'high'];
+    const thinking = values.thinking;
+    if (!validThinking.includes(thinking)) {
+        printError(`Invalid thinking level: ${thinking}`);
+        printMuted(`Valid options: ${validThinking.join(', ')}`);
+        process.exit(1);
+    }
+    // Validate model
+    const validModels = ['pro', 'flash'];
+    const model = values.model;
+    if (!validModels.includes(model)) {
+        printError(`Invalid model: ${model}`);
+        printMuted(`Valid options: ${validModels.join(', ')}`);
+        process.exit(1);
+    }
+    const theme = t();
+    const s = spinner();
+    try {
+        // Suppress logger output for CLI (we use our own spinner/output)
+        setupLogger('quiet');
+        // Initialize Gemini client
+        s.start('Connecting to Gemini...');
+        await initGeminiClient();
+        // Query Gemini based on model
+        s.update(`Thinking (${thinking})...`);
+        const options = {
+            thinkingLevel: thinking
+        };
+        const result = model === 'flash'
+            ? await generateWithGeminiFlash(prompt, options)
+            : await generateWithGeminiPro(prompt, options);
+        s.success('Response received');
+        print('');
+        // Show the response
+        print(theme.colors.primary('Response:'));
+        print('');
+        print(result);
+        print('');
+    }
+    catch (error) {
+        s.error('Query failed');
+        printError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}

package/dist/cli/commands/research.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Research Command
+ *
+ * Deep research agent for comprehensive investigation.
+ * gemini research "your research question"
+ */
+export declare function researchCommand(argv: string[]): Promise<void>;