g4-data-mcp 0.1.0__tar.gz

g4_data_mcp-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.env

g4_data_mcp-0.1.0/INSTALL_G4OS.md

@@ -0,0 +1,99 @@
+# Instalar o G4 Data MCP no G4OS
+
+Onboarding do source `g4-data` (o MCP de dados) no G4OS. O MCP roda local (stdio) via `uvx`, em nome
+do usuário: comercial (Looker/CA API), Genie One e SQL puro do Databricks. O usuário **não configura
+nada** (hosts e projeto são default embutido; identidade e allowlist vêm do token). O G4OS executa os
+comandos; a única ação do usuário é completar os dois logins no browser na primeira vez.
+
+## 0. Pré-requisito: `uv` (traz o `uvx`)
+
+Se `uvx` não existir, instalar o `uv`:
+- **Mac:** `curl -LsSf https://astral.sh/uv/install.sh | sh` (ou `brew install uv`)
+- **Windows:** `irm https://astral.sh/uv/install.ps1 | iex` (ou `winget install --id=astral-sh.uv -e`)
+
+Conferir: `uvx --version`.
+
+## 1. Criar o source `g4-data`
+
+Criar `sources/g4-data/config.json` (o `id` é `g4-data_<8hex>`, gerar o random):
+
+```json
+{
+  "id": "g4-data_0a1b2c3d",
+  "name": "G4 Data",
+  "slug": "g4-data",
+  "provider": "g4",
+  "type": "mcp",
+  "icon": "📊",
+  "tagline": "Pergunte dados do G4: comercial (Looker), Genie e SQL do Databricks, em nome do usuário.",
+  "mcp": {
+    "transport": "stdio",
+    "command": "uvx",
+    "args": ["g4-data-mcp"],
+    "authType": "none"
+  }
+}
+```
+
+> `authType: "none"` porque o **próprio pacote** faz o OAuth (Databricks U2M + Looker PKCE) no
+> primeiro uso; não é o G4OS que dispara o fluxo de auth do source.
+
+## 2. Permissões (Explore mode, read-only)
+
+Criar `sources/g4-data/permissions.json`:
+
+```json
+{
+  "allowedMcpPatterns": [
+    { "pattern": "ask_commercial", "comment": "Pergunta ao agente comercial (Looker)" },
+    { "pattern": "question", "comment": "Pergunta de dados (Genie ou pede SQL)" },
+    { "pattern": "run_sql", "comment": "Executa SELECT read-only no Databricks" }
+  ]
+}
+```
+
+## 3. guide.md
+
+Criar `sources/g4-data/guide.md`:
+
+```markdown
+# G4 Data
+
+Dados do G4 em linguagem natural, em nome do usuário logado.
+
+## Tools
+- `ask_commercial(question)` — funil comercial (Win Rate, conversões, deals, ranking de AE/SDR).
+- `question(question)` — dados fora do comercial. Se o usuário estiver no grupo `MCP Genie Users` do
+  Databricks, responde via Genie; senão retorna `needs_sql` (então gere um SELECT e chame `run_sql`).
+- `run_sql(statement)` — executa um SELECT (Unity Catalog, `catalog.schema.table`), read-only.
+
+## Notas
+- Roda com as permissões do próprio usuário (audit por pessoa nos dois lados).
+- Genie é restrito ao grupo `MCP Genie Users` (gerenciado no admin do Databricks).
+```
+
+## 4. Validar
+
+```
+source_test({ sourceSlug: "g4-data" })
+```
+Deve conectar e listar as 3 tools (`ask_commercial`, `question`, `run_sql`).
+
+## 5. Primeiro login (uma vez por usuário)
+
+O OAuth é disparado pelo pacote no **primeiro uso** de cada backend, abrindo o browser:
+- primeira chamada a `question`/`run_sql` → login **Databricks** (U2M, browser);
+- primeira chamada a `ask_commercial` → login **Looker** (PKCE, browser).
+
+Para pré-autenticar de uma vez (recomendado no onboarding), fazer duas perguntas de teste, uma de
+cada tipo, e pedir ao usuário para concluir os dois logins no browser. Depois disso os tokens ficam
+cacheados (`~/.config/g4-data-mcp/` e o cache do databricks-sdk) e renovam sozinhos.
+
+## Notas
+
+- **Zero configuração do usuário:** nenhum host, chave ou e-mail é pedido. Tudo default ou derivado
+  do token.
+- **Allowlist do Genie:** pertencer ao grupo `MCP Genie Users` no Databricks. Quem não está usa o SQL
+  puro (`run_sql`). Trocar o grupo: env `GENIE_GROUP` no `config.json`.
+- **Atualização:** quando sai uma versão nova no PyPI, o `uvx` passa a usá-la (pode-se pinar com
+  `g4-data-mcp==<versão>` nos `args`).

g4_data_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: g4-data-mcp
+Version: 0.1.0
+Summary: MCP de dados do G4: roteia perguntas para o agente comercial (Looker/CA API), Genie ou SQL puro do Databricks, em nome do usuário.
+Requires-Python: >=3.10
+Requires-Dist: databricks-sdk>=0.38.0
+Requires-Dist: google-cloud-geminidataanalytics
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic-settings

g4_data_mcp-0.1.0/README.md

