Code Understanding

Analiza repositorios de GitHub locales y remotos para proporcionar comprensión del código y generación de contexto, incluyendo análisis de estructura, identificación de archivos y mapeo semántico.

GitHub

Prueba este MCPPatrocinado

Documentación

⚠️ Aviso de Soporte de Plataforma

Este servidor MCP ha sido probado en macOS y Linux. El soporte para Windows actualmente no está verificado (aún no probado).

Si pruebas Windows y encuentras problemas, por favor abre un issue para que podamos mejorar el soporte multiplataforma.

Servidor MCP de Comprensión de Código

Un servidor MCP (Protocolo de Contexto de Modelo) diseñado para comprender bases de código y proporcionar contexto inteligente a asistentes de codificación con IA. Este servidor maneja repositorios de GitHub tanto locales como remotos y soporta operaciones estándar compatibles con MCP.

🤖 Instalación con Asistente de IA

¡Haz que un asistente de codificación con IA te ayude a instalar este servidor! Copia y pega el contenido de nuestro Prompt de Asistente de Configuración a tu asistente de IA (Claude, ChatGPT, Cursor, etc.) y te guiará a través de todo el proceso de instalación.

Características

Clonar y analizar repositorios de GitHub o bases de código locales
Obtener estructura del repositorio y organización de archivos
Identificar archivos críticos basados en métricas de complejidad y estructura de código
Generar mapas detallados del repositorio que muestran:
- Firmas de funciones y relaciones
- Definiciones de clases y jerarquías
- Estructura de código y dependencias
Recuperar y analizar documentación del repositorio
Análisis dirigido a archivos o directorios específicos
Mantener el análisis actualizado con los cambios del repositorio mediante actualización

Inicio Rápido: Configuración del Cliente MCP

Requisitos Previos

Requerido: Instalación de uv

Este servidor requiere uv, un gestor de paquetes de Python moderno. Si aún no tienes uv instalado:

# Install UV (macOS/Linux)
curl -sSf https://astral.sh/uv/install.sh | sh

# Install UV (Windows PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

Para más opciones de instalación, visita la guía oficial de instalación de uv en astral.sh/uv.

Métodos de Instalación

Método 1: Ejecución directa con uvx (Recomendado)

# Run directly without installing a global binary
uvx code-understanding-mcp-server

Esto lanza el servidor en un entorno aislado gestionado por UV cada vez.

Método 2: Instalación en entorno virtual (Opcional)

Si prefieres un binario persistente dentro de un entorno virtual dedicado:

# Create a dedicated virtual environment
uv venv ~/.venvs/mcp-code-understanding

# Activate it (macOS/Linux)
source ~/.venvs/mcp-code-understanding/bin/activate

# Install the package into the venv
uv pip install code-understanding-mcp-server

# Run the server
code-understanding-mcp-server

Verificar Instalación

Dependiendo del método elegido:

# Method 1 (uvx): runs via uvx; no persistent binary is installed
uvx --version

# Method 2 (venv install): verify the binary inside your venv
which code-understanding-mcp-server
# Expected output example: /Users/username/.venvs/mcp-code-understanding/bin/code-understanding-mcp-server

Configurar Tu Cliente MCP

Usa una de las siguientes configuraciones para tu cliente MCP:

{
  "mcpServers": {
    "code-understanding": {
      "command": "uvx",
      "args": [
        "code-understanding-mcp-server"
      ]
    }
  }
}

Alternativamente, si instalaste en un entorno virtual, apunta directamente al binario en ese entorno:

{
  "mcpServers": {
    "code-understanding": {
      "command": "/path/to/.venvs/mcp-code-understanding/bin/code-understanding-mcp-server",
      "args": []
    }
  }
}

¿Por Qué Usar Este Servidor MCP?

Servidor MCP de Comprensión de Código

Propuesta de Valor

El Servidor MCP de Comprensión de Código capacita a los asistentes de IA con capacidades integrales de comprensión de código, permitiéndoles proporcionar asistencia más precisa, contextual y práctica con tareas de desarrollo de software. Al crear un puente semántico entre repositorios y sistemas de IA, este servidor reduce drásticamente el tiempo y la fricción involucrados en la exploración de código, análisis y orientación de implementación.

Casos de Uso Comunes

Análisis de Repositorios de Referencia

