estran-mcp 0.1.0__tar.gz

estran_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: estran-mcp
+Version: 0.1.0
+Summary: Connect Claude, Cursor or Codex to your Estran GEO analyses
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2

estran_mcp-0.1.0/README.md

@@ -0,0 +1,35 @@
+# estran-mcp
+
+Connect Claude Code, Claude Desktop, Cursor or Codex to your Estran GEO analyses.
+On first use your browser opens the Estran login, you click **Allow**, and that's it.
+The token is kept in `~/.estran/credentials.json` and refreshed automatically.
+
+## Install
+
+Claude Code:
+
+```bash
+claude mcp add estran -- uvx estran-mcp
+# before the PyPI release, from this repo:
+claude mcp add estran -- uvx --from /path/to/estran_mcp estran-mcp
+```
+
+Claude Desktop / Cursor (`mcpServers` config):
+
+```json
+{ "estran": { "command": "uvx", "args": ["estran-mcp"] } }
+```
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `list_analyses` | Category analyses, grouped by audited site (`audit_domain`) |
+| `get_recommendations(benchmark_id)` | GEO action plan of a category |
+| `get_analysis_data(benchmark_id)` | Visibility scores, cited sources, gaps vs competitors |
+| `get_raw_answers(benchmark_id, offset, limit, llm)` | Raw AI answers, paginated |
+| `logout` | Deletes the local token |
+
+## Local dev
+
+`ESTRAN_API_URL=http://localhost:8000 ESTRAN_DASHBOARD_URL=http://localhost:3002 uvx --from . estran-mcp`

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

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: estran-mcp
+Version: 0.1.0
+Summary: Connect Claude, Cursor or Codex to your Estran GEO analyses
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2

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

@@ -0,0 +1,9 @@
+README.md
+estran_mcp.py
+pyproject.toml
+estran_mcp.egg-info/PKG-INFO
+estran_mcp.egg-info/SOURCES.txt
+estran_mcp.egg-info/dependency_links.txt
+estran_mcp.egg-info/entry_points.txt
+estran_mcp.egg-info/requires.txt
+estran_mcp.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+[console_scripts]
+estran-mcp = estran_mcp:main

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

@@ -0,0 +1,3 @@
+mcp<3,>=2.3
+httpx>=0.27
+pydantic>=2

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

@@ -0,0 +1 @@
+estran_mcp

estran_mcp-0.1.0/estran_mcp.py

