github_repo_rag

🚀 GitHub Repository RAG MCP Server

A powerful Model Context Protocol (MCP) server that enables natural language interaction with GitHub repositories using Retrieval-Augmented Generation (RAG). This tool makes codebases conversational by leveraging AST parsing, semantic embeddings, and natural language interfaces.

✨ Features

• Multi-language Support: Process TypeScript, JavaScript, and Python codebases
• Flexible Embeddings: Choose between OpenAI, Hugging Face, or Xenova embeddings
• Seamless Integration: Works with Claude Desktop, Cursor, VS Code, and other MCP clients
• Smart Chunking: AST-powered semantic code chunking for better context
• Fast Search: Local FAISS index for quick semantic search
• Natural Q&A: Ask questions about your codebase in plain English

📋 Prerequisites

• Node.js (v14 or higher)
• Python 3.x (for Python code support)
• Git (for repository cloning)
• Optional: API keys for OpenAI or Hugging Face (required for their respective embeddings)

🔐 Environment Setup

1. Create a .env file in the project root:

   cp .env.example .env

2. Edit the .env file with your API keys:

   # OpenAI API Key (required for OpenAI embeddings)
   OPENAI_API_KEY=your_openai_api_key_here
   
   # Hugging Face API Key (required for Hugging Face embeddings)
   HUGGINGFACE_API_KEY=your_huggingface_api_key_here

   ⚠️ Important: Never commit your .env file to version control. It's already in .gitignore to prevent accidental commits.

🛠️ Installation

1. Install Claude Desktop:

   # Follow instructions at https://github.com/jxnl/cluade-desktop

2. Configure the MCP server:

   # Open VS Code with the config file
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json

3. Add the MCP server configuration:

   {
     "mcpServers": {
       "github_repo_rag_server": {
         "command": "npx",
         "args": ["-y", "github_repo_rag"],
         "env": {
           "OPENAI_API_KEY": "your_openai_key",
           "HUGGINGFACE_API_KEY": "your_huggingface_key"
         }
       }
     }
   }

🚀 Usage

Processing a Repository

Use the following command in Claude Desktop or any compatible MCP client:

process repository https://github.com/owner/repo.git use openai embeddings

Embedding Options:

• use openai embeddings - Use OpenAI's embedding models
• use huggingface - Use Hugging Face's embedding models
• Default: Xenova Transformers (no API key required)

The process will:

1. Clone the repository
2. Parse files to extract functions and classes
3. Create embeddings using your chosen model
4. Build a local searchable FAISS index

Asking Questions

Query your codebase using natural language:

How does the agent handle GitHub API authentication? repo https://github.com/owner/repo.git

The server will:

1. Search the vector index for semantically relevant code
2. Return context-rich answers with relevant functions and logic

🐛 Troubleshooting

Common Issues

Issue	Solution
Invalid repo URL	Ensure the repository is public and the URL is correct
Disk space issues	Check available space for cloning and indexing
Missing dependencies	Verify Node.js, Python, and Git installations
API key errors	Confirm correct API keys are set in environment variables
Push protection errors	Ensure no API keys are committed to the repository

Debugging

• Check console logs for detailed error messages and stack traces
• Verify all required dependencies are installed
• Ensure proper permissions for repository cloning and file access
• Verify environment variables are properly set

📚 Additional Features

• Automatic README summarization (when available)
• Support for private repositories (with proper authentication)
• Customizable chunking strategies
• Configurable embedding models

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security Best Practices

• Never commit API keys or sensitive information
• Use environment variables for all sensitive data
• Keep your .env file in .gitignore
• Use .env.example as a template for required environment variables

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.