GitHub Repository Assistant using MCP

An AI-powered GitHub repository assistant that demonstrates how MCP (Model Context Protocol) allows LLMs to interact with external tools and data through a standardized protocol.

Project Overview

This project creates an MCP server that exposes GitHub repository operations as tools. When connected to an MCP-compatible LLM client (like Claude Desktop), users can ask natural language questions about any GitHub repository, and the LLM will automatically use the appropriate tools to find and present the information.

Example interaction:

User: "Give me information about microsoft/vscode"
LLM: → calls get_repo_info("microsoft", "vscode")
LLM: "Visual Studio Code is a source-code editor developed by Microsoft..."

User: "Show me the project structure"
LLM: → calls list_files("microsoft", "vscode")
LLM: "The repository contains the following structure: src/, package.json, README.md..."

Related MCP server: github-ops-mcp

What is MCP?

MCP (Model Context Protocol) is a standardized way for LLMs (Large Language Models) to interact with external tools and data sources.

Think of MCP as a universal adapter:

• It defines how an LLM discovers what tools are available

• It defines how the LLM calls those tools

• It defines how results are returned

Without MCP:

LLM → Custom GitHub Integration → GitHub API
     (You write this for each LLM)

With MCP:

LLM → MCP → MCP Server → GitHub API
     (Write once, works with any MCP-compatible LLM)

Why MCP?

Imagine you want to connect an LLM to GitHub, Slack, and a database. Without MCP:

1. You'd write a custom GitHub integration for OpenAI

2. Another custom integration for Claude

3. Another for Google's Gemini

4. And repeat for every new LLM...

With MCP:

1. Write one GitHub MCP server

2. Any MCP-compatible LLM can use it

3. Add new tools by just adding new functions

4. No changes needed when new LLMs are released

Key benefits:

• Standardization: One protocol works everywhere

• Reusability: Write once, use with any MCP client

• Modularity: Tools are independent and composable

• Security: Servers control what data the LLM can access

• Testability: Each tool can be tested independently

Architecture

