MCP Servers

ๆจกๅž‹ไธŠไธ‹ๆ–‡ๅ่ฎฎๆœๅŠกๅ™จใ€ๆก†ๆžถใ€SDK ๅ’Œๆจกๆฟ็š„็ปผๅˆ็›ฎๅฝ•ใ€‚

G
Gitinsight MCP
ไฝœ่€… @marwaniiwael18
GitHub ไป“ๅบ“(1 ๆ˜Ÿๆ ‡)

๐Ÿš€ An MCP server that connects AI assistants to GitHub, providing intelligent insights into repositories, commits, and developer activity. Built to showcase modern AI integration patterns.

ๅˆ›ๅปบไบŽ 12/12/2025
ๆ›ดๆ–ฐไบŽ 3 days ago
README
View Source
Repository documentation and setup instructions

๐Ÿš€ GitInsight-MCP

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

.

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

TypeScript MCP License: MIT GitHub Built with Claude

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

๐Ÿ“‹ Table of Contents

๐Ÿค– 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:

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

๐Ÿ“ฆ Installation

Prerequisites

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:

  1. Go to GitHub Settings โ†’ Tokens
  2. Click "Generate new token (classic)"
  3. Select scopes: `repo`, `read:user`, `read:org`
  4. 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

  1. Restart Claude Desktop after configuration
  2. Start a new conversation
  3. 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:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. 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!

ๅฟซ้€Ÿ่ฎพ็ฝฎ
ๆญคๆœๅŠกๅ™จ็š„ๅฎ‰่ฃ…ๆŒ‡ๅ—

ๅฎ‰่ฃ…ๅŒ… ๏ผˆๅฆ‚ๆžœ้œ€่ฆ๏ผ‰

npx @modelcontextprotocol/server-gitinsight-mcp

Cursor ้…็ฝฎ (mcp.json)

{ "mcpServers": { "marwaniiwael18-gitinsight-mcp": { "command": "npx", "args": [ "marwaniiwael18-gitinsight-mcp" ] } } }