# 🎯 MCP GitHub PR — Technical Impact Analyst

> **Servidor MCP (Model Context Protocol)** que analisa suas contribuições no GitHub e as mapeia contra o framework de competências do **Andrej Karpathy Skills**.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 📋 Sumário

- [Visão Geral](#-visão-geral)
- [Arquitetura](#-arquitetura)
- [Ferramentas (Tools)](#-ferramentas-tools)
- [Instalação](#-instalação)
- [Configuração do GitHub Token](#-configuração-do-github-token)
- [Registrando o Servidor](#-registrando-o-servidor)
- [Uso](#-uso)
- [Karpathy Skills Framework](#-karpathy-skills-framework)
- [Stack Técnica](#-stack-técnica)

---

## 🔍 Visão Geral

Este servidor MCP atua como um **Analista de Impacto Técnico**, conectando-se à API GraphQL do GitHub para:

1. **Extrair** contribuições (Commits, PRs, Reviews) de um usuário
2. **Analisar** o conteúdo contra o framework Karpathy Skills
3. **Classificar** o tipo e impacto arquitetural de cada contribuição
4. **Gerar** relatórios executivos semanais com tradução técnico → negócio

### Os 5 Pilares do Karpathy Skills

| Dimensão | Descrição | Karpathy Principle |
|---|---|---|
| 🏗️ **Building from Scratch** | Soluções from first principles, substituição de deps pesadas | Goal-Driven Execution |
| 🔍 **Attention to Detail** | Testes, docs, commits descritivos, diffs cirúrgicos | Surgical Changes |
| 🧠 **Deep Understanding** | Root cause analysis, otimização na camada certa | Think Before Coding |
| ✨ **Technical Clarity** | Código simples, PRs focados, 50 linhas > 200 linhas | Simplicity First |
| 🧩 **Problem Solving** | Desafios complexos, tradeoffs, soluções verificáveis | Goal-Driven Execution |

---

## 🏛️ Arquitetura

O projeto segue **Clean Architecture** com separação clara de camadas:

```
mcp-github-pr/
├── server.py                          # 🚀 Entrypoint do servidor MCP
├── pyproject.toml                     # Configuração do projeto
├── .env.example                       # Template de variáveis de ambiente
│
├── src/
│   ├── domain/                        # 🟢 CAMADA DE DOMÍNIO
│   │   ├── entities.py                #   Entidades: Commit, PR, Review
│   │   ├── karpathy_skills.py         #   Modelo: Skills, Scores, Alignment
│   │   └── interfaces.py             #   Contratos: GitHubClient, Cache
│   │
│   ├── use_cases/                     # 🔵 CAMADA DE CASOS DE USO
│   │   ├── get_contribution_metrics.py
│   │   ├── analyze_karpathy_alignment.py
│   │   ├── get_architecture_impact.py
│   │   └── generate_weekly_summary.py
│   │
│   └── infrastructure/                # 🟠 CAMADA DE INFRAESTRUTURA
│       ├── github_client.py           #   Cliente GitHub GraphQL + REST
│       └── database.py               #   Cache SQLite com aiosqlite
│
└── data/                              # Cache SQLite (gitignored)
    └── cache.db
```

### Fluxo de Dependências

```
Domain ← Use Cases ← Infrastructure ← Server (MCP)
  │          │              │
  │          │              ├── GitHubClient (httpx)
  │          │              └── SQLiteCache (aiosqlite)
  │          │
  │          ├── GetContributionMetrics
  │          ├── AnalyzeKarpathyAlignment
  │          ├── GetArchitectureImpact
  │          └── GenerateWeeklyImpactSummary
  │
  ├── Entities (Commit, PR, Review)
  ├── KarpathySkills (SkillCategory, SkillScore)
  └── Interfaces (ABCs)
```

---

## 🛠️ Ferramentas (Tools)

### 1. `get_contribution_metrics`

Retorna dados brutos de contribuição filtrados por período.

```json
{
  "username": "choqs",
  "period": "2025-04-01 → 2025-04-30",
  "total_commits": 47,
  "total_prs": 12,
  "total_reviews": 8,
  "prs_merged": 10,
  "prs_with_tests": 7,
  "total_additions": 3421,
  "total_deletions": 1205,
  "repositories": ["org/api", "org/frontend"]
}
```

### 2. `analyze_karpathy_alignment`

Analisa contribuições e retorna scores 1-5 por dimensão com evidências.

```json
{
  "overall_score": 3.8,
  "scores": {
    "Building from Scratch": {
      "score": 4,
      "level": "Proficient",
      "evidence": ["PR #42: 'Implement custom auth from scratch'"],
      "suggestions": []
    },
    "Attention to Detail": {
      "score": 3,
      "level": "Competent",
      "evidence": ["70% of PRs include test updates"],
      "suggestions": ["Update README/docs alongside code changes"]
    }
  },
  "spider_chart_data": {
    "Building from Scratch": 4,
    "Attention to Detail": 3,
    "Deep Understanding": 4,
    "Technical Clarity": 4,
    "Problem Solving": 3
  },
  "first_principles_indicators": [
    "PR #42: Replaced dependency with custom implementation"
  ]
}
```

### 3. `get_architecture_impact`

Classifica contribuições e avalia impacto na saúde do código.

```json
{
  "impacts": [
    {
      "pr_number": 42,
      "contribution_type": "refactor",
      "impact_level": "high",
      "health_delta": 0.50,
      "complexity_score": 0.67,
      "first_principles": {
        "detected": true,
        "explanation": "Removed unnecessary abstraction layer"
      }
    }
  ]
}
```

### 4. `generate_weekly_impact_summary`

Consolida atividades da semana em um relatório executivo.

```json
{
  "executive_summary": "During the week of May 05 to May 11, 2025...",
  "key_achievements": [
    "Merged 5 pull request(s) across 2 repositories",
    "3 PR(s) included test coverage updates"
  ],
  "business_value_translations": [
    "Improved code maintainability and reduced technical debt",
    "Delivered new functionality expanding product capabilities"
  ],
  "spider_chart_data": { ... }
}
```

---

## 📦 Instalação

### Pré-requisitos

- **Python 3.10+**
- **uv** (recomendado) ou **pip**

### Com `uv` (Recomendado)

```bash
# Clonar o repositório
git clone https://github.com/seu-usuario/mcp-github-pr.git
cd mcp-github-pr

# Instalar dependências
uv sync

# Copiar e configurar variáveis de ambiente
cp .env.example .env
# Edite o .env com seu GITHUB_TOKEN e GITHUB_USERNAME
```

### Com `pip`

```bash
# Clonar o repositório
git clone https://github.com/seu-usuario/mcp-github-pr.git
cd mcp-github-pr

# Criar virtual environment
python -m venv .venv

# Ativar (Windows)
.venv\Scripts\activate

# Ativar (Linux/Mac)
source .venv/bin/activate

# Instalar dependências
pip install -e .

# Configurar ambiente
cp .env.example .env
```

### Dependências de Desenvolvimento

```bash
# Com uv
uv sync --extra dev

# Com pip
pip install -e ".[dev]"
```

---

## 🔑 Configuração do GitHub Token

1. Acesse [GitHub Settings → Tokens](https://github.com/settings/tokens)
2. Clique em **"Generate new token (classic)"**
3. Selecione os escopos (scopes):
   - ✅ `repo` — Acesso completo a repositórios
   - ✅ `read:user` — Leitura de perfil do usuário
   - ✅ `read:org` — Leitura de organizações (se necessário)
4. Copie o token gerado
5. Configure no arquivo `.env`:

```env
GITHUB_TOKEN=ghp_seu_token_aqui
GITHUB_USERNAME=seu_username
```

> ⚠️ **Nunca commite o arquivo `.env`!** Ele já está no `.gitignore`.

---

## 🔌 Registrando o Servidor

### Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop (`claude_desktop_config.json`):

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

```json
{
  "mcpServers": {
    "technical-impact-analyst": {
      "command": "uv",
      "args": ["run", "--directory", "D:\\dev\\mcp-github-pr", "python", "server.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_seu_token",
        "GITHUB_USERNAME": "seu_username"
      }
    }
  }
}
```

**Alternativa com pip/python:**

```json
{
  "mcpServers": {
    "technical-impact-analyst": {
      "command": "D:\\dev\\mcp-github-pr\\.venv\\Scripts\\python.exe",
      "args": ["D:\\dev\\mcp-github-pr\\server.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_seu_token",
        "GITHUB_USERNAME": "seu_username"
      }
    }
  }
}
```

### Cursor

Adicione ao arquivo `.cursor/mcp.json` na raiz do seu projeto:

```json
{
  "mcpServers": {
    "technical-impact-analyst": {
      "command": "uv",
      "args": ["run", "--directory", "D:\\dev\\mcp-github-pr", "python", "server.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_seu_token",
        "GITHUB_USERNAME": "seu_username"
      }
    }
  }
}
```

### Antigravity

Configure nas settings do Antigravity, seção MCP Servers:

```json
{
  "technical-impact-analyst": {
    "command": "uv",
    "args": ["run", "--directory", "D:\\dev\\mcp-github-pr", "python", "server.py"],
    "env": {
      "GITHUB_TOKEN": "ghp_seu_token",
      "GITHUB_USERNAME": "seu_username"
    }
  }
}
```

### Teste Manual

```bash
# Rodar o servidor diretamente (modo stdio)
cd D:\dev\mcp-github-pr
uv run python server.py

# Ou com o MCP Inspector
uv run fastmcp dev inspector server.py
```

---

## 💡 Uso

Uma vez registrado, você pode invocar as ferramentas diretamente no chat:

### Exemplos de Prompts

```
"Mostre minhas métricas de contribuição do último mês"

"Analise meu alinhamento com o Karpathy Skills framework nos últimos 7 dias"

"Qual foi o impacto arquitetural das minhas contribuições no repositório org/api?"

"Gere um resumo executivo da minha semana para stakeholders"

"Compare meu Karpathy Score desta semana com a semana passada"
```

---

## 🧠 Karpathy Skills Framework

O framework é baseado nas observações de [Andrej Karpathy](https://x.com/karpathy/status/2015883857489522876) sobre pitfalls de engenharia de software, estruturado em 4 princípios:

### 1. Think Before Coding
> "Don't assume. Don't hide confusion. Surface tradeoffs."

Mapeado para: **Deep Understanding** + **Problem Solving**

### 2. Simplicity First
> "Minimum code that solves the problem. Nothing speculative."

Mapeado para: **Technical Clarity**

### 3. Surgical Changes
> "Touch only what you must. Clean up only your own mess."

Mapeado para: **Attention to Detail**

### 4. Goal-Driven Execution
> "Define success criteria. Loop until verified."

Mapeado para: **Building from Scratch** + **Problem Solving**

### Como o Score é Calculado

Cada dimensão é avaliada com heurísticas baseadas em:

| Sinal | Dimensão Afetada | Efeito |
|---|---|---|
| PRs com testes | Attention to Detail | +1 se >80% |
| Commits descritivos | Attention to Detail | +1 se >70% |
| PRs com docs atualizados | Attention to Detail | +1 se >50% |
| `root cause` no commit msg | Deep Understanding | +1 se ≥2 |
| Reviews substantivos | Deep Understanding | +1 se ≥3 |
| PR size < 200 linhas | Technical Clarity | +1 |
| Ratio deletions/additions | Technical Clarity | Evidência |
| First-principles patterns | Build from Scratch | +1/+2 |
| PRs 500+ linhas | Build from Scratch | +1 |
| Cross-cutting changes (5+ files) | Problem Solving | +1 |
| Merge rate ≥80% | Problem Solving | Evidência |

---

## 🔧 Stack Técnica

| Tecnologia | Propósito |
|---|---|
| **Python 3.10+** | Runtime |
| **FastMCP** | SDK do Model Context Protocol |
| **httpx** | HTTP client assíncrono |
| **aiosqlite** | Cache SQLite assíncrono |
| **Pydantic** | Validação de dados |
| **python-dotenv** | Variáveis de ambiente |
| **mypy** | Type checking estrito |
| **ruff** | Linter + formatter |
| **pytest** | Testing |

---

## 📄 Licença

MIT License — veja [LICENSE](LICENSE) para detalhes.