gemini-deep-research-mcp 0.1.0__py3-none-any.whl

gemini_deep_research_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""Gemini Deep Research MCP server package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

gemini_deep_research_mcp/__main__.py

@@ -0,0 +1,5 @@
+from .server import main
+
+
+if __name__ == "__main__":
+    main()

gemini_deep_research_mcp/config.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from dotenv import load_dotenv
+
+
+@dataclass(frozen=True)
+class Settings:
+    api_key: str
+    model: str
+    deep_research_agent: str
+    poll_interval_seconds: float = 10.0
+
+
+def load_settings() -> Settings:
+    """Load configuration from environment (and .env when present)."""
+
+    # Load .env if present; safe no-op otherwise.
+    load_dotenv(override=False)
+
+    api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY") or ""
+
+    model = os.getenv("GEMINI_MODEL", "gemini-3-pro-preview")
+    deep_research_agent = os.getenv(
+        "GEMINI_DEEP_RESEARCH_AGENT", "deep-research-pro-preview-12-2025"
+    )
+
+    return Settings(
+        api_key=api_key,
+        model=model,
+        deep_research_agent=deep_research_agent,
+    )

gemini_deep_research_mcp/extract.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Iterable, List, Optional
+
+from .resolve import resolve_sources_in_text
+
+
+def _strip_duplicate_references(text: str) -> str:
+    """Remove the redundant 'References' section while keeping 'Sources'.
+    
+    Gemini Deep Research reports contain:
+    1. Inline [cite: X] markers throughout the text
+    2. A 'References' section with brief citation titles (REDUNDANT)
+    3. A 'Sources:' section at the end with full URLs (KEEP THIS)
+    
+    We remove the References section since:
+    - The inline [cite: X] markers already show where info comes from
+    - The Sources section has the actual clickable URLs
+    - The References section just has brief titles without URLs
+    
+    This typically saves ~1-2KB per report.
+    """
+    # Match "### References" or "References" section with cite entries
+    # Format: [cite: X] Title. Description.
+    pattern = r'\n+(?:#{1,3}\s*)?References\s*\n(?:\[cite:\s*\d+\][^\n]*\n?)+'
+    cleaned = re.sub(pattern, '\n', text, flags=re.IGNORECASE)
+    return cleaned.strip()
+
+
+def _get(obj: Any, key: str, default: Any = None) -> Any:
+    if obj is None:
+        return default
+    if isinstance(obj, dict):
+        return obj.get(key, default)
+    return getattr(obj, key, default)
+
+
+def outputs_to_text(outputs: Optional[Iterable[Any]], *, include_citations: bool = True) -> str:
+    """Best-effort conversion of Interaction.outputs to a readable string."""
+
+    if not outputs:
+        return ""
+
+    parts: List[str] = []
+    for out in outputs:
+        text = _get(out, "text")
+        if isinstance(text, str) and text.strip():
+            parts.append(text)
+    
+    result = _strip_duplicate_references("\n\n".join(parts).strip())
+    
+    # Resolve redirect URLs to actual source URLs (if citations enabled)
+    if include_citations:
+        result = resolve_sources_in_text(result)
+    
+    return result
+
+
+def interaction_to_result(interaction: Any, *, include_citations: bool = True) -> dict[str, Any]:
+    """Convert an Interaction object to a JSON-serializable summary."""
+
+    outputs = _get(interaction, "outputs")
+    text = outputs_to_text(outputs, include_citations=include_citations)
+
+    return {
+        "status": _get(interaction, "status"),
+        "text": text,
+    }

