gemini-mcp-bridge: Instructions file for Codex

AGENTS.md - gemini-mcp-bridge

Guidance for AI coding agents working in the gemini-mcp-bridge repository.

Project Overview

Open source MCP server that wraps Gemini CLI as a subprocess, exposing its best features as MCP tools. Works with any MCP-compatible client: Claude Code, Codex CLI, Cursor, Windsurf, VS Code.

• npm package: gemini-mcp-bridge
• License: MIT
• Language: TypeScript
• Framework: @modelcontextprotocol/sdk

See README § Latency expectations before changing timeout defaults or adding new tools. The hard timeout cap is defined in src/utils/limits.ts and imported by both spawn.ts and retry.ts.

Architecture

MCP Client  --stdio-->  gemini-mcp-bridge  --spawn-->  gemini CLI subprocess

We assemble prompts in TypeScript and spawn the CLI. The search, structured, and query (change-mode path) tools load prompt templates from prompts/*.md via src/utils/prompts.ts and fill placeholders; the CLI then runs in agentic mode inside the target repo, using its built-in tools (read_file, grep_search, list_directory, google_web_search) to explore surrounding code or the web for context.

Tools

Tool	Purpose	Default Timeout
query	Agentic query with read-only repo exploration	120s
search	Google Search grounded query via google_web_search	120s
structured	JSON Schema validated output	120s
ping	Health check + CLI capability detection	10s
fetch-chunk	Retrieve cached follow-up chunks from oversized responses	N/A (<1s)

Query Tool Details

Text queries run under --approval-mode plan (read-only agentic). Files are passed as @{path} hints, Gemini reads them with its own tools and can explore surrounding code. Image files (png, jpg, jpeg, gif, webp, bmp) trigger --yolo mode for native pixel access. Gitignored files cannot be read in plan mode.

Search Tool Details

Spawns CLI in agentic mode with access to google_web_search. Uses a prompt template (prompts/search.md) that instructs Gemini to search, synthesize, and cite sources.