github-pr-context-mcp 0.2.5__tar.gz → 0.2.7__tar.gz

{github_pr_context_mcp-0.2.5 → github_pr_context_mcp-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-pr-context-mcp
-Version: 0.2.5
+Version: 0.2.7
 Summary: GitHub PR Review Context MCP Server
 Author: Paarth Gala
 Requires-Python: >=3.10
@@ -19,6 +19,8 @@ Dynamic: license-file
 
 # GitHub PR Review Context MCP
 
+
+
 <div align="center">
 
 ![Python](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white)
@@ -28,14 +30,53 @@ Dynamic: license-file
 ![Inference](https://img.shields.io/badge/LLM-Multi--Provider-brightgreen)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 ![Status](https://img.shields.io/badge/Render%20Hosting-Upcoming-gray)
+![Downloads](https://img.shields.io/badge/downloads-750-blue)
+<!-- [![Users](https://img.shields.io/endpoint?url=https://github-pr-context-mcp.onrender.com/usage/badge)](https://github-pr-context-mcp.onrender.com/usage) -->
 
 **Production-grade context layer for AI code review, grounded in your repository's real pull request history.**
 
 
-> Tracking unique users across **uvx**, **pipx**, and **local** sources. (Render hosting upcoming)
-
 </div>
 
+## 🚀 Quick Start
+
+### 🚀 Zero-Setup (uvx / pipx / npx)
+The fastest way to use the server. No cloning required. Just run one of these commands directly in your terminal or use them in your IDE's MCP settings:
+
+> [!TIP]
+> **Don't clone this repo to get AI rules!** 
+> Once installed, run `generate_repo_rules` inside **YOUR** project to automatically create `.cursorrules` or `CLAUDE.md` tailored to your own team's PR history.
+
+**Using uvx (Recommended for speed):**
+```bash
+uvx github-pr-context-mcp
+```
+
+**Using pipx (Recommended for stability):**
+```bash
+pipx run github-pr-context-mcp
+# Or install permanently:
+pipx install github-pr-context-mcp
+```
+
+**Using npx (Smithery bridge):**
+```bash
+npx -y @smithery/cli run github-pr-context-mcp
+```
+
+---
+
+### ⚠️ Manual Installation (Git Clone / Advanced)
+> [!WARNING]
+> Running from a git clone is **only recommended for developers** contributing to this project. For general use, please use the `pipx` method above.
+
+If you have cloned the repository for development:
+1. Create a virtual environment: `python -m venv .venv`
+2. Activate it and install: `pip install -e .`
+3. Run automatic setup: `python scripts/install_clients.py`
+
+For full configuration (Cursor, Claude Desktop), see the [**Quick Start Guide**](docs/quickstart.md).
+
 ---
 
 ## Overview
@@ -88,6 +129,24 @@ If your team has Hosted this MCP on Render, you do **NOT** need to `git clone` o
 
 ---
 
+> [!IMPORTANT]
+> **🚀 USE THE OFFICIAL PACKAGE:** This project is now on PyPI. 
+> To ensure seamless updates and zero configuration friction, do **NOT** `git clone`.
+>
+> **Recommended Install:**
+> ```bash
+> pipx install github-pr-context-mcp
+> ```
+> Or run instantly with: `uvx github-pr-context-mcp`
+
+<div align="center">
+  <img src="assets/mcp_tool_guide_premium_v2.png" width="800" alt="GitHub PR Context MCP Tools">
+</div>
+
+<br/>
+
+---
+
 ## Key Capabilities
 
 | Capability | What It Delivers |
@@ -100,20 +159,6 @@ If your team has Hosted this MCP on Render, you do **NOT** need to `git clone` o
 | Flexible storage modes | Permanent (disk) and temporary (in-memory) indexing options |
 | Portable inference layer | Switch LLM providers using environment configuration only |
 
----
-
-## Demo
-
-![demo](assets/demo.gif)
-
-Example workflow:
-- Ask the assistant to review a diff using repository history.
-- The server retrieves similar past review context.
-- The model returns grounded feedback aligned to team expectations.
-
-## Usage Analytics
-
-To help us understand adoption, the MCP server collects privacy-first, anonymous telemetry on deployments. Future hosted deployments will expose HTTP endpoints (`/stats` and `/ping`) that publicly display the **number of unique users**.
 
 ---
 
@@ -138,24 +183,17 @@ The server exposes 12 core tools for IDE agents and developers. For a deep dive
 
 ---
 
-## Documentation
-
-Detailed guides are split into focused pages:
-
-- [Quick Start and Usage](docs/quickstart.md)
-- [LLM Configuration](docs/llm-configuration.md)
-- [Integrations](docs/integrations/index.md)
-- [Architecture and Tools](docs/architecture.md)
-- [Pipeline Deep Dive](docs/pipeline.md)
-- [Configuration Guide (Change Tokens/Settings)](docs/guides/configuration.md)
-- [Roadmap](docs/roadmap.md)
-
 ---
 
-## Quick Links
+## 📖 Documentation
 
-- Access setup: [GitHub Token Guide](docs/GUIDE_GITHUB_TOKEN.md)
-- Client connection: [Integrations](docs/integrations/index.md)
+Detailed guides for deep dives and specific configurations:
+
+- 🛠️ [**Quick Start & Usage**](docs/quickstart.md) — Setup and basic commands.
+- ⚙️ [**LLM Configuration**](docs/llm-configuration.md) — Switching between OpenAI, Anthropic, Gemini, and Cerebras.
+- 🧩 [**Tool Strategy & Selection Guide**](docs/tools_strategy.md) — When to use which tool (for humans and agents).
+- 🏗️ [**Architecture & Pipeline**](docs/architecture.md) — How the RAG engine and indexing work.
+- 🔌 [**Integrations**](docs/integrations/index.md) — Connecting to Cursor, Claude Desktop, and more.
 
 ---
 
@@ -163,24 +201,12 @@ Detailed guides are split into focused pages:
 
 We want to hear from you—whether you are a solo developer or a team at a large company!
 
-### 👤 For Individuals
 - **Feedback**: Please open an issue or start a discussion if you have ideas or encounter bugs.
-- **Show your support**: If this tool saves you time, give it a **Star ⭐**! It helps others find the project.
-
-### 🏢 For Corporate & Teams
-- **Usage**: Is your team using this MCP server? Join our "Adopters" list by opening a PR to add your team's name.
-- **Corporate Feedback**: Open an issue with the `corporate-usage` label to tell us how this has improved your PR review workflow.
-- **Custom Integration**: Need help deploying this to your private cloud? Reach out via GitHub Discussions.
+- **Star ⭐**: If this tool saves you time, give it a star! It helps others find the project.
+- **Corporate**: Is your team using this? Join our "Adopters" list by opening a PR to add your team's name.
 
 ---
 
-## 📜 Documentation & Guides
-
-- **Strategy & Best Practices**: [Tool Strategy & Selection Guide](docs/tools_strategy.md)
-- **Architecture**: [Architecture and Tools](docs/architecture.md)
-- **Pipeline**: [Pipeline Deep Dive](docs/pipeline.md)
-- **Usage**: [Quick Start and Usage](docs/quickstart.md)
-
 ## 🛠️ Troubleshooting
 
 - **"command not found"**: Use absolute paths in your configuration. Run `github-pr-context-mcp config` to get your exact path.

{github_pr_context_mcp-0.2.5 → github_pr_context_mcp-0.2.7}/README.md

@@ -1,5 +1,7 @@
 # GitHub PR Review Context MCP
 
+
+
 <div align="center">
 
 ![Python](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white)
@@ -9,14 +11,53 @@
 ![Inference](https://img.shields.io/badge/LLM-Multi--Provider-brightgreen)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 ![Status](https://img.shields.io/badge/Render%20Hosting-Upcoming-gray)
+![Downloads](https://img.shields.io/badge/downloads-750-blue)
+<!-- [![Users](https://img.shields.io/endpoint?url=https://github-pr-context-mcp.onrender.com/usage/badge)](https://github-pr-context-mcp.onrender.com/usage) -->
 
 **Production-grade context layer for AI code review, grounded in your repository's real pull request history.**
 
 
-> Tracking unique users across **uvx**, **pipx**, and **local** sources. (Render hosting upcoming)
-
 </div>
 
+## 🚀 Quick Start
+
+### 🚀 Zero-Setup (uvx / pipx / npx)
+The fastest way to use the server. No cloning required. Just run one of these commands directly in your terminal or use them in your IDE's MCP settings:
+
+> [!TIP]
+> **Don't clone this repo to get AI rules!** 
+> Once installed, run `generate_repo_rules` inside **YOUR** project to automatically create `.cursorrules` or `CLAUDE.md` tailored to your own team's PR history.
+
+**Using uvx (Recommended for speed):**
+```bash
+uvx github-pr-context-mcp
+```
+
+**Using pipx (Recommended for stability):**
+```bash
+pipx run github-pr-context-mcp
+# Or install permanently:
+pipx install github-pr-context-mcp
+```
+
+**Using npx (Smithery bridge):**
+```bash
+npx -y @smithery/cli run github-pr-context-mcp
+```
+
+---
+
+### ⚠️ Manual Installation (Git Clone / Advanced)
+> [!WARNING]
+> Running from a git clone is **only recommended for developers** contributing to this project. For general use, please use the `pipx` method above.
+
+If you have cloned the repository for development:
+1. Create a virtual environment: `python -m venv .venv`
+2. Activate it and install: `pip install -e .`
+3. Run automatic setup: `python scripts/install_clients.py`
+
+For full configuration (Cursor, Claude Desktop), see the [**Quick Start Guide**](docs/quickstart.md).
+
 ---
 
 ## Overview
@@ -69,6 +110,24 @@ If your team has Hosted this MCP on Render, you do **NOT** need to `git clone` o
 
 ---
 
+> [!IMPORTANT]
+> **🚀 USE THE OFFICIAL PACKAGE:** This project is now on PyPI. 
+> To ensure seamless updates and zero configuration friction, do **NOT** `git clone`.
+>
+> **Recommended Install:**
+> ```bash
+> pipx install github-pr-context-mcp
+> ```
+> Or run instantly with: `uvx github-pr-context-mcp`
+
+<div align="center">
+  <img src="assets/mcp_tool_guide_premium_v2.png" width="800" alt="GitHub PR Context MCP Tools">
+</div>
+
+<br/>
+
+---
+
 ## Key Capabilities
 
 | Capability | What It Delivers |
@@ -81,20 +140,6 @@ If your team has Hosted this MCP on Render, you do **NOT** need to `git clone` o
 | Flexible storage modes | Permanent (disk) and temporary (in-memory) indexing options |
 | Portable inference layer | Switch LLM providers using environment configuration only |
 
----
-
-## Demo
-
-![demo](assets/demo.gif)
-
-Example workflow:
-- Ask the assistant to review a diff using repository history.
-- The server retrieves similar past review context.
-- The model returns grounded feedback aligned to team expectations.
-
-## Usage Analytics
-
-To help us understand adoption, the MCP server collects privacy-first, anonymous telemetry on deployments. Future hosted deployments will expose HTTP endpoints (`/stats` and `/ping`) that publicly display the **number of unique users**.
 
 ---
 
@@ -119,24 +164,17 @@ The server exposes 12 core tools for IDE agents and developers. For a deep dive
 
 ---
 
-## Documentation
-
-Detailed guides are split into focused pages:
-
-- [Quick Start and Usage](docs/quickstart.md)
-- [LLM Configuration](docs/llm-configuration.md)
-- [Integrations](docs/integrations/index.md)
-- [Architecture and Tools](docs/architecture.md)
-- [Pipeline Deep Dive](docs/pipeline.md)
-- [Configuration Guide (Change Tokens/Settings)](docs/guides/configuration.md)
-- [Roadmap](docs/roadmap.md)
-
 ---
 
-## Quick Links
+## 📖 Documentation
 
-- Access setup: [GitHub Token Guide](docs/GUIDE_GITHUB_TOKEN.md)
-- Client connection: [Integrations](docs/integrations/index.md)
+Detailed guides for deep dives and specific configurations:
+
+- 🛠️ [**Quick Start & Usage**](docs/quickstart.md) — Setup and basic commands.
+- ⚙️ [**LLM Configuration**](docs/llm-configuration.md) — Switching between OpenAI, Anthropic, Gemini, and Cerebras.
+- 🧩 [**Tool Strategy & Selection Guide**](docs/tools_strategy.md) — When to use which tool (for humans and agents).
+- 🏗️ [**Architecture & Pipeline**](docs/architecture.md) — How the RAG engine and indexing work.
+- 🔌 [**Integrations**](docs/integrations/index.md) — Connecting to Cursor, Claude Desktop, and more.
 
 ---
 
@@ -144,24 +182,12 @@ Detailed guides are split into focused pages:
 
 We want to hear from you—whether you are a solo developer or a team at a large company!
 
-### 👤 For Individuals
 - **Feedback**: Please open an issue or start a discussion if you have ideas or encounter bugs.
-- **Show your support**: If this tool saves you time, give it a **Star ⭐**! It helps others find the project.
-
-### 🏢 For Corporate & Teams
-- **Usage**: Is your team using this MCP server? Join our "Adopters" list by opening a PR to add your team's name.
-- **Corporate Feedback**: Open an issue with the `corporate-usage` label to tell us how this has improved your PR review workflow.
-- **Custom Integration**: Need help deploying this to your private cloud? Reach out via GitHub Discussions.
+- **Star ⭐**: If this tool saves you time, give it a star! It helps others find the project.
+- **Corporate**: Is your team using this? Join our "Adopters" list by opening a PR to add your team's name.
 
 ---
 
-## 📜 Documentation & Guides
-
-- **Strategy & Best Practices**: [Tool Strategy & Selection Guide](docs/tools_strategy.md)
-- **Architecture**: [Architecture and Tools](docs/architecture.md)
-- **Pipeline**: [Pipeline Deep Dive](docs/pipeline.md)
-- **Usage**: [Quick Start and Usage](docs/quickstart.md)
-
 ## 🛠️ Troubleshooting
 
 - **"command not found"**: Use absolute paths in your configuration. Run `github-pr-context-mcp config` to get your exact path.

{github_pr_context_mcp-0.2.5 → github_pr_context_mcp-0.2.7}/analytics/usage_metrics.py

@@ -178,7 +178,13 @@ class UsageMetricsStore:
         return {
             "tracked_since": tracked_since_val,
             "total_tool_calls": total_calls_val,
-            "total_unique_users": total_unique,
+            "metrics": {
+                "total_unique_users": total_unique,
+                "active_cli_users": total_ping_users,
+                "authenticated_users": total_auth_users,
+                "github_clones": github_clones_val,
+                "github_downloads": github_downloads_val
+            },
             "users_by_mode": users_by_mode,
             "top_tools": top_tools,
             "daily": daily_series,

github_pr_context_mcp-0.2.7/app/mcp_app.py

@@ -0,0 +1,55 @@
+import os
+import threading
+from mcp.server.fastmcp import FastMCP
+
+from app.state import (
+    build_auth_settings,
+    token_verifier,
+    build_transport_security,
+    usage_store
+)
+from app.tools.indexing import register_indexing_tools
+from app.tools.analysis import register_analysis_tools
+from app.tools.generation import register_generation_tools
+from app.tools.admin import register_admin_tools
+from app.routes.http import register_http_routes
+
+# Initialize FastMCP
+mcp = FastMCP(
+    "github-pr-review-context",
+    host=os.getenv("HOST", "0.0.0.0"),
+    port=int(os.getenv("PORT", "8000")),
+    streamable_http_path=os.getenv("MCP_HTTP_PATH", "/mcp"),
+    auth=build_auth_settings(),
+    token_verifier=token_verifier,
+    transport_security=build_transport_security(),
+)
+
+# Register Tools
+register_indexing_tools(mcp)
+register_analysis_tools(mcp)
+register_generation_tools(mcp)
+register_admin_tools(mcp)
+
+# Register HTTP Routes
+register_http_routes(mcp)
+
+# Background Sync Loop (GitHub Traffic)
+def _github_sync_loop():
+    repo = os.getenv("GITHUB_TRAFFIC_REPO")
+    token = os.getenv("GITHUB_TOKEN")
+    if not repo or not token or not usage_store:
+        return
+    
+    owner, name = repo.split("/", 1)
+    print(f"Starting GitHub traffic sync for {repo}...", flush=True)
+    while True:
+        try:
+            usage_store.sync_github_traffic(owner, name, token)
+        except Exception as e:
+            print(f"GitHub traffic sync failed: {e}", flush=True)
+        import time
+        time.sleep(3600 * 12)  # Sync every 12 hours
+
+if os.getenv("GITHUB_TRAFFIC_REPO"):
+    threading.Thread(target=_github_sync_loop, daemon=True).start()

github_pr_context_mcp-0.2.7/app/routes/http.py

@@ -0,0 +1,90 @@
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from mcp.server.auth.middleware.auth_context import get_access_token
+from app.state import (
+    identity_store,
+    usage_store,
+    current_user_email,
+    current_user_settings,
+    validate_admin_token
+)
+
+def register_http_routes(mcp):
+    @mcp.custom_route("/settings", methods=["PUT"], include_in_schema=False)
+    async def update_settings_route(request: Request):
+        access_token = get_access_token()
+        if access_token is None or identity_store is None:
+            return JSONResponse({"error": "unauthorized"}, status_code=401)
+
+        try:
+            payload = await request.json()
+        except Exception:
+            return JSONResponse({"error": "invalid_json"}, status_code=400)
+
+        settings = payload.get("settings") if isinstance(payload, dict) else None
+        if not isinstance(settings, dict):
+            return JSONResponse({"error": "settings must be an object"}, status_code=400)
+
+        try:
+            updated = identity_store.update_user_settings(access_token.client_id, settings)
+        except ValueError as exc:
+            return JSONResponse({"error": str(exc)}, status_code=400)
+
+        return JSONResponse({"email": access_token.client_id, "settings": updated})
+
+    @mcp.custom_route("/whoami", methods=["GET"], include_in_schema=False)
+    async def whoami_route(_: Request):
+        access_token = get_access_token()
+        if access_token is None:
+            return JSONResponse({"error": "unauthorized"}, status_code=401)
+        user_settings = current_user_settings()
+        return JSONResponse({
+            "email": access_token.client_id,
+            "scopes": access_token.scopes,
+            "has_custom_github_token": bool(user_settings.get("github_token")),
+            "has_custom_llm": any(user_settings.get(k) for k in ("llm_provider", "llm_model", "llm_api_key", "llm_base_url")),
+        })
+
+    @mcp.custom_route("/healthz", methods=["GET"], include_in_schema=False)
+    async def healthz(_: Request):
+        return JSONResponse({"status": "ok"})
+
+    @mcp.custom_route("/ping", methods=["POST"], include_in_schema=False)
+    async def ping(request: Request):
+        """Anonymous telemetry ping from CLI (uvx/pipx)."""
+        if usage_store is None:
+            return JSONResponse({"enabled": False}, status_code=503)
+        try:
+            payload = await request.json()
+            uid = payload.get("id")
+            mode = payload.get("mode", "unknown")
+            if not uid:
+                return JSONResponse({"error": "invalid_id"}, status_code=400)
+            usage_store.record_ping(uid, mode)
+            return JSONResponse({"ok": True})
+        except Exception:
+            return JSONResponse({"error": "invalid_request"}, status_code=400)
+
+    @mcp.custom_route("/usage", methods=["GET"], include_in_schema=False)
+    async def usage(request: Request):
+        if usage_store is None:
+            return JSONResponse({"enabled": False}, status_code=503)
+        token = request.query_params.get("token")
+        if not validate_admin_token(token):
+            return JSONResponse({"error": "unauthorized"}, status_code=401)
+        return JSONResponse(usage_store.summary())
+
+    @mcp.custom_route("/usage/badge", methods=["GET"], include_in_schema=False)
+    async def usage_badge(_: Request):
+        """Returns a Shields.io compatible JSON for the user count."""
+        if usage_store is None:
+            return JSONResponse({"schemaVersion": 1, "label": "users", "message": "off", "color": "gray"})
+        summary = usage_store.summary()
+        count = summary.get("metrics", {}).get("total_unique_users", 0)
+        return JSONResponse({
+            "schemaVersion": 1,
+            "label": "users",
+            "message": str(count),
+            "color": "blueviolet",
+            "style": "flat-square",
+        })

github_pr_context_mcp-0.2.7/app/state.py

@@ -0,0 +1,174 @@
+import hmac
+import os
+import re
+import sys
+from mcp.server.fastmcp import Context
+from mcp.server.auth.middleware.auth_context import get_access_token
+from mcp.server.auth.provider import AccessToken
+from mcp.server.auth.settings import AuthSettings
+from mcp.server.transport_security import TransportSecuritySettings
+from urllib.parse import urlparse
+
+from auth import GmailIdentityStore, GmailTokenVerifier
+from analytics import UsageMetricsStore
+from storage import (
+    repo_is_indexed_permanently,
+    repo_is_indexed_temporarily,
+)
+
+# --- Configuration Constants ---
+USAGE_TRACKING_ENABLED = os.getenv("USAGE_TRACKING_ENABLED", "true").strip().lower() in {"1", "true", "yes", "on"}
+AUTH_REQUIRED = os.getenv("AUTH_REQUIRED", "false").strip().lower() in {"1", "true", "yes", "on"}
+REGISTRATION_SECRET = os.getenv("REGISTRATION_SECRET", "").strip()
+MCP_PUBLIC_URL = os.getenv("MCP_PUBLIC_URL", "").strip()
+AUTH_REGISTRY_PATH = os.getenv("AUTH_REGISTRY_PATH", "./chroma_db/auth_registry.json")
+USAGE_METRICS_TOKEN = os.getenv("USAGE_METRICS_TOKEN", "").strip()
+USAGE_STATS_PATH = os.getenv("USAGE_STATS_PATH", "./chroma_db/usage_stats.json")
+
+# --- Globals ---
+identity_store = GmailIdentityStore(AUTH_REGISTRY_PATH) if AUTH_REQUIRED else None
+token_verifier = GmailTokenVerifier(identity_store) if identity_store else None
+usage_store = UsageMetricsStore(USAGE_STATS_PATH) if USAGE_TRACKING_ENABLED else None
+
+# Stateful per connected client/session
+_sessions: dict[str, dict] = {}
+
+# --- Helper Functions ---
+def normalize_repo(repo: str | None) -> str:
+    """Strict validation for GitHub repository identifiers (owner/name)."""
+    if not repo:
+        raise ValueError("Repository identifier is required (e.g. 'owner/repo').")
+    
+    # Handle full URLs
+    if repo.endswith(".git"):
+        repo = repo[:-4]
+    match = re.search(r"(?:github\.com/)?([^/]+/[^/]+)", repo)
+    if match:
+        repo = match.group(1).split("#")[0].split("?")[0]
+
+    if not re.fullmatch(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$", repo):
+        raise ValueError(f"Invalid repository format: '{repo}'. Expected 'owner/repo'.")
+    
+    return repo
+
+def normalize_namespace(namespace: str | None) -> str | None:
+    if namespace is None:
+        return None
+    ns = namespace.strip()
+    return ns or None
+
+def current_user_email() -> str | None:
+    access_token = get_access_token()
+    if isinstance(access_token, AccessToken):
+        return normalize_namespace(access_token.client_id)
+    return None
+
+def current_user_settings() -> dict:
+    store = identity_store
+    if not store:
+        return {}
+    email = current_user_email()
+    if not email:
+        return {}
+    return store.get_user_settings(email)
+
+def llm_settings(user_settings: dict[str, str]) -> dict[str, str]:
+    llm: dict[str, str] = {}
+    for key in ("llm_provider", "llm_model", "llm_api_key", "llm_base_url"):
+        value = user_settings.get(key)
+        if value:
+            llm[key] = value
+    return llm
+
+def repo_state_key(repo_key: str, namespace: str | None) -> str:
+    ns = normalize_namespace(namespace) or "_default"
+    return f"{ns}::{repo_key}"
+
+def session_id(ctx: Context) -> str:
+    return current_user_email() or ctx.client_id or f"session-{id(ctx.session)}"
+
+def get_state(ctx: Context) -> dict:
+    sid = session_id(ctx)
+    if sid not in _sessions:
+        configured_ns = normalize_namespace(os.getenv("MCP_NAMESPACE", ""))
+        _sessions[sid] = {
+            "active_repo": None,
+            "active_namespace": configured_ns or current_user_email() or normalize_namespace(ctx.client_id),
+            "storage_types": {},
+        }
+    return _sessions[sid]
+
+def resolve_namespace(requested_namespace: str | None, state: dict) -> str | None:
+    current_email = current_user_email()
+    if AUTH_REQUIRED:
+        if not current_email:
+            raise ValueError("Unauthorized: missing identity when AUTH_REQUIRED is true.")
+        return normalize_namespace(current_email)
+    return normalize_namespace(requested_namespace if requested_namespace is not None else state.get("active_namespace"))
+
+def resolve_repo(repo: str | None, state: dict) -> str:
+    if repo:
+        return normalize_repo(repo)
+    active = state.get("active_repo")
+    if not active:
+        raise ValueError("No repo specified and no active repo set. Use ensure_repo_ready first, or pass repo explicitly.")
+    return normalize_repo(active)
+
+def is_temporary(repo_key: str, namespace: str | None, state: dict) -> bool:
+    key = repo_state_key(repo_key, namespace)
+    known = state["storage_types"].get(key)
+    if known is not None:
+        return known == "temporary"
+    return repo_is_indexed_temporarily(repo_key, namespace=namespace)
+
+def namespace_text(namespace: str | None) -> str:
+    if namespace:
+        return f"\nNamespace: {namespace}"
+    return ""
+
+def usage_user_id(ctx: Context, namespace: str | None) -> str:
+    current_email = current_user_email()
+    if current_email:
+        return f"email:{current_email}"
+    if namespace:
+        return f"ns:{namespace}"
+    if ctx.client_id:
+        return f"client:{ctx.client_id}"
+    return session_id(ctx)
+
+def track_usage(ctx: Context, namespace: str | None, tool_name: str) -> None:
+    if usage_store is None:
+        return
+    usage_store.record_event(usage_user_id(ctx, namespace), tool_name)
+
+def validate_admin_token(admin_token: str | None) -> bool:
+    if not USAGE_METRICS_TOKEN:
+        return True
+    return hmac.compare_digest(admin_token or "", USAGE_METRICS_TOKEN)
+
+def build_auth_settings() -> AuthSettings | None:
+    if not AUTH_REQUIRED:
+        return None
+    if not MCP_PUBLIC_URL:
+        raise ValueError("MCP_PUBLIC_URL is required when AUTH_REQUIRED=true")
+    if not REGISTRATION_SECRET:
+        raise ValueError("REGISTRATION_SECRET is required when AUTH_REQUIRED=true")
+    public_url = MCP_PUBLIC_URL.rstrip("/")
+    return AuthSettings(
+        issuer_url=public_url,
+        resource_server_url=public_url,
+        service_documentation_url=os.getenv("AUTH_SERVICE_DOC_URL", public_url),
+        required_scopes=["identity:gmail"],
+    )
+
+def build_transport_security() -> TransportSecuritySettings | None:
+    if not AUTH_REQUIRED or not MCP_PUBLIC_URL:
+        return None
+    parsed = urlparse(MCP_PUBLIC_URL)
+    host = parsed.netloc
+    origin = f"{parsed.scheme}://{parsed.netloc}"
+    return TransportSecuritySettings(
+        enable_dns_rebinding_protection=True,
+        allowed_hosts=[host],
+        allowed_origins=[origin],
+    )