🚀 GitHub Next.js Optimizer MCP Server

<div align="center">

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

Características • Instalación • Configuración • Uso • Patrones

</div>

---

📋 Tabla de Contenidos

• ¿Qué es este proyecto?
• Características
• Requisitos Previos
• Instalación
• Configuración con Cline (VS Code)
• Configuración con Continue
• Herramientas Disponibles
• Ejemplos de Uso
• Patrones Analizados
• Troubleshooting
• Contribuir
• 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)
• 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)

# 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

# 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)

# 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)

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:

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

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

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

---

🔧 Configuración con Continue

Si prefieres usar Continue en lugar de Cline:

Paso 1: Instalar Continue

code --install-extension continue.continue

Paso 2: Configurar Continue

Edita el archivo ~/.continue/config.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:

   # Prueba el token manualmente
   curl -H "Authorization: token ghp_tu_token" https://api.github.com/user
   

2. Verifica que Node.js está actualizado:

   node --version  # Debe ser >= 18.0.0
   

3. Prueba el servidor manualmente:

   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:

# 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:

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

# 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:

# 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 para más detalles.

---

🙏 Agradecimientos

• Model Context Protocol por el SDK
• Anthropic por Claude y el soporte de MCP
• Octokit por la integración con GitHub
• La comunidad de Next.js y React por las best practices

---

📧 Contacto

Gian Baeza - GitHub Profile

Link del Proyecto: 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>