Jinni

Una herramienta para proporcionar contexto de proyecto a Modelos de Lenguaje de Gran Escala mediante el filtrado y concatenación inteligente de archivos relevantes.

GitHub
274
Prueba este MCPPatrocinado

Documentación

Jinni Banner

Jinni: Lleva tu Proyecto al Contexto

Jinni: Bring Your Project Into Context MCP server

Jinni es una herramienta para proporcionar eficientemente a los Modelos de Lenguaje de Gran Tamaño el contexto de tus proyectos. Ofrece una vista consolidada de los archivos relevantes del proyecto, superando las limitaciones e ineficiencias de leer archivos uno por uno. El contenido de cada archivo va precedido de un encabezado simple que indica su ruta:

```path=src/app.py
print("hello")

La filosofía detrás de esta herramienta es que las ventanas de contexto de los LLM son grandes, los modelos son inteligentes, y ver directamente tu proyecto es lo que mejor prepara al modelo para ayudarte con cualquier cosa que le plantees.

Existe un servidor MCP (Model Context Protocol) para la integración con herramientas de IA y una utilidad de línea de comandos (CLI) para uso manual que copia el contexto del proyecto al portapapeles, listo para pegar donde lo necesites.

Estas herramientas tienen opiniones definidas sobre lo que cuenta como contexto relevante del proyecto para funcionar de la mejor manera sin configuración previa en la mayoría de los casos de uso, excluyendo automáticamente:

* Archivos binarios
* Dotfiles y directorios ocultos
* Convenciones de nomenclatura comunes para logs, directorios de compilación, archivos temporales, etc.

Las inclusiones/exclusiones son personalizables con total granularidad si es necesario usando .contextfiles – esto funciona como .gitignore excepto que define inclusiones. Los archivos .gitignore también se respetan automáticamente, pero cualquier regla en .contextfiles tiene prioridad.

El servidor MCP puede proporcionar tanto o tan poco del proyecto como se desee. Por defecto, el alcance es todo el proyecto, pero el modelo puede solicitar módulos específicos / patrones coincidentes / etc.

Inicio Rápido con MCP

Archivo de configuración del servidor MCP para Cursor / Roo / Claude Desktop / el cliente que prefieras:

{
    "mcpServers": {
        "jinni": {
            "command": "uvx",
            "args": ["jinni-server"]
        }
    }
}

Opcionalmente puedes restringir el servidor para que solo lea dentro de un árbol por seguridad en caso de que tu LLM se desvíe: añade "--root", "/absolute/path/" a la lista de args.

Instala uv si no está en tu sistema: https://docs.astral.sh/uv/getting-started/installation/

Recarga tu IDE y ya puedes pedirle al agente que lea el contexto.

Si quieres restringir esto a módulos/rutas particulares, solo pídelo, por ejemplo: «Lee el contexto para los tests».

En acción con Cursor:

Usage Example

Nota para Usuarios de Cursor

Cursor puede descartar silenciosamente el contexto que supere el máximo permitido, así que si tienes un proyecto considerable y el agente actúa como si la llamada a la herramienta nunca hubiera ocurrido, intenta reducir lo que estás incluyendo («lee el contexto para xyz»).

Componentes

  1. jinni Servidor MCP:

    • Se integra con clientes MCP como Cursor, Cline, Roo, Claude Desktop, etc.
    • Expone una herramienta read_context que devuelve una cadena concatenada de los contenidos de archivos relevantes de un directorio de proyecto especificado.

  2. jinni CLI:

    • Una herramienta de línea de comandos para generar manualmente el volcado de contexto del proyecto.
    • Útil para proporcionar contexto a los LLM mediante copiar y pegar o entrada de archivos. O canaliza la salida a donde la necesites.

Características

  • Recopilación Eficiente de Contexto: Lee y concatena los archivos relevantes del proyecto en una sola operación.
  • Filtrado Inteligente (Inclusión estilo Gitignore):
    • Utiliza un sistema basado en la sintaxis de .gitignore (el gitwildmatch de la librería pathspec).
    • Carga automáticamente los archivos .gitignore desde la raíz del proyecto hacia abajo. Estas exclusiones pueden ser anuladas por reglas en .contextfiles.
    • Admite configuración jerárquica usando .contextfiles colocados dentro de los directorios de tu proyecto. Las reglas se aplican dinámicamente según el archivo/directorio que se esté procesando.
    • Comportamiento de Coincidencia: Los patrones coinciden con la ruta relativa al directorio objetivo que se está procesando. Las rutas de salida permanecen relativas a la raíz original del proyecto.
    • Comportamiento de la Raíz de Reglas: Cada objetivo tiene su propia raíz de reglas:
      • Los objetivos dentro de la raíz del proyecto (o CWD) usan la raíz del proyecto/CWD como su raíz de reglas
      • Los objetivos externos se usan a sí mismos como su raíz de reglas, garantizando conjuntos de reglas autocontenidos
    • Anulaciones: Admite --overrides (CLI) o rules (MCP) para usar un conjunto específico de reglas de forma exclusiva. Cuando las anulaciones están activas, tanto las reglas predeterminadas integradas como cualquier .contextfiles se ignoran. La coincidencia de rutas para las anulaciones sigue siendo relativa al directorio objetivo.
    • Inclusión Explícita de Objetivos: Los archivos proporcionados explícitamente como objetivos siempre se incluyen (omitiendo las comprobaciones de reglas, pero no las de binario/tamaño).
  • Configuración Personalizable (.contextfiles / Anulaciones):
    • Define con precisión qué archivos/directorios incluir o excluir usando patrones de estilo .gitignore aplicados a la ruta relativa.
    • Los patrones que comienzan con ! niegan la coincidencia (un patrón de exclusión). (Consulta la sección de Configuración a continuación).
  • Manejo de Contexto Grande: Se aborta con un DetailedContextSizeError si el tamaño total de los archivos incluidos supera un límite configurable (predeterminado: 100MB). El mensaje de error incluye una lista de los 10 archivos más grandes que contribuyen al tamaño, ayudándote a identificar candidatos para exclusión. Consulta la sección de Solución de Problemas para obtener orientación sobre cómo gestionar el tamaño del contexto.
  • Encabezados de Metadatos: La salida incluye un encabezado de ruta para cada archivo incluido (p. ej., ````path=src/app.py). Esto se puede desactivar con list_only`.
  • Manejo de Codificación: Intenta múltiples codificaciones de texto comunes (UTF-8, Latin-1, etc.).
  • Modo Solo Lista: Opción para listar únicamente las rutas relativas de los archivos que se incluirían, sin su contenido.

