GitHub Repository Intelligence MCP Server
README.md
# GitHub Repository Intelligence MCP Server 🤖
An AI-powered GitHub Repository Intelligence system that allows a Large Language Model (LLM) to explore, inspect, and analyze GitHub repositories through the **Model Context Protocol (MCP)**.
The system combines **Qwen, Groq, MCP, and the GitHub REST API** to create an agentic workflow where the LLM can understand a user's request, select the appropriate tool, retrieve information from GitHub, and generate a natural-language response.
---
## 📋 Table of Contents
- [Overview](#-overview)
- [Why This Project](#-why-this-project)
- [Architecture](#-architecture)
- [How It Works](#-how-it-works)
- [Features](#-features)
- [MCP Tools](#-mcp-tools)
- [Project Structure](#-project-structure)
- [Components](#-components)
- [Agent Loop](#-agent-loop)
- [Example Queries](#-example-queries)
- [Technologies](#-technologies)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Running the Project](#-running-the-project)
- [Testing](#-testing)
- [Example Workflow](#-example-workflow)
- [Design Decisions](#-design-decisions)
- [Current Limitations](#-current-limitations)
- [Future Improvements](#-future-improvements)
- [Security](#-security)
- [Learning Outcomes](#-learning-outcomes)
- [Project Status](#-project-status)
- [Author](#-author)
---
## 🚀 Overview
**GitHub Repository Intelligence MCP Server** is an agentic AI project that enables an LLM to interact with GitHub repositories through the **Model Context Protocol (MCP)**.
Instead of manually navigating GitHub, searching through files, opening repositories, and inspecting source code, users can interact with their GitHub account using natural language.
For example:
```text
What repositories do I have?
```
```text
Tell me about my Autonomous-research-agent repository.
```
```text
Show me the structure of my Autonomous-research-agent repository.
```
```text
Explain agents/researcher.py.
```
```text
Where is Tavily used in my Autonomous-research-agent repository?
```
The AI agent determines which tool is required, calls the MCP server, retrieves the required information from GitHub, and then uses the retrieved information to generate the final response.
---
## 💡 Why This Project?
Modern LLM applications are increasingly moving from simple question-answering systems toward **agentic systems** that can interact with external tools and data sources.
This project demonstrates how an LLM can be connected to an external system using MCP.
Instead of implementing GitHub functionality directly inside the LLM application, the GitHub capabilities are exposed as independent MCP tools.
This creates a clean separation between:
- AI reasoning
- Tool orchestration
- MCP communication
- GitHub API integration
The result is a modular architecture that can be extended with additional tools in the future.
---
## 🧠 Architecture
The overall architecture is:
```text
┌──────────────────────┐
│ User │
│ Natural Language │
│ Query │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Qwen / Groq │
│ │
│ LLM Reasoning │
│ Tool Selection │
└──────────┬───────────┘
│
│ Tool Call
▼
┌──────────────────────┐
│ MCP Client │
│ agent.py │
└──────────┬───────────┘
│
│ MCP Protocol
▼
┌──────────────────────┐
│ MCP Server │
│ server.py │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Tool Layer │
│ repositories.py │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ GitHub Client │
│ github_client.py │
└──────────┬───────────┘
│
│ GitHub REST API
▼
┌──────────────────────┐
│ GitHub │
│ Repositories │
│ Files / Code │
└──────────────────────┘
```
The result is then returned through the same chain:
```text
GitHub
↓
GitHub Client
↓
Tool Layer
↓
MCP Server
↓
MCP Client
↓
Qwen / Groq
↓
Natural Language Answer
```
---
## 🔄 How It Works
The system follows an agentic tool-calling workflow.
### Step 1 — User Query
The user provides a natural-language request.
Example:
```text
Where is Tavily used in my Autonomous-research-agent repository?
```
### Step 2 — Tool Discovery
The MCP client connects to the MCP server and discovers the available tools.
The current MCP server exposes:
```text
get_my_repositories
get_repository
list_files
read_file
search_code
```
### Step 3 — LLM Reasoning
The available tools are converted into a format that can be used by the Groq API.
Qwen receives:
- The system instructions
- The user's question
- The available tools
The model determines which tool is appropriate.
For the Tavily example, it can select:
```text
search_code
```
### Step 4 — MCP Tool Execution
The MCP client sends the tool request to the MCP server.
The MCP server executes the corresponding Python function.
### Step 5 — GitHub API Request
The tool layer calls the `GitHubClient`.
The GitHub client communicates with the GitHub REST API using the authenticated GitHub token.
### Step 6 — Tool Result
The GitHub data is returned to the MCP server and then to the MCP client.
### Step 7 — LLM Receives the Result
The tool result is added to the conversation as a tool message.
Qwen receives the retrieved information and decides whether:
- More tools are required
- Or enough information exists to answer the user
### Step 8 — Final Answer
Once enough information has been collected, Qwen generates the final natural-language response.
---
## ✨ Features
### 🔍 Repository Discovery
Retrieve repositories belonging to the authenticated GitHub account.
The system can return information such as:
- Repository name
- Full repository name
- Visibility
- Description
- GitHub URL
---
### 📊 Repository Information
Retrieve detailed information about a specific repository.
The returned information includes:
- Repository name
- Full name
- Description
- Visibility
- Primary programming language
- Stars
- Forks
- Open issues
- Default branch
- Creation date
- Last update date
- GitHub URL
---
### 📁 Repository File Exploration
The `list_files` tool allows the agent to explore repository files and directories.
The tool supports directory paths, allowing the agent to progressively explore a repository.
For example:
```text
list_files(
repo="Autonomous-research-agent",
path=""
)
```
Then:
```text
list_files(
repo="Autonomous-research-agent",
path="agents"
)
```
Then:
```text
list_files(
repo="Autonomous-research-agent",
path="tools"
)
```
This allows the agent to construct a repository tree.
---
### 📖 File Reading
The `read_file` tool retrieves the content of a specific repository file.
For example:
```text
read_file(
repo="Autonomous-research-agent",
path="agents/researcher.py"
)
```
The retrieved content can then be analyzed by the LLM.
This allows users to ask questions such as:
```text
Explain agents/researcher.py.
```
or:
```text
What does this file do?
```
---
### 🔎 Code Search
The `search_code` tool searches for a text string across repository files.
It can be used to find:
- Functions
- Classes
- Variables
- Libraries
- APIs
- Configuration values
- Imports
- Any specific text
For example:
```text
search_code(
repo="Autonomous-research-agent",
query="Tavily"
)
```
The result includes:
- File path
- Matching line number
- Matching line content
- GitHub URL
---
### 🤖 Agentic Tool Selection
The LLM automatically determines which tool should be used.
The application does not require the user to manually select a tool.
For example:
```text
User:
"What repositories do I have?"
```
The LLM can select:
```text
get_my_repositories
```
For:
```text
"Tell me about my Autonomous-research-agent repository."
```
The LLM can select:
```text
get_repository
```
For:
```text
"Explain agents/researcher.py."
```
The LLM can select:
```text
read_file
```
For:
```text
"Where is Tavily used?"
```
The LLM can select:
```text
search_code
```
---
### 🔁 Multi-Step Reasoning
The agent can execute multiple tool calls when a request requires additional information.
For example, a repository structure request can result in:
```text
list_files("")
↓
list_files("agents")
↓
list_files("config")
↓
list_files("models")
↓
list_files("reports")
↓
list_files("tests")
↓
list_files("tools")
↓
Final Answer
```
This creates a practical agentic workflow instead of a single API call.
---
## 🛠️ MCP Tools
The MCP server currently provides five tools.
| Tool | Description |
|------|-------------|
| `get_my_repositories` | Retrieves repositories from the authenticated GitHub account |
| `get_repository` | Retrieves detailed information about a repository |
| `list_files` | Lists files and directories at a specific repository path |
| `read_file` | Reads the content of a specific repository file |
| `search_code` | Searches for a text string across repository files |
---
## 📂 Project Structure
```text
GitHub-MCP-server/
│
├── src/
│ │
│ ├── __init__.py
│ │
│ ├── agent.py
│ │
│ ├── server.py
│ │
│ ├── github_client.py
│ │
│ ├── test_client.py
│ │
│ └── tools/
│ │
│ ├── __init__.py
│ │
│ └── repositories.py
│
├── .env
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md
```
---
## 🧩 Components
### `src/agent.py`
This is the main AI agent.
It is responsible for:
- Starting the MCP server
- Creating the MCP client
- Connecting to the MCP server using stdio
- Discovering available MCP tools
- Converting MCP tools into Groq-compatible function tools
- Sending user queries to Qwen
- Processing LLM tool calls
- Calling MCP tools
- Sending tool results back to Qwen
- Managing the agent loop
- Returning the final natural-language response
The agent supports multiple tool-calling steps.
A maximum number of steps is defined to prevent an infinite loop.
```python
MAX_STEPS = 8
```
---
### `src/server.py`
This file implements the MCP server.
It creates the MCP server using the MCP Python SDK:
```python
from mcp.server.mcpserver import MCPServer
```
The server exposes the GitHub functionality as MCP tools.
The tools currently exposed are:
```text
get_my_repositories
get_repository
list_files
read_file
search_code
```
The server communicates with the MCP client through standard input/output.
---
### `src/github_client.py`
This module handles communication with the GitHub REST API.
The `GitHubClient` class is responsible for:
- GitHub authentication
- Getting the authenticated user
- Getting repositories
- Getting repository details
- Listing repository files
- Reading repository files
- Searching repository code
The client uses `httpx.AsyncClient` for asynchronous HTTP requests.
---
### `src/tools/repositories.py`
This module acts as an abstraction layer between the MCP server and the GitHub client.
It calls the appropriate methods from `GitHubClient` and converts the raw GitHub API responses into structured results.
This separation keeps the architecture modular.
---
### `src/test_client.py`
This is a lightweight MCP client used for testing the MCP server independently from the AI agent.
It verifies:
- MCP server startup
- MCP client connection
- Tool discovery
- Tool execution
This makes it useful during development and debugging.
---
## 🔁 Agent Loop
The core agent follows a repeated loop.
Conceptually:
```text
User Query
↓
Qwen
↓
Does Qwen need a tool?
│
├── No ──→ Final Answer
│
└── Yes
↓
Tool Call
↓
MCP Client
↓
MCP Server
↓
GitHub API
↓
Tool Result
↓
Qwen
│
├── Need more information
│ ↓
│ Another Tool Call
│
└── Enough information
↓
Final Answer
```
The implementation limits the number of iterations using:
```python
MAX_STEPS = 8
```
This prevents the agent from continuing indefinitely.
---
## 💬 Example Queries
### 1. List Repositories
User:
```text
What repositories do I have?
```
Expected tool:
```text
get_my_repositories
```
---
### 2. Repository Information
User:
```text
Tell me about my Autonomous-research-agent repository.
```
Expected tool:
```text
get_repository
```
---
### 3. Repository Structure
User:
```text
Show me the structure of my Autonomous-research-agent repository.
```
The agent can use:
```text
list_files
```
multiple times to explore directories.
Example workflow:
```text
list_files("")
↓
list_files("agents")
↓
list_files("config")
↓
list_files("models")
↓
list_files("reports")
↓
list_files("tests")
↓
list_files("tools")
↓
Final repository tree
```
---
### 4. File Explanation
User:
```text
Explain agents/researcher.py in my Autonomous-research-agent repository.
```
The agent uses:
```text
read_file
```
The file content is then provided to Qwen for analysis.
---
### 5. Code Search
User:
```text
Where is Tavily used in my Autonomous-research-agent repository?
```
The agent uses:
```text
search_code
```
The tool searches the repository and returns matching files and lines.
The LLM can then summarize the results.
---
## 🧪 Example Result
A query such as:
```text
Where is Tavily used in my Autonomous-research-agent repository?
```
can result in findings such as:
```text
tools/web_search.py
config/settings.py
requirements.txt
agents/researcher.py
agents/report_generator.py
utils/retry.py
.env.example
README.md
```
The LLM can then explain how Tavily is integrated and where it is consumed in the project.
---
## 🧰 Technologies
### Python
The main programming language used to implement the application.
### Model Context Protocol
MCP is used as the communication protocol between the AI application and the available tools.
### Qwen
Qwen is used as the reasoning model responsible for understanding user requests and selecting tools.
### Groq
Groq provides the API interface used to run the Qwen model.
### GitHub REST API
GitHub's API provides repository information, files, and source-code data.
### HTTPX
Used for asynchronous HTTP requests to the GitHub API.
### python-dotenv
Used to load environment variables from the `.env` file.
### asyncio
Used to run the asynchronous MCP and GitHub operations.
---
## 📦 Installation
### Prerequisites
Make sure you have:
- Python 3.10+
- A GitHub account
- A GitHub Personal Access Token
- A Groq API key
---
### 1. Clone the Repository
```bash
git clone https://github.com/Ibrahimhussein711/GitHub-MCP-server.git
```
Move into the project directory:
```bash
cd GitHub-MCP-server
```
---
### 2. Create a Virtual Environment
On Windows:
```powershell
python -m venv .venv
```
Activate the environment:
```powershell
.venv\Scripts\activate
```
---
### 3. Install Dependencies
```bash
pip install -r requirements.txt
```
---
## 🔐 Configuration
Create a `.env` file in the project root:
```env
GITHUB_TOKEN=your_github_token
GROQ_API_KEY=your_groq_api_key
```
### GitHub Token
The GitHub token is used to authenticate requests to the GitHub REST API.
### Groq API Key
The Groq API key is used to access the Qwen model through Groq.
---
## ⚠️ Environment Variable Security
Never commit your `.env` file to GitHub.
The repository includes a `.gitignore` file that excludes:
```text
.venv/
.env
__pycache__/
*.pyc
```
A safe `.env.example` file is included:
```env
GITHUB_TOKEN=
GROQ_API_KEY=
```
Users can copy this file and add their own credentials.
---
## ▶️ Running the Project
Make sure your virtual environment is activated.
From the project root, run:
```bash
python -m src.agent
```
The application will display:
```text
Ask me something about your GitHub:
```
You can then enter a natural-language request.
For example:
```text
What repositories do I have?
```
or:
```text
Show me the structure of my Autonomous-research-agent repository.
```
or:
```text
Where is Tavily used in my Autonomous-research-agent repository?
```
---
## 🧪 Testing
The project includes a lightweight MCP test client.
Run:
```bash
python -m src.test_client
```
This test verifies that the MCP communication works correctly without involving the LLM.
The test confirms:
```text
MCP Client
↓
MCP Server
↓
MCP Tool
↓
GitHub API
↓
Result
```
---
## 🔬 MCP Communication
The application uses the MCP Python SDK.
The MCP server is started as a subprocess using:
```python
StdioServerParameters(
command=sys.executable,
args=["-m", "src.server"],
)
```
The client then connects to the server:
```python
async with Client(server) as mcp_client:
```
The client discovers the available tools:
```python
tools_result = await mcp_client.list_tools()
```
The discovered tools are then converted into the format expected by Groq.
---
## 🔗 Tool Calling
The LLM receives the available tools as function definitions.
Each tool contains:
- Name
- Description
- Input schema
For example:
```text
get_repository
```
can be represented to the LLM with a schema containing:
```text
repo: string
```
When the LLM decides to use a tool, it generates a tool call.
The agent extracts:
```text
tool name
tool arguments
tool call ID
```
The MCP client then executes the corresponding MCP tool.
---
## 🧱 Layered Architecture
The project follows a layered architecture:
```text
┌───────────────────────────────┐
│ AI Agent Layer │
│ agent.py │
└───────────────┬───────────────┘
│
┌───────────────▼───────────────┐
│ MCP Layer │
│ server.py │
└───────────────┬───────────────┘
│
┌───────────────▼───────────────┐
│ Tool Layer │
│ tools/repositories.py │
└───────────────┬───────────────┘
│
┌───────────────▼───────────────┐
│ GitHub API Layer │
│ github_client.py │
└───────────────┬───────────────┘
│
┌───────────────▼───────────────┐
│ GitHub API │
└───────────────────────────────┘
```
This separation provides better maintainability and makes future extensions easier.
---
## ⚡ Design Decisions
### Why MCP?
MCP provides a standardized interface for connecting AI applications with external tools and data sources.
Instead of tightly coupling the AI agent with GitHub-specific logic, GitHub operations are exposed through MCP tools.
This makes the system easier to extend.
---
### Why Separate the GitHub Client?
The GitHub API implementation is isolated inside:
```text
github_client.py
```
This prevents GitHub-specific HTTP logic from being mixed with MCP logic.
The MCP server only needs to expose tools.
The GitHub client handles API communication.
---
### Why Have a Tool Layer?
The file:
```text
tools/repositories.py
```
acts as an abstraction between the MCP server and the GitHub client.
This makes it possible to change the GitHub implementation without heavily modifying the MCP server.
---
### Why Use an Agent Loop?
A single tool call is not enough for complex repository questions.
For example:
```text
Show me the repository structure.
```
may require several calls:
```text
list_files("")
list_files("agents")
list_files("config")
list_files("models")
list_files("tools")
...
```
The agent loop allows the LLM to continue calling tools until it has enough information to answer.
---
## 🚧 Current Limitations
The current implementation is an MVP focused on GitHub repository exploration and code intelligence.
Some limitations include:
### Large Repository Performance
The current `search_code` implementation retrieves the repository tree and reads files individually.
For very large repositories, this can result in many GitHub API requests.
### GitHub Pagination
The current implementation is primarily designed for the current MVP workflow and does not provide a complete pagination abstraction for every GitHub endpoint.
### Search Optimization
The current search implementation performs text matching across repository files.
It does not yet provide semantic code search or advanced ranking.
### Repository Scope
The current tools focus mainly on:
- Repositories
- Files
- File content
- Code search
Other GitHub resources are not currently exposed as MCP tools.
---
## 🔮 Future Improvements
Potential future improvements include:
### 🌳 Repository Tree Tool
Add a dedicated:
```text
get_repository_tree
```
tool to retrieve repository structure more efficiently.
---
### 🔎 Improved Code Search
Improve code search performance by:
- Reducing GitHub API calls
- Adding search ranking
- Supporting GitHub's native code search
- Adding semantic search
---
### 🧠 Semantic Code Intelligence
Add embeddings and vector search to allow queries such as:
```text
Where is authentication implemented?
```
even when the exact word "authentication" is not present.
---
### 🏗️ Architecture Analysis
Add tools that allow the agent to understand:
```text
What are the main components of this project?
```
```text
Explain the architecture of this repository.
```
---
### 📦 Dependency Analysis
Analyze:
```text
requirements.txt
package.json
pyproject.toml
```
and explain project dependencies.
---
### 📜 Commit Analysis
Add tools for:
- Commit history
- Recent changes
- Contributors
- Changed files
---
### 🔀 Pull Request Intelligence
Allow users to ask:
```text
What changed in the latest pull request?
```
```text
Summarize this pull request.
```
---
### 🐛 Issue Intelligence
Add GitHub issue tools to support questions such as:
```text
What are the open issues in this repository?
```
---
### 💾 Caching
Add caching to reduce repeated GitHub API requests and improve performance.
---
## 🔒 Security
The project uses environment variables for sensitive credentials.
Credentials should never be hard-coded into source files.
Sensitive files are excluded through `.gitignore`:
```text
.env
```
The GitHub token is only used for authenticated requests to the GitHub API.
Before publishing the project, always verify that no secrets have been committed.
You can check staged files using:
```bash
git status
```
---
## 🎯 Learning Outcomes
This project demonstrates practical experience with:
- Generative AI
- Agentic AI
- LLM tool calling
- Function calling
- Model Context Protocol
- MCP Client / Server architecture
- API integration
- GitHub REST API
- Asynchronous Python
- Tool discovery
- Multi-step agent loops
- Structured tool schemas
- Environment variable management
- Modular software architecture
---
## 📈 What Makes This Project Different?
This is not simply a chatbot connected to GitHub.
The main goal is to demonstrate an **agentic architecture**.
The LLM is given access to multiple tools and is responsible for determining:
```text
What information do I need?
↓
Which tool can provide it?
↓
What parameters should I provide?
↓
Do I need another tool?
↓
Do I have enough information?
↓
Generate the final answer.
```
This makes the project a practical example of how LLMs can interact with external systems through a standardized tool protocol.
---
## 🧪 Verified Workflows
The current implementation has been tested with several workflows.
### Repository Discovery
```text
User Query
↓
Qwen
↓
get_my_repositories
↓
GitHub API
↓
Repository List
↓
Qwen
↓
Final Answer
```
### Repository Information
```text
User Query
↓
Qwen
↓
get_repository
↓
GitHub API
↓
Repository Details
↓
Qwen
↓
Final Answer
```
### Repository Structure
```text
User Query
↓
Qwen
↓
list_files
↓
More list_files calls
↓
Repository Structure
↓
Qwen
↓
Clean Tree
```
### File Analysis
```text
User Query
↓
Qwen
↓
read_file
↓
GitHub API
↓
File Content
↓
Qwen
↓
File Explanation
```
### Code Search
```text
User Query
↓
Qwen
↓
search_code
↓
Repository Files
↓
Matching Lines
↓
Qwen
↓
Code Search Summary
```
---
## 📌 Project Status
**MVP Completed and Functional ✅**
The current version successfully demonstrates an end-to-end agentic workflow:
```text
User
↓
Qwen / Groq
↓
MCP Client
↓
MCP Server
↓
GitHub API
↓
MCP Client
↓
Qwen / Groq
↓
Natural Language Answer
```
The project currently supports:
- Repository discovery
- Repository information
- File exploration
- File reading
- Code searching
- Automatic tool selection
- Multi-step tool execution
- Natural-language repository analysis
---
## 👨💻 Author
**Ibrahim Hussein**
Senior Electronics & Electrical Communication Engineering Student
### Interests
- Generative AI
- Agentic AI
- Machine Learning
- RAG Systems
- AI Automation
- Software Engineering
- Intelligent Systems
---
## ⭐ Support
If you find this project useful or interesting, consider giving the repository a ⭐ on GitHub.
Repository:
https://github.com/Ibrahimhussein711/GitHub-MCP-server
---
## 📄 License
This project is intended for educational, experimental, and portfolio purposes.This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues