Jinni: Bring Your Project Into Context

진니: 프로젝트를 맥락에 맞게 구성하세요

Jinni는 대규모 언어 모델에 프로젝트의 맥락을 효율적으로 제공하는 도구입니다. 메타데이터를 포함한 관련 프로젝트 파일에 대한 통합된 뷰를 제공하여 파일을 하나씩 읽는 방식의 한계와 비효율성을 극복합니다.

이 도구의 철학은 LLM 컨텍스트 창이 크고 모델이 스마트하며, 프로젝트를 직접 확인하여 어떤 작업이든 모델이 가장 잘 처리할 수 있도록 돕는다는 것입니다.

AI 도구와 통합하기 위한 MCP(Model Context Protocol) 서버가 있고, 프로젝트 컨텍스트를 클립보드에 복사하여 필요한 곳에 붙여넣을 수 있는 수동 명령줄 유틸리티(CLI)가 있습니다.

이러한 도구는 대부분의 사용 사례에서 가장 잘 작동하는 관련 프로젝트 컨텍스트로 간주되는 것에 대해 의견을 가지고 있으며, 자동으로 다음을 제외합니다.

지엑스피1

필요한 경우 .contextfiles를 사용하여 포함/제외를 완전한 세부 사항으로 사용자 정의할 수 있습니다. 이는 .gitignore와 유사하지만 포함을 정의합니다.

MCP 서버는 원하는 만큼의 프로젝트 정보를 제공할 수 있습니다. 기본적으로 범위는 전체 프로젝트이지만, 모델은 특정 모듈/매칭 패턴 등을 요청할 수 있습니다.

MCP 빠른 시작

커서/Roo/Claude Desktop/선택한 클라이언트에 대한 MCP 서버 구성 파일:

LLM이 불량이 되는 경우 보안을 위해 서버가 트리 내에서만 읽도록 제한할 수 있습니다. args 목록에 "--root", "/absolute/path/" 추가합니다.

시스템에 uv가 없다면 설치하세요: https://docs.astral.sh/uv/getting-started/installation/

IDE를 다시 로드하면 에이전트에게 상황에 맞게 읽어달라고 요청할 수 있습니다.

이를 특정 모듈/경로로 제한하려면 "테스트에 대한 컨텍스트 읽기"와 같이 요청하세요.

커서를 사용한 작업:

커서 사용자를 위한 참고 사항

커서는 허용된 최대값보다 큰 컨텍스트를 자동으로 삭제할 수 있으므로 규모가 큰 프로젝트가 있고 에이전트가 도구 호출이 전혀 발생하지 않은 것처럼 행동하는 경우 가져오는 내용을 줄여보세요("xyz에 대한 컨텍스트 읽기").

구성 요소

1. jinni MCP 서버:
   • Cursor, Cline, Roo, Claude Desktop 등의 MCP 클라이언트와 통합됩니다.
   • 지정된 프로젝트 디렉토리에서 관련 파일 내용의 연결된 문자열을 반환하는 read_context 도구를 제공합니다.
2. jinni CLI:
   • 프로젝트 컨텍스트 덤프를 수동으로 생성하기 위한 명령줄 도구입니다.
   • 복사-붙여넣기 또는 파일 입력을 통해 LLM에 컨텍스트를 제공하는 데 유용합니다. 또는 필요한 곳 어디든 출력을 파이프로 전송할 수 있습니다.

특징