gemini_deep_research_mcp/gemini.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+from google import genai
+
+from .config import Settings
+
+
+def create_client(settings: Settings) -> genai.Client:
+    # The SDK supports GOOGLE_API_KEY env var, but we pass explicitly for clarity.
+    if not settings.api_key:
+        raise ValueError(
+            "Missing GEMINI_API_KEY (or GOOGLE_API_KEY fallback). "
+            "Set it in your environment or .env."
+        )
+    return genai.Client(api_key=settings.api_key)
+
+
+def start_deep_research(client: genai.Client, *, prompt: str, agent: str) -> Any:
+    # For Deep Research: background=True requires store=True.
+    return client.interactions.create(
+        input=prompt,
+        agent=agent,
+        background=True,
+        store=True,
+    )
+
+
+def get_interaction(client: genai.Client, job_id: str) -> Any:
+    return client.interactions.get(job_id)
+
+
+def poll_until_terminal(
+    client: genai.Client,
+    *,
+    job_id: str,
+    timeout_seconds: float,
+    poll_interval_seconds: float,
+) -> Any:
+    deadline = time.monotonic() + max(0.0, timeout_seconds)
+
+    interaction: Optional[Any] = None
+    while True:
+        interaction = get_interaction(client, job_id)
+        status = getattr(interaction, "status", None) or (
+            interaction.get("status") if isinstance(interaction, dict) else None
+        )
+
+        if status in {"completed", "failed", "cancelled"}:
+            return interaction
+
+        if time.monotonic() >= deadline:
+            return interaction
+
+        time.sleep(poll_interval_seconds)

gemini_deep_research_mcp/resolve.py

@@ -0,0 +1,90 @@
+"""Resolve Gemini grounding redirect URLs to actual source URLs."""
+from __future__ import annotations
+
+import logging
+import re
+from functools import lru_cache
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Pattern to match Gemini grounding redirect URLs
+REDIRECT_URL_PATTERN = re.compile(
+    r'https://vertexaisearch\.cloud\.google\.com/grounding-api-redirect/[A-Za-z0-9_-]+'
+)
+
+# HTTP timeout for resolving redirects (seconds)
+RESOLVE_TIMEOUT = 10.0
+
+
+@lru_cache(maxsize=256)
+def resolve_redirect_url(url: str) -> Optional[str]:
+    """Follow a redirect URL and return the final destination.
+    
+    Args:
+        url: A Gemini grounding redirect URL
+        
+    Returns:
+        The resolved destination URL, or None if resolution fails
+    """
+    if not url or 'grounding-api-redirect' not in url:
+        return None
+    
+    try:
+        # Use HEAD request to follow redirects without downloading content
+        # follow_redirects=False so we can capture the Location header
+        with httpx.Client(timeout=RESOLVE_TIMEOUT, follow_redirects=False) as client:
+            response = client.head(url)
+            
+            # The redirect URL returns a 302/301 with Location header
+            if response.status_code in (301, 302, 303, 307, 308):
+                location = response.headers.get('location')
+                if location:
+                    logger.debug(f"Resolved {url[:60]}... -> {location}")
+                    return location
+            
+            # If no redirect, try GET as fallback (some servers don't respond to HEAD)
+            response = client.get(url, follow_redirects=True)
+            final_url = str(response.url)
+            
+            # Only return if we actually got redirected somewhere different
+            if final_url != url and 'grounding-api-redirect' not in final_url:
+                logger.debug(f"Resolved {url[:60]}... -> {final_url}")
+                return final_url
+                
+    except httpx.TimeoutException:
+        logger.warning(f"Timeout resolving URL: {url[:80]}...")
+    except httpx.HTTPError as e:
+        logger.warning(f"HTTP error resolving URL: {e}")
+    except Exception as e:
+        logger.warning(f"Unexpected error resolving URL: {e}")
+    
+    return None
+
+
+def resolve_sources_in_text(text: str) -> str:
+    """Find and resolve all grounding redirect URLs in text.
+    
+    Scans the text for Gemini grounding redirect URLs and replaces them
+    with resolved destination URLs where possible.
+    
+    Args:
+        text: The text containing potential redirect URLs
+        
+    Returns:
+        Text with redirect URLs replaced by resolved URLs where possible
+    """
+    if not text or 'grounding-api-redirect' not in text:
+        return text
+    
+    def replace_url(match: re.Match) -> str:
+        original_url = match.group(0)
+        resolved = resolve_redirect_url(original_url)
+        if resolved:
+            return resolved
+        # Keep original if resolution failed
+        return original_url
+    
+    return REDIRECT_URL_PATTERN.sub(replace_url, text)

