Jinni: Pon tu proyecto en contexto

Jinni es una herramienta que proporciona eficientemente a los Modelos de Lenguaje Grandes el contexto de sus proyectos. Ofrece una vista consolidada de los archivos relevantes del proyecto, con metadatos incluidos, superando las limitaciones e ineficiencias de leer los archivos uno por uno.

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

Hay un servidor MCP (Protocolo de contexto de modelo) 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 pegarlo donde lo necesite.

Estas herramientas tienen opiniones firmes sobre lo que se considera un contexto de proyecto relevante para funcionar mejor de inmediato en la mayoría de los casos de uso, excluyendo automáticamente:

Las inclusiones/exclusiones se pueden personalizar con granularidad completa si es necesario usando .contextfiles: esto funciona como .gitignore excepto que define las inclusiones.

El servidor MCP puede proporcionar la parte del proyecto que se desee. Por defecto, el alcance es el proyecto completo, pero el modelo puede solicitar módulos específicos, patrones coincidentes, etc.

Guía de inicio rápido de MCP

Configuración del servidor MCP para Cursor / Roo / Claude Desktop / cliente de elección:

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

Recargue su IDE y ahora podrá pedirle al agente que lea en contexto.

Si desea restringir esto a módulos o rutas particulares, simplemente pregunte, por ejemplo, "Leer contexto para pruebas".

En acción con Cursor:

Nota para los usuarios del cursor

El cursor puede eliminar silenciosamente el contexto que es más grande que el máximo permitido, por lo que si tiene un proyecto considerable y el agente actúa como si la llamada a la herramienta nunca hubiera ocurrido, intente reducir lo que está incorporando ("leer contexto para xyz")

Componentes

1. Servidor MCP jinni :
   • Se integra con clientes MCP como Cursor, Cline, Roo, Claude Desktop, etc.
   • Expone una herramienta read_context que devuelve una cadena concatenada de 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 introducir contexto en los LLM mediante copiar y pegar o la entrada de archivos. También puede canalizar la salida donde la necesite.

Características

• Recopilación de contexto eficiente: lee y concatena archivos de proyecto relevantes en una sola operación.
• Filtrado inteligente (inclusión al estilo Gitignore):
  • Utiliza un sistema basado en la sintaxis .gitignore ( gitwildmatch de la biblioteca pathspec ).
  • Admite configuración jerárquica mediante .contextfiles ubicados en los directorios del proyecto. Las reglas se aplican dinámicamente según el archivo o directorio que se esté procesando.
  • Comportamiento de coincidencia: Los patrones se comparan con la ruta relativa al directorio de destino que se está procesando (o con la raíz del proyecto si no se especifica un destino específico). Por ejemplo, si se selecciona src/ , la regla !app.py en src/.contextfiles coincidirá con app.py Las rutas de salida se mantienen relativas a la raíz del proyecto original.
  • Anulaciones: Admite --overrides (CLI) o rules (MCP) para usar exclusivamente un conjunto específico de reglas. Cuando las anulaciones están activas, se ignoran tanto las reglas predeterminadas integradas como cualquier archivo .contextfiles . La coincidencia de rutas para las anulaciones sigue siendo relativa al directorio de destino.
  • Inclusión explícita de destinos: Los archivos proporcionados explícitamente como destinos siempre se incluyen (omitiendo las comprobaciones de reglas, pero no las de binario/tamaño). Los directorios proporcionados explícitamente como destinos siempre se introducen, y el descubrimiento/coincidencia de reglas se realiza en relación con ese directorio de destino.
• Configuración personalizable ( .contextfiles / Anulaciones):
  • Define con precisión qué archivos/directorios incluir o excluir utilizando patrones de estilo .gitignore aplicados a la ruta relativa .
  • Los patrones que empiezan con ! invalidan la coincidencia (un patrón de exclusión). (Consulte la sección Configuración a continuación).
• Manejo de contextos grandes: Se cancela con un error DetailedContextSizeError si el tamaño total de los archivos incluidos supera un límite configurable (predeterminado: 100 MB). El mensaje de error incluye una lista de los 10 archivos más grandes que contribuyen al tamaño, lo que ayuda a identificar candidatos para la exclusión. Consulte la sección "Solución de problemas" para obtener instrucciones sobre la gestión del tamaño del contexto.
• Encabezados de metadatos: la salida incluye la ruta del archivo, el tamaño y la hora de modificación de cada archivo incluido (se puede deshabilitar con list_only ).
• Manejo de codificación: intenta múltiples codificaciones de texto comunes (UTF-8, Latin-1, etc.).
• Modo de solo lista: opción para enumerar solo las rutas relativas de los archivos que se incluirían, sin su contenido.