Examinar repositorios externos (bibliotecas, dependencias, etc.) para informar el desarrollo actual
Encontrar patrones de implementación y ejemplos en proyectos de código abierto
Entender cómo funcionan internamente bibliotecas específicas cuando la documentación es insuficiente
Comparar enfoques de implementación entre proyectos similares
Identificar mejores prácticas de bases de código de alta calidad

Extracción de Conocimiento y Documentación

Generar documentación completa para bases de código pobremente documentadas
Crear resúmenes arquitectónicos y diagramas de relaciones de componentes
Desarrollar rutas de aprendizaje progresivo para la incorporación de desarrolladores
Extraer lógica de negocio y conocimiento de dominio incrustado en el código
Identificar y documentar puntos de integración del sistema y dependencias

Evaluación y Mejora de la Base de Código

Analizar deuda técnica y priorizar esfuerzos de refactorización
Identificar vulnerabilidades de seguridad y problemas de cumplimiento
Evaluar cobertura de pruebas y calidad
Detectar código muerto, lógica duplicada y oportunidades de optimización
Evaluar la implementación contra patrones de diseño y principios arquitectónicos

Comprensión de Sistemas Legados

Recuperar conocimiento de sistemas con documentación mínima
Apoyar la planificación de migraciones entendiendo los límites del sistema
Analizar dependencias complejas antes de realizar cambios
Rastrear implementaciones de características a través de múltiples componentes
Entender decisiones de diseño históricas y sus fundamentos

Transferencia de Conocimiento Entre Proyectos

Aplicar patrones de un proyecto a otro
Cerrar brechas de conocimiento entre equipos que trabajan en sistemas relacionados
Identificar componentes reutilizables en múltiples proyectos
Entender diferencias en enfoques de implementación entre equipos
Facilitar el intercambio de conocimiento en entornos de desarrollo distribuidos

Para ejemplos detallados de cómo el Servidor MCP de Comprensión de Código puede usarse en escenarios del mundo real, consulta nuestro documento de Escenarios de Ejemplo. Incluye recorridos paso a paso de:

Acelerar la incorporación de desarrolladores a una base de código compleja
Planificar y ejecutar migraciones de API
Realizar evaluaciones de vulnerabilidades de seguridad

Cómo Funciona

El Servidor MCP de Comprensión de Código procesa repositorios a través de una serie de pasos de análisis:

Clonación del Repositorio: El servidor clona el repositorio objetivo en su caché
Análisis de Estructura: Análisis de directorios, archivos y su organización
Identificación de Archivos Críticos: Determinación de componentes estructuralmente significativos
Recuperación de Documentación: Recopilación de todos los archivos de documentación
Mapeo Semántico: Creación de un mapa detallado que muestra relaciones entre componentes
Análisis de Contenido: Examen de archivos específicos según sea necesario para una comprensión más profunda

Los asistentes de IA se integran con el servidor realizando solicitudes dirigidas para cada etapa analítica, construyendo una comprensión integral de la base de código que puede usarse para abordar preguntas y necesidades específicas de los usuarios.

Flujo de Trabajo Recomendado para Asistentes de IA

Al trabajar con repositorios, los asistentes de IA deben seguir este flujo de trabajo para obtener resultados óptimos:

Verificar Caché Primero: Usa list_cached_repository_branches para ver si el repositorio ya está en caché
- Si está en caché: Ve al paso 3 (actualizar)
- Si no está en caché: Continúa al paso 2
Descubrir Nombres de Ramas: Muchos repositorios usan "master", "develop" u otros nombres en lugar de "main"
- Usa list_remote_branches para descubrir las ramas disponibles
- Identifica la rama predeterminada correcta antes de clonar
Actualizar Antes de Analizar: Los repositorios en caché se vuelven obsoletos con el tiempo
- Usa refresh_repo para obtener los últimos cambios antes de cualquier análisis
- Esto asegura que el análisis se base en el código actual, no en caché desactualizada
Realizar Análisis: Una vez que el repositorio esté actualizado, usa las herramientas de análisis
- get_source_repo_map para estructura de código
- get_repo_critical_files para identificar componentes clave
- get_repo_documentation para descubrimiento de documentación

Este flujo de trabajo previene problemas comunes como fallos de clonación por nombres de rama incorrectos, intentos de clonación redundantes y análisis basados en datos de caché desactualizados.

