Gemini CLI RAG MCP

Gemini CLI RAG MCP

Este projeto constrói um serviço RAG independente, transformando a documentação estática do gemini-cli em uma ferramenta dinâmica e consultável. Esta ferramenta expõe conhecimento através de um protocolo (como MCP), tornando-o acessível a qualquer cliente integrado. Portanto, ambientes como gemini-cli, VS Code ou Cursor podem fornecer aos desenvolvedores respostas instantâneas e precisas em linguagem natural, diretamente em seu fluxo de trabalho. Acelerando o aprendizado e permitindo que você aproveite intuitivamente todo o potencial da ferramenta.

Sumário

• Visão Geral do Projeto
• Recursos
• Arquitetura do Sistema
• Começando
  • Pré-requisitos
  • Instalação
• Uso
  • 1. Execute o Serviço MCP com Docker
  • 2. Configure o Gemini CLI
  • 3. Faça Perguntas
• Como Funciona
  • Extração de Dados e Vetorização
  • Servidor MCP
  • Integração com Gemini CLI
• Scripts
• Dependências

Visão Geral do Projeto

Este projeto integra um pipeline RAG e consiste em três componentes principais:

1. Extração e Processamento de Dados: Scripts Python que extraem conteúdo de todos os arquivos markdown no diretório gemini-cli/docs e subdiretórios, processam e criam um armazenamento vetorial.
2. Servidor MCP: Um servidor MCP baseado em Python que expõe o armazenamento vetorial como uma ferramenta consultável.
3. Gemini CLI/VSCode/ClaudeCode/Windsurf/Cursor...etc: O Gemini CLI oficial, que pode se conectar ao servidor MCP para responder perguntas sobre sua documentação.

Recursos

• Perguntas e Respostas baseadas em RAG: Faça perguntas sobre o Gemini CLI em linguagem natural e obtenha respostas baseadas em sua documentação oficial.
• Armazenamento Vetorial Local: Toda a documentação é armazenada e indexada localmente usando SKLearnVectorStore.
• Extensível: O servidor MCP pode ser facilmente estendido com novas ferramentas e fontes de dados.

Arquitetura do Sistema

O sistema é composto pelas seguintes partes:

1. extract.py: Este script percorre o diretório gemini-cli/docs, encontra todos os arquivos .md e concatena seu conteúdo em um único arquivo gemini_cli_docs.txt.
2. create_vectorstore.py: Este script carrega o arquivo gemini_cli_docs.txt, divide-o em partes e cria um arquivo gemini_cli_vectorstore.parquet usando HuggingFaceEmbeddings e SKLearnVectorStore.
3. gemini_cli_mcp.py: Este script executa um servidor FastMCP que carrega o armazenamento vetorial e expõe dois endpoints:
   • gemini_cli_query_tool(query: str): Uma ferramenta que recebe uma consulta do usuário, recupera documentos relevantes do armazenamento vetorial e os retorna.
   • docs://gemini-cli/full: Um recurso que retorna o conteúdo completo do arquivo gemini_cli_docs.txt.
4. gemini-cli/: O Gemini CLI oficial, que pode ser configurado para usar o servidor MCP.

Começando

Pré-requisitos

• Python 3.13
• Node.js 18+
• Uma instalação existente do gemini-cli. Se você não tiver, pode clonar o repositório oficial:

  git clone https://github.com/google-gemini/gemini-cli.git
  

Instalação

1. Clone o repositório:

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

2. Instale as dependências Python:

   pip install -r requirements.txt
   

3. Prepare os dados da documentação: Execute o script extract.py para reunir toda a documentação markdown em um único arquivo.

   python extract.py
   

4. Crie o armazenamento vetorial: Execute o script create_vectorstore.py para criar o armazenamento vetorial a partir do arquivo de documentação.

   python create_vectorstore.py
   

Uso

Antes de executar com docker, tente executar o mcp em modo de desenvolvimento e teste:

mcp dev gemini_cli_mcp.py

Em Command field type 'python' and on Arguments digite 'gemini_cli_mcp.py' e pressione Conectar.

1. Execute o Serviço MCP com Docker