@@ -0,0 +1,73 @@
+# g4-data-mcp
+
+MCP de dados do G4, instalado no G4OS como pacote **stdio local**. Recebe perguntas e roteia, **em
+nome do usuário** (OBO), para o agente comercial (Looker/CA API), o Genie ou o SQL puro do Databricks.
+
+Sem IA de classificação aqui: o G4OS escolhe a tool pela descrição. Cada agente especializado é uma
+tool; a decisão Genie-vs-SQL (allowlist) mora dentro deste MCP.
+
+## Tools
+
+- **`ask_commercial(question)`** — funil comercial (oportunidades, Win Rate, conversões, deals,
+  faturamento, ranking de AE/SDR). Chama a Conversational Analytics API do Google sobre o DataAgent
+  `comercial-g4-v0` (explore `funil_comercial` do Looker), com o token do Looker **do usuário**.
+- **`question(question)`** — perguntas de dados fora do comercial. Se o usuário está na allowlist do
+  Genie, responde via **Genie One** (managed MCP `/api/2.0/mcp/genie`, enterprise-wide, sem space).
+  Senão, retorna `status: needs_sql` e o G4OS escreve o SELECT.
+- **`run_sql(statement)`** — executa o SELECT via o **managed MCP SQL** (`/api/2.0/mcp/sql`,
+  `execute_sql_read_only`) com as permissões do próprio usuário.
+
+## Auth (por usuário, OBO)
+
+- **Databricks:** unified auth do `databricks-sdk` (OAuth U2M `external-browser`, `profile`, ou env).
+  O MCP vira **cliente** dos managed MCP do Databricks (Genie One e SQL) com o Bearer do usuário, como
+  o `uc-mcp-proxy`. A query roda como o usuário (`current_user()` confirma) → audit por pessoa.
+- **Looker:** OAuth PKCE per-user (`looker_oauth.py`). O OAuth client app `g4-data-mcp` já está
+  registrado no Looker (`redirect_uri=http://localhost:47821/callback`, scope `cors_api`). O usuário
+  loga no browser (`{host}/auth`), troca o code em `{host}:19999/api/token` por um `access_token`
+  dele + `refresh_token`, cacheado em `~/.config/g4-data-mcp/looker_token.json`. Esse token vira a
+  credencial da CA API. Sem client_secret (é PKCE).
+- **Identidade e allowlist:** o e-mail e os grupos vêm do **token do Databricks** do usuário
+  (`current_user().me()`), nada é passado por env. A allowlist do Genie = pertencer ao grupo
+  `genie_group` (default `MCP Genie Users`) no Databricks; gerenciado no admin do Databricks, vale para
+  todos na hora, sem republicar o pacote.
+
+## Rodar local
+
+```bash
+uv venv --python 3.12 .venv && . .venv/bin/activate
+uv pip install -e .
+
+# SQL puro (read-only), em nome do usuário do profile (via managed MCP SQL):
+DATABRICKS_PROFILE=g4 python -m scripts.smoke sql "SELECT current_user()"
+# Genie One (custa):
+DATABRICKS_PROFILE=g4 python -m scripts.smoke genie "quantos leads em janeiro de 2026?"
+# Servir via stdio (o que o G4OS roda):
+g4-data-mcp
+```
+
+## Config do source no G4OS
+
+O pacote é publicado no PyPI, então o G4OS instala e roda com `uvx g4-data-mcp` (sem GitHub, sem
+auth de índice). Hosts/projeto/location são default embutido e identidade/allowlist vêm do token, então
+o source **não precisa de env nenhuma**:
+
+```json
+{
+  "type": "mcp",
+  "mcp": {
+    "transport": "stdio",
+    "command": "uvx",
+    "args": ["g4-data-mcp"]
+  }
+}
+```
+
+O usuário não configura nada: na 1a vez faz OAuth U2M do Databricks (browser) e OAuth PKCE do Looker
+(browser); os tokens ficam cacheados e renovam sozinhos. Qualquer default pode ser sobrescrito por env
+(ver `config.py`) — ex. `GENIE_GROUP` para trocar o grupo da allowlist.
+
+## Pendências
+
+- Publicar no PyPI (workflow `release-data-mcp.yml`, Trusted Publishing) e escrever o doc de
+  instalação do source no G4OS. Databricks (Genie One + SQL) e comercial já validados E2E.

g4_data_mcp-0.1.0/g4_data_mcp/allowlist.py

@@ -0,0 +1,11 @@
+"""Allowlist do Genie: pertencer a um grupo do Databricks (`genie_group`), global e vivo.
+
+O Lucas gerencia quem pode usar o Genie (caro) adicionando/removendo pessoas do grupo no admin do
+Databricks; vale na hora, para todos, sem republicar o pacote. Quem não está no grupo cai no SQL
+puro. Reforço real (defense-in-depth): grant no Genie space + Genie budget por grupo no Databricks.
+"""
+from .config import get_settings
+
+
+def can_use_genie(user_groups: set[str]) -> bool:
+    return get_settings().genie_group in user_groups

g4_data_mcp-0.1.0/g4_data_mcp/auth.py

