README.md

metadata

title: GitNexus
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
tags:
  - mcp-in-action-track-consumer

🚀 GitNexus

MCP-Enabled GitHub Automation for AI Agents 🤖 Track 2: MCP in Action tags:

• mcp-in-action-track-consumer

👥 Project Team

Name	Hugging Face Profile
Viraj Talathi	@Viraj77
Pranjal Prakash	@pranjal00
Karan Singh	@karansingh99
Shriprasasd Patil	@Shriprasad-P
Bharath Nuthalapati	@bharath-nuthalapati

This Hugging Face Space demonstrates GitHub automation using MCP (Model Context Protocol) tools integrated with a Gradio UI. AI agents like Claude, Cursor, and Antigravity can discover and call GitHub functions via MCP, while humans can use the intuitive web interface.

▶️YouTube Demo: https://youtu.be/enW1gmE6Xrc

Huggingface 🤗: https://huggingface.co/spaces/Viraj77/GitNexus

X Post: https://x.com/TalathiViraj/status/1994856982319436242?s=20

Github Token Generation: https://youtu.be/iLrywUfs7yU?si=s3nQA5DbCb_QFINw

🎯 Features

GitHub Operations

• Create Repository - Create new public/private GitHub repositories
• List Repositories - View all repositories for the authenticated account
• Create Issue - Open issues in any repository
• List Issues - View issues filtered by state (open/closed/all)
• Commit File - Create or update files in repositories
• Read File - Read file contents from repositories

MCP Tools for AI Agents

The following tools are exposed via MCP for AI agent automation:

• github.create_repo
• github.list_repos
• github.create_issue
• github.list_issues
• github.commit_file
• github.read_file
• github.generate_docs_with_tts

🔧 Tech Stack

• Python - Core language
• Gradio - Web UI framework with MCP server support
• PyGithub - GitHub API wrapper
• MCP - Model Context Protocol for AI agent integration
• Gemini 2.5 Flash - AI Code Analysis & Documentation
• ElevenLabs - Text-to-Speech Generation

📦 Project Structure

HF-Pro/
├── app.py              # Main Gradio application with MCP handlers
├── ghclient.py         # GitHub API client wrapper
├── ai_helper.py        # AI Documentation & TTS helper
├── requirements.txt    # Python dependencies
└── README.md          # This file

🚀 Deployment to Hugging Face Spaces

Prerequisites

1. A Hugging Face account
2. A GitHub Personal Access Token (PAT) with repo permissions
3. A Google Gemini API Key
4. An ElevenLabs API Key

🎮 Usage

For Humans (Web UI)

The Gradio interface has 3 tabs:

📦 Repositories Tab

• Create new repositories with name, privacy setting, and description
• List all repositories for the authenticated account

📋 Issues Tab

• Create issues in any repository (format: username/repo)
• List issues filtered by state (open/closed/all)

📄 Custom Files Tab

• Commit files to repositories (creates or updates)
• Read file contents from repositories

🤖 Code Documentation Tab

• Upload code files for AI analysis
• Generate comprehensive documentation
• Listen to 2-line audio summary
• Commit documentation to GitHub

🔒 Security Notes

• No user authentication required - The Space uses a server-side GitHub token
• All repos are public by default - Anyone can view created repositories
• Repository name validation - Input validation prevents malicious repo names
• Token security - GitHub token is stored securely in HF Spaces secrets (never in code)

🛠️ Local Development

To run locally:

1. Clone the repository

   git clone <your-space-url>
   cd HF-Pro
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Set environment variables

   # Windows (PowerShell)
   $env:GITHUB_TOKEN="your_github_token"
   $env:GEMINI_API_KEY="your_gemini_key"
   $env:ELEVENLABS_API_KEY="your_elevenlabs_key"
   

4. Run the application

   python app.py
   

5. Open in browser

   • Navigate to http://localhost:7860

📄 License

MIT License - feel free to use this code for your own projects.