Jinni: Bring Your Project Into Context

Jinni: Bringen Sie Ihr Projekt in den Kontext

Jinni ist ein Tool, das Large Language Models effizient den Kontext Ihrer Projekte bereitstellt. Es bietet eine konsolidierte Ansicht relevanter Projektdateien und überwindet so die Einschränkungen und Ineffizienzen, die beim Lesen einzelner Dateien entstehen. Jedem Dateiinhalt ist ein einfacher Header vorangestellt, der den Pfad angibt:

Die Philosophie hinter diesem Tool besteht darin, dass LLM-Kontextfenster groß und Modelle intelligent sind und dass das Modell durch die direkte Anzeige Ihres Projekts optimal für alle Aufgaben gerüstet ist, die Sie ihm stellen.

Es gibt einen MCP-Server (Model Context Protocol) für die Integration mit KI-Tools und ein Befehlszeilenprogramm (CLI) für die manuelle Verwendung, das den Projektkontext in die Zwischenablage kopiert und ihn dort einfügt, wo Sie ihn benötigen.

Diese Tools haben eine klare Meinung dazu, was als relevanter Projektkontext gilt, um in den meisten Anwendungsfällen sofort einsatzbereit zu sein, und schließen Folgendes automatisch aus:

Einschlüsse/Ausschlüsse können bei Bedarf mithilfe von .contextfiles vollständig detailliert angepasst werden – dies funktioniert wie .gitignore, außer dass Einschlüsse definiert werden.

Der MCP-Server kann beliebig viele oder wenige Projektinhalte bereitstellen. Standardmäßig umfasst der Umfang das gesamte Projekt, das Modell kann jedoch bestimmte Module, passende Muster usw. anfordern.

MCP-Schnellstart

MCP-Serverkonfigurationsdatei für Cursor / Roo / Claude Desktop / Client der Wahl:

Sie können den Server optional aus Sicherheitsgründen so einschränken, dass er nur innerhalb eines Baums liest, falls Ihr LLM ausfällt: Fügen Sie der args "--root", "/absolute/path/" hinzu.

Installieren Sie uv, falls es nicht auf Ihrem System vorhanden ist: https://docs.astral.sh/uv/getting-started/installation/

Laden Sie Ihre IDE neu und Sie können den Agenten jetzt bitten, im Kontext zu lesen.

Wenn Sie dies auf bestimmte Module/Pfade beschränken möchten, fragen Sie einfach – z. B. „Kontext für Tests lesen“.

In Aktion mit Cursor:

Hinweis für Cursor-Benutzer

Der Cursor kann Kontext, der größer als das zulässige Maximum ist, stillschweigend löschen. Wenn Sie also ein umfangreiches Projekt haben und der Agent so tut, als hätte der Tool-Aufruf nie stattgefunden, versuchen Sie, die Menge, die Sie einbringen, zu reduzieren („Kontext für xyz lesen“).

Komponenten

1. jinni MCP-Server:
   • Integriert mit MCP-Clients wie Cursor, Cline, Roo, Claude Desktop usw.
   • Stellt ein read_context -Tool bereit, das eine zusammengesetzte Zeichenfolge mit relevanten Dateiinhalten aus einem angegebenen Projektverzeichnis zurückgibt.
2. jinni -CLI:
   • Ein Befehlszeilentool zum manuellen Generieren des Projektkontext-Dumps.
   • Nützlich, um LLMs Kontext per Kopieren und Einfügen oder Dateieingabe zuzuführen. Oder leiten Sie die Ausgabe dorthin weiter, wo Sie sie benötigen.

Merkmale