A maneira mais eficiente de executar o servidor MCP é com Docker Compose. Isso inicia um contêiner em segundo plano e o mantém pronto para o Gemini CLI se conectar.

docker-compose up -d

O contêiner continuará em execução, mas o script Python MCP em si só será executado sob demanda pelo Gemini CLI.

2. Configure o Gemini CLI

Para tornar o Gemini CLI ciente do seu servidor MCP local, você precisa criar um arquivo de configuração.

• Dentro do diretório .gemini, adicione o seguinte conteúdo ao arquivo settings.json:

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

Esta configuração informa ao Gemini CLI como iniciar seu servidor MCP usando docker exec. Obs: Para usar no VSCode, vá para Settings, digite 'mcp' e clique em settings.json. Em seguida, coloque no modo Agente e peça ao copilot para implementar o servidor gemini-cli-mcp (forneça o json acima como contexto).

3. Faça Perguntas

Após reiniciar o terminal para que as alterações tenham efeito, simplesmente execute gemini a partir do seu terminal. Ele descobrirá automaticamente o local_rag_server e usará suas ferramentas quando necessário.

Exemplo:

Como personalizo meu gemini-cli?

ou algo mais específico:

Meu gemini cli não está mostrando um prompt interativo quando o executo no meu servidor de build, ele apenas sai. Tenho uma variável de ambiente CI_TOKEN definida. Por que isso está acontecendo e como posso corrigir?

Como Funciona

Extração de Dados e Vetorização

O script extract.py encontra recursivamente todos os arquivos markdown no diretório gemini-cli/docs. Ele lê seu conteúdo e o combina em um único arquivo de texto, gemini_cli_docs.txt.

O script create_vectorstore.py então pega este arquivo de texto e:

1. Carrega o documento.
2. Divide-o em partes menores e sobrepostas usando RecursiveCharacterTextSplitter.
3. Usa HuggingFaceEmbeddings (com o modelo BAAI/bge-large-en-v1.5) para criar embeddings para cada parte.
4. Armazena esses embeddings em um SKLearnVectorStore, que é persistido em gemini_cli_vectorstore.parquet.

Servidor MCP

O script gemini_cli_mcp.py cria um servidor FastMCP. Este servidor define uma ferramenta, gemini_cli_query_tool, que pode ser chamada pelo Gemini CLI ou VSCode/Cursor/etc. Quando esta ferramenta é invocada, ela:

1. Carrega o SKLearnVectorStore persistido.
2. Usa o armazenamento vetorial como um recuperador para encontrar as partes de documento mais relevantes para a consulta dada.
3. Retorna o conteúdo dessas partes para o Gemini CLI.

Integração com Gemini CLI

O Gemini CLI é projetado para ser extensível através de servidores MCP. O CLI descobre ferramentas disponíveis conectando-se a servidores definidos no objeto mcpServers em um arquivo settings.json (seja no diretório .gemini do projeto ou no diretório ~/.gemini do usuário).

O Gemini CLI suporta três mecanismos de transporte para comunicação:

• Transporte Stdio: Cria um subprocesso e comunica-se com ele através de stdin e stdout. Este é o método usado neste projeto, com a propriedade command em settings.json.
• Transporte SSE: Conecta-se a um endpoint Server-Sent Events (SSE), definido com uma propriedade url.
• Transporte HTTP Streamable: Usa streaming HTTP para comunicação, configurado com uma propriedade httpUrl.

Ao usar o comando docker exec, estamos aproveitando o transporte stdio para criar um canal de comunicação direto com o script Python dentro do contêiner.

Scripts

• extract.py: Extrai documentação de arquivos markdown.
• create_vectorstore.py: Cria o armazenamento vetorial.
• gemini_cli_mcp.py: Executa o servidor MCP.

Dependências

Python

As principais dependências Python estão listadas em requirements.txt:

• langchain: Para divisão de texto, armazenamentos vetoriais e embeddings.
• tiktoken: Para contagem de tokens.
• sentence-transformers: Para o modelo de embedding.
• scikit-learn: Para o armazenamento vetorial.
• mcp: Para o servidor MCP.
• fastapi: Para o servidor MCP.

Node.js

O projeto depende do pacote gemini-cli e suas dependências. Veja gemini-cli/package.json para mais detalhes.