Uso

Servidor MCP (herramienta read_context)

  1. Configuración: Configura tu cliente MCP (p. ej., el claude_desktop_config.json de Claude Desktop) para ejecutar el servidor jinni mediante uvx.
  2. Invocación: Al interactuar con tu LLM a través del cliente MCP, el modelo puede invocar la herramienta read_context.
    • project_root (cadena, obligatorio): La ruta absoluta al directorio raíz del proyecto. El descubrimiento de reglas y las rutas de salida son relativas a esta raíz.
    • targets (matriz JSON de cadenas, obligatorio): Especifica una lista obligatoria de archivo(s)/directorio(s) dentro de project_root a procesar. Debe ser una matriz JSON de rutas de cadena (p. ej., ["path/to/file1", "path/to/dir2"]). Las rutas pueden ser absolutas o relativas a CWD. Todas las rutas objetivo deben resolverse a ubicaciones dentro de project_root. Si se proporciona una lista vacía [], se procesa todo project_root.
    • rules (matriz JSON de cadenas, obligatorio): Una lista obligatoria de reglas de filtrado en línea (usando sintaxis de estilo .gitignore, p. ej., ["src/**/*.py", "!*.tmp"]). Proporciona una lista vacía [] si no se necesitan reglas específicas (esto usará los valores predeterminados integrados). Si no está vacía, estas reglas se usan de forma exclusiva, ignorando los valores predeterminados integrados y .contextfiles.
    • list_only (booleano, opcional): Si es verdadero, devuelve solo la lista de rutas de archivo relativas en lugar del contenido.
    • size_limit_mb (entero, opcional): Anula el límite de tamaño de contexto en MB.
    • debug_explain (booleano, opcional): Habilita el registro de depuración en el servidor.
    • exclusions (objeto, opcional): Configuración de exclusión con tres campos opcionales:
      • global (matriz de cadenas): Palabras clave para excluir globalmente (p. ej., ["tests", "deprecated"])
      • scoped (objeto): Mapa de rutas a matrices de palabras clave para exclusiones con alcance (p. ej., {"src/legacy": ["old", "deprecated"]})
      • patterns (matriz de cadenas): Patrones de archivo para excluir (p. ej., ["*.test.js", "*_old.*"])
    1. Salida: La herramienta devuelve una sola cadena que contiene el contenido concatenado (con encabezados) o la lista de archivos. Las rutas en encabezados/listas son relativas al project_root proporcionado. En caso de un error de tamaño de contexto, devuelve un DetailedContextSizeError con detalles sobre los archivos más grandes.