@@ -0,0 +1,189 @@
+"""Estran MCP server: exposes the user's GEO analyses to Claude, Cursor, Codex...
+
+Runs locally (stdio). On first use it opens dashboard.estran.io/connect in the browser,
+the user signs in, and the page posts the Firebase refresh token back to a loopback
+port. Calls then go to the existing dashboard API with a Firebase ID token.
+"""
+
+import os
+import secrets
+import threading
+import time
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Any, Optional
+from urllib.parse import parse_qs
+
+import httpx
+from mcp.server.mcpserver import MCPServer
+from pydantic import BaseModel
+
+API_URL = os.getenv("ESTRAN_API_URL", "https://api.estran.io/dashboard").rstrip("/")
+DASHBOARD_URL = os.getenv("ESTRAN_DASHBOARD_URL", "https://dashboard.estran.io").rstrip("/")
+# Public Firebase web key (same one the dashboard ships to every browser).
+FIREBASE_API_KEY = os.getenv("ESTRAN_FIREBASE_API_KEY", "AIzaSyDgwJt3K0gDaZcU7KJOMD2AGD0moyijBVw")
+CREDS_PATH = Path(os.getenv("ESTRAN_HOME", Path.home() / ".estran")) / "credentials.json"
+LOGIN_TIMEOUT_S = 300
+
+
+class Credentials(BaseModel):
+    refresh_token: str
+    id_token: str = ""
+    expires_at: float = 0
+
+
+# --- Auth -------------------------------------------------------------------
+
+def _save(creds: Credentials) -> None:
+    CREDS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CREDS_PATH.write_text(creds.model_dump_json())
+    CREDS_PATH.chmod(0o600)
+
+
+def _load() -> Optional[Credentials]:
+    try:
+        return Credentials.model_validate_json(CREDS_PATH.read_text())
+    except (OSError, ValueError):
+        return None
+
+
+def _browser_login() -> Credentials:
+    """Open the dashboard /connect page and wait for it to POST the refresh token back."""
+    state = secrets.token_urlsafe(32)
+    received: dict[str, str] = {}
+    done = threading.Event()
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_POST(self) -> None:
+            length = int(self.headers.get("Content-Length", 0))
+            form = {k: v[0] for k, v in parse_qs(self.rfile.read(length).decode()).items()}
+            ok = self.path == "/callback" and secrets.compare_digest(form.get("state", ""), state) and form.get("refresh_token")
+            if ok:
+                received.update(form)
+                done.set()
+            self.send_response(200 if ok else 400)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            msg = "Estran est connecté. Vous pouvez fermer cet onglet. / Estran is connected, you can close this tab." if ok else "Invalid request."
+            self.wfile.write(f"<html><body style='font-family:sans-serif;padding:3rem'>{msg}</body></html>".encode())
+
+        def log_message(self, format: str, *args: Any) -> None:  # stdout is the MCP channel: stay silent
+            pass
+
+    server = HTTPServer(("127.0.0.1", 0), Handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    try:
+        webbrowser.open(f"{DASHBOARD_URL}/connect?port={server.server_port}&state={state}")
+        if not done.wait(LOGIN_TIMEOUT_S):
+            raise RuntimeError("Connexion Estran non terminée dans le navigateur (5 min). Relancez l'outil.")
+    finally:
+        server.shutdown()
+    creds = Credentials(refresh_token=received["refresh_token"])
+    _save(creds)
+    return creds
+
+
+def _refresh(creds: Credentials) -> Optional[Credentials]:
+    r = httpx.post(
+        f"https://securetoken.googleapis.com/v1/token?key={FIREBASE_API_KEY}",
+        data={"grant_type": "refresh_token", "refresh_token": creds.refresh_token},
+        timeout=15,
+    )
+    if r.status_code != 200:
+        return None  # revoked / expired → caller falls back to browser login
+    d = r.json()
+    creds = Credentials(
+        refresh_token=d["refresh_token"],
+        id_token=d["id_token"],
+        expires_at=time.time() + int(d["expires_in"]) - 60,
+    )
+    _save(creds)
+    return creds
+
+
+def _id_token(force_refresh: bool = False) -> str:
+    creds = _load()
+    if creds and creds.id_token and creds.expires_at > time.time() and not force_refresh:
+        return creds.id_token
+    refreshed = _refresh(creds) if creds else None
+    if not refreshed:
+        refreshed = _refresh(_browser_login())
+    if not refreshed:
+        raise RuntimeError("Impossible d'obtenir un token Estran après connexion.")
+    return refreshed.id_token
+
+
+def _get(path: str, **params: Any) -> Any:
+    def call(force_refresh: bool) -> httpx.Response:
+        headers = {"Authorization": f"Bearer {_id_token(force_refresh)}"}
+        return httpx.get(f"{API_URL}{path}", params=params, headers=headers, timeout=60)
+
+    r = call(False)
+    if r.status_code == 401:
+        r = call(True)
+    if r.status_code >= 400:
+        raise RuntimeError(f"Estran API {r.status_code}: {r.text[:300]}")
+    return r.json()
+
+
+# --- Tools ------------------------------------------------------------------
+
+mcp = MCPServer(
+    "estran",
+    instructions=(
+        "Estran mesure la visibilité d'une marque dans les réponses des IA (GEO). "
+        "Commencez par list_analyses, puis get_recommendations sur une catégorie. "
+        "N'utilisez get_analysis_data et get_raw_answers que pour justifier ou creuser une reco."
+    ),
+)
+
+
+@mcp.tool()
+def list_analyses() -> list[dict[str, Any]]:
+    """Liste les analyses par catégorie du compte (les plus récentes d'abord).
+    `audit_domain` indique le site audité dont la catégorie fait partie (null = analyse autonome)."""
+    return _get("/referencing/history_records")
+
+
+@mcp.tool()
+def get_recommendations(benchmark_id: int) -> dict[str, Any]:
+    """Plan d'action GEO d'une catégorie : recommandations priorisées, sources à travailler, concurrents."""
+    b = _get(f"/referencing/benchmark/{benchmark_id}")
+    keys = ("id", "status", "category_name", "country", "language", "brief", "created_at", "geo_action_plan")
+    return {k: b.get(k) for k in keys}
+
+
+@mcp.tool()
+def get_analysis_data(benchmark_id: int) -> dict[str, Any]:
+    """Données agrégées d'une catégorie : scores de visibilité, sources citées par les IA, gaps vs concurrents."""
+    b = _get(f"/referencing/benchmark/{benchmark_id}")
+    keys = ("id", "category_name", "results", "aggregated_sources", "source_types")
+    return {k: b.get(k) for k in keys}
+
+
+@mcp.tool()
+def get_raw_answers(benchmark_id: int, offset: int = 0, limit: int = 20, llm: Optional[str] = None) -> dict[str, Any]:
+    """Réponses brutes des IA (prompt, réponse, sources citées, marques mentionnées), paginées.
+    Filtre optionnel par `llm` (ex. "openai", "gemini", "perplexity")."""
+    # ponytail: the API returns every prompt, we page client-side; add server paging if payloads hurt.
+    prompts = _get(f"/referencing/benchmark/{benchmark_id}", include_prompts="true").get("prompts") or []
+    if llm:
+        prompts = [p for p in prompts if llm.lower() in (p.get("provider") or "").lower()]
+    limit = max(1, min(limit, 50))
+    return {"total": len(prompts), "offset": offset, "items": prompts[offset:offset + limit]}
+
+
+@mcp.tool()
+def logout() -> str:
+    """Déconnecte Estran sur cette machine (supprime le token local)."""
+    CREDS_PATH.unlink(missing_ok=True)
+    return "Déconnecté."
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

estran_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "estran-mcp"
+version = "0.1.0"
+description = "Connect Claude, Cursor or Codex to your Estran GEO analyses"
+requires-python = ">=3.10"
+dependencies = ["mcp>=2.3,<3", "httpx>=0.27", "pydantic>=2"]
+
+[project.scripts]
+estran-mcp = "estran_mcp:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ["estran_mcp"]

estran_mcp-0.1.0/setup.cfg

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