• Effiziente Kontexterfassung: Liest und verkettet relevante Projektdateien in einem Vorgang.
• Intelligente Filterung (Einbeziehung im Gitignore-Stil):
  • Verwendet ein auf .gitignore -Syntax basierendes System ( gitwildmatch der pathspec Bibliothek).
  • Unterstützt hierarchische Konfiguration mithilfe von .contextfiles in Ihren Projektverzeichnissen. Regeln werden dynamisch basierend auf der verarbeiteten Datei/dem verarbeiteten Verzeichnis angewendet.
  • Abgleichsverhalten: Muster werden mit dem Pfad relativ zum verarbeiteten Zielverzeichnis (oder dem Projektstammverzeichnis, wenn kein spezifisches Ziel angegeben ist) abgeglichen. Wenn beispielsweise src/ als Zielverzeichnis verwendet wird, entspricht die Regel !app.py in src/.contextfiles``app.py . Ausgabepfade bleiben relativ zum ursprünglichen Projektstammverzeichnis.
  • Overrides: Unterstützt --overrides (CLI) oder rules (MCP), um einen bestimmten Regelsatz exklusiv zu verwenden. Bei aktiven Overrides werden sowohl integrierte Standardregeln als auch alle .contextfiles ignoriert. Die Pfadzuordnung für Overrides erfolgt weiterhin relativ zum Zielverzeichnis.
  • Explizite Zielaufnahme: Explizit als Ziele angegebene Dateien werden immer aufgenommen (Regelprüfungen werden umgangen, Binär-/Größenprüfungen jedoch nicht). Explizit als Ziele angegebene Verzeichnisse werden immer eingegeben, und die Regelerkennung/-abgleichung erfolgt dann relativ zu diesem Zielverzeichnis.
• Anpassbare Konfiguration ( .contextfiles /Overrides):
  • Definieren Sie genau, welche Dateien/Verzeichnisse ein- oder ausgeschlossen werden sollen, indem Sie Muster im .gitignore -Stil auf den relativen Pfad anwenden.
  • Muster, die mit ! beginnen, negieren die Übereinstimmung (ein Ausschlussmuster). (Siehe Abschnitt „Konfiguration“ weiter unten).
• Handhabung großer Kontexte: Der Vorgang wird mit einem DetailedContextSizeError abgebrochen, wenn die Gesamtgröße der eingeschlossenen Dateien einen konfigurierbaren Grenzwert (Standard: 100 MB) überschreitet. Die Fehlermeldung enthält eine Liste der zehn größten Dateien, die zur Größe beitragen, sodass Sie Kandidaten für den Ausschluss identifizieren können. Hinweise zur Verwaltung der Kontextgröße finden Sie im Abschnitt „Fehlerbehebung“.
• Metadaten-Header: Die Ausgabe enthält einen Pfad-Header für jede eingebundene Datei (z. B. ````path=src/app.py ). This can be disabled with .
• Kodierungsbehandlung: Versucht mehrere gängige Textkodierungen (UTF-8, Latin-1 usw.).
• Nur-Liste-Modus: Option zum Auflisten nur der relativen Pfade der einzuschließenden Dateien ohne deren Inhalt.

Verwendung

MCP-Server ( read_context -Tool)

1. Setup: Konfigurieren Sie Ihren MCP-Client (z. B. claude_desktop_config.json von Claude Desktop), um den jinni -Server über uvx auszuführen.
2. Aufruf: Bei der Interaktion mit Ihrem LLM über den MCP-Client kann das Modell das Tool read_context aufrufen.
   • project_root (Zeichenfolge, erforderlich): Der absolute Pfad zum Stammverzeichnis des Projekts. Regelerkennungs- und Ausgabepfade sind relativ zu diesem Stammverzeichnis.
   • targets (JSON-Array von Strings, erforderlich): Gibt eine obligatorische Liste der zu verarbeitenden Dateien/Verzeichnisse innerhalb project_root an. Es muss sich um ein JSON-Array von Stringpfaden handeln (z. B. ["path/to/file1", "path/to/dir2"] ). Pfade können absolut oder relativ zu CWD sein. Alle Zielpfade müssen auf Speicherorte innerhalb project_root verweisen. Bei Angabe einer leeren Liste [] wird das gesamte project_root verarbeitet.
   • rules (JSON-Array von Zeichenfolgen, erforderlich): Eine obligatorische Liste von Inline-Filterregeln (mit .gitignore -Syntax, z. B. ["src/**/*.py", "!*.tmp"] ). Geben Sie eine leere Liste [] an, wenn keine spezifischen Regeln benötigt werden (dadurch werden integrierte Standardwerte verwendet). Wenn die Liste nicht leer ist, werden ausschließlich diese Regeln verwendet, wobei integrierte Standardwerte und .contextfiles ignoriert werden.
   • list_only (boolesch, optional): Wenn „true“, wird anstelle des Inhalts nur die Liste der relativen Dateipfade zurückgegeben.
   • size_limit_mb (Ganzzahl, optional): Überschreibt die Kontextgrößenbeschränkung in MB.
   • debug_explain (boolesch, optional): Aktivieren Sie die Debug-Protokollierung auf dem Server.
   3. Ausgabe: Das Tool gibt eine einzelne Zeichenfolge zurück, die den verknüpften Inhalt (mit Headern) oder die Dateiliste enthält. Pfade in Headern/Listen sind relativ zum angegebenen project_root . Im Falle eines Kontextgrößenfehlers gibt es einen DetailedContextSizeError mit Details zu den größten Dateien zurück.

