grounder-mcp 0.1.0__tar.gz

grounder_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: grounder-mcp
+Version: 0.1.0
+Summary: Current Google answers (Search + AI Overview + AI Mode) as MCP tools for local LLMs and agents.
+Project-URL: Homepage, https://grounder.dev
+Keywords: mcp,google,ai-overview,ai-mode,search,llm,ollama,lm-studio
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.2
+Requires-Dist: httpx>=0.27
+
+# grounder-mcp
+
+From training data to current knowledge. Gives a local LLM or agent Google's live
+answers — the real **AI Overview**, **AI Mode**, and organic **Search** with citations —
+as three MCP tools. Privacy-first: the hosted service stores no query content.
+
+This package is a thin MCP client; the scraping and billing run on the hosted service,
+so it installs with no Playwright and runs fine on a laptop.
+
+## Use
+
+```json
+{
+  "mcpServers": {
+    "grounder": {
+      "command": "uvx",
+      "args": ["grounder-mcp"],
+      "env": { "GROUNDER_API_KEY": "your_key_here" }
+    }
+  }
+}
+```
+
+Get a key at https://grounder.dev. Tools: `google_search`, `google_ai_overview`,
+`google_ai_mode` — one credit per call.

grounder_mcp-0.1.0/README.md

@@ -0,0 +1,25 @@
+# grounder-mcp
+
+From training data to current knowledge. Gives a local LLM or agent Google's live
+answers — the real **AI Overview**, **AI Mode**, and organic **Search** with citations —
+as three MCP tools. Privacy-first: the hosted service stores no query content.
+
+This package is a thin MCP client; the scraping and billing run on the hosted service,
+so it installs with no Playwright and runs fine on a laptop.
+
+## Use
+
+```json
+{
+  "mcpServers": {
+    "grounder": {
+      "command": "uvx",
+      "args": ["grounder-mcp"],
+      "env": { "GROUNDER_API_KEY": "your_key_here" }
+    }
+  }
+}
+```
+
+Get a key at https://grounder.dev. Tools: `google_search`, `google_ai_overview`,
+`google_ai_mode` — one credit per call.

grounder_mcp-0.1.0/grounder/__init__.py

@@ -0,0 +1,2 @@
+"""grounder — current Google answers (Search + AI Overview + AI Mode) as MCP tools."""
+__version__ = "0.1.0"

grounder_mcp-0.1.0/grounder/mcp_server.py