@@ -0,0 +1,47 @@
+"""Autenticação por usuário (on-behalf-of).
+
+Databricks: unified auth do databricks-sdk (OAuth U2M external-browser/profile/env); o token roda as
+REST/MCP como o próprio usuário. Looker: OAuth PKCE per-user (ver looker_oauth), o access_token do
+usuário vira a credencial da CA API, atribuindo a atividade a ele.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from databricks.sdk import WorkspaceClient
+from google.cloud import geminidataanalytics
+
+from . import looker_oauth
+from .config import get_settings
+
+
+@lru_cache
+def workspace() -> WorkspaceClient:
+    s = get_settings()
+    if s.databricks_profile:
+        return WorkspaceClient(profile=s.databricks_profile)
+    return WorkspaceClient(
+        host=s.databricks_host or None,
+        auth_type=s.databricks_auth_type or None,
+    )
+
+
+@lru_cache
+def _me():
+    return workspace().current_user.me()
+
+
+def current_user_email() -> str:
+    return _me().user_name or ""
+
+
+def user_groups() -> set[str]:
+    """Grupos do usuário no Databricks (do próprio token), para a allowlist do Genie."""
+    return {g.display for g in (_me().groups or []) if g.display}
+
+
+def ca_credentials() -> geminidataanalytics.Credentials:
+    """Credencial da CA API = access_token do Looker do próprio usuário (OAuth PKCE)."""
+    creds = geminidataanalytics.Credentials()
+    creds.oauth.token.access_token = looker_oauth.access_token()
+    return creds

g4_data_mcp-0.1.0/g4_data_mcp/commercial.py

@@ -0,0 +1,194 @@
+"""Agente comercial via Conversational Analytics API (chat stateless).
+
+Fala com o DataAgent `comercial-g4-v0` já provisionado (comercial/scripts/provision_agent.py),
+que aponta para o explore `funil_comercial` do Looker. Lógica migrada de comercial/app/ca_client.py;
+a diferença é que a credencial do Looker é a do usuário final (impersonation), não a de serviço.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from google.api_core import client_options as client_options_lib
+from google.cloud import geminidataanalytics
+
+from .config import Settings, get_settings
+
+
+@dataclass
+class AgentResult:
+    answer: str = ""
+    sql: str | None = None
+    explore_used: str | None = None
+    data: list[dict[str, Any]] | None = None
+    chart: dict[str, Any] | None = None
+    looker_queries: list[dict[str, Any]] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+_client: geminidataanalytics.DataChatServiceClient | None = None
+
+
+def _chat_client(settings: Settings) -> geminidataanalytics.DataChatServiceClient:
+    global _client
+    if _client is None:
+        opts = client_options_lib.ClientOptions(api_endpoint=settings.api_endpoint)
+        _client = geminidataanalytics.DataChatServiceClient(client_options=opts)
+    return _client
+
+
+def chat(question: str, credentials: geminidataanalytics.Credentials, settings: Settings | None = None) -> AgentResult:
+    settings = settings or get_settings()
+    client = _chat_client(settings)
+
+    message = geminidataanalytics.Message()
+    message.user_message.text = question
+
+    data_agent_context = geminidataanalytics.DataAgentContext()
+    data_agent_context.data_agent = settings.data_agent_path
+
+    request = geminidataanalytics.ChatRequest(
+        parent=settings.parent_path,
+        messages=[message],
+        data_agent_context=data_agent_context,
+        credentials=credentials,
+    )
+    return _parse_stream(client.chat(request=request, timeout=300))
+
+
+def _parse_stream(stream) -> AgentResult:
+    final_blocks: list[str] = []
+    errors: list[str] = []
+    looker_queries: list[dict[str, Any]] = []
+    sql: str | None = None
+    explore_used: str | None = None
+    data_rows: list[dict[str, Any]] | None = None
+    chart: dict[str, Any] | None = None
+
+    for response in stream:
+        sys_msg = getattr(response, "system_message", None)
+        if sys_msg is None:
+            continue
+
+        text = getattr(sys_msg, "text", None)
+        if text is not None:
+            joined = " ".join(str(p) for p in (getattr(text, "parts", []) or []) if p).strip()
+            if joined and _is_final(text):
+                final_blocks.append(joined)
+
+        data_obj = getattr(sys_msg, "data", None)
+        if data_obj is not None:
+            lq = _extract_looker_query(data_obj)
+            if lq:
+                looker_queries.append(lq)
+                explore_used = explore_used or lq.get("explore")
+            sql = sql or _first_str(
+                getattr(data_obj, "generated_sql", None), getattr(data_obj, "sql", None)
+            )
+            rows = _extract_rows(data_obj)
+            if rows is not None:
+                data_rows = rows
+
+        schema_obj = getattr(sys_msg, "schema", None)
+        if schema_obj is not None and explore_used is None:
+            explore_used = _explore_from_schema(schema_obj)
+
+        chart_obj = getattr(sys_msg, "chart", None)
+        if chart_obj is not None and chart is None:
+            chart = _extract_chart(chart_obj)
+
+        err = getattr(sys_msg, "error", None)
+        if err is not None:
+            s = str(err).replace("\n", " ").strip()
+            if s:
+                errors.append(s[:500])
+
+    deduped: list[str] = []
+    for block in final_blocks:
+        if block not in deduped:
+            deduped.append(block)
+
+    return AgentResult(
+        answer="\n\n".join(deduped).strip(),
+        sql=sql,
+        explore_used=explore_used,
+        data=data_rows,
+        chart=chart,
+        looker_queries=looker_queries,
+        errors=errors,
+    )
+
+
+def _is_final(text_msg) -> bool:
+    return getattr(text_msg, "text_type", None) == (
+        geminidataanalytics.TextMessage.TextType.FINAL_RESPONSE
+    )
+
+
+def _extract_looker_query(data_obj) -> dict[str, Any] | None:
+    query = getattr(data_obj, "query", None)
+    looker = getattr(query, "looker", None) if query is not None else None
+    if looker is None:
+        return None
+    fields = list(getattr(looker, "fields", []) or [])
+    filters = {f.field: f.value for f in (getattr(looker, "filters", []) or [])}
+    if not fields and not filters:
+        return None
+    return {
+        "model": _first_str(getattr(looker, "model", None)),
+        "explore": _first_str(getattr(looker, "explore", None)),
+        "fields": fields,
+        "filters": filters,
+    }
+
+
+def _first_str(*values) -> str | None:
+    for v in values:
+        if v:
+            s = str(v).strip()
+            if s:
+                return s
+    return None
+
+
+def _jsonable(value: Any) -> Any:
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if hasattr(value, "items"):
+        return {str(k): _jsonable(v) for k, v in value.items()}
+    if hasattr(value, "__iter__") and not isinstance(value, (str, bytes)):
+        return [_jsonable(v) for v in value]
+    return str(value)
+
+
+def _extract_rows(data_obj) -> list[dict[str, Any]] | None:
+    result = getattr(data_obj, "result", None)
+    rows = getattr(result, "data", None) if result is not None else None
+    if not rows:
+        return None
+    try:
+        return [_jsonable(r) for r in rows]
+    except Exception:
+        return None
+
+
+def _extract_chart(chart_obj) -> dict[str, Any] | None:
+    result = getattr(chart_obj, "result", None)
+    vega = getattr(result, "vega_config", None) if result is not None else None
+    if vega is None:
+        return None
+    try:
+        return _jsonable(vega)
+    except Exception:
+        return None
+
+
+def _explore_from_schema(schema_obj) -> str | None:
+    result = getattr(schema_obj, "result", None)
+    datasources = getattr(result, "datasources", None) if result is not None else None
+    for ds in datasources or []:
+        ref = getattr(ds, "looker_explore_reference", None)
+        explore = getattr(ref, "explore", None) if ref is not None else None
+        if explore:
+            return str(explore)
+    return None

