# choplin/mcp-gemini-cli architecture

> Architecture diagram of the GitHub repository choplin/mcp-gemini-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/choplin/mcp-gemini-cli
- Repository: https://github.com/choplin/mcp-gemini-cli

## Overview

##### Project type and purpose
- This is an open-source CLI “MCP server” wrapper around Google’s Gemini CLI.
- It exposes three “tools” (googleSearch, chat, analyzeFile) via the Model Context Protocol (MCP) so that AI assistants can invoke Gemini’s multimodal capabilities.

##### File structure
- Top-level files:
– index.ts: the main entry point and command dispatcher
– package.json, bun.lock, biome.json, tsconfig.json, .lefthook.yml, .markdownlintignore, .npmignore, .gitignore
- tests/integration/tools.test.ts: end-to-end tests for each tool
- No separate “frontend” or “backend” directories—this is a single CLI service.

##### README for additional insights
- Confirms three MCP tools, needed external dependency (Gemini CLI installed or invoked via npx)
- Shows quick-start commands, installation options (npx vs. bun run), and usage examples
- Mentions Bun as the runtime and standard build/test/lint scripts

a. Main components
1. MCP Client (e.g., Claude Desktop or any MCP-compatible client)
2. mcp-gemini-cli server process (index.ts running under Bun or npx)
– Tool Dispatcher
– Tool Implementations: googleSearch, chat, analyzeFile
3. External Gemini CLI binary (invoked via `gemini` command or `npx mcp-gemini-cli --allow-npx`)
4. Filesystem (for analyzeFile reads)
5. Tests (integration tests—optional to show separately)
b. Relationships & interactions
- MCP Client → (STDIN/STDOUT or IPC) → mcp-gemini-cli
- Dispatcher maps incoming MCP JSON requests to one of the three tool functions
- Each tool function spawns or calls the Gemini CLI process with appropriate flags
- Gemini CLI executes search/chat/analysis, returns output (text or JSON)
- mcp-gemini-cli captures output, reformats it in MCP response schema, sends back to the client
- analyzeFile also interacts with the local file system to read binary/text data
c. Architectural patterns & design principles
- CLI server pattern: single entrypoint + command dispatcher
- Tool abstraction: each “tool” is a pure function implementing a well-defined interface
- Process isolation: external Gemini CLI called as a subprocess (shell out)
- Minimal layering: Request parsing → Tool execution → Response formatting
d. Relevant technologies/frameworks
- Bun runtime or Node.js via npx
- TypeScript (index.ts)
- Model Context Protocol (MCP) JSON messaging over STDIO/IPC
- External Gemini CLI tool
- Testing: Bun’s built-in test runner for integration tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    MCPClient["MCP Client"]:::external
    GeminiCLI["Gemini CLI"]:::external

    %% Resources
    Filesystem["Filesystem"]:::resource

    %% Server Components
    subgraph "mcp-gemini-cli Server"
        Dispatcher["Tool Dispatcher (index.ts)"]:::internal
        googleSearch["googleSearch Tool"]:::internal
        chat["chat Tool"]:::internal
        analyzeFile["analyzeFile Tool"]:::internal
    end

    %% Test Suite
    Tests["Integration Tests"]:::test

    %% Configuration Files
    subgraph "Configuration & Dependencies"
        PackageJSON["package.json"]:::config
        BunLock["bun.lock"]:::config
        BiomeJSON["biome.json"]:::config
        TSConfig["tsconfig.json"]:::config
    end

    %% Metadata & Docs
    README["README.md"]:::config

    %% Git Hooks
    Lefthook[".lefthook.yml"]:::config

    %% Lint & Ignore Rules
    subgraph "Lint & Ignore Rules"
        MarkdownIgnore[".markdownlintignore"]:::config
        NpmIgnore[".npmignore"]:::config
        GitIgnore[".gitignore"]:::config
    end

    %% Relationships
    MCPClient -->|"MCP request"| Dispatcher
    Dispatcher -->|"invokes"| googleSearch
    Dispatcher -->|"invokes"| chat
    Dispatcher -->|"invokes"| analyzeFile
    googleSearch -->|"spawn process"| GeminiCLI
    chat -->|"spawn process"| GeminiCLI
    analyzeFile -->|"spawn process"| GeminiCLI
    analyzeFile -->|"reads"| Filesystem
    GeminiCLI -->|"returns output"| Dispatcher
    Dispatcher -->|"MCP response"| MCPClient

    %% Side connections
    Dispatcher --- Tests
    Dispatcher --- PackageJSON
    Dispatcher --- BunLock
    Dispatcher --- BiomeJSON
    Dispatcher --- TSConfig
    Dispatcher --- README
    Dispatcher --- Lefthook
    Dispatcher --- MarkdownIgnore
    Dispatcher --- NpmIgnore
    Dispatcher --- GitIgnore

    %% Click Events
    click Dispatcher "https://github.com/choplin/mcp-gemini-cli/blob/master/index.ts"
    click googleSearch "https://github.com/choplin/mcp-gemini-cli/blob/master/index.ts"
    click chat "https://github.com/choplin/mcp-gemini-cli/blob/master/index.ts"
    click analyzeFile "https://github.com/choplin/mcp-gemini-cli/blob/master/index.ts"
    click Tests "https://github.com/choplin/mcp-gemini-cli/blob/master/tests/integration/tools.test.ts"
    click PackageJSON "https://github.com/choplin/mcp-gemini-cli/blob/master/package.json"
    click BunLock "https://github.com/choplin/mcp-gemini-cli/blob/master/bun.lock"
    click BiomeJSON "https://github.com/choplin/mcp-gemini-cli/blob/master/biome.json"
    click TSConfig "https://github.com/choplin/mcp-gemini-cli/blob/master/tsconfig.json"
    click README "https://github.com/choplin/mcp-gemini-cli/blob/master/README.md"
    click Lefthook "https://github.com/choplin/mcp-gemini-cli/blob/master/.lefthook.yml"
    click MarkdownIgnore "https://github.com/choplin/mcp-gemini-cli/blob/master/.markdownlintignore"
    click NpmIgnore "https://github.com/choplin/mcp-gemini-cli/blob/master/.npmignore"
    click GitIgnore "https://github.com/choplin/mcp-gemini-cli/blob/master/.gitignore"

    %% Styles
    classDef external fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px
    classDef internal fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px
    classDef resource fill:#FFF9C4,stroke:#F9A825,stroke-width:2px
    classDef test fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px
    classDef config fill:#CFD8DC,stroke:#37474F,stroke-width:2px
```