gemini_deep_research_mcp/server.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Annotated, Any, TypedDict
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import CallToolResult, ToolAnnotations
+
+from .config import Settings, load_settings
+from .extract import interaction_to_result
+from .gemini import create_client, poll_until_terminal, start_deep_research
+
+
+logger = logging.getLogger(__name__)
+
+
+class DeepResearchOutput(TypedDict):
+    status: str
+    report_text: str
+
+
+def _configure_logging() -> None:
+    # IMPORTANT: stdout is reserved for MCP protocol.
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s - %(message)s",
+        stream=sys.stderr,
+    )
+
+
+_configure_logging()
+
+
+mcp = FastMCP("Gemini Deep Research MCP")
+
+
+def _get_client_and_settings() -> tuple[Any, Settings]:
+    settings = load_settings()
+    client = create_client(settings)
+    return client, settings
+
+
+def _require_nonempty(value: Optional[str], *, field: str) -> str:
+    if value is None:
+        raise ValueError(f"`{field}` is required")
+    value = str(value)
+    if not value.strip():
+        raise ValueError(f"`{field}` is required")
+    return value
+
+
+# Default timeout for research
+_DEFAULT_TIMEOUT_SECONDS = 1200.0
+
+_DEEP_RESEARCH_DESCRIPTION = """
+Conduct comprehensive web research using Gemini's Deep Research Agent.
+
+When to use this tool:
+- Researching complex topics requiring multi-source analysis
+- Need synthesized information from the web
+- Require fact-checking and cross-referencing of information
+
+Parameters:
+- `prompt`: Your research question or topic (required)
+- `include_citations`: Whether to include source URLs in the report (default: true)
+
+Returns:
+- `status`: Final state (completed, failed, cancelled)
+- `report_text`: The synthesized research report with findings
+- `sources`: List of sources used in the research (if enabled)
+
+Notes:
+- This tool blocks until research completes (typically 10-20 minutes)
+""".strip()
+
+
+@mcp.tool(
+    title="Gemini Deep Research",
+    description=_DEEP_RESEARCH_DESCRIPTION,
+    annotations=ToolAnnotations(
+        openWorldHint=True,
+        readOnlyHint=False,
+        idempotentHint=False,
+    ),
+    structured_output=True,
+)
+def gemini_deep_research(
+    prompt: str,
+    include_citations: bool = True,
+) -> Annotated[CallToolResult, DeepResearchOutput]:
+    """Conduct deep research on a topic and wait for the complete report."""
+
+    if not prompt or not prompt.strip():
+        raise ValueError("`prompt` is required")
+
+    client, settings = _get_client_and_settings()
+
+    # Start the deep research job
+    initial = start_deep_research(client, prompt=prompt.strip(), agent=settings.deep_research_agent)
+    job_id = getattr(initial, "id", None) or (
+        initial.get("id") if isinstance(initial, dict) else None
+    )
+    if not job_id:
+        raise RuntimeError("Gemini SDK did not return a research job id.")
+
+    # Wait for completion
+    interaction = poll_until_terminal(
+        client,
+        job_id=job_id,
+        timeout_seconds=_DEFAULT_TIMEOUT_SECONDS,
+        poll_interval_seconds=settings.poll_interval_seconds,
+    )
+    result = interaction_to_result(interaction, include_citations=include_citations)
+    status = result.get("status")
+    if status is None:
+        status = "unknown"
+    payload: DeepResearchOutput = {
+        "status": str(status),
+        "report_text": result.get("text", ""),
+    }
+
+    # IMPORTANT: when returning a dict from a structured tool, the MCP lowlevel server
+    # will also serialize it to JSON text and include it in `content`, which some
+    # clients then print in addition to `structuredContent` (leading to duplicate
+    # outputs). Returning CallToolResult avoids that double-serialization.
+    return CallToolResult(content=[], structuredContent=payload, isError=False)
+
+
+
+
+
+def main() -> None:
+    # Run over STDIO.
+    logger.info("Starting Gemini Deep Research MCP server (stdio)")
+    mcp.run()