g4_data_mcp-0.1.0/g4_data_mcp/config.py

@@ -0,0 +1,60 @@
+"""Configuração do MCP de dados, lida de variáveis de ambiente.
+
+O G4OS roda o pacote como processo stdio local e injeta o contexto do usuário e os
+endpoints via env (bloco `env` do source). Nada é hardcoded para manter o container portável.
+"""
+from functools import lru_cache
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore", populate_by_name=True)
+
+    # Databricks (Genie + SQL). auth via unified auth do databricks-sdk. Defaults embutidos para o
+    # usuário não configurar nada: só o OAuth U2M no browser na 1a vez. Protegido por login.
+    databricks_host: str = Field(
+        default="https://dbc-8acefaf9-a170.cloud.databricks.com", validation_alias="DATABRICKS_HOST"
+    )
+    databricks_profile: str = Field(default="", validation_alias="DATABRICKS_PROFILE")
+    databricks_auth_type: str = Field(default="external-browser", validation_alias="DATABRICKS_AUTH_TYPE")
+
+    # Allowlist do Genie = pertencer a este grupo do Databricks (global e vivo; o Lucas gerencia no
+    # admin do Databricks). Fonte única: o token do usuário já traz os grupos dele.
+    genie_group: str = Field(default="MCP Genie Users", validation_alias="GENIE_GROUP")
+
+    # Looker (fonte do agente comercial); auth = OAuth PKCE per-user (ver looker_oauth)
+    looker_instance_uri: str = Field(
+        default="https://g4educacao.cloud.looker.com", validation_alias="LOOKER_INSTANCE_URI"
+    )
+
+    # Conversational Analytics API (agente comercial)
+    gcp_project: str = Field(default="g4-data", validation_alias="GCP_PROJECT")
+    gcp_location: str = Field(default="us-east4", validation_alias="GCP_LOCATION")
+    ca_data_agent_id: str = Field(default="comercial-g4-v0", validation_alias="CA_DATA_AGENT_ID")
+
+    @property
+    def data_agent_path(self) -> str:
+        return (
+            f"projects/{self.gcp_project}/locations/{self.gcp_location}"
+            f"/dataAgents/{self.ca_data_agent_id}"
+        )
+
+    @property
+    def parent_path(self) -> str:
+        return f"projects/{self.gcp_project}/locations/{self.gcp_location}"
+
+    @property
+    def api_endpoint(self) -> str:
+        loc = self.gcp_location
+        if not loc or loc == "global":
+            return "geminidataanalytics.googleapis.com"
+        if "-" in loc:
+            return f"geminidataanalytics-{loc}.googleapis.com"
+        return f"geminidataanalytics.{loc}.rep.googleapis.com"
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

g4_data_mcp-0.1.0/g4_data_mcp/databricks.py