Consideraciones de Diseño para Bases de Código Grandes

El servidor emplea varias estrategias para mantener el rendimiento y la usabilidad incluso con repositorios a escala empresarial:

Procesamiento Asíncrono: La clonación y el análisis del repositorio ocurren en hilos de fondo, proporcionando retroalimentación inmediata mientras el análisis más profundo continúa
Análisis Progresivo: El análisis inicial rápido permite interacción inmediata, con una comprensión más detallada que se construye con el tiempo
Control de Alcance: Parámetros para max_tokens, files y directories permiten análisis dirigido de áreas específicas de interés
Gestión de Umbrales: Detección automática del tamaño del repositorio con orientación apropiada para estrategias de análisis
Comprensión Jerárquica: La estructura del repositorio se analiza primero, permitiendo la priorización inteligente de componentes críticos para un análisis semántico más profundo

Estas elecciones de diseño aseguran que los desarrolladores puedan comenzar a trabajar inmediatamente con bases de código grandes mientras el sistema construye una comprensión progresivamente más profunda en segundo plano, logrando un equilibrio óptimo entre profundidad de análisis y capacidad de respuesta.

Autenticación de GitHub (Opcional)

Si necesitas acceder a repositorios privados o quieres evitar los límites de tasa de la API de GitHub, agrega tu token de GitHub a la configuración:

{
  "mcpServers": {
    "code-understanding": {
      "command": "/path/to/code-understanding-mcp-server",
      "args": [],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token-here"
      }
    }
  }
}

Opciones de Configuración Avanzadas

Para usuarios avanzados, el servidor soporta varias opciones de configuración:

{
  "mcpServers": {
    "code-understanding": {
      "command": "/path/to/code-understanding-mcp-server",
      "args": [
        "--cache-dir", "~/custom-cache-dir",     // Override repository cache location
        "--max-cached-repos", "20",              // Override maximum number of cached repos
        "--transport", "stdio",                  // Transport type (stdio or sse)
        "--port", "3001"                         // Port for SSE transport (only used with sse)
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token-here"
      }
    }
  }
}

Opciones disponibles:

--cache-dir: Anular la ubicación del directorio de caché del repositorio (predeterminado: ~/.cache/mcp-code-understanding)
--max-cached-repos: Establecer el número máximo de repositorios en caché (predeterminado: 10)
--transport: Elegir tipo de transporte (stdio o sse, predeterminado: stdio)
--port: Establecer puerto para transporte SSE (predeterminado: 3001, solo se usa con transporte sse)

Notas Específicas de Plataforma

macOS

Con uvx, no se instala un binario persistente; no se requieren cambios de PATH
Con un entorno virtual, asegúrate de activarlo o referencia la ruta completa al binario del venv

Linux

Con uvx, no se instala un binario persistente; no se requieren cambios de PATH
Con un entorno virtual, puedes preferir agregar un alias de ayuda o activar el venv antes de usar

Windows

Actualmente no soportado - El soporte para Windows está planificado para una versión futura
El trabajo de desarrollo está en curso para habilitar la compatibilidad con Windows

Solución de Problemas

Conflictos de Dependencias

Si encuentras conflictos de dependencias al usar uvx, crea un entorno aislado e instala el paquete allí:

# Create a dedicated virtual environment
uv venv ~/.venvs/mcp-code-understanding

# Activate it (macOS/Linux)
source ~/.venvs/mcp-code-understanding/bin/activate

# Install the package
uv pip install code-understanding-mcp-server

# Run the server
code-understanding-mcp-server

Binario No Encontrado

Si el binario instalado no se encuentra:

Verifica la ubicación de instalación:

# macOS/Linux
find ~/.local -name "code-understanding-mcp-server" 2>/dev/null

Agrega al PATH si es necesario:

# Add to ~/.bashrc, ~/.zshrc, or appropriate shell config
export PATH="$HOME/.local/bin:$PATH"

Usa la ruta absoluta al binario de tu venv en la configuración de MCP si no estás activando el venv

Configuración del Servidor

El servidor usa un archivo config.yaml para la configuración base. Este archivo se crea automáticamente en el directorio de configuración estándar (~/.config/mcp-code-understanding/config.yaml) cuando el servidor se ejecuta por primera vez. También puedes colocar un archivo config.yaml en tu directorio actual para anular la configuración predeterminada.