Servidor MCP (herramienta usage)

  • Invocación: El modelo puede invocar la herramienta usage (no se necesitan argumentos).
  • Salida: Devuelve el contenido del archivo README.md como una cadena.

(Las instrucciones detalladas de configuración del servidor variarán según tu cliente MCP. En general, necesitas configurar el cliente para ejecutar el servidor Jinni).

Ejecutando el Servidor:

  • Método Recomendado: Usa uvx para ejecutar el punto de entrada del servidor directamente (requiere que el paquete jinni esté publicado en PyPI o sea localizable por uvx): 
    uvx jinni-server [OPTIONS]
    Ejemplo de configuración de cliente MCP (p. ej., claude_desktop_config.json): 
    {
  "mcpServers": {
    "jinni": {
      "command": "uvx",
      "args": ["jinni-server"]
    }
  }
}

Opcionalmente puedes restringir el servidor para que solo lea dentro de un árbol por seguridad en caso de que tu LLM se desvíe: añade "--root", "/absolute/path/" a la lista de args.

Consulta la documentación de tu cliente MCP específico para conocer los pasos de configuración precisos. Asegúrate de que uv esté instalado

Utilidad de Línea de Comandos (CLI jinni)

jinni [OPTIONS] [<PATH...>]
  • <PATH...> (opcional): Una o más rutas a los directorios o archivos del proyecto a analizar. Por defecto usa el directorio actual (.) si no se proporciona ninguno.
  • -r <DIR> / --root <DIR> (opcional): Especifica el directorio raíz del proyecto. Si se proporciona, el descubrimiento de reglas comienza aquí y las rutas de salida son relativas a este directorio. Si se omite, la raíz se infiere del ancestro común de los argumentos <PATH...> (o CWD si solo se procesa '.').
  • --output <FILE> / -o <FILE> (opcional): Escribe la salida en <FILE> en lugar de imprimirla en la salida estándar.
  • --list-only / -l (opcional): Solo lista las rutas relativas de los archivos que se incluirían.
  • --overrides <FILE> (opcional): Añade reglas de <FILE> como reglas de alta prioridad además de .contextfiles y .gitignore.
  • --size-limit-mb <MB> / -s <MB> (opcional): Anula el tamaño máximo de contexto en MB.
  • --debug-explain (opcional): Imprime razones detalladas de inclusión/exclusión en stderr y jinni_debug.log.
  • --root <DIR> / -r <DIR> (opcional): Ver arriba.
  • --no-copy (opcional): Evita copiar automáticamente el contenido de salida al portapapeles del sistema al imprimir en la salida estándar (el valor predeterminado es copiar).
  • --not <keyword> (opcional, repetible): Excluye módulos/directorios que coincidan con la palabra clave (p. ej., --not tests --not vendor). Se puede usar varias veces.
  • --not-in <path:keywords> (opcional, repetible): Excluye palabras clave específicas dentro de una ruta (p. ej., --not-in src/legacy:old,deprecated). Se puede usar varias veces.
  • --not-files <pattern> (opcional, repetible): Excluye archivos que coincidan con el patrón (p. ej., --not-files '*.test.js' --not-files '*_old.*'). Se puede usar varias veces.
  • --keep-only <modules> (opcional): Conserva solo los módulos/directorios especificados, excluye todo lo demás (separados por comas, p. ej., --keep-only src,lib,docs).

Ejemplos de Exclusión

Ejemplos de CLI:

# Exclude all test directories
jinni --not tests

# Exclude multiple keywords
jinni --not tests --not vendor --not deprecated

# Exclude old code only in specific paths
jinni --not-in src/legacy:old,deprecated --not-in lib/v1:legacy

# Exclude specific file patterns
jinni --not-files "*.test.js" --not-files "*_old.*"

# Keep only src and docs, exclude everything else
jinni --keep-only src,docs

# Combine different exclusion types
jinni --not tests --not-in src/experimental:wip --not-files "*.bak"

Nota: Los comandos de exclusión (banderas --not*) funcionan además de las reglas existentes de .gitignore y .contextfiles. Filtran aún más lo que de otro modo se incluiría.

Ejemplos de MCP:

