# 🚀 GitHub Next.js Optimizer MCP Server

<div align="center">

![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)
![MCP](https://img.shields.io/badge/MCP-1.0.4-purple.svg)

**Servidor MCP inteligente que analiza repositorios de GitHub y proporciona recomendaciones avanzadas de optimización para proyectos Next.js y React**

[Características](#-características) •
[Instalación](#-instalación) •
[Configuración](#️-configuración) •
[Uso](#-uso) •
[Patrones](#-patrones-analizados)

</div>

---

## 📋 Tabla de Contenidos

- [¿Qué es este proyecto?](#-qué-es-este-proyecto)
- [Características](#-características)
- [Requisitos Previos](#-requisitos-previos)
- [Instalación](#-instalación)
- [Configuración con Cline (VS Code)](#️-configuración-con-cline-vs-code)
- [Configuración con Continue](#-configuración-con-continue)
- [Herramientas Disponibles](#-herramientas-disponibles)
- [Ejemplos de Uso](#-ejemplos-de-uso)
- [Patrones Analizados](#-patrones-analizados)
- [Troubleshooting](#-troubleshooting)
- [Contribuir](#-contribuir)
- [Licencia](#-licencia)

---

## 🤔 ¿Qué es este proyecto?

**GitHub Next.js Optimizer MCP Server** es un servidor del **Model Context Protocol (MCP)** que se integra con herramientas de IA como Claude para analizar repositorios de GitHub y proporcionar recomendaciones inteligentes sobre:

- ✅ Arquitectura limpia (Clean Architecture)
- ✅ Principios SOLID
- ✅ Patrones de diseño (Design Patterns)
- ✅ Optimizaciones de rendimiento en React/Next.js
- ✅ Server Components vs Client Components
- ✅ Anti-patrones y code smells
- ✅ Best practices de Next.js App Router

---

## ✨ Características

### 🔍 Análisis Profundo
- **Análisis de repositorio completo**: Escanea todos los archivos React/Next.js (.tsx, .jsx, .ts, .js)
- **Análisis de archivos individuales**: Obtén recomendaciones específicas para un archivo
- **Detección de patrones**: Identifica más de 50+ patrones y anti-patrones

### 🎯 Recomendaciones Inteligentes
- **Principios SOLID**: SRP, OCP, LSP, ISP, DIP
- **Clean Architecture**: Domain, Use Cases, Infrastructure, Presentation
- **React/Next.js Best Practices**: Server Components, memoización, hooks optimizados
- **Performance**: Lazy loading, code splitting, optimizaciones de rendering

### 🛠️ Herramientas
- `analizar_repositorio`: Análisis completo del proyecto
- `listar_archivos_react`: Lista todos los archivos React/Next.js
- `analizar_archivo`: Análisis detallado de un archivo específico

---

## 📦 Requisitos Previos

Antes de comenzar, asegúrate de tener instalado:

- **Node.js**: >= 18.0.0 ([Descargar](https://nodejs.org/))
- **npm**: >= 9.0.0 (viene con Node.js)
- **Git**: Para clonar el repositorio
- **GitHub Personal Access Token**: Para acceder a la API de GitHub
- **VS Code**: Con la extensión Cline instalada

---

## 🚀 Instalación

### Opción 1: Instalación Global (Recomendada)

```bash
# Instalar desde npm
npm install -g github-nextjs-optimizer-mcp

# Verificar instalación
github-nextjs-optimizer-mcp --version
```

### Opción 2: Instalación desde Repositorio

```bash
# Clonar el repositorio
git clone https://github.com/GianBaeza/Next.js-Optimizer-MCP-Server.git
cd Next.js-Optimizer-MCP-Server

# Instalar dependencias
npm install

# Compilar el proyecto
npm run build

# Enlazar globalmente (opcional)
npm link
```

### Opción 3: Uso con npx (Sin instalación)

```bash
# Usar directamente con npx
npx github-nextjs-optimizer-mcp
```

---

## 🔑 Obtener GitHub Personal Access Token

1. Ve a [GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)](https://github.com/settings/tokens)

2. Haz clic en **"Generate new token (classic)"**

3. Configura el token:
   - **Note**: "MCP Server Token" (o cualquier nombre descriptivo)
   - **Expiration**: 90 días (o sin expiración para desarrollo)
   - **Scopes**: Selecciona los siguientes permisos:
     - ✅ `repo` (Full control of private repositories)
     - ✅ `read:org` (Read org and team membership)
     - ✅ `read:user` (Read user profile data)

4. Haz clic en **"Generate token"**

5. **⚠️ IMPORTANTE**: Copia el token inmediatamente (solo se muestra una vez)
   - Ejemplo: `ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

---

## ⚙️ Configuración con Cline (VS Code)

### Paso 1: Instalar Cline

1. Abre VS Code
2. Ve a Extensions (`Ctrl+Shift+X` o `Cmd+Shift+X`)
3. Busca **"Cline"**
4. Instala la extensión oficial de Cline

### Paso 2: Ubicar el archivo de configuración

El archivo de configuración de Cline se encuentra en:

- **Windows**: 
  ```
  %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  ```

- **macOS**: 
  ```
  ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  ```

- **Linux**: 
  ```
  ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  ```

### Paso 3: Configurar el servidor MCP

Abre el archivo `cline_mcp_settings.json` y agrega la siguiente configuración:

#### Si instalaste globalmente:

```json
{
  "mcpServers": {
    "github-nextjs-optimizer": {
      "command": "github-nextjs-optimizer-mcp",
      "args": [],
      "env": {
        "GITHUB_TOKEN": "ghp_tu_token_de_github_aqui"
      }
    }
  }
}
```

#### Si usas npx (sin instalación global):

```json
{
  "mcpServers": {
    "github-nextjs-optimizer": {
      "command": "npx",
      "args": [
        "-y",
        "github-nextjs-optimizer-mcp"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_tu_token_de_github_aqui"
      }
    }
  }
}
```

#### Si instalaste desde el repositorio local:

```json
{
  "mcpServers": {
    "github-nextjs-optimizer": {
      "command": "node",
      "args": [
        "/ruta/completa/a/Next.js-Optimizer-MCP-Server/build/index.js"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_tu_token_de_github_aqui"
      }
    }
  }
}
```

### Paso 4: Reiniciar VS Code

1. Cierra completamente VS Code
2. Ábrelo nuevamente
3. Abre la extensión Cline desde la barra lateral

### Paso 5: Verificar la conexión

1. Abre Cline en VS Code
2. Haz clic en el ícono de configuración (⚙️)
3. Ve a **"MCP Servers"**
4. Deberías ver `github-nextjs-optimizer` con estado **"Connected"** ✅

Si aparece **"Disconnected"** ❌, ve a la sección [Troubleshooting](#-troubleshooting).

---

## 🔧 Configuración con Continue

Si prefieres usar Continue en lugar de Cline:

### Paso 1: Instalar Continue

```bash
code --install-extension continue.continue
```

### Paso 2: Configurar Continue

Edita el archivo `~/.continue/config.json`:

```json
{
  "models": [
    {
      "title": "Claude Sonnet 4.5",
      "provider": "anthropic",
      "model": "claude-sonnet-4-5-20250929",
      "apiKey": "tu_anthropic_api_key"
    }
  ],
  "mcpServers": [
    {
      "name": "github-nextjs-optimizer",
      "command": "npx",
      "args": ["-y", "github-nextjs-optimizer-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_tu_token_de_github_aqui"
      }
    }
  ]
}
```

---

## 🛠️ Herramientas Disponibles

### 1. `analizar_repositorio`

Analiza un repositorio completo de GitHub.

**Parámetros:**
- `owner` (string, requerido): Propietario del repositorio
- `repo` (string, requerido): Nombre del repositorio
- `branch` (string, opcional): Rama a analizar (default: "main")

**Ejemplo de uso en Cline:**
```
Analiza el repositorio GianBaeza/veterinariaFrontend
```

**Respuesta:**
- Total de archivos React/Next.js encontrados
- Problemas detectados por archivo
- Recomendaciones específicas
- Nivel de severidad (high, medium, low)

---

### 2. `listar_archivos_react`

Lista todos los archivos React/Next.js en un repositorio.

**Parámetros:**
- `owner` (string, requerido): Propietario del repositorio
- `repo` (string, requerido): Nombre del repositorio
- `path` (string, opcional): Ruta específica a listar

**Ejemplo de uso en Cline:**
```
Lista todos los archivos React del repositorio GianBaeza/veterinariaFrontend
```

---

### 3. `analizar_archivo`

Analiza un archivo específico en detalle.

**Parámetros:**
- `owner` (string, requerido): Propietario del repositorio
- `repo` (string, requerido): Nombre del repositorio
- `path` (string, requerido): Ruta al archivo
- `branch` (string, opcional): Rama (default: "main")

**Ejemplo de uso en Cline:**
```
Analiza el archivo src/app/page.tsx del repositorio GianBaeza/veterinariaFrontend
```

---

## 💡 Ejemplos de Uso

### Análisis Completo de un Proyecto

```
Usuario: Analiza mi proyecto de veterinaria en GitHub
```

Cline (con MCP):
```
Voy a analizar tu repositorio usando el servidor MCP...

📁 Repositorio: GianBaeza/veterinariaFrontend
📊 Total de archivos: 9

Problemas encontrados:

1. src/app/page.tsx:
   ❗ Componente sin 'use client' pero usa hooks
   💡 Recomendación: Agregar 'use client' al inicio del archivo

2. src/feature/auth/Auth.tsx:
   ⚠️ Componente muy simple sin funcionalidad
   💡 Recomendación: Implementar formulario de autenticación con validación
```

### Análisis de Archivo Específico

```
Usuario: Analiza el middleware.ts de mi proyecto
```

Cline (con MCP):
```
📄 Análisis de middleware.ts:

❌ CRÍTICO: Configuración de matcher incorrecta
🔄 Redirección infinita detectada

Código actual:
export const config = {
    matcher: ['/home/:path*']
}

Problema: El middleware redirige a /home pero el matcher captura /home/*

Solución recomendada:
export const config = {
    matcher: '/'  // Solo captura la raíz
}
```

---

## 🎨 Patrones Analizados

### 🏛️ Arquitectura Limpia
- **Domain Layer**: Entidades, Value Objects
- **Use Cases**: Lógica de negocio
- **Infrastructure**: Repositorios, API clients
- **Presentation**: Componentes UI

### 🔷 Principios SOLID
- **Single Responsibility Principle**
- **Open/Closed Principle**
- **Liskov Substitution Principle**
- **Interface Segregation Principle**
- **Dependency Inversion Principle**

### ⚛️ React/Next.js Best Practices
- Server Components vs Client Components
- React.memo y optimizaciones
- useCallback y useMemo
- Lazy loading y code splitting
- Suspense y streaming

### 📐 Design Patterns
- Singleton
- Factory
- Observer
- Strategy
- Composite
- Adapter
- Repository Pattern

### ⚠️ Anti-Patrones Detectados
- Prop drilling excesivo
- God components
- Tight coupling
- Funciones inline en props
- Arrays/Objects inline
- useEffect sin dependencias
- Fetch en cliente sin caché

---

## 🐛 Troubleshooting

### Problema: "Server disconnected" en Cline

**Causa**: El servidor MCP no puede iniciarse correctamente.

**Soluciones**:

1. **Verifica que el token de GitHub es válido:**
   ```bash
   # Prueba el token manualmente
   curl -H "Authorization: token ghp_tu_token" https://api.github.com/user
   ```

2. **Verifica que Node.js está actualizado:**
   ```bash
   node --version  # Debe ser >= 18.0.0
   ```

3. **Prueba el servidor manualmente:**
   ```bash
   export GITHUB_TOKEN="ghp_tu_token"
   github-nextjs-optimizer-mcp
   ```

4. **Revisa los logs de Cline:**
   - Abre Cline
   - Ve a Settings → MCP Servers
   - Haz clic en el servidor y revisa los logs

---

### Problema: "Cannot find module"

**Solución:**

```bash
# Limpia la caché de npm
npm cache clean --force

# Reinstala las dependencias
cd Next.js-Optimizer-MCP-Server
rm -rf node_modules package-lock.json
npm install

# Recompila
npm run build
```

---

### Problema: "GITHUB_TOKEN is not defined"

**Solución:**

Asegúrate de que el token está configurado en `cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "github-nextjs-optimizer": {
      "command": "github-nextjs-optimizer-mcp",
      "args": [],
      "env": {
        "GITHUB_TOKEN": "ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
      }
    }
  }
}
```

⚠️ El token debe empezar con `ghp_` y tener 40 caracteres.

---

### Problema: Permission denied en macOS/Linux

**Solución:**

```bash
# Da permisos de ejecución
chmod +x build/index.js

# O reinstala con permisos
sudo npm install -g github-nextjs-optimizer-mcp
```

---

### Problema: El servidor se conecta pero no responde

**Solución:**

1. Verifica que el repositorio existe y es accesible
2. Verifica que tu token tiene los permisos correctos
3. Prueba con un repositorio público primero

```
Analiza el repositorio facebook/react
```

---

## 📝 Logs y Debugging

El servidor genera logs detallados. Para ver los logs:

### En Cline:
1. Abre Cline
2. Settings → MCP Servers
3. Selecciona tu servidor
4. Haz clic en "View Logs"

### En la terminal:

```bash
# Ejecuta el servidor con logs
export DEBUG=*
export GITHUB_TOKEN="tu_token"
github-nextjs-optimizer-mcp
```

---

## 🤝 Contribuir

¡Las contribuciones son bienvenidas! Si quieres mejorar este proyecto:

1. **Fork** el repositorio
2. Crea una **branch** para tu feature (`git checkout -b feature/AmazingFeature`)
3. **Commit** tus cambios (`git commit -m 'Add some AmazingFeature'`)
4. **Push** a la branch (`git push origin feature/AmazingFeature`)
5. Abre un **Pull Request**

### Ideas para contribuir:
- 🎯 Agregar más patrones de análisis
- 🔍 Mejorar la detección de anti-patrones
- 📚 Agregar más ejemplos de código
- 🌐 Soporte para otros frameworks (Vue, Angular)
- 🧪 Agregar tests unitarios
- 📖 Mejorar la documentación

---

## 📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo [LICENSE](LICENSE) para más detalles.

---

## 🙏 Agradecimientos

- [Model Context Protocol](https://modelcontextprotocol.io) por el SDK
- [Anthropic](https://www.anthropic.com) por Claude y el soporte de MCP
- [Octokit](https://github.com/octokit/rest.js) por la integración con GitHub
- La comunidad de Next.js y React por las best practices

---

## 📧 Contacto

**Gian Baeza** - [GitHub Profile](https://github.com/GianBaeza)

**Link del Proyecto**: [https://github.com/GianBaeza/Next.js-Optimizer-MCP-Server](https://github.com/GianBaeza/Next.js-Optimizer-MCP-Server)

---

<div align="center">

⭐ Si este proyecto te fue útil, considera darle una estrella en GitHub ⭐

**Made with ❤️ by Gian Baeza**

</div>