mcp-gemini: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Run

npm install      # Install dependencies
npm run build    # Compile TypeScript (tsc)
npm start        # Run server (node dist/index.js)

Unit tests via node:test (built-in), linting via Biome:

npm test            # Build + run tests
npm run test:only   # Run tests without rebuilding
npm run lint        # Check for issues
npm run lint:fix    # Auto-fix issues

Environment

Requires GEMINI_API_KEY env var.

Optional: GEMINI_DEFAULT_MODEL overrides the default model (falls back to gemini-flash-latest).

Manual Testing

Pipe JSON-RPC messages to stdin:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize"}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"generate_text","arguments":{"prompt":"Say hello"}}}\n' | GEMINI_API_KEY=your-key node dist/index.js

Architecture

This is a Model Context Protocol (MCP) server that wraps Google Gemini's API. It communicates over stdin/stdout using JSON-RPC 2.0 — there is no HTTP server.

Source files:

• src/index.ts — Entrypoint: I/O helpers (send, reply, textReply, errorReply, error), request dispatch, readline listener
• src/handlers.ts — createHandlers() factory returning a handler map; individual tool handler functions
• src/tools.ts — Tool schema definitions (static JSON Schema data for MCP tools/list)
• src/conversations.ts — Conversation store with TTL pruning (30min expiry, max 100 conversations)
• src/models.ts — Model lists, defaults, GEMINI_DEFAULT_MODEL env var override
• src/types.ts — All type definitions: RequestId, ToolName, ToolResult, ToolHandler, tool arg interfaces, MCP interfaces (MCPToolAnnotations, MCPToolDefinition, MCPRequest, MCPResponse)

Request flow: stdin line → JSON parse → handleRequest dispatches by MCP method (initialize, tools/list, tools/call) → handleToolCall looks up handler in map → handler returns ToolResult → dispatch maps result to JSON-RPC response on stdout.