README.md•18.1 kB
# GitIngest MCP Server
Un servidor MCP (Model Context Protocol) que integra GitIngest para generar archivos de contexto de repositorios de GitHub privados, diseñado para nodos de resolución de tareas LLM.
## 🚀 Características
- **Integración completa con GitIngest**: Soporte para repositorios públicos y privados de GitHub
- **Protocolo MCP**: Compatible con el estándar MCP para integración con agentes de IA
- **Dockerizado**: Fácil despliegue y ejecución en contenedores
- **Configuración flexible**: Patrones de inclusión/exclusión personalizables
- **Manejo robusto de errores**: Fallback automático a CLI si el paquete Python no está disponible
- **Seguridad**: Ejecución como usuario no-root en contenedores
## 📋 Requisitos
- Python 3.11+
- Docker (opcional, para ejecución en contenedor)
- Token de acceso personal de GitHub (para repositorios privados)
## 🛠️ Instalación
### Opción 1: Ejecución Directa
```bash
# Clonar o descargar el proyecto
cd "Gitingest MCP"
# Crear entorno virtual
python -m venv venv
source venv/bin/activate # En Windows: venv\Scripts\activate
# Instalar dependencias
pip install -r requirements.txt
# Configurar variables de entorno
cp env.example .env
# Editar .env y agregar tu GITHUB_TOKEN
```
### Opción 2: Docker
```bash
# Construir la imagen localmente
docker build -t gitingest-mcp .
# O usar docker-compose
docker-compose up --build
# O usar el script automatizado
./build_and_publish.sh
```
### 3. Publicación de Imagen Docker
Para publicar la imagen en GitHub Container Registry:
```bash
# Usar el script automatizado (recomendado)
./build_and_publish.sh
# O manualmente
docker build -t ghcr.io/gooapps/gitingest-mcp:latest .
docker push ghcr.io/gooapps/gitingest-mcp:latest
```
## ⚙️ Configuración
### Variables de Entorno
Crea un archivo `.env` basado en `env.example`:
```bash
# Token de GitHub (requerido para repositorios privados)
GITHUB_TOKEN=ghp_your_token_here
# Configuración opcional
LOG_LEVEL=INFO
GITINGEST_MAX_FILE_SIZE=1048576 # 1MB
GITINGEST_TIMEOUT=300 # 5 minutos
```
### Token de GitHub
Para acceder a repositorios privados, necesitas un token de acceso personal de GitHub:
1. Ve a [GitHub Settings > Personal Access Tokens](https://github.com/settings/tokens)
2. Genera un nuevo token con los siguientes scopes:
- `repo` (para repositorios privados)
- `public_repo` (para repositorios públicos)
3. Copia el token y configúralo en la variable `GITHUB_TOKEN`
## 🚀 Uso
### Ejecución Directa
```bash
# Usar el script de inicio (recomendado)
./start.sh
# O ejecutar directamente
python -m gitingest_mcp.mcp_server
```
### Docker
```bash
# Ejecutar con docker-compose
docker-compose up
# O ejecutar directamente
docker run -e GITHUB_TOKEN=your_token_here gitingest-mcp
```
## 🔧 Herramientas MCP Disponibles
### `ingest_git`
**Descripción:** Clona y analiza el repositorio indicado, generando resumen, estructura y contenido. Evita la duplicación de cabeceras Authorization en entornos Docker persistentes.
**Parámetros:**
- `source` (requerido): URL del repositorio Git o ruta local a analizar
- `token` (requerido): Access token de GitHub para autenticación
- `max_file_size` (opcional): Tamaño máximo de archivo permitido para ingestión (por defecto 10 MB)
- `include_patterns` (opcional): Patrones de archivos a incluir, ej. '*.py, src/'
- `exclude_patterns` (opcional): Patrones de archivos a excluir, ej. 'node_modules/, *.md'
- `branch` (opcional): Branch del repositorio a clonar (por defecto 'main')
**Ejemplo de uso desde un cliente MCP:**
```json
{
"name": "ingest_git",
"arguments": {
"source": "https://github.com/usuario/repositorio-privado",
"token": "ghp_tu_token_aqui",
"include_patterns": "*.py, *.js, *.md",
"exclude_patterns": "node_modules/, __pycache__/, *.log",
"max_file_size": 1048576,
"branch": "main"
}
}
```
**Casos de uso comunes:**
1. **Analizar repositorio completo:**
```json
{
"name": "ingest_git",
"arguments": {
"source": "https://github.com/empresa/proyecto",
"token": "ghp_tu_token_aqui"
}
}
```
2. **Solo archivos de código fuente:**
```json
{
"name": "ingest_git",
"arguments": {
"source": "https://github.com/empresa/proyecto",
"token": "ghp_tu_token_aqui",
"include_patterns": "*.py, *.js, *.ts, *.java, *.cpp, *.h",
"exclude_patterns": "test/, tests/, __pycache__/, node_modules/"
}
}
```
3. **Documentación específica:**
```json
{
"name": "ingest_git",
"arguments": {
"source": "https://github.com/empresa/proyecto",
"token": "ghp_tu_token_aqui",
"include_patterns": "*.md, *.rst, docs/, README*",
"max_file_size": 524288
}
}
```
## 📊 Formato de Salida
El servidor devuelve texto estructurado optimizado para consumo de LLM:
```
Repository: owner/repo-name
Files analyzed: 42
Estimated tokens: 15.2k
Directory structure:
└── project-name/
├── src/
│ ├── main.py
│ └── utils.py
├── tests/
│ └── test_main.py
└── README.md
================================================
FILE: src/main.py
================================================
def hello_world():
print("Hello, World!")
if __name__ == "__main__":
hello_world()
```
## 🔗 Integración con Nodos LLM
### Configuración para GitHub Copilot (IntelliJ/VSCode)
Para integrar con GitHub Copilot, crea o actualiza el archivo de configuración MCP:
**Archivo:** `~/.config/github-copilot/intellij/mcp.json` (IntelliJ) o `~/.config/github-copilot/vscode/mcp.json` (VSCode)
```json
{
"servers": {
"gitingest": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/develgooapps/gitingest-mcp:main-26b875d"
]
}
}
}
```
### Configuración usando Imagen Docker Local
Si prefieres construir la imagen localmente:
```json
{
"servers": {
"gitingest": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"gitingest-mcp:latest"
]
}
}
}
```
### Configuración para Claude Desktop
Para usar con Claude Desktop, agrega al archivo de configuración:
**Archivo:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
```json
{
"mcpServers": {
"gitingest": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/develgooapps/gitingest-mcp:main-26b875d"
]
}
}
}
```
### Configuración para Cline (VSCode Extension)
Para usar con la extensión Cline en VSCode:
```json
{
"mcpServers": {
"gitingest": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/develgooapps/gitingest-mcp:main-26b875d"
]
}
}
}
```
## 🎯 Guía de Uso Práctica
### Configuración Inicial Rápida
1. **Obtener un Token de GitHub:**
```bash
# Ve a: https://github.com/settings/tokens
# Genera un nuevo token con permisos:
# - repo (para repositorios privados)
# - public_repo (para repositorios públicos)
# Nota: Este token se usará directamente en las llamadas al MCP
```
2. **Configurar en GitHub Copilot (IntelliJ/VSCode):**
```bash
# Crear directorio de configuración si no existe
mkdir -p ~/.config/github-copilot/intellij
# Crear archivo mcp.json
cat > ~/.config/github-copilot/intellij/mcp.json << 'EOF'
{
"servers": {
"gitingest": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/develgooapps/gitingest-mcp:main-26b875d"
]
}
}
}
EOF
```
3. **Reiniciar GitHub Copilot** para que cargue la nueva configuración.
### Casos de Uso Comunes
#### 1. Análisis Completo de Repositorio
**Escenario:** Necesitas entender un repositorio completo para hacer contribuciones o debugging.
**Comando en el chat de Copilot:**
```
@gitingest analiza el repositorio https://github.com/empresa/proyecto-backend
Token: ghp_tu_token_aqui
```
**Llamada MCP interna:**
```json
{
"name": "ingest_git",
"arguments": {
"source": "https://github.com/empresa/proyecto-backend",
"token": "ghp_tu_token_aqui"
}
}
```
#### 2. Análisis de Solo Código Fuente
**Escenario:** Solo quieres ver el código, sin documentación ni archivos de configuración.
**Comando en el chat:**
```
@gitingest analiza solo el código fuente de https://github.com/empresa/api-service
Incluye: *.py, *.js, *.ts, *.java
Excluye: tests/, docs/, *.md, node_modules/
Token: ghp_tu_token_aqui
```
**Llamada MCP interna:**
```json
{
"name": "ingest_git",
"arguments": {
"source": "https://github.com/empresa/api-service",
"token": "ghp_tu_token_aqui",
"include_patterns": "*.py, *.js, *.ts, *.java",
"exclude_patterns": "tests/, docs/, *.md, node_modules/"
}
}
```
#### 3. Análisis de Documentación
**Escenario:** Solo necesitas la documentación del proyecto.
**Comando en el chat:**
```
@gitingest extrae solo la documentación de https://github.com/empresa/frontend-app
Incluye: *.md, *.rst, docs/, README*, CHANGELOG*
Token: ghp_tu_token_aqui
```
**Llamada MCP interna:**
```json
{
"name": "ingest_git",
"arguments": {
"source": "https://github.com/empresa/frontend-app",
"token": "ghp_tu_token_aqui",
"include_patterns": "*.md, *.rst, docs/, README*, CHANGELOG*"
}
}
```
#### 4. Análisis de Branch Específico
**Escenario:** Quieres analizar una feature branch específica.
**Comando en el chat:**
```
@gitingest analiza la rama feature/nueva-funcionalidad del repo https://github.com/empresa/proyecto
Token: ghp_tu_token_aqui
```
**Llamada MCP interna:**
```json
{
"name": "ingest_git",
"arguments": {
"source": "https://github.com/empresa/proyecto",
"token": "ghp_tu_token_aqui",
"branch": "feature/nueva-funcionalidad"
}
}
```
#### 5. Análisis con Límite de Tamaño
**Escenario:** El repo es muy grande y solo quieres archivos pequeños.
**Comando en el chat:**
```
@gitingest analiza https://github.com/empresa/proyecto-grande pero solo archivos menores a 500KB
Token: ghp_tu_token_aqui
```
**Llamada MCP interna:**
```json
{
"name": "ingest_git",
"arguments": {
"source": "https://github.com/empresa/proyecto-grande",
"token": "ghp_tu_token_aqui",
"max_file_size": 512000
}
}
```
### Flujo de Trabajo Típico
1. **Identificar Repositorio:** Obtén la URL del repositorio que necesitas analizar
2. **Determinar Scope:** Decide qué archivos necesitas (código, docs, config, etc.)
3. **Usar Filtros:** Aplica patrones de inclusión/exclusión según tu necesidad
4. **Ejecutar Análisis:** Usa el comando con @gitingest en tu cliente MCP
5. **Revisar Resultados:** El MCP retornará el contenido estructurado del repositorio
### Consejos de Uso
- **Repositorios Grandes:** Usa `exclude_patterns` para evitar `node_modules/`, `__pycache__/`, `.git/`
- **Análisis Específico:** Usa `include_patterns` para enfocarte en tipos de archivo específicos
- **Branches:** Especifica el branch si no quieres analizar `main`/`master`
- **Tamaño de Archivos:** Limita `max_file_size` para evitar archivos binarios grandes
- **Tokens:** Usa tokens con permisos mínimos necesarios para el repositorio
## 🐳 Docker Compose
El archivo `docker-compose.yml` incluye:
- Configuración de salud del contenedor
- Límites de recursos
- Política de reinicio
- Configuración de seguridad
- Sistema de archivos de solo lectura
## 🔒 Seguridad
- Ejecución como usuario no-root en contenedores
- Sistema de archivos de solo lectura
- Límites de recursos configurados
- Validación de URLs de GitHub
- Manejo seguro de tokens
## 🐛 Solución de Problemas
### Problemas Comunes y Soluciones
#### 1. Error: "Authentication failed" o "Repository not found"
**Síntomas:**
```
Error: Repository not found or access denied
HTTP 404: Not Found
```
**Soluciones:**
- Verifica que la URL del repositorio sea correcta
- Asegúrate de que el token de GitHub tenga los permisos necesarios:
- `repo` para repositorios privados
- `public_repo` para repositorios públicos
- Para repositorios de organizaciones, el token debe tener acceso a la organización
```bash
# Verificar permisos del token
curl -H "Authorization: token TU_TOKEN" https://api.github.com/user
```
#### 2. Error: "Docker image not found"
**Síntomas:**
```
Unable to find image 'docker.io/develgooapps/gitingest-mcp:main-26b875d'
```
**Soluciones:**
```bash
# Descargar la imagen manualmente
docker pull docker.io/develgooapps/gitingest-mcp:main-26b875d
# O construir localmente
cd "Gitingest MCP"
docker build -t gitingest-mcp:latest .
# Actualizar mcp.json para usar imagen local
# Cambiar "docker.io/develgooapps/gitingest-mcp:main-26b875d" por "gitingest-mcp:latest"
```
#### 3. Error: "GITHUB_TOKEN not set"
**Síntomas:**
```
Error: GitHub token is required but not provided
```
**Soluciones:**
- Verificar que estés pasando el token correctamente en la llamada al MCP
- Asegurar que el token no tenga espacios ni caracteres especiales
- El token debe incluirse en cada llamada individual al MCP, no en la configuración
**Ejemplo correcto de uso:**
```json
{
"name": "ingest_git",
"arguments": {
"source": "https://github.com/usuario/repo",
"token": "ghp_tu_token_sin_espacios"
}
}
```
#### 4. Error: "Rate limit exceeded"
**Síntomas:**
```
API rate limit exceeded for user
```
**Soluciones:**
- Esperar una hora antes de hacer más requests
- Usar un token de GitHub autenticado (aumenta el límite de 60 a 5000 requests/hora)
- Para uso intensivo, considera usar GitHub Apps
#### 5. Error: "File too large" o "Repository too large"
**Síntomas:**
```
Error: File exceeds maximum size limit
Warning: Repository is very large
```
**Soluciones:**
```json
{
"name": "ingest_git",
"arguments": {
"source": "https://github.com/user/large-repo",
"token": "ghp_tu_token",
"max_file_size": 1048576,
"exclude_patterns": "*.zip, *.tar.gz, *.pdf, *.png, *.jpg, node_modules/, .git/"
}
}
```
#### 6. Error: "MCP server not responding"
**Síntomas:**
- El chat no reconoce @gitingest
- No aparecen las herramientas del MCP
**Soluciones:**
1. Verificar que Docker esté ejecutándose:
```bash
docker ps
```
2. Probar la imagen manualmente:
```bash
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | \
docker run -i --rm \
docker.io/develgooapps/gitingest-mcp:main-26b875d
```
3. Reiniciar GitHub Copilot/IDE después de cambios en mcp.json
4. Verificar logs de Docker:
```bash
docker logs $(docker ps -q --filter ancestor=docker.io/develgooapps/gitingest-mcp:main-26b875d)
```
### Mejores Prácticas
#### Gestión de Tokens
- **Rotación:** Rota los tokens de GitHub regularmente
- **Scope Mínimo:** Usa tokens con el mínimo scope necesario
- **Seguridad:** Nunca compartas tokens en código o logs
- **Uso Dinámico:** El token se pasa directamente en cada llamada al MCP, no se almacena en configuración
#### Optimización de Rendimiento
- **Filtros Inteligentes:** Usa patrones de exclusión para evitar archivos innecesarios
```json
{
"exclude_patterns": "node_modules/, __pycache__/, .git/, *.log, *.tmp, dist/, build/"
}
```
- **Límites de Tamaño:** Establece límites apropiados para tu caso de uso
```json
{
"max_file_size": 524288 // 512KB para análisis de código
}
```
#### Uso Eficiente
- **Branches Específicos:** Analiza branches específicos en lugar de todo el repositorio
- **Análisis Incremental:** Para repos grandes, analiza directorios específicos
- **Cache Local:** Docker cachea las imágenes, aprovecha esto para múltiples usos
### Verificación de Configuración
Usa este script para verificar que todo esté configurado correctamente:
```bash
#!/bin/bash
echo "🔍 Verificando configuración GitIngest MCP..."
# Verificar Docker
if ! command -v docker &> /dev/null; then
echo "❌ Docker no está instalado"
exit 1
fi
echo "✅ Docker está disponible"
# Verificar imagen
if docker image inspect docker.io/develgooapps/gitingest-mcp:main-26b875d &> /dev/null; then
echo "✅ Imagen Docker encontrada"
else
echo "⚠️ Descargando imagen Docker..."
docker pull docker.io/develgooapps/gitingest-mcp:main-26b875d
fi
# Verificar archivo de configuración
MCP_CONFIG="$HOME/.config/github-copilot/intellij/mcp.json"
if [ -f "$MCP_CONFIG" ]; then
echo "✅ Archivo mcp.json encontrado"
if grep -q "gitingest" "$MCP_CONFIG"; then
echo "✅ Configuración gitingest encontrada"
else
echo "❌ Configuración gitingest no encontrada en mcp.json"
fi
else
echo "❌ Archivo mcp.json no encontrado en $MCP_CONFIG"
fi
# Verificar que el MCP responda
echo "🧪 Probando conexión con el MCP..."
if echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | \
docker run -i --rm docker.io/develgooapps/gitingest-mcp:main-26b875d > /dev/null 2>&1; then
echo "✅ MCP responde correctamente"
else
echo "❌ MCP no responde - verificar imagen Docker"
fi
echo "🎉 Verificación completada"
echo "💡 Recuerda: El token de GitHub se pasa dinámicamente en cada llamada al MCP"
```
## 📝 Logs
Los logs se pueden configurar con la variable `LOG_LEVEL`:
- `DEBUG`: Información detallada
- `INFO`: Información general (por defecto)
- `WARNING`: Solo advertencias y errores
- `ERROR`: Solo errores
## 🤝 Contribución
1. Fork el proyecto
2. Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
4. Push a la rama (`git push origin feature/AmazingFeature`)
5. Abre un Pull Request
## 📄 Licencia
Este proyecto está bajo la Licencia MIT. Ver el archivo `LICENSE` para más detalles.
## 🆘 Soporte
- **Issues**: [GitHub Issues](https://github.com/your-repo/gitingest-mcp/issues)
- **Documentación**: [GitIngest Docs](https://github.com/coderamp-labs/gitingest)
- **Comunidad**: [Discord](https://discord.gg/zerRaGK9EC)