Gemini CLI RAG MCP

Un servidor de preguntas y respuestas basado en RAG que utiliza un almacén vectorial construido a partir de la documentación de Gemini CLI.

GitHub
9
Prueba este MCPPatrocinado

Documentación

Gemini CLI RAG MCP

Este proyecto construye un servicio RAG independiente, transformando la documentación estática gemini-cli en una herramienta dinámica y consultable. Esta herramienta expone conocimiento a través de un protocolo (como MCP), haciéndolo accesible a cualquier cliente integrado. Por lo tanto, entornos como gemini-cli, VS Code o Cursor pueden proporcionar a los desarrolladores respuestas instantáneas y precisas en lenguaje natural, directamente en su flujo de trabajo. Acelerando el aprendizaje y permitiéndote aprovechar intuitivamente todo el potencial de la herramienta.

Tabla de Contenidos

Descripción General del Proyecto

Este proyecto integra un pipeline RAG y consta de tres componentes principales:

  1. Extracción y Procesamiento de Datos: Scripts de Python que extraen contenido de todos los archivos markdown en el directorio gemini-cli/docs y subdirectorios, lo procesan y crean un almacén vectorial.
  2. Servidor MCP: Un servidor MCP basado en Python que expone el almacén vectorial como una herramienta consultable.
  3. Gemini CLI/VSCode/ClaudeCode/Windsurf/Cursor...etc: La CLI oficial de Gemini, que puede conectarse al servidor MCP para responder preguntas sobre su documentación.

Características

  • Preguntas y Respuestas basadas en RAG: Haz preguntas sobre Gemini CLI en lenguaje natural y obtén respuestas basadas en su documentación oficial.
  • Almacén Vectorial Local: Toda la documentación se almacena e indexa localmente usando SKLearnVectorStore.
  • Extensible: El servidor MCP se puede extender fácilmente con nuevas herramientas y fuentes de datos.

Arquitectura del Sistema

El sistema se compone de las siguientes partes:

  1. extract.py: Este script recorre el directorio gemini-cli/docs, encuentra todos los archivos .md y concatena su contenido en un único archivo gemini_cli_docs.txt.
  2. create_vectorstore.py: Este script carga el archivo gemini_cli_docs.txt, lo divide en fragmentos y crea un archivo gemini_cli_vectorstore.parquet usando HuggingFaceEmbeddings y SKLearnVectorStore.
  3. gemini_cli_mcp.py: Este script ejecuta un servidor FastMCP que carga el almacén vectorial y expone dos endpoints:
    • gemini_cli_query_tool(query: str): Una herramienta que toma una consulta del usuario, recupera documentos relevantes del almacén vectorial y los devuelve.
    • docs://gemini-cli/full: Un recurso que devuelve el contenido completo del archivo gemini_cli_docs.txt.
  4. gemini-cli/: La CLI oficial de Gemini, que se puede configurar para usar el servidor MCP.

Primeros Pasos

Requisitos Previos

  • Python 3.13
  • Node.js 18+
  • Una instalación existente de gemini-cli. Si no la tienes, puedes clonar el repositorio oficial: 
    git clone https://github.com/google-gemini/gemini-cli.git

Instalación

  1. Clonar el repositorio:

    git clone https://github.com/your-username/gemini-cli-rag-mcp.git
cd gemini-cli-rag-mcp

  2. Instalar dependencias de Python:

    pip install -r requirements.txt

  3. Preparar los datos de documentación: Ejecuta el script extract.py para recopilar toda la documentación markdown en un solo archivo.

    python extract.py

  4. Crear el almacén vectorial: Ejecuta el script create_vectorstore.py para crear el almacén vectorial a partir del archivo de documentación.

    python create_vectorstore.py

Uso

Antes de ejecutar con docker, intenta ejecutar el mcp en modo desarrollo y pruébalo:

mcp dev gemini_cli_mcp.py

En Command field type 'python' and on Arguments escribe 'gemini_cli_mcp.py' y presiona Conectar.

1. Ejecutar el Servicio MCP con Docker

La forma más eficiente de ejecutar el servidor MCP es con Docker Compose. Esto inicia un contenedor en segundo plano y lo mantiene listo para que Gemini CLI se conecte.

docker-compose up -d