{
  "project_root": "/path/to/project",
  "targets": [],
  "rules": [],
  "exclusions": {
    "global": ["tests", "vendor"],
    "scoped": {
      "src/legacy": ["old", "deprecated"],
      "lib/experimental": ["wip", "unstable"]
    },
    "patterns": ["*.test.js", "*_backup.*"]
  }
}

Instalación

Puedes instalar Jinni usando pip o uv:

Usando pip:

pip install jinni

Usando uv:

uv pip install jinni

Esto hará que el comando CLI jinni esté disponible en tu entorno. Consulta la sección «Ejecutando el Servidor» anterior para saber cómo iniciar el servidor MCP según tu método de instalación.

Notas específicas de plataforma

Windows + WSL

Jinni v0.1.7+ convierte automáticamente las rutas WSL.

Proporciona cualquiera de estas como project_root (CLI --root o argumento MCP):

/home/user/project
vscode-remote://wsl+Ubuntu-22.04/home/user/project

No se requieren envoltorios, montajes ni banderas adicionales: Jinni resuelve la ruta UNC (\\wsl$\...) en Windows automáticamente. Formato de ruta UNC: Jinni siempre usa \\wsl$\<distro>\... para máxima compatibilidad con todas las versiones de Windows que admiten WSL.
Manejo del nombre de distribución: Se permiten espacios y la mayoría de caracteres especiales en el nombre de la distribución. Solo los caracteres UNC realmente ilegales se reemplazan con _.
Caché: Las búsquedas y conversiones de rutas WSL se almacenan en caché por rendimiento. Si instalas WSL mientras Jinni está en ejecución, reinicia Jinni para que detecte el nuevo wslpath.
Exclusión voluntaria: Establece la variable de entorno JINNI_NO_WSL_TRANSLATE=1 para deshabilitar toda la lógica de traducción de rutas WSL.

Solo se traducen los URI wsl+<distro> y las rutas POSIX absolutas (que comienzan con /); para remotos SSH o contenedores, ejecuta Jinni dentro de ese entorno.

Sistema operativo en tiempo de ejecuciónLo que pasasLo que devuelve _translate_wsl_path()
Windowsvscode-remote://wsl%2BUbuntu/home/a/b\\wsl$\\Ubuntu\home\a\b
Windows/home/a/b\\wsl$\\Ubuntu\home\a\b (vía wslpath)
Linux/WSLvscode-remote://wsl+Ubuntu/home/a/b/home/a/b
Linux/WSL/home/a/b/home/a/b (sin cambios)

Ejemplos

  • Vuelca el contexto de my_project/ en la consola:

    jinni ./my_project/ # Process a single directory
jinni ./src ./docs/README.md # Process multiple targets
jinni # Process current directory (.)

  • Lista los archivos que se incluirían en my_project/ sin contenido:

    jinni -l ./my_project/
jinni --list-only ./src ./docs/README.md

  • Vuelca el contexto de my_project/ a un archivo llamado context_dump.txt:

    jinni -o context_dump.txt ./my_project/

  • Usa reglas de anulación de custom.rules en lugar de .contextfiles:

    jinni --overrides custom.rules ./my_project/

  • Muestra información de depuración:

    jinni --debug-explain ./src

  • Vuelca el contexto (la salida se copia automáticamente al portapapeles por defecto):

    jinni ./my_project/

  • Vuelca el contexto pero no lo copies al portapapeles:

    jinni --no-copy ./my_project/

Configuración (.contextfiles y anulaciones)

