Skip to main content
Glama
technical-impact-analyst

technical-impact-analyst

by Gaells

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


📋 Sumário


Related MCP server: GitHub MCP Server

🔍 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.

Available Tools

8 tools
analyze_karpathy_alignmentA

Analyze GitHub contributions against the Andrej Karpathy Skills framework.

Returns scores (1-5) for five skill dimensions:

  • Building from Scratch: First-principles thinking and custom implementations

  • Attention to Detail: Tests, docs, descriptive commits, clean diffs

  • Deep Understanding: Root cause analysis, performance optimization, substantive reviews

  • Technical Clarity: Focused PRs, clear descriptions, code simplification

  • Problem Solving: Complex challenges, cross-cutting changes, effective solutions

Also detects "First Principles" indicators (Karpathy's emphasis on understanding things from scratch rather than relying on heavy abstractions).

Inputs: repo, since, until, username. Returns: result

detect_attention_to_detailA

Advanced attention-to-detail analysis with bonus scoring.

Checks:

  • README updated alongside API changes

  • CHANGELOG updated

  • Edge case tests (not just happy path)

  • Descriptive commit messages

  • Migrations included with schema changes

  • Environment variables documented

  • Type hints updated

Returns bonus points, anti-pattern flags (red/yellow), and checklist.

Inputs: repo, since, until, username. Returns: result

export_evolution_dataA

Export Karpathy skill evolution data for Spider Chart visualization.

Analyzes the last N weeks and returns scores for each dimension per week, plus trend analysis (improving/declining/stable).

Designed to feed the external Next.js Karpathy Dashboard.

Inputs: repo, weeks, username. Returns: result

generate_client_reportA

Generate a client-facing delivery report translating technical contributions into business value.

Designed for freelancers, MEI, and consultants who need to communicate value to non-technical stakeholders.

Returns a formatted Markdown report with:

  • Executive summary

  • Deliveries table with business impact

  • Impact highlights

  • Period metrics

Inputs: repo, since, until, username, +1 more. Returns: result

generate_weekly_impact_summaryA

Generate an executive weekly impact summary for stakeholders.

Consolidates the week's activities into a structured report including:

  • Executive paragraph summarizing contributions

  • Key achievements list

  • Karpathy Skills highlights

  • Metrics snapshot

  • Business value translations (technical → business language)

  • Spider chart data for visualization

Inputs: repo, username, week_offset. Returns: result

get_architecture_impactA

Identify contribution types (Feature, Refactor, Bug Fix) and assess their impact on codebase health.

For each PR, returns:

  • Classification: Feature, Refactor, Bug Fix, Performance, Documentation, Test, Chore

  • Impact level: critical, high, medium, low, trivial

  • Health delta: -1.0 (degradation) to +1.0 (improvement)

  • Complexity score: 0.0 to 1.0

  • First Principles detection: whether the contribution demonstrates building from scratch

Inputs: repo, since, until, username. Returns: result

get_contribution_metricsA

Retrieve raw GitHub contribution metrics filtered by time period.

Returns aggregated data including commits, PRs, reviews, and code changes. Useful for understanding contribution volume and patterns.

Inputs: repo, since, until, username. Returns: result

scan_first_principlesA

Scan contributions for first-principles thinking patterns.

Analyzes PRs looking for:

  • Dependency removals (package.json, requirements.txt, go.mod, etc.)

  • Custom implementations replacing external libraries

  • Utility/internal file additions

  • Root cause fixes vs band-aid patches

  • First-principles keywords in commit messages

Returns:

  • Abstraction Control Level (0.0-1.0)

  • Dependency Delta (negative = fewer deps = positive)

  • Root Fix Ratio (0.0-1.0)

  • Overall Score (1.0-5.0)

  • Detailed signals and evidence

Inputs: repo, since, until, username. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog


    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools have distinct purposes: metrics retrieval, skills alignment, architecture impact, first-principles scanning, attention-to-detail checking, and report generation. The two report generators (weekly summary vs client report) could be confused, but their descriptions clarify different audiences and content.

    Naming Consistency4/5

    All tool names follow a verb_noun pattern (export_, get_, analyze_, generate_, scan_, detect_). There is some variety in verbs (export, get, analyze, generate, scan, detect) but no mixing of naming conventions like camelCase or inconsistent styles, making the set predictable.

    Tool Count5/5

    Eight tools is well-scoped for a technical impact analysis server. Each tool covers a distinct aspect of analysis or reporting, and the count is neither too thin nor overloaded.

    Completeness4/5

    The tool surface covers the full workflow from raw metrics retrieval to specialized Karpathy skill analysis and report generation. Minor gaps exist, such as lacking a tool for directly comparing historical periods beyond export_evolution_data, but the core capabilities are present and well-integrated.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to analyze employee GitHub activity including PRs, code reviews, comments, and contributions across repositories with time-range filtering for performance assessment and impact analysis.
      6
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides GitHub repository analysis tools for Claude, including repo summaries, commit history, issue tracking, contributor stats, and code quality assessment. Enables natural language queries about code quality, contributor activity, and repository comparisons.
      -