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

# 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

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

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

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

# Usar el script de inicio (recomendado)
./start.sh

# O ejecutar directamente
python -m gitingest_mcp.mcp_server

Docker

# Ejecutar con docker-compose
docker-compose up

# O ejecutar directamente
docker run -e GITHUB_TOKEN=your_token_here gitingest-mcp

🔧 Herramientas MCP Disponibles

1. ingest_repository

Genera un digest de texto de un repositorio de GitHub.

Parámetros:

• repository_url (requerido): URL del repositorio de GitHub
• github_token (opcional): Token de GitHub (si no está en variables de entorno)
• branch (opcional): Rama específica a analizar
• include_patterns (opcional): Patrones de archivos a incluir
• exclude_patterns (opcional): Patrones de archivos a excluir
• max_file_size (opcional): Tamaño máximo de archivo en bytes

Ejemplo:

{
  "name": "ingest_repository",
  "arguments": {
    "repository_url": "https://github.com/user/private-repo",
    "include_patterns": ["*.py", "*.js", "*.md"],
    "exclude_patterns": ["node_modules/*", "*.log"],
    "max_file_size": 51200
  }
}

2. ingest_repository_async

Versión asíncrona para procesamiento por lotes.

3. validate_repository_url

Valida si una URL es un repositorio de GitHub válido.

📊 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

Uso con Imagen Docker Publicada (Recomendado)

Para usar la imagen Docker publicada en GitHub Container Registry:

{
  "mcpServers": {
    "gitingest": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "GITHUB_TOKEN",
        "ghcr.io/gooapps/gitingest-mcp:latest"
      ],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

Uso con Imagen Docker Local

Si prefieres construir la imagen localmente:

{
  "mcpServers": {
    "gitingest": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "GITHUB_TOKEN",
        "gitingest-mcp:latest"
      ],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

Configuración Estilo Atlassian

Para usar con herramientas que requieren configuración similar al MCP de Atlassian:

{
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "-e", "GITHUB_TOKEN",
    "-e", "LOG_LEVEL",
    "-e", "GITINGEST_MAX_FILE_SIZE",
    "-e", "GITINGEST_TIMEOUT",
    "ghcr.io/gooapps/gitingest-mcp:latest"
  ],
  "env": {
    "GITHUB_TOKEN": "",
    "LOG_LEVEL": "INFO",
    "GITINGEST_MAX_FILE_SIZE": "1048576",
    "GITINGEST_TIMEOUT": "300"
  }
}

Ejemplo de Uso con Otros Clientes MCP

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    async with stdio_client(StdioServerParameters(
        command="python",
        args=["mcp_server.py"]
    )) as (read, write):
        async with ClientSession(read, write) as session:
            # Inicializar
            await session.initialize()
            
            # Listar herramientas
            tools = await session.list_tools()
            print("Herramientas disponibles:", tools)
            
            # Usar herramienta
            result = await session.call_tool(
                "ingest_repository",
                {
                    "repository_url": "https://github.com/user/repo",
                    "include_patterns": ["*.py", "*.md"]
                }
            )
            print("Resultado:", result)

asyncio.run(main())

🐳 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

Error: "GitIngest package not found"

# Instalar GitIngest
pip install gitingest

# O verificar que el CLI esté disponible
gitingest --help

Error: "GitHub token required"

# Configurar token de GitHub
export GITHUB_TOKEN=your_token_here

# O crear archivo .env
echo "GITHUB_TOKEN=your_token_here" > .env

Error: "Repository not found"

• Verifica que la URL del repositorio sea correcta
• Asegúrate de que el token tenga permisos para el repositorio
• Para repositorios privados, el token debe tener scope repo

📝 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
• Documentación: GitIngest Docs
• Comunidad: Discord