Uso

Servidor MCP (herramienta read_context )

1. Configuración: configure su cliente MCP (por ejemplo, claude_desktop_config.json de Claude Desktop) para ejecutar el servidor jinni a través de uvx .
2. Invocación: al interactuar con su LLM a través del cliente MCP, el modelo puede invocar la herramienta read_context .
   • project_root (cadena, obligatoria): La ruta absoluta al directorio raíz del proyecto. Las rutas de descubrimiento de reglas y de salida son relativas a esta raíz.
   • targets (matriz JSON de cadenas, obligatoria): Especifica una lista obligatoria de archivos/directorios dentro de project_root para 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 de destino deben resolverse en ubicaciones dentro de project_root . Si se proporciona una lista [] vacía, se procesa todo project_root .
   • rules (matriz JSON de cadenas, obligatoria): Una lista obligatoria de reglas de filtrado en línea (con sintaxis de estilo .gitignore , p. ej., ["src/**/*.py", "!*.tmp"] ). Proporcione una lista vacía [] si no se necesitan reglas específicas (esto usará los valores predeterminados integrados). Si no está vacía, se usan exclusivamente estas reglas, ignorando los valores predeterminados integrados y .contextfiles .
   • list_only (booleano, opcional): si es verdadero, devuelve solo la lista de rutas de archivos relativas en lugar del contenido.
   • size_limit_mb (entero, opcional): anula el límite de tamaño del contexto en MB.
   • debug_explain (booleano, opcional): habilita el registro de depuración en el servidor.
   3. Salida: La herramienta devuelve una sola cadena con el contenido concatenado (con encabezados) o la lista de archivos. Las rutas en los encabezados/listas son relativas al valor project_root proporcionado. En caso de un error de tamaño del contexto, devuelve un error 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 su cliente MCP. Generalmente, debe configurar el cliente para ejecutar el servidor Jinni).

Ejecutando el servidor:

