🚀 GitInsight-MCP

https://github.com/user-attachments/assets/22716a0c-2dc6-4d00-a761-1fee7341afca

A Model Context Protocol (MCP) Server for GitHub Profile Integration

A learning project built to explore the Model Context Protocol (MCP) and MCP Inspector tool. This server provides GitHub profile integration and was entirely built in collaboration with Claude AI.

Author: Wael Marwani
Portfolio: marwaniwael.engineer
Email: wael.marwani@esprit.tn
Location: Ariana, Tunisia

🤖 Built with Claude AI - Every commit co-authored with Claude

🤖 What is MCP?

The Model Context Protocol (MCP) is an open protocol that enables AI assistants to securely connect to external data sources and tools. Think of it as a standardized way for AI models like Claude to interact with your applications and services.

Key Concepts:

MCP Server: Provides tools and data (this project!)
MCP Client: AI assistant that uses the tools (e.g., Claude Desktop)
Tools: Functions that the AI can call to perform actions
Protocol: Standardized communication format using JSON-RPC

GitInsight-MCP implements an MCP server that exposes your GitHub profile data to AI assistants, allowing them to answer questions about your repositories, analyze your coding patterns, and generate portfolio insights. I Built This Project

I created GitInsight-MCP to:

🔍 Explore the MCP Inspector - Wanted to see how MCP servers work and test them interactively
🛠️ Discover New MCP Tools - Learn about the Model Context Protocol ecosystem
🤖 Collaborate with Claude AI - Built entirely using Claude as a coding partner
📚 Learn by Doing - Hands-on experience with TypeScript, Node.js, and GitHub API
🚀 Create Something Useful - A practical tool that actually works with my GitHub profile

This is a learning project showcasing:

AI-Assisted Development - Every line of code written with Claude
Modern Backend Stack - TypeScript, Node.js, MCP SDK
Real API Integration - GitHub Octokit, caching, error handling
Production Quality - Full documentation, proper architecture

Perfect for:

Developers exploring MCP and AI-assisted coding
Learning how to build tools that AI assistants can use
Understanding the Model Context Protocol specification
DevOps Engineers wanting to showcase AI integration skills
Full Stack Developers building MCP servers
Anyone creating an intelligent portfolio assistant

✨ Features

🔧 Core Functionality

✅ 8 Powerful MCP Tools - From basic queries to advanced portfolio generation
✅ 3 MCP Resources - Readable developer profile, resume, and skills data
✅ 3 MCP Prompts - Pre-configured for recruiters and technical assessment
✅ Intelligent Caching - Reduces GitHub API calls and respects rate limits
✅ Rate Limit Protection - Automatic handling of GitHub API constraints
✅ Error Resilience - Comprehensive error handling with helpful messages
✅ TypeScript Safety - Full type coverage for reliability

🎯 Recruiter-Focused Features

📊 Skills Matrix - Automated technical skills assessment with proficiency levels
📄 Portfolio Summary - Professional candidate evaluation ready for HR
📝 Auto-Generated Resume - Markdown CV from GitHub data
🎤 Recruiter Prompts - Pre-built evaluation templates for hiring managers

📊 Data Insights

📦 Repository metadata (stars, forks, languages, topics)
📝 Commit history and activity tracking
📈 Aggregate statistics and analytics
🔍 Advanced filtering by technology, topic, or stars
📅 Contribution patterns and streaks
💼 Comprehensive skills categorization

🎨 Developer Experience

🚀 Easy setup with clear documentation
🔐 Secure token-based authentication
🎯 Clear error messages for debugging
📖 Comprehensive inline code comments
🧪 Production-ready architecture

🏗️ Architecture

┌─────────────────┐
│  Claude Desktop │  ← AI Assistant (MCP Client)
└────────┬────────┘
         │ MCP Protocol (JSON-RPC over stdio)
         ▼
┌─────────────────┐
│ GitInsight-MCP  │  ← This Server
│   MCP Server    │
└────────┬────────┘
         │
    ┌────┴────┬──────────┬─────────┐
    ▼         ▼          ▼         ▼
┌────────┐ ┌──────┐ ┌────────┐ ┌─────┐
│ GitHub │ │Cache │ │ Tools  │ │Error│
│ Client │ │Layer │ │Handler │ │ Mgmt│
└────┬───┘ └──────┘ └────────┘ └─────┘
     │
     ▼
┌─────────────────┐
│  GitHub API     │  ← Data Source
│  (Octokit)      │
└─────────────────┘

Flow:

