Gemini Researcher

개발자 에이전트(Claude Code, GitHub Copilot)가 Gemini CLI에 심층적인 저장소 분석을 위임할 수 있도록 하는 가볍고 상태 비저장(stateless)인 MCP(Model Context Protocol) 서버입니다. 이 서버는 읽기 전용이며 구조화된 JSON(텍스트 콘텐츠로)을 반환하고, 호출하는 에이전트의 컨텍스트 및 모델 사용량을 줄이도록 설계되었습니다.

상태: v1 완료. 핵심 기능은 안정적이지만 아직 초기 단계입니다. 피드백을 환영합니다!

이 도구로 토큰을 절약하셨다면, ⭐ 별표를 눌러주세요! :)

주요 목표:

• Gemini CLI가 로컬에서 대규모 코드베이스를 읽고 자체적으로 연구를 수행하게 하여 에이전트 컨텍스트 사용량 감소

• 무거운 분석 작업을 Gemini로 오프로드하여 호출 에이전트의 모델 사용량 감소

• 안전을 위해 서버를 상태 비저장 및 읽기 전용으로 유지

왜 이 도구를 사용해야 하나요?

전체 파일을 에이전트의 컨텍스트에 복사(토큰을 소모하고 대화를 복잡하게 만듦)하는 대신, 이 서버를 사용하면 Gemini CLI가 프로젝트에서 직접 파일을 읽을 수 있습니다. 에이전트가 연구 쿼리를 보내면 Gemini가 대규모 컨텍스트 창을 사용하여 읽고 합성한 뒤 구조화된 결과를 반환합니다. 토큰을 절약하고 에이전트의 집중력을 유지하며 복잡한 코드베이스 분석을 실용적으로 만들 수 있습니다.

검증된 클라이언트: Claude Code, Cursor, VS Code (GitHub Copilot)

목차

• Gemini Researcher

  • 개요

  • 전제 조건

  • 빠른 시작

    • 1단계: 환경 검증

    • 2단계: MCP 클라이언트 구성

    • 3단계: MCP 클라이언트 재시작

    • 4단계: 테스트

  • 도구

    • 예시 워크플로우

  • Docker

  • 문제 해결 (일반적인 문제)

  • 기여

  • 라이선스

개요

Gemini Researcher는 MCP 프로토콜을 통해 연구 스타일의 쿼리를 수락하고, @path로 참조된 로컬 파일을 분석하기 위해 헤드리스 모드에서 Gemini CLI를 실행합니다. 결과는 에이전트 클라이언트를 위해 포맷된 JSON 문자열로 반환됩니다.

런타임 안전 계약

표준 런타임 의미 체계는 docs/runtime-contract.md에 유지됩니다.

Gemini Researcher는 분석 요청에 대해 다음과 같은 호출 계약을 강제합니다:

gemini [ -m <model> ] --output-format json --approval-mode default [--admin-policy <path>] -p "<prompt>"

• 서버는 명시적인 비대화형 헤드리스 실행을 위해 -p/--prompt를 사용합니다.

• 서버는 서버 생성 argv에서 -y/--yolo를 사용하지 않습니다.

• 읽기 전용 동작은 기본적으로 번들된 관리자 정책을 통해 강제됩니다.

• 관리자 정책의 엄격한 강제는 GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0(또는 false|no|off)으로 완화할 수 있습니다.

읽기 전용 정책 동작

• 기본 모드는 엄격한 실패 차단(fail-closed) 강제입니다.

• 번들된 정책은 알려진 변경 도구(예: write_file, replace, run_shell_command)를 거부합니다.

• 정책은 거부 목록 기반입니다. 향후 릴리스에서 Gemini가 새로운 변경 도구 이름을 도입하면 정책 업데이트가 필요할 수 있습니다.

• 확장은 설계상 활성화된 상태로 유지됩니다. 이는 편리하지만 프로덕션 환경에서는 정책 강제가 활성화된 상태로 유지되어야 함을 의미합니다.

인증 및 상태 의미 체계

includeDiagnostics: true와 함께 health_check를 실행하면 진단 정보에 인증 상태 및 강제 상태가 포함됩니다.

health_check.status는 다음과 같습니다:

• ok: Gemini를 사용할 수 있고, 인증이 구성되었으며, 엄격한 읽기 전용 강제가 충족된 경우(또는 환경 변수 토글로 의도적으로 완화된 경우)에만 해당합니다.

• degraded: 모든 설정/안전/인증 불확실성 경로에 해당합니다.

전제 조건

• Node.js 18+ 설치됨

• Gemini CLI 설치됨: npm install -g @google/gemini-cli

• Gemini CLI 인증됨 (권장: gemini → Google로 로그인) 또는 GEMINI_API_KEY 설정

빠른 확인:

node --version
gemini --version

빠른 시작

1단계: 환경 검증

설정 마법사를 실행하여 Gemini CLI가 설치되고 인증되었는지 확인합니다:

npx gemini-researcher init

2단계: MCP 클라이언트 구성

표준 구성은 대부분의 도구에서 작동합니다:

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

VS Code MCP 설정에 추가합니다 (필요한 경우 .vscode/mcp.json 생성):