• 효율적인 컨텍스트 수집: 한 번의 작업으로 관련 프로젝트 파일을 읽고 연결합니다.
• 지능형 필터링(Gitignore 스타일 포함):
  • .gitignore 구문( pathspec 라이브러리의 gitwildmatch )을 기반으로 하는 시스템을 사용합니다.
  • 프로젝트 디렉터리 내에 있는 .contextfiles 사용하여 계층적 구성을 지원합니다. 처리 중인 파일/디렉토리에 따라 규칙이 동적으로 적용됩니다.
  • 일치 동작: 패턴은 처리 중인 대상 디렉터리 (특정 대상이 지정되지 않은 경우 프로젝트 루트)를 기준으로 하는 상대 경로와 일치합니다. 예를 들어, src/ 대상으로 하는 경우 src/.contextfiles 의 !app.py 규칙은 app.py 와 일치합니다. 출력 경로는 원래 프로젝트 루트를 기준으로 유지됩니다.
  • 오버라이드: --overrides (CLI) 또는 rules (MCP)를 지원하여 특정 규칙 집합만 사용할 수 있습니다. 오버라이드가 활성화되면 기본 제공 규칙과 .contextfiles 는 모두 무시됩니다. 오버라이드 경로 일치는 여전히 대상 디렉터리를 기준으로 합니다.
  • 명시적 대상 포함: 대상으로 명시적으로 제공된 파일은 항상 포함됩니다(규칙 검사는 우회하지만, 바이너리/크기 검사는 우회하지 않음). 대상으로 명시적으로 제공된 디렉터리는 항상 입력되며, 규칙 검색/매칭은 해당 대상 디렉터리를 기준으로 진행됩니다.
• 사용자 정의 가능한 구성( .contextfiles / Overrides):
  • .gitignore 스타일 패턴을 상대 경로 에 적용하여 어떤 파일/디렉토리를 포함하거나 제외할지 정확하게 정의합니다.
  • ! 로 시작하는 패턴은 일치 항목을 무효화합니다(제외 패턴). (아래 구성 섹션 참조).
• 대용량 컨텍스트 처리: 포함된 파일의 총 크기가 설정 가능한 제한(기본값: 100MB)을 초과하면 DetailedContextSizeError 발생시키며 중단됩니다. 오류 메시지에는 크기에 영향을 미치는 가장 큰 파일 10개 목록이 포함되어 있어 제외 대상을 파악하는 데 도움이 됩니다. 컨텍스트 크기 관리에 대한 지침은 문제 해결 섹션을 참조하십시오.
• 메타데이터 헤더: 출력에는 포함된 각 파일의 파일 경로, 크기, 수정 시간이 포함됩니다( list_only 로 비활성화 가능).
• 인코딩 처리: 여러 가지 일반적인 텍스트 인코딩(UTF-8, Latin-1 등)을 시도합니다.
• 목록 전용 모드: 내용은 제외하고 포함되는 파일의 상대 경로만 나열하는 옵션입니다.

용법

MCP 서버( read_context 도구)

1. 설정: uvx 통해 jinni 서버를 실행하도록 MCP 클라이언트(예: Claude Desktop의 claude_desktop_config.json )를 구성합니다.
2. 호출: MCP 클라이언트를 통해 LLM과 상호 작용할 때 모델은 read_context 도구를 호출할 수 있습니다.
   • project_root (문자열, 필수): 프로젝트 루트 디렉터리의 절대 경로입니다. 규칙 검색 및 출력 경로는 이 루트를 기준으로 합니다.
   • targets (JSON 문자열 배열, 필수): 처리할 project_root 내의 파일/디렉토리 목록 을 지정합니다. 문자열 경로의 JSON 배열이어야 합니다(예: ["path/to/file1", "path/to/dir2"] ). 경로는 절대 경로이거나 CWD를 기준으로 상대 경로일 수 있습니다. 모든 대상 경로는 project_root 내부의 위치로 확인되어야 합니다. 빈 목록 [] 이 제공되면 project_root 전체가 처리됩니다.
   • rules (문자열 JSON 배열, 필수): 인라인 필터링 규칙의 필수 목록( .gitignore 스타일 구문 사용, 예: ["src/**/*.py", "!*.tmp"] ). 특정 규칙이 필요하지 않으면 빈 목록 [] 을 제공합니다(기본 제공 기본값 사용). 비어 있지 않으면 이러한 규칙만 사용되며, 기본 제공 기본값과 .contextfiles 무시됩니다.
   • list_only (부울, 선택 사항): true인 경우 콘텐츠 대신 상대 파일 경로 목록만 반환합니다.
   • size_limit_mb (정수, 선택 사항): 컨텍스트 크기 제한을 MB 단위로 재정의합니다.
   • debug_explain (boolean, 선택 사항): 서버에서 디버그 로깅을 활성화합니다.
   3. 출력: 도구는 연결된 콘텐츠(헤더 포함) 또는 파일 목록을 포함하는 단일 문자열을 반환합니다. 헤더/목록의 경로는 제공된 project_root 기준으로 합니다. 컨텍스트 크기 오류가 발생하면 가장 큰 파일에 대한 세부 정보가 포함된 DetailedContextSizeError 를 반환합니다.

