Gemini Researcher

Легковесный, не имеющий состояния MCP-сервер (Model Context Protocol), который позволяет агентам разработчика (Claude Code, GitHub Copilot) делегировать глубокий анализ репозитория Gemini CLI. Сервер работает только для чтения, возвращает структурированный 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 и запускает Gemini CLI в headless-режиме для анализа локальных файлов, на которые ссылаются через @path. Результаты возвращаются в виде отформатированных JSON-строк для клиентских агентов.

Контракт безопасности среды выполнения

Каноническая семантика среды выполнения поддерживается в docs/runtime-contract.md.

Gemini Researcher обеспечивает следующий контракт вызова для запросов на анализ:

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

• Сервер использует -p/--prompt для явного неинтерактивного headless-выполнения.

• Сервер не использует -y/--yolo в сгенерированных сервером аргументах командной строки.

• Режим «только для чтения» принудительно обеспечивается с помощью встроенной политики администратора по умолчанию.

• Строгое соблюдение политики администратора можно ослабить с помощью GEMINI_RESEARCHER_ENFORCE_ADMIN_POLICY=0 (или false|no|off).

Поведение политики «только для чтения»

• Режим по умолчанию — строгое закрытие при ошибке.

• Встроенная политика запрещает известные мутирующие инструменты (например: write_file, replace, run_shell_command).

• Политика основана на черном списке. Если Gemini представит новые имена мутирующих инструментов в будущих выпусках, могут потребоваться обновления политики.

• Расширения остаются включенными по дизайну. Это удобно, но означает, что принудительное применение политики должно оставаться включенным в рабочей среде.

Семантика аутентификации и работоспособности

Когда вы запускаете health_check с includeDiagnostics: true, диагностика включает состояние аутентификации и статус принудительного применения политики.

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"
      ]
    }
  }
}

Добавьте в настройки MCP VS Code (создайте .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). Большие ответы разбиваются на части (~10 КБ на часть) и кэшируются на 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

Для настройки MCP-клиента с Docker:

{
  "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; переключите fileFiltering.respectGitIgnore в gemini /settings, если вы намеренно хотите включить игнорируемые файлы (примечание: это меняет поведение Gemini глобально)

• PATH_NOT_ALLOWED: Все ссылки @path должны разрешаться внутри настроенного корня проекта (по умолчанию process.cwd()). Используйте validate_paths для предварительной проверки путей.

• QUOTA_EXCEEDED: Сервер повторяет попытки с резервными моделями; если все уровни исчерпаны, уменьшите область действия (используйте quick_query) или дождитесь сброса квоты.

Участие в разработке

Прочитайте Руководство по участию, чтобы начать.

Быстрые ссылки:

• Настройка среды разработки

• Запуск тестов

• Рекомендации по коду

• Отправка изменений

Лицензия

Лицензия BSD-3-Clause