MCP-Server ( usage )

• Aufruf: Das Modell kann das usage aufrufen (keine Argumente erforderlich).
• Ausgabe: Gibt den Inhalt der Datei README.md als Zeichenfolge zurück.

(Detaillierte Anweisungen zur Servereinrichtung variieren je nach MCP-Client. Im Allgemeinen müssen Sie den Client so konfigurieren, dass er den Jinni-Server ausführt.)

Ausführen des Servers:

• Empfohlene Methode: Verwenden Sie uvx , um den Server-Einstiegspunkt direkt auszuführen (erfordert, dass das jinni -Paket auf PyPI veröffentlicht ist oder von uvx gefunden werden kann):
  uvx jinni-server [OPTIONS]
  Beispiel einer MCP-Clientkonfiguration (z. B. claude_desktop_config.json ):
  { "mcpServers": { "jinni": { "command": "uvx", "args": ["jinni-server"] } } }

Sie können den Server optional aus Sicherheitsgründen so einschränken, dass er nur innerhalb eines Baums liest, falls Ihr LLM ausfällt: Fügen Sie der args "--root", "/absolute/path/" hinzu.

Die genauen Einrichtungsschritte finden Sie in der Dokumentation Ihres MCP-Clients. Stellen Sie sicher, dass uv installiert ist.

Befehlszeilenprogramm ( jinni CLI)

• <PATH...> (optional): Ein oder mehrere Pfade zu den zu analysierenden Projektverzeichnissen oder Dateien. Standardmäßig wird das aktuelle Verzeichnis ( . ) verwendet, wenn keines angegeben ist.
• -r <DIR> / --root <DIR> (optional): Gibt das Stammverzeichnis des Projekts an. Falls angegeben, beginnt die Regelerkennung hier, und die Ausgabepfade sind relativ zu diesem Verzeichnis. Andernfalls wird das Stammverzeichnis aus dem gemeinsamen Vorgänger der <PATH...> Argumente abgeleitet (oder CWD, wenn nur '.' verarbeitet wird).
• --output <FILE> / -o <FILE> (optional): Schreibt die Ausgabe in <FILE> , anstatt sie auf der Standardausgabe zu drucken.
• --list-only / -l (optional): Listet nur die relativen Pfade der Dateien auf, die eingeschlossen werden sollen.
• --overrides <FILE> (optional): Verwenden Sie Regeln aus <FILE> , anstatt .contextfiles zu ermitteln.
• --size-limit-mb <MB> / -s <MB> (optional): Überschreibt die maximale Kontextgröße in MB.
• --debug-explain (optional): Druckt detaillierte Einschluss-/Ausschlussgründe in stderr und jinni_debug.log .
• --root <DIR> / -r <DIR> (optional): Siehe oben.
• --no-copy (optional): Verhindert das automatische Kopieren des Ausgabeinhalts in die Systemzwischenablage beim Drucken in die Standardausgabe (die Standardeinstellung ist „Kopieren“).

Installation

Sie können Jinni mit pip oder uv installieren:

Verwenden von pip:

Verwendung von UV:

Dadurch wird der jinni CLI-Befehl in Ihrer Umgebung verfügbar. Informationen zum Starten des MCP-Servers je nach Installationsmethode finden Sie oben im Abschnitt „Server ausführen“.

Plattformspezifische Hinweise

Windows + WSL

Jinni v0.1.7+ konvertiert WSL-Pfade automatisch.

Geben Sie eines davon als project_root (CLI --root oder MCP-Argument):