gemini_deep_research_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: gemini-deep-research-mcp
+Version: 0.1.0
+Summary: MCP server exposing Gemini Deep Research (Interactions API) tools
+Author-email: Ayush <ayusin439@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/bharatvansh/gemini-deep-research-mcp
+Project-URL: Repository, https://github.com/bharatvansh/gemini-deep-research-mcp
+Project-URL: Issues, https://github.com/bharatvansh/gemini-deep-research-mcp/issues
+Keywords: mcp,gemini,deep-research,ai,google,model-context-protocol,research,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: google-genai>=0.6.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+
+# Gemini Deep Research MCP
+
+An MCP server that exposes Gemini's **Deep Research Agent** for comprehensive web research.
+
+## Quick Start
+
+```bash
+pip install gemini-deep-research-mcp
+```
+
+Set your API key:
+```bash
+export GEMINI_API_KEY="your-api-key"  # macOS/Linux
+set GEMINI_API_KEY=your-api-key       # Windows CMD
+$env:GEMINI_API_KEY="your-api-key"    # Windows PowerShell
+```
+
+## MCP Client Setup
+
+### VS Code (Copilot)
+
+Add to your VS Code settings or `.vscode/mcp.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "gemini-deep-research": {
+        "command": "gemini-deep-research-mcp",
+        "env": {
+          "GEMINI_API_KEY": "your-api-key"
+        }
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gemini-deep-research": {
+      "command": "gemini-deep-research-mcp",
+      "env": {
+        "GEMINI_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+> **Windows**: If `gemini-deep-research-mcp` isn't in PATH, use full path: `C:\\Users\\YOU\\...\\python.exe` with args `["-m", "gemini_deep_research_mcp"]`
+
+## Tool: `gemini_deep_research`
+
+Conducts comprehensive web research using Gemini's Deep Research Agent. Blocks until research completes (typically 10-20 minutes).
+
+**When to use:**
+- Complex topics requiring multi-source analysis
+- Synthesized information from the web
+- Fact-checking and cross-referencing
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `prompt` | string | ✓ | — | Your research question or topic |
+| `include_citations` | boolean | | `true` | Include resolved source URLs |
+
+**Output:**
+
+| Field | Description |
+|-------|-------------|
+| `status` | `completed`, `failed`, or `cancelled` |
+| `report_text` | Synthesized research report |
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GEMINI_API_KEY` | ✓ | — | Your Gemini API key |
+| `GEMINI_DEEP_RESEARCH_AGENT` | | `deep-research-pro-preview-12-2025` | Model to use |
+
+## Development
+
+```bash
+git clone https://github.com/bharatvansh/gemini-deep-research-mcp.git
+cd gemini-deep-research-mcp
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT

gemini_deep_research_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+gemini_deep_research_mcp/__init__.py,sha256=b2shbKOn0cCFFhUSy85dPhwl6ERjORIn1-t6vRrPesA,96
+gemini_deep_research_mcp/__main__.py,sha256=kXwGR0h4I_1BdqTv1YV6f86NLM1OwukbORECfPc9OPg,65
+gemini_deep_research_mcp/config.py,sha256=7Cbk8EnW7VhaqkVwoX4sW2jekccQRdLraM89LoL11W4,827
+gemini_deep_research_mcp/extract.py,sha256=lBFB2GfpHdPQXRszV6yulfSTa5cU3ApwU0KwwGg3450,2300
+gemini_deep_research_mcp/gemini.py,sha256=-4wptf99qVcukl0vsohsQQDBwMPq-B7LzZHqjpPZSqg,1572
+gemini_deep_research_mcp/resolve.py,sha256=LmSuTGOe1-qjToKdQL6pcpNlzoMQwn43_uzX1KSQvOo,3105
+gemini_deep_research_mcp/server.py,sha256=lAolJPB-fV4oN9W0Ldq4VQYkXt86Zxd3SVInwT3QsNk,3991
+gemini_deep_research_mcp-0.1.0.dist-info/METADATA,sha256=_CahiTs3Q1OqndH2hXmMuy7FYwqKcwtlCJlBNw6N4sc,3503
+gemini_deep_research_mcp-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+gemini_deep_research_mcp-0.1.0.dist-info/entry_points.txt,sha256=nE5DP4kZ2RG5LB1Ied-hykIRmBei2GJw0wy_PijepRE,82
+gemini_deep_research_mcp-0.1.0.dist-info/top_level.txt,sha256=sk90gOv-N7MHdyHhJE6N-fLVHrtFPfme8m1opjwXoMM,25
+gemini_deep_research_mcp-0.1.0.dist-info/RECORD,,

gemini_deep_research_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gemini_deep_research_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gemini-deep-research-mcp = gemini_deep_research_mcp.server:main

gemini_deep_research_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gemini_deep_research_mcp