# Gemini CLI RAG MCP
This project builds a standalone RAG service, transforming the static `gemini-cli` documentation into a dynamic and queryable tool. This tool exposes knowledge via a protocol (like MCP), making it accessible to any integrated client. Therefore, environments like gemini-cli, VS Code, or Cursor can provide developers with instant, accurate answers in natural language, directly within their workflow. Accelerating learning and letting you intuitively leverage the tool's full potential.
## Table of Contents
- [Project Overview](#project-overview)
- [Features](#features)
- [System Architecture](#system-architecture)
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [1. Run the MCP Service with Docker](#1-run-the-mcp-service-with-docker)
- [2. Configure Gemini CLI](#2-configure-gemini-cli)
- [3. Ask Questions](#3-ask-questions)
- [How It Works](#how-it-works)
- [Data Extraction and Vectorization](#data-extraction-and-vectorization)
- [MCP Server](#mcp-server)
- [Gemini CLI Integration](#gemini-cli-integration)
- [Scripts](#scripts)
- [Dependencies](#dependencies)
## Project Overview
This project integrates a RAG pipeline and it consists of three main components:
1. **Data Extraction and Processing**: Python scripts that extract content from all markdown files in the `gemini-cli/docs` directory and sub-directories, process it, and create a vector store.
2. **MCP Server**: A Python-based MCP server that exposes the vector store as a queryable tool.
3. **Gemini CLI/VSCode/ClaudeCode/Windsurf/Cursor...etc**: The official Gemini CLI, which can connect to the MCP server to answer questions about its documentation.
## Features
- **RAG-based Q&A**: Ask questions about the Gemini CLI in natural language and get answers based on its official documentation.
- **Local Vector Store**: The entire documentation is stored and indexed locally using `SKLearnVectorStore`.
- **Extensible**: The MCP server can be easily extended with new tools and data sources.
## System Architecture
The system is composed of the following parts:
1. **`extract.py`**: This script walks through the `gemini-cli/docs` directory, finds all `.md` files, and concatenates their content into a single `gemini_cli_docs.txt` file.
2. **`create_vectorstore.py`**: This script loads the `gemini_cli_docs.txt` file, splits it into chunks, and creates a `gemini_cli_vectorstore.parquet` file using `HuggingFaceEmbeddings` and `SKLearnVectorStore`.
3. **`gemini_cli_mcp.py`**: This script runs a `FastMCP` server that loads the vector store and exposes two endpoints:
- `gemini_cli_query_tool(query: str)`: A tool that takes a user query, retrieves relevant documents from the vector store, and returns them.
- `docs://gemini-cli/full`: A resource that returns the entire content of the `gemini_cli_docs.txt` file.
4. **`gemini-cli/`**: The official Gemini CLI, which can be configured to use the MCP server.
## Getting Started
### Prerequisites
- Python 3.13
- [Node.js 18+](https://nodejs.org/en/download)
- An existing `gemini-cli` installation. If you don't have it, you can clone the official repository:
```bash
git clone https://github.com/google-gemini/gemini-cli.git
```
### Installation
1. **Clone the repository:**
```bash
git clone https://github.com/your-username/gemini-cli-rag-mcp.git
cd gemini-cli-rag-mcp
```
2. **Install Python dependencies:**
```bash
pip install -r requirements.txt
```
3. **Prepare the documentation data:**
Run the `extract.py` script to gather all the markdown documentation into a single file.
```bash
python extract.py
```
4. **Create the vector store:**
Run the `create_vectorstore.py` script to create the vector store from the documentation file.
```bash
python create_vectorstore.py
```
## Usage
Before running with docker, try running the mcp in dev mode and test:
```bash
mcp dev gemini_cli_mcp.py
```
On ``Command`` field type 'python' and on ``Arguments`` type 'gemini_cli_mcp.py' and press Connect.
### 1. Run the MCP Service with Docker
The most efficient way to run the MCP server is with Docker Compose. This starts a container in the background and keeps it ready for Gemini CLI to connect to.
```bash
docker-compose up -d
```
The container will keep running, but the Python MCP script itself will only be executed on-demand by Gemini CLI.
### 2. Configure Gemini CLI
To make Gemini CLI aware of your local MCP server, you need to create a configuration file.
- Inside the `.gemini` directory add the following content to the `settings.json` file:
```json
{
"mcpServers": {
"local_rag_server": {
"command": "docker",
"args": [
"exec",
"-i",
"gemini-cli-mcp-container",
"python",
"gemini_cli_mcp.py"
]
}
}
}
```
This configuration tells Gemini CLI how to launch your MCP server using `docker exec`.
**Obs**: To use it in VSCode, go to `Settings` type 'mcp' and click on `settings.json`. Then put on Agent mode and ask copilot to implement the gemini-cli-mcp server (give the json above as context).
### 3. Ask Questions
After restarting terminal to changes make effect, simply run `gemini` from your terminal. It will automatically discover the `local_rag_server` and use its tools when needed.
**Example:**
> How do I customize my gemini-cli?
or something more specific:
> My gemini cli is not showing an interactive prompt when I run it on my build server, it just exits. I have a CI_TOKEN environment variable set. Why is this happening and how can I fix it?
## How It Works
### Data Extraction and Vectorization
The `extract.py` script recursively finds all markdown files in the `gemini-cli/docs` directory. It reads their content and combines it into a single text file, `gemini_cli_docs.txt`.
The `create_vectorstore.py` script then takes this text file and:
1. Loads the document.
2. Splits it into smaller, overlapping chunks using `RecursiveCharacterTextSplitter`.
3. Uses `HuggingFaceEmbeddings` (with the `BAAI/bge-large-en-v1.5` model) to create embeddings for each chunk.
4. Stores these embeddings in a `SKLearnVectorStore`, which is persisted to `gemini_cli_vectorstore.parquet`.
### MCP Server
The `gemini_cli_mcp.py` script creates a `FastMCP` server. This server defines a tool, `gemini_cli_query_tool`, which can be called by the Gemini CLI or VSCode/Cursor/etc. When this tool is invoked, it:
1. Loads the persisted `SKLearnVectorStore`.
2. Uses the vector store as a retriever to find the most relevant document chunks for the given query.
3. Returns the content of these chunks to the Gemini CLI.
### Gemini CLI Integration
The Gemini CLI is designed to be extensible through MCP servers. The CLI discovers available tools by connecting to servers defined in the `mcpServers` object in a `settings.json` file (either in the project's `.gemini` directory or in the user's home `~/.gemini` directory).
Gemini CLI supports three transport mechanisms for communication:
- **Stdio Transport**: Spawns a subprocess and communicates with it over `stdin` and `stdout`. This is the method used in this project, with the `command` property in `settings.json`.
- **SSE Transport**: Connects to a Server-Sent Events (SSE) endpoint, defined with a `url` property.
- **Streamable HTTP Transport**: Uses HTTP streaming for communication, configured with an `httpUrl` property.
By using the `docker exec` command, we are leveraging the `stdio` transport to create a direct communication channel with the Python script inside the container.
## Scripts
- **`extract.py`**: Extracts documentation from markdown files.
- **`create_vectorstore.py`**: Creates the vector store.
- **`gemini_cli_mcp.py`**: Runs the MCP server.
## Dependencies
### Python
The main Python dependencies are listed in `requirements.txt`:
- `langchain`: For text splitting, vector stores, and embeddings.
- `tiktoken`: For token counting.
- `sentence-transformers`: For the embedding model.
- `scikit-learn`: For the vector store.
- `mcp`: For the MCP server.
- `fastapi`: For the MCP server.
### Node.js
The project relies on the `gemini-cli` package and its dependencies. See `gemini-cli/package.json` for more details.