User asks Claude a question about your GitHub profile
Claude calls GitInsight-MCP tools via MCP protocol
Server checks cache or queries GitHub API
Results are formatted and returned to Claude
Claude presents insights to the user in natural language

📦 Installation

Prerequisites

Node.js 18+ (Download)
npm or yarn
GitHub Personal Access Token (Create one)
Claude Desktop (optional, for testing) (Download)

Step 1: Clone the Repository

```bash git clone https://github.com/marwaniiwael18/GitInsight-MCP.git cd GitInsight-MCP ```

Step 2: Install Dependencies

```bash npm install ```

Step 3: Build the Project

```bash npm run build ```

⚙️ Configuration

Step 1: Create Environment File

Copy the example environment file:

```bash cp .env.example .env ```

Step 2: Configure Environment Variables

Edit `.env` with your details:

```env

GitHub Personal Access Token

Generate at: https://github.com/settings/tokens

Required scopes: repo, read:user

GITHUB_TOKEN=ghp_your_actual_token_here

Your GitHub Username

GITHUB_USERNAME=marwaniiwael18

Cache Settings (optional)

CACHE_TTL_SECONDS=3600 CACHE_CHECK_PERIOD_SECONDS=600 ```

Creating a GitHub Token:

Go to GitHub Settings → Tokens
Click "Generate new token (classic)"
Select scopes: `repo`, `read:user`, `read:org`
Copy the token and paste it in your `.env` file

Step 3: Configure Claude Desktop

Add this to your Claude Desktop config file:

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

```json { "mcpServers": { "gitinsight-mcp": { "command": "node", "args": [ "/absolute/path/to/GitInsight-MCP/dist/index.js" ], "env": { "GITHUB_TOKEN": "your_github_token_here", "GITHUB_USERNAME": "marwaniiwael18" } } } } ```

Important: Replace `/absolute/path/to/` with the actual path to your project!

🚀 Usage

Running the Server Standalone

```bash npm start ```

You should see: ```

GitInsight MCP Server - Starting...

GitHub User: marwaniiwael18 Cache TTL: 3600 seconds Tools Available: 6

GitHub API Rate Limit: 5000/5000 Server ready! Waiting for MCP client connections...

```

Using with Claude Desktop

Restart Claude Desktop after configuration
Start a new conversation
Ask questions about your GitHub profile!

The server will automatically start when Claude needs it.

🛠️ Available Tools

1️⃣ `list_repositories`

Lists all your public repositories with metadata.

Parameters:

`use_cache` (boolean): Use cached data (default: true)
`sort_by` (string): Sort by 'stars', 'forks', 'updated', 'name'
`limit` (number): Maximum repositories to return

Returns: Array of repositories with name, description, stars, forks, language, topics, etc.

2️⃣ `get_repository_details`

Get detailed information about a specific repository.

Parameters:

`repository_name` (string, required): Repository name
`use_cache` (boolean): Use cached data
`include_readme` (boolean): Include README content

Returns: Full repository details, topics, README (if requested)

3️⃣ `get_recent_commits`

Fetch recent commits for a repo or across all repos.

Parameters:

`repository_name` (string, optional): Specific repo or all repos
`limit` (number): Max commits to return (default: 50)
`use_cache` (boolean): Use cached data

Returns: Array of commits with SHA, message, author, date, URL

4️⃣ `get_repository_stats`

Calculate aggregate statistics across all repositories.

Parameters:

`use_cache` (boolean): Use cached data

Returns:

Total repositories, stars, forks
Language breakdown with percentages
Most starred/forked repos
Recently updated repos
Total open issues

5️⃣ `search_projects_by_tech`

Search and filter repositories by technology.

Parameters:

`language` (string): Filter by language (e.g., "Python", "JavaScript")
`topic` (string): Filter by topic (e.g., "devops", "ai")
`min_stars` (number): Minimum stars required
`sort_by` (string): Sort field
`order` (string): 'asc' or 'desc'

Returns: Filtered and sorted repositories

6️⃣ `get_contribution_activity`

Analyze contribution activity and patterns.

Parameters:

`use_cache` (boolean): Use cached data

Returns:

Total commits
Repositories contributed to
Most active day
Contribution streak

7️⃣ `get_skills_matrix` 🎯 FOR RECRUITERS

Generate a comprehensive technical skills assessment matrix.

Parameters:

`use_cache` (boolean): Use cached data

Returns:

Developer profile summary
Categorized technical skills (Languages, DevOps, Cloud)
Proficiency levels (Expert/Advanced/Intermediate/Beginner)
Domain expertise breakdown (DevOps, Web Dev, AI/ML, etc.)
Top languages with percentages
Project counts per skill

