GitHub DevTools MCP Server

A production-grade Model Context Protocol (MCP) server that gives AI assistants like Claude Desktop, Cursor, and VS Code Copilot the ability to interact with GitHub and perform AI-powered code analysis — directly as native tool calls.

What is MCP?

Model Context Protocol is an open standard by Anthropic that lets AI assistants call external tools natively. Instead of copying data between apps, the AI calls your tools directly over stdio — no REST API, no HTTP server, no endpoints.

This project implements an MCP server that exposes 16 tools across 5 categories: GitHub data retrieval, AI-powered code analysis, hybrid GitHub+AI workflows, agentic multi-step orchestration, and cache management.

Why This Project?

Most AI tools are simple API wrappers. This project goes further:

• Agentic orchestration — One tool chains 5 parallel API calls, handles partial failures, and feeds aggregated data to AI for reasoning
• Structured AI output — Gemini responses are validated against Pydantic schemas, not just trusted as free-text
• Production patterns — TTL caching, graceful error handling, 33 mocked tests, CI/CD pipeline

Project Structure

github-dev-tools-mcp/
├── src/github_mcp/
│   ├── server.py          # MCP server + 16 tool registrations
│   ├── github_client.py   # Async GitHub API functions (httpx)
│   ├── ai_tools.py        # Gemini AI functions with structured output
│   ├── models.py          # Pydantic models for AI response validation
│   └── cache.py           # TTL cache decorator for API responses
├── tests/
│   ├── test_github_client.py   # GitHub API tests (mocked with respx)
│   ├── test_ai_tools.py        # AI tool tests (mocked Gemini)
│   ├── test_server.py          # Tool registration + orchestration tests
│   └── test_cache.py           # Cache behavior tests
├── .github/workflows/ci.yml    # GitHub Actions CI (Python 3.11-3.13)
├── DESIGN.md              # Architecture & design decisions
├── pyproject.toml         # Dependencies + build config
└── .env.example           # Required API keys template

Tools (16 total)

GitHub Tools (7)

These call the GitHub REST API directly. All responses are cached with TTL.

AI-Powered Tools (3)

These use Gemini Flash for analysis. Code review returns structured JSON validated by Pydantic.

Hybrid Tools (3) — GitHub + AI

These fetch real data from GitHub, then send it to Gemini for AI-powered analysis.

Agentic Tool (1) — Multi-Step Orchestration

This is the flagship tool. It demonstrates agentic AI patterns: parallel execution, data aggregation, partial failure handling, and AI reasoning over multiple data sources.

Health check output includes:

• 5 scored dimensions (1-10 each): Overall, Maintenance, CI/CD, Documentation, Community
• Identified risks with severity levels and actionable recommendations
• Executive summary of repository health

Utility Tools (2)

Key Technical Decisions

Setup

Prerequisites

• Python 3.11 or higher
• A GitHub Personal Access Token (create one here)
• A Gemini API Key (get one here)

Installation

git clone https://github.com/yashgarg4/GitHub-DevTools-MCP-Server.git
cd GitHub-DevTools-MCP-Server
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

pip install -e .

Environment Variables

cp .env.example .env

Edit .env and add your keys:

GITHUB_TOKEN=ghp_your_personal_access_token_here
GEMINI_API_KEY=your_gemini_api_key_here

• GITHUB_TOKEN: Needs repo scope for creating issues. Read-only tools work without a token (with lower rate limits).
• GEMINI_API_KEY: Required only for AI-powered tools. GitHub-only tools work without it.

Connecting to AI Assistants

Claude Desktop

Add to your config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "github-dev-tools": {
      "command": "/absolute/path/to/.venv/Scripts/python.exe",
      "args": ["-m", "github_mcp.server"],
      "cwd": "/absolute/path/to/GitHub-DevTools-MCP-Server",
      "env": {
        "GITHUB_TOKEN": "your_token_here",
        "GEMINI_API_KEY": "your_key_here"
      }
    }
  }
}

VS Code (Workspace-level)

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "github-dev-tools": {
      "command": "/absolute/path/to/.venv/Scripts/python.exe",
      "args": ["-m", "github_mcp.server"],
      "cwd": "/absolute/path/to/GitHub-DevTools-MCP-Server",
      "env": {
        "GITHUB_TOKEN": "your_token_here",
        "GEMINI_API_KEY": "your_key_here"
      }
    }
  }
}

VS Code (User-level — available in all projects)

Open Settings JSON (Ctrl+Shift+P > "Preferences: Open User Settings (JSON)"):

{
  "mcp": {
    "servers": {
      "github-dev-tools": {
        "command": "/absolute/path/to/.venv/Scripts/python.exe",
        "args": ["-m", "github_mcp.server"],
        "cwd": "/absolute/path/to/GitHub-DevTools-MCP-Server",
        "env": {
          "GITHUB_TOKEN": "your_token_here",
          "GEMINI_API_KEY": "your_key_here"
        }
      }
    }
  }
}

Note: Replace all paths with absolute paths to your installation. Use forward slashes even on Windows.

Testing with MCP Inspector

Test tools interactively without any AI assistant:

npx @modelcontextprotocol/inspector .venv/Scripts/python -m github_mcp.server

This opens a browser UI at http://localhost:5173 where you can select any tool, fill in inputs, and see results. Requires Node.js.

Example Prompts

Once connected to an AI assistant, try these:

GitHub Tools:

• "Get info about the python/cpython repository"
• "List open PRs on facebook/react"
• "Show me the open issues on expressjs/express"
• "Get the profile of torvalds on GitHub"
• "Compare the v3.12.0 and v3.13.0 tags on python/cpython"
• "Show me the recent GitHub Actions runs for actions/toolkit"
• "Create an issue on my-org/my-repo titled 'Fix login bug' with the label 'bug'"

AI Tools:

• "Review this Python code for bugs: def add(a, b): return a - b"
• "Generate a commit message for: added dark mode toggle to settings page"
• "Analyze this code and generate a bug report issue for it: def divide(a, b): return a / b"

Hybrid Tools (GitHub + AI):

• "Review PR #123 on my-org/my-repo"
• "Explain what the expressjs/express repository is about"
• "Generate release notes for python/cpython between v3.12.0 and v3.13.0"

Agentic Tools:

• "Run a full health check on python/cpython"
• "How healthy is the expressjs/express repository?"

Utility:

• "Clear the cache"
• "Show me cache stats"

Running Tests

All 33 tests run without API keys — every external call is mocked:

pip install -e ".[dev]"
python -m pytest tests/ -v

Test coverage:

Architecture

See DESIGN.md for detailed documentation on:

• Why MCP over REST
• Tool taxonomy (Pure GitHub / Pure AI / Hybrid / Agentic)
• Data flow diagrams
• Structured output strategy (Pydantic + JSON schema injection + graceful fallback)
• Prompt engineering approach (persona, few-shot, temperature tuning)
• Caching strategy (per-function TTLs, decorator pattern)
• Error handling (3-layer strategy — tools never crash)
• Testing strategy (respx for HTTP, mock for AI)

Tech Stack