MCP 서버( usage 도구)

• 호출: 모델은 usage 도구를 호출할 수 있습니다(인수 필요 없음).
• 출력: README.md 파일의 내용을 문자열로 반환합니다.

(자세한 서버 설정 지침은 MCP 클라이언트에 따라 다릅니다. 일반적으로 Jinni 서버를 실행하도록 클라이언트를 구성해야 합니다.)

서버 실행:

• 권장 방법: uvx 사용하여 서버 진입점을 직접 실행합니다( jinni 패키지가 PyPI에 게시되었거나 uvx 에서 찾을 수 있어야 함):
  uvx jinni-server [OPTIONS]
  MCP 클라이언트 구성 예시(예: claude_desktop_config.json ):
  { "mcpServers": { "jinni": { "command": "uvx", "args": ["jinni-server"] } } }

LLM이 불량이 되는 경우 보안을 위해 서버가 트리 내에서만 읽도록 제한할 수 있습니다. args 목록에 "--root", "/absolute/path/" 추가합니다.

정확한 설정 단계는 해당 MCP 클라이언트의 설명서를 참조하세요. uv 설치되어 있는지 확인하세요.

명령줄 유틸리티( jinni CLI)

• <PATH...> (선택 사항): 분석할 프로젝트 디렉터리 또는 파일에 대한 하나 이상의 경로입니다. 경로가 지정되지 않으면 현재 디렉터리( . )가 기본값으로 사용됩니다.
• -r <DIR> / --root <DIR> (선택 사항): 프로젝트 루트 디렉터리를 지정합니다. 이 옵션을 지정하면 규칙 검색이 여기서 시작되고 출력 경로는 이 디렉터리를 기준으로 합니다. 생략하면 <PATH...> 인수의 공통 조상(또는 '.'만 처리되는 경우 CWD)에서 루트가 유추됩니다.
• --output <FILE> / -o <FILE> (선택 사항): 표준 출력에 인쇄하는 대신 <FILE> 에 출력을 씁니다.
• --list-only / -l (선택 사항): 포함될 파일의 상대 경로만 나열합니다.
• --overrides <FILE> (선택 사항): .contextfiles 검색하는 대신 <FILE> 의 규칙을 사용합니다.
• --size-limit-mb <MB> / -s <MB> (선택 사항): 최대 컨텍스트 크기를 MB 단위로 재정의합니다.
• --debug-explain (선택 사항): stderr 및 jinni_debug.log 에 자세한 포함/제외 이유를 출력합니다.
• --root <DIR> / -r <DIR> (선택 사항): 위를 참조하세요.
• --no-copy (선택 사항): 표준 출력으로 인쇄할 때 출력 내용을 시스템 클립보드에 자동으로 복사하지 않습니다(기본값은 복사입니다).

설치

pip 또는 uv 사용하여 Jinni를 설치할 수 있습니다.

pip 사용하기:

uv를 사용하여:

이렇게 하면 사용자 환경에서 jinni CLI 명령을 사용할 수 있습니다. 설치 방법에 따라 MCP 서버를 시작하는 방법은 위의 "서버 실행" 섹션을 참조하세요.

플랫폼별 참고 사항

윈도우 + WSL

Jinni v0.1.7+는 WSL 경로를 자동 변환합니다.

