marketing-data-platform 0.1.0__py3-none-any.whl

data_platform_agent_tools/__init__.py

@@ -0,0 +1,5 @@
+"""Local agent tools for the Data Platform API."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

data_platform_agent_tools/config.py

@@ -0,0 +1,87 @@
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+DEFAULT_SESSION_FILE = "~/.config/data-platform/mcp.env"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(extra="ignore")
+
+    api_base_url: str = Field(default="http://127.0.0.1:8002", alias="DATA_PLATFORM_API_BASE_URL")
+    api_session_token: str = Field(default="", alias="DATA_PLATFORM_API_SESSION_TOKEN")
+    session_file: str = Field(default=DEFAULT_SESSION_FILE, alias="DATA_PLATFORM_MCP_SESSION_FILE")
+    default_limit: int = Field(default=100, alias="DATA_PLATFORM_MCP_DEFAULT_LIMIT")
+    max_limit: int = Field(default=1000, alias="DATA_PLATFORM_MCP_MAX_LIMIT")
+
+    @field_validator("api_base_url", "session_file")
+    @classmethod
+    def non_empty_string(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value must not be empty")
+        return value
+
+    @field_validator("default_limit", "max_limit")
+    @classmethod
+    def positive_int(cls, value: int) -> int:
+        if value < 1:
+            raise ValueError("value must be positive")
+        return value
+
+
+@lru_cache
+def get_settings() -> Settings:
+    settings = Settings()
+    file_values = read_env_file(Path(settings.session_file).expanduser())
+    fallback_file = read_env_file(Path(DEFAULT_SESSION_FILE).expanduser())
+
+    return Settings(
+        DATA_PLATFORM_API_BASE_URL=first_value(
+            file_values.get("DATA_PLATFORM_API_BASE_URL"),
+            fallback_file.get("DATA_PLATFORM_API_BASE_URL"),
+            settings.api_base_url,
+        ),
+        DATA_PLATFORM_API_SESSION_TOKEN=first_value(
+            file_values.get("DATA_PLATFORM_API_SESSION_TOKEN"),
+            fallback_file.get("DATA_PLATFORM_API_SESSION_TOKEN"),
+            settings.api_session_token,
+        ),
+        DATA_PLATFORM_MCP_SESSION_FILE=settings.session_file,
+        DATA_PLATFORM_MCP_DEFAULT_LIMIT=int(
+            first_value(
+                file_values.get("DATA_PLATFORM_MCP_DEFAULT_LIMIT"),
+                fallback_file.get("DATA_PLATFORM_MCP_DEFAULT_LIMIT"),
+                str(settings.default_limit),
+            )
+        ),
+        DATA_PLATFORM_MCP_MAX_LIMIT=int(
+            first_value(
+                file_values.get("DATA_PLATFORM_MCP_MAX_LIMIT"),
+                fallback_file.get("DATA_PLATFORM_MCP_MAX_LIMIT"),
+                str(settings.max_limit),
+            )
+        ),
+    )
+
+
+def first_value(*values: str | None) -> str:
+    for value in values:
+        if value:
+            return value
+    return ""
+
+
+def read_env_file(path: Path) -> dict[str, str]:
+    if not path.exists():
+        return {}
+    values: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        key, value = stripped.split("=", 1)
+        values[key.strip()] = value.strip().strip('"').strip("'")
+    return values

data_platform_agent_tools/login_cli.py

@@ -0,0 +1,295 @@
+import argparse
+import secrets
+import sys
+import threading
+import urllib.parse
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth"
+TOKEN_URL = "https://oauth2.googleapis.com/token"
+DEFAULT_SCOPES = "openid email profile"
+DEFAULT_MCP_ENV_PATH = "~/.config/data-platform/mcp.env"
+
+
+class OAuthCallbackState:
+    def __init__(self, expected_state: str) -> None:
+        self.expected_state = expected_state
+        self.code: str | None = None
+        self.error: str | None = None
+        self.event = threading.Event()
+
+
+def main() -> None:
+    args = parse_args()
+
+    client_id = args.client_id or read_env_value("DATA_PLATFORM_GOOGLE_OAUTH_CLIENT_ID")
+    client_secret = args.client_secret or read_env_value("DATA_PLATFORM_GOOGLE_OAUTH_CLIENT_SECRET")
+    if not client_id:
+        raise SystemExit("DATA_PLATFORM_GOOGLE_OAUTH_CLIENT_ID or --client-id is required.")
+    if not client_secret:
+        raise SystemExit("DATA_PLATFORM_GOOGLE_OAUTH_CLIENT_SECRET or --client-secret is required.")
+
+    redirect_uri = f"http://127.0.0.1:{args.port}/callback"
+    state = secrets.token_urlsafe(24)
+    callback_state = OAuthCallbackState(expected_state=state)
+
+    server = build_callback_server(args.port, callback_state)
+    server_thread = threading.Thread(target=server.serve_forever, daemon=True)
+    server_thread.start()
+
+    auth_url = build_auth_url(
+        client_id=client_id,
+        redirect_uri=redirect_uri,
+        state=state,
+    )
+
+    print("Opening browser for Google login...")
+    if not webbrowser.open(auth_url):
+        print(f"Open this URL manually:\n{auth_url}")
+
+    if not callback_state.event.wait(timeout=args.timeout_seconds):
+        server.shutdown()
+        raise SystemExit("Timed out waiting for Google OAuth callback.")
+    server.shutdown()
+
+    if callback_state.error:
+        raise SystemExit(f"Google OAuth failed: {callback_state.error}")
+    if not callback_state.code:
+        raise SystemExit("Google OAuth callback did not include an authorization code.")
+
+    id_token = exchange_code_for_id_token(
+        code=callback_state.code,
+        client_id=client_id,
+        client_secret=client_secret,
+        redirect_uri=redirect_uri,
+    )
+    session = exchange_id_token_for_session(
+        api_base_url=args.api_base_url,
+        id_token=id_token,
+    )
+
+    write_mcp_env(
+        output_path=args.output,
+        api_base_url=args.api_base_url,
+        session_token=session["access_token"],
+        default_limit=args.default_limit,
+        max_limit=args.max_limit,
+    )
+
+    print(f"Logged in as {session.get('email')} ({session.get('role')})")
+    print(f"Saved MCP session config to {args.output}")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Login with Google and save a Data Platform API session for MCP."
+    )
+    parser.add_argument(
+        "--api-base-url",
+        default=read_env_value("DATA_PLATFORM_API_BASE_URL") or "http://127.0.0.1:8002",
+        help="Data Platform API base URL.",
+    )
+    parser.add_argument(
+        "--client-id",
+        default=None,
+        help="Google OAuth client id. Defaults to DATA_PLATFORM_GOOGLE_OAUTH_CLIENT_ID.",
+    )
+    parser.add_argument(
+        "--client-secret",
+        default=None,
+        help="Google OAuth client secret. Defaults to DATA_PLATFORM_GOOGLE_OAUTH_CLIENT_SECRET.",
+    )
+    parser.add_argument(
+        "--output",
+        default=DEFAULT_MCP_ENV_PATH,
+        help="Path to write MCP environment config.",
+    )
+    parser.add_argument("--port", type=int, default=8765, help="Local OAuth callback port.")
+    parser.add_argument(
+        "--timeout-seconds",
+        type=int,
+        default=180,
+        help="Seconds to wait for OAuth callback.",
+    )
+    parser.add_argument("--default-limit", type=int, default=100)
+    parser.add_argument("--max-limit", type=int, default=1000)
+    return parser.parse_args()
+
+
+def build_callback_server(port: int, callback_state: OAuthCallbackState) -> ThreadingHTTPServer:
+    class CallbackHandler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802
+            parsed = urllib.parse.urlparse(self.path)
+            params = urllib.parse.parse_qs(parsed.query)
+            received_state = first(params.get("state"))
+            if parsed.path != "/callback":
+                self.respond(404, "Not found.")
+                return
+            if received_state != callback_state.expected_state:
+                callback_state.error = "OAuth state mismatch."
+                callback_state.event.set()
+                self.respond(400, "Login failed: state mismatch.")
+                return
+
+            error = first(params.get("error"))
+            if error:
+                callback_state.error = error
+                callback_state.event.set()
+                self.respond(400, "Login failed. You can close this tab.")
+                return
+
+            callback_state.code = first(params.get("code"))
+            callback_state.event.set()
+            self.respond(200, "Login complete. You can close this tab.")
+
+        def log_message(self, format: str, *args: object) -> None:
+            return
+
+        def respond(self, status_code: int, body: str) -> None:
+            encoded = body.encode("utf-8")
+            self.send_response(status_code)
+            self.send_header("Content-Type", "text/plain; charset=utf-8")
+            self.send_header("Content-Length", str(len(encoded)))
+            self.end_headers()
+            self.wfile.write(encoded)
+
+    return ThreadingHTTPServer(("127.0.0.1", port), CallbackHandler)
+
+
+def build_auth_url(*, client_id: str, redirect_uri: str, state: str) -> str:
+    query = urllib.parse.urlencode(
+        {
+            "client_id": client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": "code",
+            "scope": DEFAULT_SCOPES,
+            "state": state,
+            "access_type": "offline",
+            "prompt": "select_account",
+        }
+    )
+    return f"{AUTH_URL}?{query}"
+
+
+def exchange_code_for_id_token(
+    *,
+    code: str,
+    client_id: str,
+    client_secret: str,
+    redirect_uri: str,
+) -> str:
+    response = httpx.post(
+        TOKEN_URL,
+        data={
+            "code": code,
+            "client_id": client_id,
+            "client_secret": client_secret,
+            "redirect_uri": redirect_uri,
+            "grant_type": "authorization_code",
+        },
+        timeout=30,
+    )
+    response.raise_for_status()
+    payload = response.json()
+    id_token = payload.get("id_token")
+    if not id_token:
+        raise SystemExit("Google token response did not include id_token.")
+    return str(id_token)
+
+
+def exchange_id_token_for_session(*, api_base_url: str, id_token: str) -> dict[str, Any]:
+    session_url = f"{api_base_url.rstrip('/')}/auth/google/session"
+    try:
+        response = httpx.post(
+            session_url,
+            json={"id_token": id_token},
+            timeout=30,
+        )
+    except httpx.ConnectError as exc:
+        raise SystemExit(
+            "Could not connect to Data Platform API. "
+            f"Start it first, or pass the correct --api-base-url. Tried: {session_url}"
+        ) from exc
+    if response.status_code == 403:
+        raise SystemExit("Login succeeded, but this email is not allowlisted.")
+    response.raise_for_status()
+    payload = response.json()
+    if "access_token" not in payload:
+        raise SystemExit("Data Platform API response did not include access_token.")
+    return payload
+
+
+def write_mcp_env(
+    *,
+    output_path: str,
+    api_base_url: str,
+    session_token: str,
+    default_limit: int,
+    max_limit: int,
+) -> None:
+    path = Path(output_path).expanduser()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        "\n".join(
+            [
+                f"DATA_PLATFORM_API_BASE_URL={api_base_url.rstrip('/')}",
+                f"DATA_PLATFORM_API_SESSION_TOKEN={session_token}",
+                f"DATA_PLATFORM_MCP_DEFAULT_LIMIT={default_limit}",
+                f"DATA_PLATFORM_MCP_MAX_LIMIT={max_limit}",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    path.chmod(0o600)
+
+
+def read_env_value(name: str) -> str | None:
+    import os
+
+    value = os.getenv(name)
+    if value:
+        return value.strip()
+
+    for env_path in [
+        Path(".env"),
+        Path(".env.local"),
+        Path("apps/data-platform-api/.env"),
+        Path("apps/data-platform-api/.env.local"),
+    ]:
+        value = read_env_file_value(env_path, name)
+        if value:
+            return value
+    return None
+
+
+def read_env_file_value(path: Path, name: str) -> str | None:
+    if not path.exists():
+        return None
+    for line in path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        key, value = stripped.split("=", 1)
+        if key.strip() == name:
+            return value.strip().strip('"').strip("'")
+    return None
+
+
+def first(values: list[str] | None) -> str | None:
+    if not values:
+        return None
+    return values[0]
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except httpx.HTTPStatusError as exc:
+        print(f"HTTP error: {exc.response.status_code} {exc.response.text}", file=sys.stderr)
+        raise SystemExit(1) from exc

data_platform_agent_tools/mcp_server.py

@@ -0,0 +1,74 @@
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+from data_platform_agent_tools.config import get_settings
+
+mcp = FastMCP("data-platform-mart")
+
+
+def bounded_limit(limit: int | None) -> int:
+    settings = get_settings()
+    value = limit or settings.default_limit
+    return min(max(value, 1), settings.max_limit)
+
+
+@mcp.tool()
+def get_daily_ad_performance(
+    start_date: str,
+    end_date: str,
+    client_name: str | None = None,
+    project_id: str | None = None,
+    media: str | None = None,
+    campaign_id: str | None = None,
+    external_campaign_id: str | None = None,
+    ad_group_id: str | None = None,
+    external_ad_group_id: str | None = None,
+    ad_id: str | None = None,
+    external_ad_id: str | None = None,
+    limit: int | None = None,
+) -> list[dict[str, Any]]:
+    """Read daily ad performance rows through the Data Platform API."""
+    settings = get_settings()
+    if not settings.api_session_token:
+        raise RuntimeError(
+            "MCP session token is missing. Run `data-platform-login` first, "
+            "or set DATA_PLATFORM_API_SESSION_TOKEN."
+        )
+    params: dict[str, str | int] = {
+        "start_date": start_date,
+        "end_date": end_date,
+        "limit": bounded_limit(limit),
+    }
+    for key, value in {
+        "client_name": client_name,
+        "project_id": project_id,
+        "media": media,
+        "campaign_id": campaign_id,
+        "external_campaign_id": external_campaign_id,
+        "ad_group_id": ad_group_id,
+        "external_ad_group_id": external_ad_group_id,
+        "ad_id": ad_id,
+        "external_ad_id": external_ad_id,
+    }.items():
+        if value is not None:
+            params[key] = value
+
+    response = httpx.get(
+        f"{settings.api_base_url.rstrip('/')}/agent/mart/daily-ad-performance",
+        params=params,
+        headers={"Authorization": f"Bearer {settings.api_session_token}"},
+        timeout=30,
+    )
+    response.raise_for_status()
+    payload = response.json()
+    return payload["rows"]
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

marketing_data_platform-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: marketing-data-platform
+Version: 0.1.0
+Summary: Login CLI and MCP server for the Data Platform API.
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic-settings>=2.6.0
+Description-Content-Type: text/markdown
+
+# Marketing Data Platform
+
+Python package for local agents and MCP clients that need to access the Data Platform API.
+
+It provides two commands:
+
+- `data-platform-login`: login with Google and save a local Data Platform API session.
+- `data-platform-mcp`: start the MCP server that exposes mart access tools.
+
+The MCP server does not connect to BigQuery directly. It calls the Data Platform API, and the API owns BigQuery credentials, authorization, and tenant access control.
+
+## Install
+
+For local development:
+
+```bash
+uv run --package marketing-data-platform data-platform-login --help
+uv run --package marketing-data-platform data-platform-mcp
+```
+
+After publishing to PyPI:
+
+```bash
+uvx --from marketing-data-platform data-platform-login --help
+uvx --from marketing-data-platform data-platform-mcp
+```
+
+## Login
+
+The Data Platform API must be running and configured with Google OAuth.
+
+```bash
+uvx --from marketing-data-platform data-platform-login \
+  --api-base-url https://data-platform-api.example.com
+```
+
+By default, the command writes the MCP session file to:
+
+```text
+~/.config/data-platform/mcp.env
+```
+
+The session token is saved locally with file mode `600` and is not printed.
+
+## MCP Config
+
+For a published package:
+
+```toml
+[mcp_servers.data-platform-mart]
+command = "uvx"
+args = ["--from", "marketing-data-platform", "data-platform-mcp"]
+startup_timeout_sec = 120
+```
+
+For this monorepo during development:
+
+```toml
+[mcp_servers.data-platform-mart]
+command = "uv"
+args = [
+  "run",
+  "--directory",
+  "/path/to/data-platform",
+  "--package",
+  "marketing-data-platform",
+  "data-platform-mcp",
+]
+startup_timeout_sec = 120
+```
+
+## MCP Tools
+
+- `get_daily_ad_performance`
+
+## Environment Variables
+
+| Name | Required | Description |
+| --- | --- | --- |
+| `DATA_PLATFORM_API_BASE_URL` | optional | Data Platform API base URL. Default: `http://127.0.0.1:8002` |
+| `DATA_PLATFORM_API_SESSION_TOKEN` | optional | Session JWT issued by login. Usually read from the session file. |
+| `DATA_PLATFORM_MCP_SESSION_FILE` | optional | Session env file. Default: `~/.config/data-platform/mcp.env` |
+| `DATA_PLATFORM_MCP_DEFAULT_LIMIT` | optional | Default row limit. Default: `100` |
+| `DATA_PLATFORM_MCP_MAX_LIMIT` | optional | Max row limit. Default: `1000` |

marketing_data_platform-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+data_platform_agent_tools/__init__.py,sha256=bvvRHhIbw1cKJ6YOmLJq6fYN8HE2X9F5MIofFK1sgMw,101
+data_platform_agent_tools/config.py,sha256=gYP5Sjpc2FpsYiYJj-hzVRFOCX1vo6-0XoIAU9HpVWU,3097
+data_platform_agent_tools/login_cli.py,sha256=H8WJ1SyouA52MpmDVj_utFsOkRNqVwCApTq_wgrh3u4,9558
+data_platform_agent_tools/mcp_server.py,sha256=SrnJasmV-Ba8ShFTDrHQ1N-A93eKcHaG987ipy9hYaI,2110
+marketing_data_platform-0.1.0.dist-info/METADATA,sha256=0xi8qIVEEEVfOohWXhqKs-YZFo8uGMuWVPWUQzl8bu8,2558
+marketing_data_platform-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+marketing_data_platform-0.1.0.dist-info/entry_points.txt,sha256=f2PmBpsGyLspVepGo2v9UD3UNFtmGJVqZZCCkjtxEMY,143
+marketing_data_platform-0.1.0.dist-info/RECORD,,

marketing_data_platform-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

marketing_data_platform-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+data-platform-login = data_platform_agent_tools.login_cli:main
+data-platform-mcp = data_platform_agent_tools.mcp_server:main