@@ -0,0 +1,123 @@
+"""Databricks em nome do usuário, via os managed MCP servers (cliente MCP + Bearer do usuário).
+
+Ambos os paths rodam com a identidade e as permissões da pessoa (audit + Unity Catalog por usuário),
+como o uc-mcp-proxy faz. É o padrão que o Databricks suporta para stdio local (o token OAuth U2M do
+usuário, obtido pelo databricks-sdk, autentica o cliente MCP).
+
+- Genie One: `/api/2.0/mcp/genie` (enterprise-wide, sem space), tools genie_ask/genie_poll_response.
+- SQL puro:  `/api/2.0/mcp/sql`, tool execute_sql_read_only/poll_sql_result (read-only nativo).
+"""
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from typing import Any
+
+from databricks.sdk import WorkspaceClient
+from mcp.client.session import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+
+def _bearer(w: WorkspaceClient) -> str:
+    return w.config.authenticate()["Authorization"].split(" ", 1)[1]
+
+
+def _mcp_url(w: WorkspaceClient, suffix: str) -> str:
+    return w.config.host.rstrip("/") + suffix
+
+
+def _text(res) -> str:
+    return "\n\n".join(c.text for c in (res.content or []) if getattr(c, "text", None)).strip()
+
+
+@asynccontextmanager
+async def _session(url: str, token: str):
+    headers = {"Authorization": f"Bearer {token}"}
+    async with streamablehttp_client(url, headers=headers) as (read, write, _):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            yield session
+
+
+async def _genie_call(url: str, token: str, question: str, *, poll_max: int = 120, poll_interval: float = 3.0) -> dict[str, Any]:
+    async with _session(url, token) as s:
+        res = await s.call_tool("genie_ask", {"question": question})
+        sc: dict[str, Any] = res.structuredContent or {}
+        cid, rid = sc.get("conversation_id"), sc.get("response_id")
+
+        for _ in range(poll_max):
+            status = sc.get("status")
+            if sc.get("final_answer") or (status and status != "in_progress"):
+                break
+            if not (cid and rid):
+                break
+            await asyncio.sleep(poll_interval)
+            res = await s.call_tool("genie_poll_response", {"conversation_id": cid, "response_id": rid})
+            sc = res.structuredContent or {}
+
+        return {
+            "answer": sc.get("final_answer") or _text(res),
+            "status": sc.get("status"),
+            "deep_link": sc.get("deep_link"),
+            "conversation_id": cid,
+            "response_id": rid,
+        }
+
+
+def _sql_state(sc: dict[str, Any]) -> str:
+    return ((sc.get("status") or {}).get("state") or "").upper()
+
+
+def _cell(v: Any) -> Any:
+    if isinstance(v, dict):
+        return next(iter(v.values()), None)
+    return v
+
+
+def _sql_rows(sc: dict[str, Any]) -> dict[str, Any]:
+    manifest = sc.get("manifest") or {}
+    cols = [c["name"] for c in (manifest.get("schema") or {}).get("columns", [])]
+    raw = (sc.get("result") or {}).get("data_array") or []
+    rows = []
+    for r in raw:
+        values = r.get("values", []) if isinstance(r, dict) else r
+        rows.append(dict(zip(cols, (_cell(v) for v in values))))
+    return {
+        "columns": cols,
+        "rows": rows,
+        "row_count": manifest.get("total_row_count", len(rows)),
+        "truncated": bool(manifest.get("truncated")),
+        "statement_id": sc.get("statement_id"),
+    }
+
+
+async def _sql_call(url: str, token: str, statement: str, *, poll_max: int = 100, poll_interval: float = 2.0) -> dict[str, Any]:
+    async with _session(url, token) as s:
+        res = await s.call_tool("execute_sql_read_only", {"query": statement})
+        sc: dict[str, Any] = res.structuredContent or {}
+
+        for _ in range(poll_max):
+            if _sql_state(sc) not in ("PENDING", "RUNNING"):
+                break
+            sid = sc.get("statement_id")
+            if not sid:
+                break
+            await asyncio.sleep(poll_interval)
+            res = await s.call_tool("poll_sql_result", {"statement_id": sid})
+            sc = res.structuredContent or {}
+
+        state = _sql_state(sc)
+        if state and state != "SUCCEEDED":
+            err = ((sc.get("status") or {}).get("error") or {}).get("message") or state
+            raise RuntimeError(f"SQL {state}: {err}")
+        return _sql_rows(sc)
+
+
+def genie_ask(w: WorkspaceClient, question: str) -> dict[str, Any]:
+    """Pergunta ao Genie One (managed MCP enterprise-wide), como o usuário."""
+    return asyncio.run(_genie_call(_mcp_url(w, "/api/2.0/mcp/genie"), _bearer(w), question))
+
+
+def run_sql(w: WorkspaceClient, statement: str) -> dict[str, Any]:
+    """Executa um SELECT read-only via o managed MCP SQL, como o usuário."""
+    return asyncio.run(_sql_call(_mcp_url(w, "/api/2.0/mcp/sql"), _bearer(w), statement))

g4_data_mcp-0.1.0/g4_data_mcp/looker_oauth.py