Keine Wrapper, Mounts oder zusätzlichen Flags erforderlich – Jinni löst den UNC-Pfad ( \\wsl$\... ) unter Windows automatisch auf.

UNC-Pfadformat: Jinni verwendet immer \\wsl$\<distro>\... für maximale Kompatibilität mit allen Windows-Versionen, die WSL unterstützen. Handhabung des Distributionsnamens: Leerzeichen und die meisten Sonderzeichen sind im Distributionsnamen zulässig. Nur wirklich unzulässige UNC-Zeichen werden durch _ ersetzt. Caching: WSL-Pfadsuchen und -Konvertierungen werden aus Performancegründen zwischengespeichert. Wenn Sie WSL installieren, während Jinni ausgeführt wird, starten Sie Jinni neu, um den neuen wslpath zu übernehmen. Opt-out: Setzen Sie die Umgebungsvariable JINNI_NO_WSL_TRANSLATE=1 um die gesamte WSL-Pfadübersetzungslogik zu deaktivieren.

Nur wsl+<distro> -URIs und absolute POSIX-Pfade (beginnend mit / ) werden übersetzt. Führen Sie Jinni für SSH- oder Container-Remotes innerhalb dieser Umgebung aus.

Beispiele

• Kontext von my_project/ in die Konsole kopieren:
  jinni ./my_project/ # Process a single directory jinni ./src ./docs/README.md # Process multiple targets jinni # Process current directory (.)
• Listen Sie Dateien auf, die ohne Inhalt in my_project/ aufgenommen würden:
  jinni -l ./my_project/ jinni --list-only ./src ./docs/README.md
• Dumpen Sie den Kontext von my_project/ in eine Datei mit dem Namen context_dump.txt :
  jinni -o context_dump.txt ./my_project/
• Verwenden Sie Override-Regeln aus custom.rules anstelle von .contextfiles :
  jinni --overrides custom.rules ./my_project/
• Debug-Informationen anzeigen:
  jinni --debug-explain ./src
• Kontext ausgeben (die Ausgabe wird standardmäßig automatisch in die Zwischenablage kopiert):
  jinni ./my_project/
• Kontext ausgeben, aber nicht in die Zwischenablage kopieren:
  jinni --no-copy ./my_project/

Konfiguration ( .contextfiles und Overrides)

Jinni verwendet .contextfiles (oder eine Override-Datei), um basierend auf Mustern im .gitignore -Stil zu bestimmen, welche Dateien und Verzeichnisse ein- oder ausgeschlossen werden sollen.

• Grundprinzip: Regeln werden während der Durchquerung dynamisch angewendet, relativ zum aktuell verarbeiteten Zielverzeichnis.
• Speicherort ( .contextfiles ): Platzieren Sie .contextfiles in einem beliebigen Verzeichnis. Bei der Verarbeitung eines Verzeichnisses (entweder des ursprünglichen Zielverzeichnisses oder eines Unterverzeichnisses) sucht Jinni von diesem Verzeichnis abwärts nach .contextfiles . Regeln von übergeordneten Verzeichnissen außerhalb des aktuellen Zielverzeichnisses werden bei der Verarbeitung innerhalb dieses Zielverzeichnisses ignoriert.
• Format: Klartext, UTF-8-kodiert, ein Muster pro Zeile.
• Syntax: Verwendet die Standard-Syntax .gitignore Musters (insbesondere die gitwildmatch -Implementierung von pathspec ).
  • Kommentare: Zeilen, die mit # beginnen, werden ignoriert.
  • Einschlussmuster: Geben Sie die einzuschließenden Dateien/Verzeichnisse an (z. B. src/**/*.py , *.md , /config.yaml ).
  • Ausschlussmuster: Zeilen, die mit ! beginnen, geben an, dass eine übereinstimmende Datei ausgeschlossen werden soll (negiert das Muster).
  • Verankerung: Ein vorangestellter / verankert das Muster im Verzeichnis, das die .contextfiles enthält.
  • Verzeichnisübereinstimmung: Ein abschließender / stimmt nur mit Verzeichnissen überein.
  • Platzhalter: * , ** , ? funktionieren wie in .gitignore .
