GitHub仓库管理工具

git clone https://github.com/AlexAlonsoMontero/mcp-py-github.git
cd mcp-py-github

# Crear entorno virtual
python3 -m venv .venv

# Activarlo
source .venv/bin/activate
# En Windows: .venv\Scripts\activate

# Verificar activación
which python  # Debe mostrar ruta dentro de .venv

pip install --upgrade pip
pip install -r requirements.txt

cp .env.example .env
# Editar .env con tu token real
nano .env  # macOS/Linux
# o notepad .env  # Windows

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
LOG_LEVEL=info
MCP_SERVER_NAME=github-manager

python3 -c "
import os
from dotenv import load_dotenv
from github import Github

load_dotenv()
token = os.getenv('GITHUB_TOKEN')
if token:
    gh = Github(token)
    user = gh.get_user()
    print(f'✅ Conectado como: {user.login}')
    print(f'📊 Repositorios: {user.get_repos().totalCount}')
else:
    print('❌ GITHUB_TOKEN no encontrado en .env')
"

python src/main.py

# Salida esperada:
# 2025-02-08 14:30:45 - INFO - FastMCP Server starting...
# 2025-02-08 14:30:45 - INFO - Connected as: AlexAlonsoMontero
# 2025-02-08 14:30:46 - INFO - Server ready on stdio

mcp-py-github/
├── src/
│   └── main.py                    # Servidor MCP (879 líneas, 28 tools)
├── .env.example                   # Plantilla de variables
├── .env                           # Config real (git-ignorado)
├── .gitignore                     # Exclusiones
├── requirements.txt               # Dependencias (87 paquetes)
├── sonar-project.properties       # SonarQube config
└── README.md                      # Este archivo

Cliente MCP (Claude, OpenCode, etc.)
         ↓
    Protocolo MCP (stdio)
         ↓
FastMCP Server (src/main.py)
  • 28 funciones @mcp.tool()
  • Validación inteligente
  • Manejo de errores
         ↓
    Librería PyGithub
         ↓
    API REST de GitHub
  • Repositorios
  • Issues & Comentarios
  • Etiquetas & Milestones
  • Ramas & Referencias
  • Pull Requests

1. Cargar GITHUB_TOKEN desde .env
2. Inicializar Github(GITHUB_TOKEN) vía PyGithub
3. Verificar token con get_user().login
4. Almacenar gh_user para resolución de repos
5. Cada herramienta usa objeto gh autenticado

Validaciones aplicadas:
• Colores: regex ^[a-fA-F0-9]{6}$
• Fechas: datetime.fromisoformat()
• Ramas: lista de protegidas
• Repositorios: verificación vía API

protected_branches = ['main', 'master', 'develop', 'dev', 'staging', 'production']

# Nombre completo (siempre funciona)
owner/repo-name

# Nombre corto (auto-antepone tu usuario)
repo-name  →  AlexAlonsoMontero/repo-name

call_tool("list_my_repositories")
# Devuelve:
# AlexAlonsoMontero/mcp-py-github
# AlexAlonsoMontero/otro-proyecto

call_tool("create_issue_with_labels",
    repo_name="mcp-py-github",
    title="Añadir soporte para webhooks",
    labels="enhancement,documentation",
    body="## Descripción\n..."
)

# Crear
call_tool("create_label",
    repo_name="mcp-py-github",
    name="prioridad-alta",
    color="FF0000",  # Sin símbolo #
    description="Issues que necesitan atención inmediata"
)

# Actualizar
call_tool("update_label",
    repo_name="mcp-py-github",
    current_name="prioridad-alta",
    color="FF6600"
)

# Listar
call_tool("list_labels", repo_name="mcp-py-github")

call_tool("create_milestone",
    repo_name="mcp-py-github",
    title="v2.0 - Integración MCP",
    description="Integración completa",
    due_on="2025-06-30",
    state="open"
)

# Crear
call_tool("create_branch",
    repo_name="mcp-py-github",
    branch_name="feature/webhooks",
    base_branch="main"
)

# Eliminar (seguro - ramas protegidas bloqueadas)
call_tool("delete_branch",
    repo_name="mcp-py-github",
    branch_name="feature/webhooks"
)

# Buscar
call_tool("search_issue",
    repo_name="mcp-py-github",
    query="webhook"
)

# Actualizar (título, estado, etiquetas)
call_tool("update_issue",
    repo_name="mcp-py-github",
    issue_number=42,
    title="[En Progreso] Añadir soporte",
    state="open",
    labels=["enhancement", "in-progress"]
)

# Asignar a un milestone
call_tool("update_issue",
    repo_name="mcp-py-github",
    issue_number=42,
    milestone_number=3  # Asigna a milestone #3 (ej: v2.0)
)

call_tool("assign_issue",
    repo_name="mcp-py-github",
    issue_number=42,
    assignees="AlexAlonsoMontero,otro-desarrollador"
)

call_tool("create_pull_request",
    repo_name="mcp-py-github",
    title="feat: Añadir soporte para webhooks",
    head="feature/webhooks",
    base="main",
    body="## Cambios\n- Endpoint de webhook\n- Dispatcher de eventos\n\nFix #42"
)

call_tool("search_issues_by_label",
    repo_name="mcp-py-github",
    labels="bug,prioridad-alta",  # AND logic
    state="open"
)

call_tool("close_issue",
    repo_name="mcp-py-github",
    issue_number=42
)

# 1. Verificar que .env existe
ls -la .env

# 2. Verificar token configurado
cat .env | grep GITHUB_TOKEN

# 3. Generar nuevo token si es necesario
# https://github.com/settings/tokens

# 1. Verificar token válido (expirados son comunes)
python3 -c "
from github import Github
import os
from dotenv import load_dotenv

load_dotenv()
gh = Github(os.getenv('GITHUB_TOKEN'))
try:
    print(f'Usuario: {gh.get_user().login}')
except Exception as e:
    print(f'Error: {e}')
"

# 2. Verificar permisos: debe tener 'repo' scope
# 3. Si usas 2FA, puede afectar la autenticación

# Listar ramas existentes
call_tool("list_branches", repo_name="tu-repo")

# Usar la rama base correcta
call_tool("create_branch",
    repo_name="tu-repo",
    branch_name="feature/xyz",
    base_branch="master"  # Ajusta según resultado anterior
)

# Actualizar en lugar de crear
call_tool("update_label",
    repo_name="tu-repo",
    current_name="bug",
    color="FF0000"
)

# Color: 6 dígitos hexadecimales SIN #
✅ FF0000  (rojo)
✅ 00FF00  (verde)
✅ aabbcc  (minúsculas ok)

❌ #FF0000  (no incluyas #)
❌ FF00    (muy corto)
❌ GGGGGG  (no es hex)

# Colores comunes:
Rojo:    FF0000
Verde:   00FF00
Azul:    0000FF
Amarillo:FFFF00
Naranja: FF8000
Púrpura: 8000FF

# Formato: YYYY-MM-DD
✅ 2025-06-30
✅ 2025-12-31

❌ 30/06/2025  (DD/MM/YYYY)
❌ 06-30-2025  (MM-DD/YYYY)

# Obtener fecha hoy:
python3 -c "from datetime import datetime; print(datetime.now().strftime('%Y-%m-%d'))"