Perfect for: HR screening, technical assessment, candidate evaluation

8️⃣ `generate_portfolio_summary` 📄 FOR RECRUITERS

Create a recruiter-friendly professional portfolio summary.

Parameters:

`use_cache` (boolean): Use cached data

Returns:

Candidate profile (name, title, contact, location)
Professional summary paragraph
Key achievements list
Featured projects with highlights and technologies
Technical proficiency breakdown
GitHub metrics (repos, stars, contributions, streak)
Availability status

Perfect for: Initial screening, candidate presentation, hiring decisions

📚 MCP Resources

Resources are readable data endpoints that AI assistants can access:

Resource: `portfolio://profile`

Developer profile with contact information and specializations (JSON)

Resource: `portfolio://resume`

Auto-generated professional resume from GitHub data (Markdown)

Resource: `portfolio://skills`

Complete skills matrix with proficiency assessment (JSON)

Usage Example: Ask Claude: "Read my portfolio profile" or "Show me my resume"

🎤 MCP Prompts

Pre-configured prompt templates for common scenarios:

Prompt: `recruiter_evaluation`

🎯 Comprehensive candidate evaluation for HR and recruiters
Combines portfolio summary, skills matrix, stats, and activity into a hiring recommendation

Prompt: `technical_assessment`

🔧 Deep technical analysis for engineering managers
Analyzes code quality, tech stack depth, and suggests interview questions

Prompt: `portfolio_showcase`

💼 Impressive portfolio presentation
Creates a compelling narrative highlighting achievements and value proposition

Usage Example: In Claude Desktop or MCP Inspector, select a prompt to execute the evaluation automatically

💬 Example Queries

Try asking Claude these questions:

For Developers:

"What are my most starred repositories?"

"Show me statistics about my GitHub profile"

"What programming languages do I use most?"

For Project Discovery:

"Find all my DevOps projects"

"Show me my Python projects with the most stars"

"What are my recent AI/ML repositories?"

For Recruiters & HR: 🎯

"Generate a portfolio summary for this candidate"

"Show me the skills matrix with proficiency levels"

"Read the portfolio resume"

"Use the recruiter_evaluation prompt"

"What are this developer's key strengths?"

For Activity Tracking:

"What have I been working on recently?"

"Show my commit activity for the last month"

"What's my contribution streak?"

For Detailed Analysis:

"Give me details about my DEVOPS-Project repository"

"Analyze my AWS-App project and tell me about it"

"Generate a technical assessment for hiring managers"

👨‍💻 Development

Scripts

```bash

Build TypeScript

npm run build

Development mode (watch for changes)

npm run dev

Run the server

npm start

Test with MCP Inspector

npm run inspector ```

MCP Inspector

Test your server with the official MCP Inspector:

```bash npm run inspector ```

This opens a web interface to test your tools interactively.

📁 Project Structure

``` GitInsight-MCP/ ├── src/ │ ├── index.ts # MCP server entry point │ ├── config.ts # Environment configuration │ ├── github-client.ts # GitHub API wrapper (Octokit) │ ├── cache.ts # Caching service │ ├── utils.ts # Helper functions │ ├── types/ │ │ └── index.ts # TypeScript type definitions │ └── tools/ │ ├── index.ts # Tools barrel export │ ├── list-repositories.ts │ ├── get-repository-details.ts │ ├── get-recent-commits.ts │ ├── get-repository-stats.ts │ ├── search-projects-by-tech.ts │ └── get-contribution-activity.ts ├── dist/ # Compiled JavaScript ├── .env # Environment variables (create this) ├── .env.example # Environment template ├── package.json # Dependencies ├── tsconfig.json # TypeScript config ├── claude-desktop-config.json # Example Claude config └── README.md # This file ```

🔧 Technical Stack

| Technology | Purpose | |------------|---------| | TypeScript | Type-safe development | | Node.js | Runtime environment | | @modelcontextprotocol/sdk | MCP protocol implementation | | @octokit/rest | GitHub API client | | node-cache | In-memory caching | | dotenv | Environment configuration |

🐛 Troubleshooting

Issue: "Missing required environment variables"

Solution: Create a `.env` file with `GITHUB_TOKEN` and `GITHUB_USERNAME`

Issue: "GitHub API rate limit exceeded"

Solution:

Wait for the rate limit to reset (shown in server logs)
Use caching (`use_cache: true`)
Authenticate with a valid token (increases limit to 5000/hour)

Issue: "Invalid GitHub token"

Solution:

Generate a new token at https://github.com/settings/tokens
Ensure scopes include: `repo`, `read:user`
Check for typos in your `.env` file