@@ -0,0 +1,152 @@
+"""OAuth PKCE do Looker (per-user), para o agente comercial.
+
+O OAuth client app foi registrado 1x no Looker (`client_guid=g4-data-mcp`). Aqui só o login do
+usuário: browser (Authorization Code + PKCE) → `access_token` DELE + `refresh_token` (~1 mês),
+cacheado local e renovado sozinho. O token vira a credencial da CA API, então a query roda como a
+pessoa. Espelha o external-browser do databricks-sdk (nenhum client_secret, é PKCE).
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import http.server
+import json
+import secrets
+import threading
+import time
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from urllib.parse import urlparse
+
+from .config import Settings, get_settings
+
+_CLIENT_GUID = "g4-data-mcp"
+_REDIRECT_PORT = 47821
+_REDIRECT_URI = f"http://localhost:{_REDIRECT_PORT}/callback"
+_SCOPE = "cors_api"
+
+
+def _cache_path() -> Path:
+    d = Path.home() / ".config" / "g4-data-mcp"
+    d.mkdir(parents=True, exist_ok=True)
+    return d / "looker_token.json"
+
+
+def _urls(settings: Settings) -> tuple[str, str]:
+    p = urlparse(settings.looker_instance_uri)
+    auth_url = f"{p.scheme}://{p.hostname}/auth"
+    token_url = f"{p.scheme}://{p.hostname}:19999/api/token"
+    return auth_url, token_url
+
+
+def _pkce() -> tuple[str, str]:
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
+    digest = hashlib.sha256(verifier.encode()).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+    return verifier, challenge
+
+
+def _exchange(token_url: str, payload: dict) -> dict:
+    data = json.dumps(payload).encode()
+    req = urllib.request.Request(
+        token_url, data=data, method="POST",
+        headers={"Content-Type": "application/json;charset=UTF-8"},
+    )
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        tok = json.loads(resp.read().decode())
+    tok["_obtained_at"] = int(time.time())
+    _cache_path().write_text(json.dumps(tok))
+    return tok
+
+
+def _browser_login(auth_url: str, token_url: str) -> dict:
+    verifier, challenge = _pkce()
+    state = secrets.token_urlsafe(16)
+    query = urllib.parse.urlencode({
+        "response_type": "code",
+        "client_id": _CLIENT_GUID,
+        "redirect_uri": _REDIRECT_URI,
+        "scope": _SCOPE,
+        "state": state,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+    })
+
+    received: dict[str, str | None] = {}
+
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def do_GET(self):
+            parsed = urllib.parse.urlparse(self.path)
+            if parsed.path != "/callback":
+                self.send_response(404)
+                self.end_headers()
+                return
+            qs = urllib.parse.parse_qs(parsed.query)
+            received["code"] = qs.get("code", [None])[0]
+            received["state"] = qs.get("state", [None])[0]
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(b"<h3>Login concluido. Pode fechar esta aba.</h3>")
+
+        def log_message(self, *args):
+            pass
+
+    class _Server(http.server.HTTPServer):
+        allow_reuse_address = True
+        allow_reuse_port = True
+
+    httpd = _Server(("localhost", _REDIRECT_PORT), Handler)
+    threading.Thread(target=httpd.handle_request, daemon=True).start()
+
+    import webbrowser
+    webbrowser.open(f"{auth_url}?{query}")
+
+    for _ in range(300):
+        if received.get("code"):
+            break
+        time.sleep(1)
+    httpd.server_close()
+
+    if not received.get("code") or received.get("state") != state:
+        raise RuntimeError("Looker OAuth: callback sem code válido (ou state divergente)")
+
+    return _exchange(token_url, {
+        "grant_type": "authorization_code",
+        "client_id": _CLIENT_GUID,
+        "redirect_uri": _REDIRECT_URI,
+        "code": received["code"],
+        "code_verifier": verifier,
+    })
+
+
+def access_token(settings: Settings | None = None) -> str:
+    """access_token do Looker do usuário (do cache com refresh, ou disparando o browser)."""
+    settings = settings or get_settings()
+    auth_url, token_url = _urls(settings)
+
+    cache = _cache_path()
+    tok = None
+    if cache.exists():
+        try:
+            tok = json.loads(cache.read_text())
+        except Exception:
+            tok = None
+
+    if tok and tok.get("access_token"):
+        valid_until = tok.get("_obtained_at", 0) + int(tok.get("expires_in", 3600)) - 60
+        if time.time() < valid_until:
+            return tok["access_token"]
+        if tok.get("refresh_token"):
+            try:
+                refreshed = _exchange(token_url, {
+                    "grant_type": "refresh_token",
+                    "client_id": _CLIENT_GUID,
+                    "refresh_token": tok["refresh_token"],
+                })
+                return refreshed["access_token"]
+            except Exception:
+                pass
+
+    return _browser_login(auth_url, token_url)["access_token"]

g4_data_mcp-0.1.0/g4_data_mcp/server.py

@@ -0,0 +1,76 @@
+"""MCP de dados do G4 (stdio).
+
+O G4OS escolhe a tool pela descrição (sem IA de classificação aqui). Cada agente especializado é
+uma tool; o fallback genérico decide, pela allowlist do usuário, entre Genie e SQL puro. Tudo roda
+em nome do usuário (OBO), para dar rastreio por pessoa no Looker e no Databricks.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from . import allowlist, auth, commercial
+from . import databricks as dbx
+
+mcp = FastMCP("g4-data")
+
+
+@mcp.tool()
+def ask_commercial(question: str) -> dict[str, Any]:
+    """Responde perguntas sobre o FUNIL COMERCIAL do G4.
+
+    Use para vendas/comercial: oportunidades, Win Rate, conversões (CR01..CR04), deals ativos,
+    faturamento, ranking de AE (proprietário) e SDR (qualificador), comparação de períodos.
+    Não use para metas/atingimento, Potencial de Receita nem dados fora do funil.
+    """
+    result = commercial.chat(question, auth.ca_credentials())
+    return {
+        "answer": result.answer,
+        "sql": result.sql,
+        "explore_used": result.explore_used,
+        "data": result.data,
+        "chart": result.chart,
+        "errors": result.errors or None,
+    }
+
+
+@mcp.tool()
+def question(question: str) -> dict[str, Any]:
+    """Responde perguntas gerais sobre os dados do G4 que NENHUM agente especializado cobre.
+
+    Use quando a pergunta não é do funil comercial (ex.: produto, marketing, financeiro, pós-venda).
+    Se o usuário puder usar o Genie, responde direto. Caso contrário, retorna status `needs_sql`:
+    escreva um SELECT (Databricks SQL, Unity Catalog `production.*`) e chame `run_sql`.
+    """
+    if not allowlist.can_use_genie(auth.user_groups()):
+        return {
+            "status": "needs_sql",
+            "message": (
+                "Você não tem acesso ao Genie. Escreva um SELECT (Databricks SQL, Unity Catalog, "
+                "namespace de três níveis catalog.schema.table, ex. production.gold.*) e chame a "
+                "tool run_sql. Para descobrir os dados: SHOW SCHEMAS IN production; "
+                "SHOW TABLES IN production.gold; DESCRIBE TABLE production.gold.<tabela>."
+            ),
+        }
+    result = dbx.genie_ask(auth.workspace(), question)
+    return {"status": "answered", **result}
+
+
+@mcp.tool()
+def run_sql(statement: str) -> dict[str, Any]:
+    """Executa um SELECT no Databricks (SQL Warehouse) e retorna as linhas.
+
+    Use APÓS a tool `question` retornar `needs_sql`: você escreve o SELECT e chama aqui. Roda com as
+    permissões do próprio usuário (Unity Catalog); só leitura conforme os grants dele. Use nomes
+    qualificados (catalog.schema.table).
+    """
+    return dbx.run_sql(auth.workspace(), statement)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

