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+ MCP License: MIT

---

📋 Sumário

• Visão Geral
• Arquitetura
• Ferramentas (Tools)
• Instalação
• Configuração do GitHub Token
• Registrando o Servidor
• Uso
• Karpathy Skills Framework
• 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.

{
  "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.

{
  "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.

{
  "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.

{
  "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)

# 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

# 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

# Com uv
uv sync --extra dev

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

---

🔑 Configuração do GitHub Token

1. Acesse GitHub 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:

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

{
  "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:

{
  "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:

{
  "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:

{
  "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

# 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 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 para detalhes.