Jinni usa .contextfiles (o un archivo de anulación) para determinar qué archivos y directorios incluir o excluir, según patrones de estilo .gitignore.

  • Principio fundamental: Las reglas se aplican dinámicamente durante el recorrido, en relación con el directorio objetivo actual que se está procesando.

  • Ubicación (.contextfiles): Coloca .contextfiles en cualquier directorio. El descubrimiento de reglas comienza desde la raíz de reglas (raíz del proyecto para objetivos internos, el propio objetivo para objetivos externos) y continúa hacia abajo hasta el directorio actual que se está procesando.

  • Formato: Texto plano, codificado en UTF-8, un patrón por línea.

  • Sintaxis: Usa la sintaxis de patrones estándar de .gitignore (específicamente la implementación de gitwildmatch de pathspec).

    • Comentarios: Las líneas que comienzan con # se ignoran.
    • Patrones de inclusión: Especifica archivos/directorios a incluir (p. ej., src/**/*.py, *.md, /config.yaml).
    • Patrones de exclusión: Las líneas que comienzan con ! indican que un archivo coincidente debe excluirse (niega el patrón).
    • Anclaje: Un / inicial ancla el patrón al directorio que contiene el .contextfiles.
    • Coincidencia de directorios: Un / final coincide solo con directorios.
    • Comodines: *, **, ? funcionan como en .gitignore.

  • Lógica de aplicación de reglas:

    1. Determinar el objetivo: Jinni identifica el directorio objetivo (ya sea proporcionado explícitamente o la raíz del proyecto).
    2. Verificación de anulaciones: Si se proporcionan --overrides (CLI) o rules (MCP), estas reglas se usan exclusivamente. Todos los .contextfiles y los valores predeterminados integrados se ignoran. La coincidencia de rutas es relativa al directorio objetivo.
    3. Reglas de contexto dinámico (sin anulaciones): Al procesar un archivo o subdirectorio:
      • Jinni encuentra todos los .gitignore y .contextfiles desde la raíz de reglas hasta el directorio del elemento actual.
      • Las reglas se combinan en orden: valores predeterminados integrados, reglas de .gitignore, reglas de .contextfiles (que tienen prioridad).
      • Compila estas reglas combinadas en una especificación (PathSpec).
      • Compara la ruta actual del archivo/subdirectorio, calculada relativa al directorio objetivo, contra esta especificación.
    4. Coincidencia: El último patrón en el conjunto de reglas combinadas que coincida con la ruta relativa del elemento determina su destino. ! niega la coincidencia. Si ningún patrón definido por el usuario coincide, el elemento se incluye a menos que coincida con una exclusión predeterminada integrada (como !.*).
    5. Manejo del objetivo: Los archivos explícitamente objetivo omiten las verificaciones de reglas. Las rutas de salida siempre permanecen relativas al project_root original.

Ejemplos (.contextfiles)

Ejemplo 1: Incluir código fuente de Python y configuración raíz

Ubicado en my_project/.contextfiles:

# Include all Python files in the src directory and subdirectories
src/**/*.py

# Include the main config file at the root of the project
/config.json

# Include all markdown files anywhere
*.md

# Exclude any test data directories found anywhere
!**/test_data/

Ejemplo 2: Anulación en un subdirectorio

Ubicado en my_project/src/.contextfiles:

# In addition to rules inherited from parent .contextfiles...

# Include specific utility scripts in this directory
utils/*.sh

# Exclude a specific generated file within src, even if *.py is included elsewhere
!generated_parser.py

Desarrollo

  • Detalles de diseño: DESIGN.md

  • Ejecutar el servidor localmente: Durante el desarrollo (después de instalar con uv pip install -e . o similar), puedes ejecutar el módulo del servidor directamente:

    python -m jinni.server [OPTIONS]

    Ejemplo de configuración de cliente MCP para desarrollo local:

    {
  "mcpServers": {
    "jinni": {
      // Adjust python path if needed, or ensure the correct environment is active
      "command": "python -m jinni.server"
      // Optionally constrain the server to only read within a tree (recommended for security):
      // "command": "python -m jinni.server --root /absolute/path/to/repo"
    }
  }
}

Solución de problemas

Errores de tamaño de contexto (DetailedContextSizeError)

Si encuentras un error que indica que se excedió el límite de tamaño de contexto, Jinni proporcionará una lista de los 10 archivos más grandes que intentó incluir. Esto te ayuda a identificar posibles candidatos para exclusión.

Para resolver esto:

  1. Revisa los archivos más grandes: Verifica la lista proporcionada en el mensaje de error. ¿Hay archivos grandes (p. ej., archivos de datos, registros, artefactos de compilación, medios) que no deberían ser parte del contexto del LLM?
  2. Configura exclusiones: Usa .contextfiles o las opciones --overrides / rules para excluir archivos o directorios innecesarios.
    • Ejemplo (.contextfiles): Para excluir todos los archivos .log y un directorio de datos grande específico: 
      # Exclude all log files
!*.log

# Exclude a large data directory
!large_data_files/
    • Consulta la sección Configuración anterior para obtener sintaxis y uso detallados.
  3. Aumenta el límite (úsalo con precaución): Si todos los archivos incluidos son realmente necesarios, puedes aumentar el límite de tamaño usando --size-limit-mb (CLI) o size_limit_mb (MCP). Ten en cuenta los límites de la ventana de contexto del LLM y los costos de procesamiento.
  4. Usa jinni usage / usage: Si necesitas consultar estas instrucciones o los detalles de configuración mientras solucionas problemas, usa el comando jinni usage o la herramienta MCP usage.