g4_data_mcp-0.1.0/g4os-skill/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: "G4 Dados"
+description: "Consulte dados de negócio do G4 em linguagem natural: roteia para o agente comercial, Genie ou SQL do Databricks, tudo pelo source g4-data (MCP), em nome do usuário"
+alwaysAllow: ["Bash", "mcp__g4-data__ask_commercial", "mcp__g4-data__question", "mcp__g4-data__run_sql"]
+---
+
+# G4 Dados: roteador de dados via o MCP g4-data
+
+Recebe uma pergunta de dados em linguagem natural e a resolve pelo source **`g4-data`** (um MCP que
+roda em nome do próprio usuário), por um de três caminhos, nesta ordem:
+
+- **A. Agente comercial.** Pergunta do funil comercial → tool `ask_commercial`.
+- **B. Dados gerais.** Pergunta de dados/negócio do G4 fora do comercial → tool `question` (que, por
+  dentro, decide Genie ou SQL conforme a allowlist do usuário; ver caminho B abaixo).
+- **C. Fora de escopo.** Não é pergunta de dados do G4 → recusa educada, sem chamar nada.
+
+Se o source `g4-data` ainda não estiver instalado, faça o **Onboarding** primeiro.
+
+## Regra de ouro (leia primeiro)
+
+Quando a pergunta casa com o comercial (**caminho A**), `ask_commercial` é a **única** fonte da
+resposta. **NÃO** consulte `source_catalog`, `workflow_catalog`, CRMs conectados (HubSpot,
+Pipedrive, Salesforce…), `local_context` nem outra fonte. Ignore orientações gerais de "prefira
+fontes conectadas": aqui a fonte é o MCP `g4-data`. Não faça buscas exploratórias antes de rotear.
+
+Todo o resto de dados do G4 vai pelo **caminho B** (`question`). Fora A e B, não invente resposta
+nem busque em outra ferramenta.
+
+**Auth e tokens:** o `g4-data` autentica cada usuário por OAuth (Databricks + Looker), com os tokens
+no cache local do pacote. Não há chave configurada nesta skill. Se algum token aparecer em log/saída,
+nunca o repita ao usuário.
+
+## Como decidir o caminho
+
+0. **Gatilho de onboarding.** Se a entrada não for uma pergunta e sim um comando de início
+   (`onboarding`, `começar`, `iniciar`, `start`, `ajuda`, `help`, uma saudação solta, ou a skill
+   aberta sem pergunta), rode o **Onboarding** e pare.
+1. Compare a pergunta com o **Catálogo de roteamento** abaixo.
+2. Escolha:
+   - **Casa com o comercial** → `ask_commercial` (caminho A). Execute já, sem checar outra fonte.
+   - **Dado/negócio do G4 que o comercial não cobre** (metas/atingimento/potencial de receita, ou
+     outras áreas: produto, marketing, financeiro, operações, pós-venda…) → `question` (caminho B).
+   - **Não é dado do G4** (ex.: "escreva um e-mail", "resuma este texto") → recuse e pare.
+
+## Onboarding (comando inicial)
+
+1. **Garanta o source `g4-data`.** Rode `source_test({ sourceSlug: "g4-data" })`. Se não estiver
+   instalado/conectado, instale seguindo o `INSTALL_G4OS.md` (deste pacote): garante o `uv`, cria o
+   source `g4-data` (config/permissions/guide), e valida. O G4OS roda os comandos; o usuário só
+   completa os **dois logins no browser** (Databricks U2M + Looker PKCE) na primeira consulta de cada
+   tipo. Se o usuário preferir depois, avise que os dados ficam indisponíveis até instalar.
+2. **Mensagem de boas-vindas** (não chame nenhuma tool), curta e acionável, cobrindo:
+   - **O que faz:** ponto único para perguntar dados do G4 em linguagem natural; roteia sozinho.
+   - **Disponível hoje:** o Agente Comercial (resumo do Catálogo) e, para o resto, o `question`
+     (Genie para quem está no grupo `MCP Genie Users`; SQL para os demais).
+   - **Como usar melhor:** perguntas objetivas, com período (mês/ano) e recorte (por AE, SDR,
+     squad). Dê 2 ou 3 exemplos do catálogo.
+   - **Status:** se o `g4-data` está conectado ou o que falta.
+
+## Catálogo de roteamento
+
+### Agente Comercial → `ask_commercial`
+
+Funil **comercial** do G4, pipeline Comercial (`pipeline_id = 1300511`). Roteie para cá quando for:
+
+**Resolve:**
+- Volumes do funil: oportunidades geradas, deals Won, MQL, SAL, agendamentos, calls, deals ativos.
+- Conversões: CR01 (MQL→SAL), CR02 (SAL→Agendamento), CR03 (Show Rate), CR04 (Win Rate, Opp→Won).
+- Financeiro do funil: faturamento real (Line Items dos Won), ticket médio (TM Won).
+- Tempo entre etapas (Delta T, "Death Valley"). Atividade de pré-vendas (ligações, agendamentos).
+- Rankings e quebras por **AE/proprietário** e **SDR/qualificador**, e comparação de períodos.
+
+**Não resolve (vai para o caminho B):**
+- Metas individuais e atingimento; ajustes/coparticipação.
+- Potencial de Receita (BRL) e vazamento de faturamento.
+- Organograma/RH comercial (SDRs/AEs, squads, hierarquia, rampagem, tenure).
+- Qualquer coisa fora do funil: produto, plataforma, marketing puro, financeiro corporativo,
+  pós-venda, field sales.
+
+**Exemplos que casam:**
+- "Quantas oportunidades foram geradas neste mês?"
+- "Win Rate (CR04) por AE em abril de 2026."
+- "Quantos deals ativos há na pipeline este mês?"
+- "Conversão de SAL em agendamento (CR02) neste mês?"
+- "Faturamento (Won) por AE em abril de 2026."
+- "Ranking de oportunidades por SDR (só elegíveis)."
+
+_(Novo agente = nova tool no MCP `g4-data` + um bloco aqui, ver "Adicionando agentes".)_
+
+## Caminho A: `ask_commercial`
+
+Avise que está consultando ("Consultando o agente comercial…") e chame
+`mcp__g4-data__ask_commercial({ question: "<pergunta>" })`. Retorna `answer`, `sql`, `explore_used`,
+`data`, `chart`. Apresente conforme "Formatação". Se falhar, informe e sugira tentar de novo; **não**
+compense buscando em outra fonte.
+
+## Caminho B: `question` (Genie ou SQL, decidido dentro do MCP)
+
+Chame `mcp__g4-data__question({ question: "<pergunta>" })`. O MCP decide pela allowlist (grupo
+`MCP Genie Users` no Databricks):
+
+- **Se o usuário pode Genie:** a resposta volta pronta (campo `answer` + `data`). Apresente.
+- **Se retornar `status: "needs_sql"`:** o usuário não tem Genie. Então **você escreve o SELECT** e
+  chama `mcp__g4-data__run_sql({ statement: "<SELECT>" })`. Use Databricks SQL, Unity Catalog com
+  nome de três níveis (`catalog.schema.table`, ex. `production.gold.*`). Para descobrir os dados:
+  `SHOW SCHEMAS IN production`, `SHOW TABLES IN production.gold`, `DESCRIBE TABLE production.gold.<t>`.
+  O `run_sql` é read-only (roda com as permissões do usuário). Itere o SQL se precisar e apresente.
+
+O `question`/Genie é um motor geral (sem a curadoria da camada semântica do comercial): deixe claro
+que é consulta direta ao Databricks e confira a sanidade antes de afirmar.
+
+## Formatação da resposta
+
+Markdown, com tabelas quando os dados forem tabulares (rankings, funil por etapa) e números-chave em
+**negrito**. Se houver fórmula, mostre-a numa linha curta. Termine com 2 ou 3 próximos passos
+acionáveis quando fizer sentido. Se vier um link (deep link do Genie), inclua-o.
+
+## Adicionando agentes
+
+1. No pacote `g4-data-mcp`, adicione uma tool nova (um agente = uma tool, ex. `ask_produto`) e
+   publique a versão.
+2. Acrescente um bloco no **Catálogo de roteamento** acima (o que resolve / não resolve / exemplos)
+   e a tool no `alwaysAllow` do frontmatter.