다음 중 하나를 project_root (CLI --root 또는 MCP 인수)로 제공합니다.

래퍼, 마운트 또는 추가 플래그가 필요하지 않습니다. Jinni는 Windows에서 UNC 경로( \\wsl$\... )를 자동으로 확인합니다.

UNC 경로 형식: Jinni는 WSL을 지원하는 모든 Windows 버전과의 호환성을 극대화하기 위해 항상 \\wsl$\<distro>\... 사용합니다. 배포판 이름 처리: 배포판 이름에는 공백과 대부분의 특수 문자가 허용됩니다. 실제로 허용되지 않는 UNC 문자만 _ 로 바뀝니다. 캐싱: WSL 경로 조회 및 변환은 성능을 위해 캐시됩니다. Jinni 실행 중에 WSL을 설치하는 경우, Jinni를 다시 시작하여 새로운 wslpath 적용합니다. 옵트아웃: 환경 변수 JINNI_NO_WSL_TRANSLATE=1 설정하여 모든 WSL 경로 변환 로직을 비활성화합니다.

wsl+<distro> URI와 절대 POSIX 경로( / 로 시작)만 변환됩니다. SSH 또는 컨테이너 원격의 경우 해당 환경 내에서 Jinni를 실행합니다.

예시

• my_project/ 의 컨텍스트를 콘솔에 덤프합니다.
  jinni ./my_project/ # Process a single directory jinni ./src ./docs/README.md # Process multiple targets jinni # Process current directory (.)
• 내용이 없는 my_project/ 에 포함될 파일을 나열하세요.
  jinni -l ./my_project/ jinni --list-only ./src ./docs/README.md
• my_project/ 의 컨텍스트를 context_dump.txt 라는 파일에 덤프합니다.
  jinni -o context_dump.txt ./my_project/
• .contextfiles 대신 custom.rules 의 재정의 규칙을 사용하세요.
  jinni --overrides custom.rules ./my_project/
• 디버그 정보 표시:
  jinni --debug-explain ./src
• 덤프 컨텍스트(출력은 기본적으로 클립보드에 자동으로 복사됨):
  jinni ./my_project/
• 컨텍스트를 덤프하지만 클립보드에 복사 하지 않습니다 .
  jinni --no-copy ./my_project/

구성( .contextfiles 및 재정의)

Jinni는 .gitignore 스타일 패턴에 따라 포함하거나 제외할 파일과 디렉토리를 결정하기 위해 .contextfiles (또는 오버라이드 파일)를 사용합니다.

• 핵심 원칙: 규칙은 현재 처리 중인 대상 디렉토리를 기준으로 순회 중에 동적으로 적용됩니다.
• 위치( .contextfiles ): .contextfiles 임의의 디렉터리에 저장합니다. 디렉터리(최초 대상 디렉터리 또는 하위 디렉터리)를 처리할 때 Jinni는 해당 디렉터리부터 아래로 .contextfiles 찾습니다. 현재 대상 디렉터리 외부 의 상위 디렉터리 규칙은 해당 대상 디렉터리 내부에서 처리할 때 무시됩니다.
• 형식: 일반 텍스트, UTF-8로 인코딩, 한 줄에 패턴 하나.
• 구문: 표준 .gitignore 패턴 구문을 사용합니다(특히 pathspec 의 gitwildmatch 구현).
  • 설명: # 으로 시작하는 줄은 무시됩니다.
  • 포함 패턴: 포함할 파일/디렉토리를 지정합니다(예: src/**/*.py , *.md , /config.yaml ).
  • 제외 패턴: ! 로 시작하는 줄은 일치하는 파일을 제외해야 함을 나타냅니다(패턴을 부정함).
  • 앵커링: 선행 / 패턴을 .contextfiles 가 포함된 디렉토리에 앵커링합니다.
  • 디렉토리 일치: 끝에 오는 / 디렉토리에만 일치합니다.
  • 와일드카드: * , ** , ?``.gitignore 와 동일하게 작동합니다.