• Regelanwendungslogik:
  1. Ziel bestimmen: Jinni identifiziert das Zielverzeichnis (entweder explizit angegeben oder das Projektstammverzeichnis).
  2. Override-Prüfung: Wenn --overrides (CLI) oder rules (MCP) angegeben sind, werden ausschließlich diese Regeln verwendet. Alle .contextfiles und integrierten Standardwerte werden ignoriert. Die Pfadübereinstimmung erfolgt relativ zum Zielverzeichnis.
  3. Dynamische Kontextregeln (keine Überschreibungen): Beim Verarbeiten einer Datei oder eines Unterverzeichnisses innerhalb des Zielverzeichnisses:
     • Jinni findet alle .contextfiles vom Zielverzeichnis bis hinunter zum Verzeichnis des aktuellen Elements.
     • Es kombiniert die Regeln aus diesen erkannten .contextfiles mit den integrierten Standardregeln.
     • Es fasst diese kombinierten Regeln in einer Spezifikation ( PathSpec ) zusammen.
     • Es gleicht den aktuellen Datei-/Unterverzeichnispfad, berechnet relativ zum Zielverzeichnis , mit dieser Spezifikation ab.
  4. Übereinstimmung: Das letzte Muster im kombinierten Regelsatz, das mit dem relativen Pfad des Elements übereinstimmt, bestimmt dessen Weiterverwendung. ! hebt die Übereinstimmung auf. Wenn kein benutzerdefiniertes Muster übereinstimmt, wird das Element eingeschlossen, es sei denn, es entspricht einem integrierten Standardausschluss (z. B. !.* ).
  5. Zielbehandlung: Explizit ausgewählte Dateien umgehen Regelprüfungen. Explizit ausgewählte Verzeichnisse werden zum Stammverzeichnis für die Regelerkennung und den Abgleich ihrer Inhalte. Ausgabepfade bleiben immer relativ zum ursprünglichen project_root .

Beispiele ( .contextfiles )

Beispiel 1: Python-Quelle und Root-Konfiguration einschließen

Befindet sich unter my_project/.contextfiles :

Beispiel 2: Überschreiben in einem Unterverzeichnis

Befindet sich unter my_project/src/.contextfiles :

Entwicklung

• Designdetails: DESIGN.md
• Server lokal ausführen: Während der Entwicklung (nach der Installation mit uv pip install -e . oder ähnlich) können Sie das Servermodul direkt ausführen:
  python -m jinni.server [OPTIONS]
  Beispiel einer MCP-Clientkonfiguration für die lokale Entwicklung:
  { "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" } } }

Fehlerbehebung

Kontextgrößenfehler ( DetailedContextSizeError )

Wenn eine Fehlermeldung angezeigt wird, dass die Kontextgrößenbeschränkung überschritten wurde, stellt Jinni eine Liste der zehn größten Dateien bereit, die es einzuschließen versuchte. Dies hilft Ihnen, potenzielle Kandidaten für den Ausschluss zu identifizieren.

So beheben Sie dieses Problem:

1. Überprüfen Sie die größten Dateien: Überprüfen Sie die Liste in der Fehlermeldung. Gibt es große Dateien (z. B. Datendateien, Protokolle, Build-Artefakte, Medien), die nicht Teil des LLM-Kontexts sein sollten?
2. Ausschlüsse konfigurieren: Verwenden Sie .contextfiles oder die Optionen --overrides / rules um unnötige Dateien oder Verzeichnisse auszuschließen.
   • Beispiel ( .contextfiles ): So schließen Sie alle .log Dateien und ein bestimmtes großes Datenverzeichnis aus:
     # Exclude all log files !*.log # Exclude a large data directory !large_data_files/
   • Ausführliche Informationen zur Syntax und Verwendung finden Sie im Abschnitt „Konfiguration“ oben.
3. Erhöhen Sie das Limit (mit Vorsicht): Wenn alle enthaltenen Dateien wirklich benötigt werden, können Sie das Größenlimit mit --size-limit-mb (CLI) oder size_limit_mb (MCP) erhöhen. Beachten Sie die LLM-Kontextfensterlimits und den Verarbeitungsaufwand.
4. Verwenden Sie jinni usage / usage “: Wenn Sie bei der Fehlerbehebung auf diese Anweisungen oder die Konfigurationsdetails zurückgreifen müssen, verwenden Sie den Befehl jinni usage oder das MCP-Tool „ usage “.