Aquí está la estructura de configuración predeterminada:

name: "Code Understanding Server"
log_level: "debug"

repository:
  cache_dir: "~/.cache/mcp-code-understanding"
  max_cached_repos: 10

documentation:
  include_tags:
    - markdown
    - rst
    - adoc
  include_extensions:
    - .md
    - .markdown
    - .rst
    - .txt
    - .adoc
    - .ipynb
  format_mapping:
    tag:markdown: markdown
    tag:rst: restructuredtext
    tag:adoc: asciidoc
    ext:.md: markdown
    ext:.markdown: markdown
    ext:.rst: restructuredtext
    ext:.txt: plaintext
    ext:.adoc: asciidoc
    ext:.ipynb: jupyter
  category_patterns:
    readme: 
      - readme
    api: 
      - api
    documentation:
      - docs
      - documentation
    examples:
      - examples
      - sample

Para Desarrolladores

Requisitos Previos

Python 3.11 o 3.12: Requerido tanto para desarrollo como para uso

# Verify your Python version
python --version
# or
python3 --version

Gestor de Paquetes UV: El instalador de paquetes de Python moderno
```
# Install UV
curl -sSf https://astral.sh/uv/install.sh | sh
```

Configuración de Desarrollo

Para contribuir o ejecutar este proyecto localmente:

# 1. Clone the repository
git clone https://github.com/yourusername/mcp-code-understanding.git
cd mcp-code-understanding

# 2. Create virtual environment
uv venv

# 3. Activate the virtual environment
#    Choose the command appropriate for your operating system and shell:

#    Linux/macOS (bash/zsh):
source .venv/bin/activate

#    Windows (Command Prompt - cmd.exe):
.venv\\Scripts\\activate.bat

#    Windows (PowerShell):
#    Note: You might need to adjust your execution policy first.
#    Run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
.venv\\Scripts\\Activate.ps1

# 4. Install dependencies (editable mode with dev extras)
#    (Ensure your virtual environment is activated first!)
uv pip install -e ".[dev]"

# 5. Set up pre-commit hooks
pre-commit install

# 6. Run tests
uv run pytest

# 7. Test the server using MCP inspector
# Without GitHub authentication:
uv run mcp dev src/code_understanding/mcp/server/app.py

# With GitHub authentication (for testing private repos):
GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here uv run mcp dev src/code_understanding/mcp/server/app.py

Esto lanzará una consola interactiva donde puedes probar todos los endpoints del servidor MCP directamente.

Herramientas de Desarrollo

Las siguientes herramientas de desarrollo están disponibles después de instalar con extras de desarrollo (.[dev]):

Ejecutar pruebas con cobertura:

uv run pytest

Formatear código (usando black e isort):

# Format with black
uv run black .

# Sort imports
uv run isort .

Verificación de tipos con mypy:

uv run mypy .

Todas las herramientas están configuradas a través de pyproject.toml con ajustes optimizados para este proyecto.

Publicación en PyPI

Cuando estés listo para publicar una nueva versión en PyPI, sigue estos pasos:

Actualiza el número de versión en pyproject.toml:

# Edit pyproject.toml and change the version field
# For example: version = "0.1.1"

Limpia los artefactos de compilación anteriores:

# Remove previous distribution packages and build directories
rm -rf dist/ 2>/dev/null || true
rm -rf build/ 2>/dev/null || true
rm -rf src/*.egg-info/ 2>/dev/null || true

Compila los paquetes de distribución:
```
uv run python -m build
```
Verifica los paquetes compilados:
```
ls dist/
```

Sube a PyPI (usa TestPyPI primero si no estás seguro):

# Install twine if you haven't already
uv pip install twine

# For PyPI release:
uv run python -m twine upload dist/*

Necesitarás credenciales de PyPI configuradas o se te pedirá que las ingreses durante la carga.

Historial de Versiones

v0.1.6 (Más Reciente)

Corrección de Dependencias: configargparse==1.7 fijado explícitamente para resolver problemas de instalación causados por la versión retirada en PyPI
Esto asegura una instalación limpia con uvx y otros gestores de paquetes al prevenir fallos de resolución de dependencias
Sin cambios funcionales en las capacidades del servidor

Licencia

MIT