┌─────────────────────────────────────────────────────────┐
│                        User                             │
│              "Show me the README"                        │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                    LLM / AI Model                       │
│         (Claude, GPT-4, or other MCP client)            │
│                                                         │
│  1. Understands user's question                         │
│  2. Decides which tool to use (get_readme)              │
│  3. Calls the tool via MCP protocol                     │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                  MCP Protocol                           │
│         (Standardized communication layer)              │
│                                                         │
│  - Tool discovery                                       │
│  - Parameter validation                                 │
│  - Request/Response formatting                          │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│              MCP Server (This Project)                   │
│                                                         │
│  Tools:                                                 │
│  - get_repo_info()                                      │
│  - list_files()                                         │
│  - read_file()                                          │
│  - search_code()                                        │
│  - get_readme()                                         │
│                                                         │
│  Uses GitHubClient to make API calls                    │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                  GitHub API                             │
│         (https://api.github.com)                        │
│                                                         │
│  - Repository metadata                                  │
│  - File contents                                        │
│  - Code search                                          │
└─────────────────────────────────────────────────────────┘

Available MCP Tools

Setup

Prerequisites

• Python 3.11 or higher

• pip (Python package manager)

• Git

• A GitHub account (optional, but recommended for full functionality)

Step 1: Clone the Repository

git clone https://github.com/your-username/github-mcp-assistant.git
cd github-mcp-assistant

Step 2: Create a Virtual Environment

# Windows
python -m venv venv
venv\Scripts\activate

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Configure Environment Variables

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and add your GitHub token:

   GITHUB_TOKEN=ghp_your_token_here

Step 5: Get a GitHub Token (Optional but Recommended)

1. Go to https://github.com/settings/tokens

2. Click "Generate new token (classic)"

3. Give it a name like "MCP Assistant"

4. Select scopes:

   • repo (for private repositories)

   • read:org (if accessing organization repos)

5. Click "Generate token"

6. Copy the token and paste it in your .env file

Note: You can use the server without a token for public repositories, but code search requires authentication.

Running the MCP Server

Option 1: Direct Python Execution

python -m server.server

The server will start and listen for MCP protocol messages on standard input/output (stdio).

Option 2: Using Docker

docker build -t github-mcp-assistant .
docker run -i -e GITHUB_TOKEN=your_token github-mcp-assistant

The -i flag is important - it keeps stdin open for the MCP protocol communication.

Connecting an MCP Client

Claude Desktop

1. Open Claude Desktop

2. Go to Settings → Developer

3. Click "Edit Config"

4. Add the server configuration:

{
  "mcpServers": {
    "github-assistant": {
      "command": "python",
      "args": ["-m", "server.server"],
      "cwd": "/path/to/github-mcp-assistant"
    }
  }
}

5. Restart Claude Desktop

6. The GitHub tools will be available when you start a new conversation

Custom MCP Client

If you're building a custom client, connect to the server via stdio and use the MCP protocol to:

1. Send initialize to start the connection

2. Send tools/list to discover available tools

3. Send tools/call to invoke a tool

Example Prompts

Once connected, try these prompts:

1. Get repository info: "Give me information about microsoft/vscode"

2. Show project structure: "Show me the project structure of facebook/react"

3. Read a specific file: "Read the main.py file in fastapi/fastapi"

4. Search for code: "Where is authentication implemented in django/django?"

5. Get the README: "Show me the README of torvalds/linux"

6. Understand a project: "Explain this repository to me: pallets/flask"

7. Compare files: "What's the difference between requirements.txt and setup.py in requests/requests?"

8. Find configuration: "Show me the configuration files in kubernetes/kubernetes"

Project Flow

When you ask: "Where is authentication implemented?"

┌─────────────────────────────────────────────────────────┐
│ 1. User asks: "Where is authentication implemented?"    │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 2. LLM understands the question and decides to          │
│    search for authentication-related code               │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 3. LLM calls search_code(owner, repo, "authentication") │
│    via MCP protocol                                     │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 4. MCP Server receives the request                      │
│    - Validates parameters                               │
│    - Calls GitHubClient.search_code()                   │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 5. GitHubClient makes HTTP request to GitHub API:       │
│    GET /search/code?q=authentication repo:owner/repo    │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 6. GitHub API returns search results                    │
│    - List of files containing "authentication"          │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 7. MCP Server formats results and returns to LLM        │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 8. LLM uses the results to answer the user:             │
│    "Authentication is implemented in:                   │
│     - src/auth.py                                       │
│     - src/login.py                                      │
│     - middleware/auth.py"                               │
└─────────────────────────────────────────────────────────┘

Security

Why the GitHub Token Should Never Be Committed

Your GitHub token is like a password - it gives access to your GitHub account. If committed to a public repository:

1. Anyone can see it - Even if you delete it later, it's in the git history

2. Automated bots scan for tokens - They'll find and use it within minutes

3. Your account is compromised - Attackers can access your repositories, create issues, delete code, etc.

4. You're responsible - GitHub may hold you accountable for any damage

Best Practices

• ✅ Store tokens in .env files (gitignored)

• ✅ Use environment variables

• ✅ Create tokens with minimal permissions

• ✅ Rotate tokens regularly

• ❌ Never hardcode tokens in source code

• ❌ Never commit .env files

• ❌ Never share tokens in chat or documentation

Testing

Run Unit Tests

# Activate virtual environment first
python -m pytest tests/ -v

Test Coverage

The tests cover:

• GitHub client initialization

• Repository information retrieval

• File listing

• File reading

• Code search

• README retrieval

• Error handling (404, 401, 403)

• Edge cases (empty results, directories vs files)

Project Structure

github-mcp-assistant/
│
├── server/
│   ├── __init__.py          # Package marker
│   ├── server.py            # MCP server with tool definitions
│   └── github_client.py     # GitHub API client (separated for testing)
│
├── tests/
│   ├── __init__.py          # Package marker
│   ├── test_github_client.py # Tests for GitHub API client
│   └── test_tools.py        # Tests for MCP tools
│
├── .env.example             # Environment variable template
├── .gitignore               # Git ignore rules
├── requirements.txt         # Python dependencies
├── Dockerfile               # Docker configuration
└── README.md                # This file

Future Improvements

Feature Enhancements

• Pull Request Analysis: Analyze PRs for code quality, review comments

• Issue Analysis: Search and analyze issues, track bugs

• Commit History: View recent commits, blame information

• Code Summarization: Use LLM to summarize code files

• Dependency Analysis: Analyze project dependencies

• Multiple Repository Support: Compare or analyze multiple repos

• Branch Comparison: Compare different branches

• Release Information: Get release notes and versions

Technical Improvements

• Caching: Cache GitHub API responses to reduce rate limit usage

• Pagination: Handle paginated API responses for large repositories

• Async Optimization: Improve async performance

• Logging: Add comprehensive logging

• Configuration: Add more configuration options

• Rate Limiting: Implement client-side rate limiting

Testing Improvements

• Integration Tests: Test against real GitHub API (with token)

• Performance Tests: Test with large repositories

• Edge Case Tests: More error scenarios

How to Explain This Project in an Interview

What is MCP?

"MCP stands for Model Context Protocol. It's a standardized way for LLMs to interact with external tools and data sources. Think of it as a universal adapter - instead of writing custom integrations for each LLM, you write one MCP server that works with any MCP-compatible client."

Why MCP Was Used

"I chose MCP because it solves the N×M problem. Without MCP, connecting N LLMs to M external services requires N×M custom integrations. With MCP, you write M servers and they work with any MCP-compatible LLM. This makes the code more maintainable, testable, and reusable."

What the MCP Server Does

"The MCP server exposes GitHub repository operations as tools. It has five main tools: get_repo_info, list_files, read_file, search_code, and get_readme. When an LLM needs to interact with GitHub, it calls these tools through the MCP protocol."

What Tools Were Created

"1. get_repo_info: Returns repository metadata like stars, forks, language 2. list_files: Shows the project structure by listing files and directories 3. read_file: Reads the content of a specific file 4. search_code: Searches for code matching a query across the repository 5. get_readme: Retrieves the README file content"

What Happens When a User Asks a Question

"When a user asks 'Where is authentication implemented?', the LLM:

1. Understands the question and decides to search for code

2. Calls the search_code tool via MCP with query='authentication'

3. The MCP server receives the request and calls GitHub's API

4. GitHub returns search results

5. The MCP server formats and returns results to the LLM

6. The LLM uses the results to provide a human-readable answer"

Why This Architecture Is Better

"This architecture is better than tightly coupled integration because:

1. Separation of Concerns: The GitHub logic is separate from the MCP protocol

2. Testability: Each component can be tested independently

3. Reusability: The MCP server works with any MCP-compatible LLM

4. Maintainability: Adding new tools doesn't require changing the LLM

5. Security: The server controls what data the LLM can access

6. Standardization: Uses a protocol that's becoming an industry standard"

Key Technical Decisions

• Separated GitHub client: Makes the code easier to test and maintain

• Async/await: Better performance for I/O-bound operations

• Type hints: Improves code readability and enables IDE support

• Environment variables: Secure configuration management

• Error handling: Graceful degradation with human-readable error messages

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Run tests to ensure they pass

6. Submit a pull request

License

This project is open source and available under the MIT License.

Acknowledgments

• MCP Protocol - The official MCP documentation

• FastMCP - The Python MCP SDK used in this project

• GitHub REST API - The API used for GitHub interactions