• Método recomendado: utilice uvx para ejecutar el punto de entrada del servidor directamente (requiere que el paquete jinni esté publicado en PyPI o que uvx pueda encontrarlo):
  uvx jinni-server [OPTIONS]
  Ejemplo de configuración de cliente MCP (por ejemplo, claude_desktop_config.json ):
  { "mcpServers": { "jinni": { "command": "uvx jinni-server" // Optionally constrain the server to only read within a tree (recommended for security): // "command": "uvx jinni-server --root /absolute/path/" } } }

Consulte la documentación de su cliente MCP para conocer los pasos de configuración precisos. Asegúrese de que uv (para uvx ) o el entorno de Python correcto (para python -m ) sean accesibles. La herramienta usage corresponde al comando jinni usage de la CLI.

Utilidad de línea de comandos ( jinni CLI)

• <PATH...> (opcional): Una o más rutas a los directorios o archivos del proyecto que se analizarán. Si no se proporciona ninguna, el valor predeterminado es el directorio actual ( . ).
• -r <DIR> / --root <DIR> (opcional): Especifica el directorio raíz del proyecto. Si se proporciona, la detección 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 imprimir en la salida estándar.
• --list-only / -l (opcional): solo enumera las rutas relativas de los archivos que se incluirán.
• --overrides <FILE> (opcional): utiliza reglas de <FILE> en lugar de descubrir .contextfiles .
• --size-limit-mb <MB> / -s <MB> (opcional): anula el tamaño máximo del 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).

Instalación

Puedes instalar Jinni usando pip o uv :

Usando pip:

Usando uv:

Esto hará que el comando CLI jinni esté disponible en su entorno. Consulte la sección "Ejecución del servidor" más arriba para saber cómo iniciar el servidor MCP según su método de instalación.

Notas específicas de la plataforma

Windows + WSL

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

Proporcione cualquiera de estos como project_root (argumento CLI --root o MCP):

No se requieren envoltorios, montajes ni indicadores 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 compatibles con WSL. Manejo de nombres de distribución: Se permiten espacios y la mayoría de los caracteres especiales en el nombre de la distribución. Solo los caracteres UNC no válidos se reemplazan con _ . Almacenamiento en caché: Las búsquedas y conversiones de rutas de WSL se almacenan en caché para mejorar el rendimiento. Si instala WSL mientras Jinni se está ejecutando, reinicie Jinni para obtener la nueva wslpath . Desactivación: Configure la variable de entorno JINNI_NO_WSL_TRANSLATE=1 para desactivar toda la lógica de traducción de rutas de WSL.

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

Ejemplos

• Vuelca el contexto de my_project/ a la consola:
  jinni ./my_project/ # Process a single directory jinni ./src ./docs/README.md # Process multiple targets jinni # Process current directory (.)
• Lista de 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/
• Utilice reglas de anulación de custom.rules en lugar de .contextfiles :
  jinni --overrides custom.rules ./my_project/
• Mostrar información de depuración:
  jinni --debug-explain ./src
• Contexto de volcado (la salida se copia automáticamente al portapapeles de manera predeterminada):
  jinni ./my_project/
• Volcar contexto pero no copiar 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, basándose en patrones de estilo .gitignore .

• Principio básico: las reglas se aplican dinámicamente durante el recorrido, en relación con el directorio de destino actual que se está procesando.
• Ubicación ( .contextfiles ): Coloque .contextfiles en cualquier directorio. Al procesar un directorio (ya sea el destino inicial o un subdirectorio), Jinni busca archivos .contextfiles a partir de ese directorio. Las reglas de directorios superiores fuera del directorio de destino actual se ignoran al procesar dentro de ese directorio.
• Formato: Texto simple, codificado en UTF-8, un patrón por línea.
• Sintaxis: utiliza la sintaxis del patrón estándar .gitignore (específicamente la implementación gitwildmatch de pathspec ).
  • Comentarios: Las líneas que comienzan con # se ignoran.
  • Patrones de inclusión: especifique los archivos/directorios que desea incluir (por ejemplo, src/**/*.py , *.md , /config.yaml ).
  • Patrones de exclusión: Las líneas que comienzan con ! indican que se debe excluir un archivo coincidente (niega el patrón).
  • Anclaje: Un / principal ancla el patrón al directorio que contiene los .contextfiles .
  • Coincidencia de directorios: un / final coincide únicamente con directorios.
  • Los comodines: * , ** , ? funcionan como en .gitignore .
• Lógica de aplicación de reglas:
  1. Determinar el objetivo: Jinni identifica el directorio de destino (ya sea proporcionado explícitamente o la raíz del proyecto).
  2. Comprobación de anulación: Si se proporcionan --overrides (CLI) o rules (MCP), estas reglas se utilizan exclusivamente. Se ignoran todos .contextfiles y los valores predeterminados integrados. La coincidencia de rutas es relativa al directorio de destino.
  3. Reglas de contexto dinámico (sin anulaciones): al procesar un archivo o subdirectorio dentro del directorio de destino:
     • Jinni encuentra todos .contextfiles desde el directorio de destino hasta el directorio del elemento actual.
     • Combina las reglas de estos .contextfiles descubiertos con las reglas predeterminadas integradas.
     • Compila estas reglas combinadas en una especificación ( PathSpec ).
     • Coincide con la ruta del archivo/subdirectorio actual, calculada en relación al directorio de destino , frente a esta especificación.
  4. Coincidencia: El último patrón del conjunto de reglas combinadas que coincide 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 (como !.* ).
  5. Manejo de destinos: Los archivos con destino explícito eluden las comprobaciones de reglas. Los directorios con destino explícito se convierten en la raíz para la detección de reglas y la coincidencia de su contenido. Las rutas de salida siempre se mantienen relativas al project_root original.

Ejemplos ( .contextfiles )

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

Ubicado en my_project/.contextfiles :

Ejemplo 2: Anulación en un subdirectorio

Ubicado en my_project/src/.contextfiles :

Desarrollo

• Detalles del diseño: DESIGN.md
• Ejecución del servidor localmente: durante el desarrollo (después de la instalación con uv pip install -e . o similar), puede 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 encuentra un error que indica que se superó el límite de tamaño del contexto, Jinni le proporcionará una lista de los 10 archivos más grandes que intentó incluir. Esto le ayudará a identificar posibles candidatos para la exclusión.

Para resolver esto:

1. Revisar los archivos más grandes: Consulta la lista proporcionada en el mensaje de error. ¿Hay archivos grandes (p. ej., archivos de datos, registros, artefactos de compilación, archivos multimedia) que no deberían formar parte del contexto del LLM?
2. Configurar exclusiones: utilice .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/
   • Consulte la sección Configuración más arriba para obtener información detallada sobre la sintaxis y el uso.
3. Aumentar el límite (Usar con precaución): Si todos los archivos incluidos son realmente necesarios, puede aumentar el límite de tamaño usando --size-limit-mb (CLI) o size_limit_mb (MCP). Tenga en cuenta los límites de la ventana de contexto de LLM y los costos de procesamiento.
4. Utilice jinni usage / usage : si necesita volver a consultar estas instrucciones o los detalles de configuración mientras soluciona problemas, utilice el comando jinni usage o la herramienta MCP usage .