g4_data_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "g4-data-mcp"
+version = "0.1.0"
+description = "MCP de dados do G4: roteia perguntas para o agente comercial (Looker/CA API), Genie ou SQL puro do Databricks, em nome do usuário."
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.2.0",
+    "databricks-sdk>=0.38.0",
+    "google-cloud-geminidataanalytics",
+    "pydantic-settings",
+]
+
+[project.scripts]
+g4-data-mcp = "g4_data_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["g4_data_mcp"]

g4_data_mcp-0.1.0/scripts/smoke.py

@@ -0,0 +1,40 @@
+"""Fumaça das tools do MCP, sem depender do G4OS. Roda o que as env vars presentes permitirem.
+
+Uso:
+    cd data-mcp && . .venv/bin/activate
+    # SQL puro (read-only), via managed MCP SQL, como o usuário do profile:
+    DATABRICKS_PROFILE=g4 python -m scripts.smoke sql "SELECT current_user()"
+    # Genie One (custa), via managed MCP genie:
+    DATABRICKS_PROFILE=g4 python -m scripts.smoke genie "quantos leads no mês?"
+    # Comercial: precisa GCP_PROJECT/GCP_LOCATION, Looker admin (client_id/secret) e G4OS_USER_EMAIL
+    ... python -m scripts.smoke commercial "Win Rate por AE em abril de 2026?"
+"""
+from __future__ import annotations
+
+import json
+import sys
+
+from g4_data_mcp import auth
+from g4_data_mcp import databricks as dbx
+
+
+def main(argv: list[str]) -> None:
+    cmd = argv[0] if argv else "sql"
+    arg = argv[1] if len(argv) > 1 else "SELECT current_user() AS whoami"
+
+    if cmd == "sql":
+        out = dbx.run_sql(auth.workspace(), arg)
+    elif cmd == "genie":
+        out = dbx.genie_ask(auth.workspace(), arg)
+    elif cmd == "commercial":
+        from g4_data_mcp import commercial
+
+        out = commercial.chat(arg, auth.ca_credentials()).__dict__
+    else:
+        raise SystemExit(f"comando desconhecido: {cmd}")
+
+    print(json.dumps(out, ensure_ascii=False, indent=2, default=str))
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])