{
  "servers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

옵션 1: 명령줄 (권장)

로컬(사용자 전체) 범위

# Add the MCP server via CLI
claude mcp add --transport stdio gemini-researcher -- npx gemini-researcher 

# Verify it was added
claude mcp list

프로젝트 범위

프로젝트 디렉토리로 이동한 후 다음을 실행합니다:

# Add the MCP server via CLI
claude mcp add --scope project --transport stdio gemini-researcher -- npx gemini-researcher

# Verify it was added
claude mcp list

옵션 2: 수동 구성

프로젝트 루트의 .mcp.json에 추가합니다 (프로젝트 범위):

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

또는 로컬 범위를 위해 ~/.claude/settings.json에 추가합니다.

서버를 추가한 후 Claude Code를 재시작하고 /mcp를 사용하여 연결을 확인합니다.

Cursor Settings -> Tools & MCP -> Add a Custom MCP Server로 이동합니다. 다음 구성을 추가합니다:

{
  "mcpServers": {
    "gemini-researcher": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "gemini-researcher"
      ]
    }
  }
}

예시

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "npx",
      "args": [
        "gemini-researcher"
      ],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

3단계: MCP 클라이언트 재시작

4단계: 테스트

에이전트에게 "Use gemini-researcher to analyze the project."라고 요청하세요.

도구

모든 도구는 구조화된 JSON(MCP 텍스트 콘텐츠로)을 반환합니다. 큰 응답은 청크로 나뉘며(청크당 약 10KB) 1시간 동안 캐시됩니다.

예시 워크플로우

보안 취약점 이해:

Agent: Use deep_research to analyze authentication flow across @src/auth and @src/middleware, focusing on security

빠른 코드 설명:

Agent: Use quick_query to explain the login flow in @src/auth.ts, be concise

익숙하지 않은 코드베이스 매핑:

Agent: Use analyze_directory on src/ with depth 3 to understand the project structure

quick_query

{
  "prompt": "Explain @src/auth.ts login flow",
  "focus": "security",
  "responseStyle": "concise"
}

deep_research

{
  "prompt": "Analyze authentication across @src/auth and @src/middleware",
  "focus": "architecture",
  "citationMode": "paths_only"
}

analyze_directory

{
  "path": "src",
  "depth": 3,
  "maxFiles": 200
}

validate_paths

{
  "paths": ["src/auth.ts", "README.md"]
}

health_check

{
  "includeDiagnostics": true
}

fetch_chunk

{
  "cacheKey": "cache_abc123",
  "chunkIndex": 2
}

Docker

사전 빌드된 다중 플랫폼 Docker 이미지는 Docker Hub에서 사용할 수 있습니다:

# Pull the image (works on Intel/AMD and Apple Silicon)
docker pull capybearista/gemini-researcher:latest

# Run the server (mount your project and provide API key)
docker run -i --rm \
  -e GEMINI_API_KEY="your-api-key" \
  -v /path/to/your/project:/workspace \
  capybearista/gemini-researcher:latest

Docker를 사용한 MCP 클라이언트 구성:

{
  "mcpServers": {
    "gemini-researcher": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GEMINI_API_KEY",
        "-v", "/path/to/your/project:/workspace",
        "capybearista/gemini-researcher:latest"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

문제 해결 (일반적인 문제)

• GEMINI_CLI_NOT_FOUND: Gemini CLI 설치: npm install -g @google/gemini-cli

• AUTH_MISSING: gemini를 실행하고 인증하거나 GEMINI_API_KEY를 설정하세요.

• AUTH_UNKNOWN: 인증을 확인할 수 없습니다 (종종 네트워크/CLI 프로브 실패). gemini가 대화형으로 작동하는지 확인한 후 다시 시도하세요.

• ADMIN_POLICY_MISSING: 패키지를 재설치하거나 설치된 패키지에 policies/read-only-enforcement.toml이 있는지 확인하세요.

• ADMIN_POLICY_UNSUPPORTED: Gemini CLI를 v0.36.0 이상으로 업그레이드하세요 (gemini --help에 --admin-policy가 포함되어야 함).

• GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0: 엄격한 시작 시 하드 실패 정책 강제를 비활성화합니다. 이는 실패 차단 보장을 약화시킵니다.

• .gitignore 차단 파일: Gemini는 기본적으로 .gitignore를 준수합니다. 의도적으로 무시된 파일을 포함하려면 gemini /settings에서 fileFiltering.respectGitIgnore를 토글하세요 (참고: 이는 Gemini 동작을 전역적으로 변경합니다).

• PATH_NOT_ALLOWED: 모든 @path 참조는 구성된 프로젝트 루트(기본값 process.cwd()) 내에서 확인되어야 합니다. validate_paths를 사용하여 경로를 사전 확인하세요.

• QUOTA_EXCEEDED: 서버가 대체 모델로 재시도합니다. 모든 티어가 소진되면 범위를 줄이거나(quick_query 사용) 할당량 재설정을 기다리세요.

기여

시작하려면 기여 가이드를 읽어보세요.

빠른 링크:

• 개발 설정

• 테스트 실행

• 코드 가이드라인

• 변경 사항 제출

라이선스

BSD-3-Clause 라이선스