• 규칙 적용 논리:
  1. 대상 결정: Jinni는 대상 디렉토리(명시적으로 제공되거나 프로젝트 루트)를 식별합니다.
  2. 재정의 확인: --overrides (CLI) 또는 rules (MCP)를 제공하는 경우, 해당 규칙만 사용됩니다. 모든 .contextfiles 및 기본 제공 기본값은 무시됩니다. 경로 일치는 대상 디렉터리를 기준으로 합니다.
  3. 동적 컨텍스트 규칙(재정의 없음): 대상 디렉토리 내의 파일이나 하위 디렉토리를 처리할 때:
     • Jinni는 대상 디렉토리부터 현재 항목 디렉토리까지 모든 .contextfiles 찾습니다.
     • 발견된 .contextfiles 의 규칙을 기본 규칙과 결합합니다.
     • 이러한 결합된 규칙을 사양( PathSpec )으로 컴파일합니다.
     • 이는 대상 디렉토리를 기준으로 계산된 현재 파일/하위 디렉토리 경로를 이 사양과 일치시킵니다.
  4. 일치: 결합된 규칙 세트에서 항목의 상대 경로와 일치하는 마지막 패턴이 항목의 운명을 결정합니다. ! 는 일치를 무효화합니다. 사용자 정의 패턴과 일치하는 항목이 없으면, 기본 제공 제외 항목(예 !.* )과 일치하지 않는 한 항목이 포함됩니다.
  5. 대상 처리: 명시적으로 지정된 파일은 규칙 검사를 우회합니다. 명시적으로 지정된 디렉터리는 규칙 검색 및 콘텐츠 매칭의 루트가 됩니다. 출력 경로는 항상 원본 project_root 기준으로 합니다.

예제( .contextfiles )

예제 1: Python 소스 및 루트 구성 포함

my_project/.contextfiles 에 위치:

예제 2: 하위 디렉토리에서 재정의

my_project/src/.contextfiles 에 위치:

개발

• 디자인 세부 정보: DESIGN.md
• 로컬에서 서버 실행: 개발 중( uv pip install -e . 또는 이와 유사한 명령어로 설치한 후) 서버 모듈을 직접 실행할 수 있습니다.
  python -m jinni.server [OPTIONS]
  로컬 개발을 위한 MCP 클라이언트 구성 예:
  { "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" } } }

문제 해결

컨텍스트 크기 오류( DetailedContextSizeError )

컨텍스트 크기 제한을 초과했다는 오류가 발생하면 Jinni는 포함하려고 시도했던 가장 큰 파일 10개 목록을 제공합니다. 이를 통해 제외할 잠재적 후보를 파악하는 데 도움이 됩니다.

이 문제를 해결하려면:

1. 가장 큰 파일 검토: 오류 메시지에 제공된 목록을 확인하세요. LLM 컨텍스트에 포함되어서는 안 되는 큰 파일(예: 데이터 파일, 로그, 빌드 아티팩트, 미디어)이 있습니까?
2. 제외 구성: .contextfiles 또는 --overrides / rules 옵션을 사용하여 불필요한 파일이나 디렉토리를 제외합니다.
   • 예( .contextfiles ): 모든 .log 파일과 특정 대용량 데이터 디렉터리를 제외하려면 다음을 수행합니다.
     # Exclude all log files !*.log # Exclude a large data directory !large_data_files/
   • 자세한 구문과 사용법은 위의 구성 섹션을 참조하세요.
3. 제한 늘리기(주의해서 사용): 포함된 모든 파일이 실제로 필요한 경우 --size-limit-mb (CLI) 또는 size_limit_mb (MCP)를 사용하여 크기 제한을 늘릴 수 있습니다. 단, LLM 컨텍스트 창 제한과 처리 비용에 유의해야 합니다.
4. jinni usage / usage : 문제를 해결하는 동안 이 지침이나 구성 세부 정보를 다시 참조해야 하는 경우 jinni usage 명령이나 usage MCP 도구를 사용하세요.