@@ -0,0 +1,84 @@
+"""grounder MCP server (stdio).
+
+Exposes the v1 tool surface — `google_search`, `google_ai_overview`, `google_ai_mode` —
+over the Model Context Protocol so any MCP client (LM Studio, Claude Desktop, Cursor,
+Continue.dev, Aider, a local-agent runtime) can ground answers in live Google.
+
+This is a **thin client**: each tool forwards to the hosted API at `grounder.dev` with
+your API key. The actual scraping (clean IP, captcha-solving) and billing happen on the
+server — this just relays the call, so it runs fine on a laptop.
+
+Run (set your key):
+    GROUNDER_API_KEY=gnd_live_... grounder-mcp
+    GROUNDER_API_KEY=gnd_live_... python -m grounder.mcp_server
+
+Install (lightweight — no Playwright):  pip install -e ".[client]"
+"""
+from __future__ import annotations
+import os
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+from .tools import GOOGLE_SEARCH, GOOGLE_AI_OVERVIEW, GOOGLE_AI_MODE
+
+API_URL = os.environ.get("GROUNDER_API_URL", "https://grounder.dev").rstrip("/")
+
+mcp = FastMCP("grounder")
+
+
+async def _run(query: str, region: str, language: str, device: str, engines: list[str]) -> dict[str, Any]:
+    """Forward a search to the hosted gateway with the API key. Returns the SearchResponse.
+
+    Raises on a missing key or an HTTP error (FastMCP surfaces it as a tool error). A
+    *fetch* failure on the server does NOT raise — it comes back as a valid response with
+    `ai_answer.present=false`.
+    """
+    key = os.environ.get("GROUNDER_API_KEY")
+    if not key:
+        raise RuntimeError(
+            "GROUNDER_API_KEY is not set. Get a key from grounder.dev and put it in the "
+            "MCP server's env (e.g. in your LM Studio / Claude Desktop mcp.json)."
+        )
+    async with httpx.AsyncClient(timeout=90.0) as client:
+        r = await client.post(
+            f"{API_URL}/v1/search",
+            headers={"Authorization": f"Bearer {key}"},
+            json={"query": query, "region": region, "language": language,
+                  "device": device, "engines": engines},
+        )
+        r.raise_for_status()
+        return r.json()
+
+
+@mcp.tool(name=GOOGLE_SEARCH["name"], description=GOOGLE_SEARCH["description"])
+async def google_search(
+    query: str, region: str = "us", language: str = "en", device: str = "desktop"
+) -> dict[str, Any]:
+    return await _run(query, region, language, device, engines=["organic"])
+
+
+@mcp.tool(name=GOOGLE_AI_OVERVIEW["name"], description=GOOGLE_AI_OVERVIEW["description"])
+async def google_ai_overview(
+    query: str, region: str = "us", language: str = "en", device: str = "desktop"
+) -> dict[str, Any]:
+    # AIO + organic come from one fetch; AIO is the headline, organic is the side-effect.
+    return await _run(query, region, language, device, engines=["aio", "organic"])
+
+
+@mcp.tool(name=GOOGLE_AI_MODE["name"], description=GOOGLE_AI_MODE["description"])
+async def google_ai_mode(
+    query: str, region: str = "us", language: str = "en", device: str = "desktop"
+) -> dict[str, Any]:
+    # AI Mode is a separate udm=50 fetch on the server; no classic organic block.
+    return await _run(query, region, language, device, engines=["ai_mode"])
+
+
+def main() -> None:
+    """Console-script entry point. Serves over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

grounder_mcp-0.1.0/grounder/tools.py

@@ -0,0 +1,327 @@
+"""MCP tool definitions — the v1 surface exposed to local LLMs.
+
+Three tools, each = 1 credit per call:
+    google_search       — organic + extras
+    google_ai_overview  — AI Overview answer + citations
+    google_ai_mode      — AI Mode (udm=50) deeper answer
+
+Tool descriptions follow MCP best practices (per the Tavily #141 D-grade lesson):
+    1. Start with a verb
+    2. State unique capability vs sibling tools
+    3. Note when NOT to use it
+    4. Document defaults explicitly
+    5. State cost
+
+These descriptions are how LLMs choose between tools. Specificity is the moat.
+"""
+from __future__ import annotations
+from typing import Any
+
+
+# ─── google_search ────────────────────────────────────────────────────────────
+
+GOOGLE_SEARCH = {
+    "name": "google_search",
+    "description": (
+        "Search Google and return the organic results + extras (People Also Ask, related searches, "
+        "knowledge panel, top stories when present). Use this when you need raw blue-link results, "
+        "source diversity, or when you want to gather URLs to read further. "
+        "Does NOT include the AI Overview text — use google_ai_overview for that. "
+        "Returns up to 10 organic results. AI Overview's presence is detected and surfaced as "
+        "`extras.aio_present: true|false` but the full AIO text is only available via the dedicated tool. "
+        "1 credit per call."
+    ),
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "The search query. Use natural language; quoted phrases work as in google.com.",
+                "minLength": 1,
+                "maxLength": 2048,
+            },
+            "region": {
+                "type": "string",
+                "description": (
+                    "ISO-3166-1 alpha-2 lowercase country code. Affects egress + `gl` param. "
+                    "Default 'us'. Note: 'de'/'fr' regions have DMA-driven citation pool restrictions."
+                ),
+                "pattern": "^[a-z]{2}$",
+                "default": "us",
+            },
+            "language": {
+                "type": "string",
+                "description": "BCP 47 lowercase. Affects `hl` param. Default 'en'.",
+                "pattern": "^[a-z]{2,3}$",
+                "default": "en",
+            },
+            "device": {
+                "type": "string",
+                "description": "Device profile. Mobile rendering surfaces different components.",
+                "enum": ["desktop", "mobile"],
+                "default": "desktop",
+            },
+        },
+        "required": ["query"],
+        "additionalProperties": False,
+    },
+    "outputSchema": {
+        "description": "See SCHEMA.md §`results`, `extras`, `meta` for the full shape.",
+    },
+}
+
+
+# ─── google_ai_overview ───────────────────────────────────────────────────────
+
+GOOGLE_AI_OVERVIEW = {
+    "name": "google_ai_overview",
+    "description": (
+        "Get Google's AI Overview answer for a query. The AI Overview is the inline AI-synthesized "
+        "answer block Google places above classic SERP results. Returns: the answer text (split into "
+        "sections with headings); inline citation badges with corroboration counts ('+N additional "
+        "sources back this claim'); the right-side citation sidebar (top-3 sources by default); the "
+        "total source pool size ('27 sites' indicator). "
+        "Use this when you need Google's authoritative synthesis with citations — particularly for "
+        "informational, comparison, or commercial queries where Google has invested in an AI answer. "
+        "AI Overview fires for ~82% of typical queries (98% for question-form like 'how does X work', "
+        "96% for commercial like 'best X 2026', 56% for dev/technical queries where Google often shows "
+        "raw docs instead). When AIO does NOT fire, returns `present: false` with an unavailable_reason "
+        "and the classic SERP organic results in `results[]`. "
+        "Do NOT use this if you only need raw blue-link results — use google_search instead. "
+        "Do NOT use this for queries with `site:` or `filetype:` operators — those typically suppress AIO. "
+        "1 credit per call. Returns include the classic SERP as a side-effect (same fetch)."
+    ),
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "The search query. Question-form queries fire AIO most reliably.",
+                "minLength": 1,
+                "maxLength": 2048,
+            },
+            "region": {
+                "type": "string",
+                "description": (
+                    "ISO-3166-1 alpha-2 lowercase. **Important**: EU regions (de/fr/etc) have heavily "
+                    "trimmed citation pools (DMA effect). For full source coverage use region='us'."
+                ),
+                "pattern": "^[a-z]{2}$",
+                "default": "us",
+            },
+            "language": {
+                "type": "string",
+                "pattern": "^[a-z]{2,3}$",
+                "default": "en",
+            },
+            "device": {
+                "type": "string",
+                "enum": ["desktop", "mobile"],
+                "default": "desktop",
+            },
+        },
+        "required": ["query"],
+        "additionalProperties": False,
+    },
+    "outputSchema": {
+        "description": "See SCHEMA.md §`ai_answer` (surface='aio') + `results[]` + `extras` + `meta`.",
+    },
+}
+
+
+# ─── google_ai_mode ───────────────────────────────────────────────────────────
+
+GOOGLE_AI_MODE = {
+    "name": "google_ai_mode",
+    "description": (
+        "Get Google's AI Mode answer for a query. AI Mode is Google's dedicated AI-search tab "
+        "(URL parameter `udm=50`), distinct from AI Overview. Different surface, different ranker. "
+        "Returns: a deeper synthesized answer (numbered sections, typically 9 sub-sections of content); "
+        "more citations than AI Overview (commonly 20-40 cited sources vs 5-10 in AIO); a right-side "
+        "citation sidebar; total source pool indicator. The answer is conversational in tone. "
+        "Use this when you need maximum source breadth for a topic, deeper exploration than what AI "
+        "Overview provides, or specifically the 'AI Mode' surface for GEO/SEO research (e.g., 'is my "
+        "brand cited in AI Mode for X query?'). "
+        "Compared to google_ai_overview: AI Mode has roughly 4× more total sources, only ~14% URL "
+        "overlap with AIO for the same query, and deeper structured text. "
+        "AI Mode is a separate Google page (URL `?q=...&udm=50`), so this tool makes its own fetch and "
+        "costs 1 credit independently of google_search/google_ai_overview. "
+        "Do NOT use this if you only need a quick fact — google_ai_overview is faster and cheaper "
+        "context for short answers. AI Mode is heavier and slower."
+    ),
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "The search query.",
+                "minLength": 1,
+                "maxLength": 2048,
+            },
+            "region": {
+                "type": "string",
+                "description": (
+                    "ISO-3166-1 alpha-2 lowercase. AI Mode availability varies — EU regions may have "
+                    "it suppressed by DMA. US is most reliable."
+                ),
+                "pattern": "^[a-z]{2}$",
+                "default": "us",
+            },
+            "language": {
+                "type": "string",
+                "pattern": "^[a-z]{2,3}$",
+                "default": "en",
+            },
+            "device": {
+                "type": "string",
+                "enum": ["desktop", "mobile"],
+                "default": "desktop",
+            },
+        },
+        "required": ["query"],
+        "additionalProperties": False,
+    },
+    "outputSchema": {
+        "description": "See SCHEMA.md §`ai_answer` (surface='ai_mode'). `results[]` is empty for ai_mode.",
+    },
+}
+
+
+# ─── Tool registry ────────────────────────────────────────────────────────────
+
+ALL_TOOLS: list[dict[str, Any]] = [
+    GOOGLE_SEARCH,
+    GOOGLE_AI_OVERVIEW,
+    GOOGLE_AI_MODE,
+]
+
+
+def get_tool_by_name(name: str) -> dict[str, Any] | None:
+    """Look up a tool definition by its MCP name."""
+    for tool in ALL_TOOLS:
+        if tool["name"] == name:
+            return tool
+    return None
+
+
+# ─── Example responses (for docs + MCP server testing) ────────────────────────
+
+# Verified against the 20 Phase 1 samples. Production response shape per SCHEMA.md.
+EXAMPLE_RESPONSES = {
+    "google_search": {
+        "input": {"query": "best wireless headphones 2026", "region": "us"},
+        "output_sketch": {
+            "schema_version": "0.1.0",
+            "query": "best wireless headphones 2026",
+            "results": [
+                {
+                    "position": 1,
+                    "title": "The Best Wireless Headphones for 2026",
+                    "url": "https://www.rtings.com/headphones/...",
+                    "domain": "www.rtings.com",
+                    "snippet": "Our top pick is the Sony WH-1000XM6...",
+                    "sitelinks": [],
+                },
+                "...",
+            ],
+            "extras": {
+                "people_also_ask": [
+                    {"question": "Which is the best wireless headphone in 2026?"}
+                ],
+                "related_searches": [
+                    {"query": "best noise cancelling headphones"}
+                ],
+            },
+        },
+    },
+    "google_ai_overview": {
+        "input": {"query": "how does photosynthesis work", "region": "us"},
+        "output_sketch": {
+            "schema_version": "0.1.0",
+            "query": "how does photosynthesis work",
+            "ai_answer": {
+                "present": True,
+                "surface": "aio",
+                "text": "Photosynthesis is the process by which plants...",
+                "format": {"has_heading": True, "has_list": True, "has_table": False, "has_image": True},
+                "sections": [
+                    {"id": None, "heading": None, "text": "Photosynthesis is..."},
+                    {"id": None, "heading": "1. The Light-Dependent Reactions", "text": "..."},
+                ],
+                "inline_citations": [
+                    {
+                        "source_name": "National Geographic Society",
+                        "corroboration_count": 3,
+                        "url": None,
+                        "href_raw": "/goto?url=CAES...",
+                    },
+                ],
+                "sidebar_citations": [
+                    {
+                        "src_id": "1",
+                        "url": "https://education.nationalgeographic.org/...",
+                        "host": "education.nationalgeographic.org",
+                        "title": "Photosynthesis - Education | National Geographic Society",
+                    },
+                ],
+                "total_sources_available": 27,
+                "unavailable_reason": None,
+            },
+            "results": ["...10 organic..."],
+        },
+    },
+    "google_ai_mode": {
+        "input": {"query": "explain transformer architecture", "region": "us"},
+        "output_sketch": {
+            "schema_version": "0.1.0",
+            "query": "explain transformer architecture",
+            "ai_answer": {
+                "present": True,
+                "surface": "ai_mode",
+                "text": "The Transformer architecture is...",
+                "sections": [
+                    {"id": "0", "heading": None, "text": "..."},
+                    {"id": "1", "heading": "Self-Attention Mechanism", "text": "..."},
+                ],
+                "sidebar_citations": ["...3 cards..."],
+                "total_sources_available": 41,
+            },
+            "results": [],
+        },
+    },
+}
+
+
+# ─── Errors per tool ──────────────────────────────────────────────────────────
+
+# When a tool fails, the MCP server returns an error response that the LLM can branch on.
+# These are the documented failure cases by tool.
+
+ERROR_CASES = {
+    "google_search": [
+        ("invalid_request", "query missing or > 2048 chars"),
+        ("rate_limited", "Customer per-key rate limit exceeded"),
+        ("quota_exceeded", "API key has no remaining credits"),
+        ("google_rate_limited", "Google rate-limited our infrastructure; retry with backoff"),
+        ("captcha_failed", "CapSolver could not bypass captcha; try again"),
+        ("timeout", "Request exceeded internal 60s timeout"),
+    ],
+    "google_ai_overview": [
+        ("invalid_request", "query missing or > 2048 chars"),
+        ("rate_limited", "Customer per-key rate limit exceeded"),
+        ("quota_exceeded", "API key has no remaining credits"),
+        # Note: "AIO didn't fire" is NOT an error — returns ai_answer.present=False in 200 OK
+        ("google_rate_limited", "Google rate-limited"),
+        ("captcha_failed", "Captcha bypass failed"),
+        ("timeout", "Request timeout"),
+    ],
+    "google_ai_mode": [
+        ("invalid_request", "query missing or > 2048 chars"),
+        ("rate_limited", "Customer per-key rate limit exceeded"),
+        ("quota_exceeded", "API key has no remaining credits"),
+        # AI Mode often suppressed in EU — returns ai_answer.present=False, not an error
+        ("google_rate_limited", "Google rate-limited"),
+        ("captcha_failed", "Captcha bypass failed"),
+        ("timeout", "Request timeout"),
+    ],
+}

grounder_mcp-0.1.0/grounder_mcp.egg-info/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: grounder-mcp
+Version: 0.1.0
+Summary: Current Google answers (Search + AI Overview + AI Mode) as MCP tools for local LLMs and agents.
+Project-URL: Homepage, https://grounder.dev
+Keywords: mcp,google,ai-overview,ai-mode,search,llm,ollama,lm-studio
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.2
+Requires-Dist: httpx>=0.27
+
+# grounder-mcp
+
+From training data to current knowledge. Gives a local LLM or agent Google's live
+answers — the real **AI Overview**, **AI Mode**, and organic **Search** with citations —
+as three MCP tools. Privacy-first: the hosted service stores no query content.
+
+This package is a thin MCP client; the scraping and billing run on the hosted service,
+so it installs with no Playwright and runs fine on a laptop.
+
+## Use
+
+```json
+{
+  "mcpServers": {
+    "grounder": {
+      "command": "uvx",
+      "args": ["grounder-mcp"],
+      "env": { "GROUNDER_API_KEY": "your_key_here" }
+    }
+  }
+}
+```
+
+Get a key at https://grounder.dev. Tools: `google_search`, `google_ai_overview`,
+`google_ai_mode` — one credit per call.

grounder_mcp-0.1.0/grounder_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+grounder/__init__.py
+grounder/mcp_server.py
+grounder/tools.py
+grounder_mcp.egg-info/PKG-INFO
+grounder_mcp.egg-info/SOURCES.txt
+grounder_mcp.egg-info/dependency_links.txt
+grounder_mcp.egg-info/entry_points.txt
+grounder_mcp.egg-info/requires.txt
+grounder_mcp.egg-info/top_level.txt

grounder_mcp-0.1.0/grounder_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

grounder_mcp-0.1.0/grounder_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+grounder-mcp = grounder.mcp_server:main

grounder_mcp-0.1.0/grounder_mcp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mcp>=1.2
+httpx>=0.27

grounder_mcp-0.1.0/grounder_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+grounder

grounder_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "grounder-mcp"
+version = "0.1.0"
+description = "Current Google answers (Search + AI Overview + AI Mode) as MCP tools for local LLMs and agents."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.2",
+    "httpx>=0.27",
+]
+keywords = ["mcp", "google", "ai-overview", "ai-mode", "search", "llm", "ollama", "lm-studio"]
+
+[project.urls]
+Homepage = "https://grounder.dev"
+
+[project.scripts]
+grounder-mcp = "grounder.mcp_server:main"
+
+[tool.setuptools]
+packages = ["grounder"]

grounder_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+