El contenedor seguirá ejecutándose, pero el script MCP de Python solo se ejecutará bajo demanda por Gemini CLI.

2. Configurar Gemini CLI

Para que Gemini CLI sea consciente de tu servidor MCP local, necesitas crear un archivo de configuración.

  • Dentro del directorio .gemini añade el siguiente contenido al archivo settings.json:

    {
  "mcpServers": {
    "local_rag_server": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "gemini-cli-mcp-container",
        "python",
        "gemini_cli_mcp.py"
      ]
    }
  }
}

Esta configuración le indica a Gemini CLI cómo lanzar tu servidor MCP usando docker exec. Nota: Para usarlo en VSCode, ve a Settings, escribe 'mcp' y haz clic en settings.json. Luego ponlo en modo Agente y pide a copilot que implemente el servidor gemini-cli-mcp (dale el json anterior como contexto).

3. Hacer Preguntas

Después de reiniciar la terminal para que los cambios surtan efecto, simplemente ejecuta gemini desde tu terminal. Descubrirá automáticamente el local_rag_server y usará sus herramientas cuando sea necesario.

Ejemplo:

¿Cómo personalizo mi gemini-cli?

o algo más específico:

Mi gemini cli no muestra un prompt interactivo cuando lo ejecuto en mi servidor de compilación, simplemente se cierra. Tengo una variable de entorno CI_TOKEN configurada. ¿Por qué sucede esto y cómo puedo solucionarlo?

Cómo Funciona

Extracción y Vectorización de Datos

El script extract.py encuentra recursivamente todos los archivos markdown en el directorio gemini-cli/docs. Lee su contenido y lo combina en un único archivo de texto, gemini_cli_docs.txt.

El script create_vectorstore.py luego toma este archivo de texto y:

  1. Carga el documento.
  2. Lo divide en fragmentos más pequeños y superpuestos usando RecursiveCharacterTextSplitter.
  3. Usa HuggingFaceEmbeddings (con el modelo BAAI/bge-large-en-v1.5) para crear embeddings para cada fragmento.
  4. Almacena estos embeddings en un SKLearnVectorStore, que se persiste en gemini_cli_vectorstore.parquet.

Servidor MCP

El script gemini_cli_mcp.py crea un servidor FastMCP. Este servidor define una herramienta, gemini_cli_query_tool, que puede ser llamada por Gemini CLI o VSCode/Cursor/etc. Cuando se invoca esta herramienta:

  1. Carga el SKLearnVectorStore persistido.
  2. Usa el almacén vectorial como recuperador para encontrar los fragmentos de documento más relevantes para la consulta dada.
  3. Devuelve el contenido de estos fragmentos a Gemini CLI.

Integración con Gemini CLI

Gemini CLI está diseñado para ser extensible a través de servidores MCP. La CLI descubre las herramientas disponibles conectándose a los servidores definidos en el objeto mcpServers en un archivo settings.json (ya sea en el directorio .gemini del proyecto o en el directorio ~/.gemini del usuario).

Gemini CLI soporta tres mecanismos de transporte para la comunicación:

  • Transporte Stdio: Genera un subproceso y se comunica con él a través de stdin y stdout. Este es el método utilizado en este proyecto, con la propiedad command en settings.json.
  • Transporte SSE: Se conecta a un endpoint de Server-Sent Events (SSE), definido con una propiedad url.
  • Transporte HTTP Streamable: Usa streaming HTTP para la comunicación, configurado con una propiedad httpUrl.

Al usar el comando docker exec, estamos aprovechando el transporte stdio para crear un canal de comunicación directo con el script de Python dentro del contenedor.

Scripts

  • extract.py: Extrae documentación de archivos markdown.
  • create_vectorstore.py: Crea el almacén vectorial.
  • gemini_cli_mcp.py: Ejecuta el servidor MCP.

Dependencias

Python

Las principales dependencias de Python se enumeran en requirements.txt:

  • langchain: Para división de texto, almacenes vectoriales y embeddings.
  • tiktoken: Para conteo de tokens.
  • sentence-transformers: Para el modelo de embeddings.
  • scikit-learn: Para el almacén vectorial.
  • mcp: Para el servidor MCP.
  • fastapi: Para el servidor MCP.

Node.js

El proyecto depende del paquete gemini-cli y sus dependencias. Consulta gemini-cli/package.json para más detalles.