Issue: Claude Desktop doesn't show the server

Solution:

Check the config file path is correct for your OS
Use absolute paths in `claude_desktop_config.json`
Restart Claude Desktop completely
Check Claude Desktop logs for errors

Issue: Server crashes on startup

Solution:

Run `npm run build` first
Check Node.js version is 18+
Verify all dependencies installed: `npm install`

🤝 Contributing

Contributions are welcome! Feel free to:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🌟 Showcase

Featured Projects Highlighted by GitInsight-MCP:

AWS-App - Skill-sharing platform (JavaScript)
Application_Web_Distibue - Microservices architecture (Spring Boot + Angular)
DEVOPS-Project - CI/CD pipeline (Jenkins, Docker)
Car-Number-Plates-Detection-IA-Model - Computer Vision (OpenCV)
Parkini - Smart parking with face recognition
SentinelX-Diagnostic-Platform - Recent diagnostic platform

📞 Contact

Wael Marwani
📧 Email: wael.marwani@esprit.tn
🌐 Portfolio: marwaniwael.engineer
💼 GitWhat I Learned

Building this project with Claude taught me:

MCP Protocol Implementation - How to build servers for AI assistants
MCP Inspector Usage - Testing and debugging MCP tools interactively
AI-Assisted Development - Collaborating with Claude to write production code
RESTful API Integration - GitHub API via Octokit
Caching Strategies - Performance optimization techniques
Error Handling - Building resilient systems
TypeScript Best Practices - Type safety and modern JavaScript
Git Collaboration - Using co-authored commits with AI

🤝 Development Process

This entire project was built using Claude AI:

✅ All code written through Claude conversations
✅ Every commit co-authored: Co-authored-by: claude <noreply@anthropic.com>
✅ Architecture designed collaboratively
✅ Documentation generated with AI assistance
✅ Debugging and testing done together

Why this matters: Demonstrates how AI can be a powerful coding partner for learning and building real projects.

Built with ❤️ and 🤖 by Wael Marwani & Claude
A collaboration between human curiosity and AI assistance

⭐ Star this repo if you're interested in MCP or AI-assisted development

Built with ❤️ by Wael Marwani
Showcasing DevOps expertise through AI integration

⭐ Star this repo if you find it useful!

🚀 GitInsight-MCP

📋 Table of Contents

🤖 What is MCP?

✨ Features

🔧 Core Functionality

🎯 Recruiter-Focused Features

📊 Data Insights

🎨 Developer Experience

🏗️ Architecture

📦 Installation

Prerequisites

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Build the Project

⚙️ Configuration

Step 1: Create Environment File

Step 2: Configure Environment Variables

GitHub Personal Access Token

Generate at: https://github.com/settings/tokens

Required scopes: repo, read:user

Your GitHub Username

Cache Settings (optional)

Step 3: Configure Claude Desktop

🚀 Usage

Running the Server Standalone

You should see: ```

GitInsight MCP Server - Starting...

GitHub User: marwaniiwael18 Cache TTL: 3600 seconds Tools Available: 6

GitHub API Rate Limit: 5000/5000 Server ready! Waiting for MCP client connections...

Using with Claude Desktop

🛠️ Available Tools

1️⃣ `list_repositories`

2️⃣ `get_repository_details`

3️⃣ `get_recent_commits`

4️⃣ `get_repository_stats`

5️⃣ `search_projects_by_tech`

6️⃣ `get_contribution_activity`

7️⃣ `get_skills_matrix` 🎯 FOR RECRUITERS

8️⃣ `generate_portfolio_summary` 📄 FOR RECRUITERS

📚 MCP Resources

Resource: `portfolio://profile`

Resource: `portfolio://resume`

Resource: `portfolio://skills`

🎤 MCP Prompts

Prompt: `recruiter_evaluation`

Prompt: `technical_assessment`

Prompt: `portfolio_showcase`

💬 Example Queries

👨‍💻 Development

Scripts

Build TypeScript

Development mode (watch for changes)

Run the server

Test with MCP Inspector

MCP Inspector

📁 Project Structure

🔧 Technical Stack

🐛 Troubleshooting

Issue: "Missing required environment variables"

Issue: "GitHub API rate limit exceeded"

Issue: "Invalid GitHub token"

Issue: Claude Desktop doesn't show the server

Issue: Server crashes on startup

🤝 Contributing

📄 License

🌟 Showcase

📞 Contact

🤝 Development Process

⭐ Star this repo if you're interested in MCP or AI-assisted development

Install Package (if required)

Cursor configuration (mcp.json)