powerbi-mcp 0.1.0__py3-none-any.whl

src/auth.py

@@ -0,0 +1,136 @@
+"""
+Authentication module for PowerBI API
+
+Handles Azure AD OAuth2 client credentials flow for service principal authentication.
+"""
+
+import os
+import logging
+from datetime import datetime, timedelta
+from typing import Optional
+
+import httpx
+from dotenv import load_dotenv
+
+from .constants import AUTH_URL_TEMPLATE, AUTH_SCOPE, AUTH_TIMEOUT, TOKEN_REFRESH_BUFFER
+from .exceptions import handle_http_error
+
+logger = logging.getLogger(__name__)
+
+# Load environment variables from current working directory (where the MCP client is running)
+# This allows .env files to be project-specific rather than server-specific
+load_dotenv(dotenv_path=os.path.join(os.getcwd(), '.env'), override=False)
+logger.info(f"Attempted to load .env from: {os.getcwd()}")
+
+
+class PowerBIAuth:
+    """Handles PowerBI authentication using client credentials flow"""
+
+    def __init__(
+        self,
+        tenant_id: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None
+    ):
+        """
+        Initialize authentication handler
+
+        Args:
+            tenant_id: Azure AD tenant ID (defaults to POWERBI_TENANT_ID env var)
+            client_id: Application client ID (defaults to POWERBI_CLIENT_ID env var)
+            client_secret: Application client secret (defaults to POWERBI_CLIENT_SECRET env var)
+
+        Note:
+            Credentials can be None at initialization. Validation happens when
+            authentication is attempted (when tools are actually used).
+        """
+        self.tenant_id = tenant_id or os.getenv("POWERBI_TENANT_ID")
+        self.client_id = client_id or os.getenv("POWERBI_CLIENT_ID")
+        self.client_secret = client_secret or os.getenv("POWERBI_CLIENT_SECRET")
+
+        self.access_token: Optional[str] = None
+        self.token_expires: Optional[datetime] = None
+        self.http_client = httpx.AsyncClient(timeout=AUTH_TIMEOUT)
+
+        if all([self.tenant_id, self.client_id, self.client_secret]):
+            logger.info("PowerBI authentication handler initialized with credentials")
+        else:
+            logger.warning(
+                "PowerBI authentication handler initialized without credentials. "
+                "Set POWERBI_TENANT_ID, POWERBI_CLIENT_ID, and POWERBI_CLIENT_SECRET "
+                "environment variables before using tools."
+            )
+
+    async def get_access_token(self) -> str:
+        """
+        Get valid access token, refreshing if necessary
+
+        Returns:
+            Valid access token string
+
+        Raises:
+            Exception: If authentication fails
+        """
+        if self.access_token and self.token_expires and datetime.now() < self.token_expires:
+            logger.debug("Using cached access token")
+            return self.access_token
+
+        logger.info("Access token expired or missing, refreshing...")
+        await self._authenticate()
+        return self.access_token
+
+    async def _authenticate(self) -> None:
+        """
+        Authenticate with Azure AD using client credentials
+
+        Raises:
+            Exception: If authentication fails with detailed error message
+        """
+        # Validate credentials before attempting authentication
+        if not all([self.tenant_id, self.client_id, self.client_secret]):
+            missing = []
+            if not self.tenant_id:
+                missing.append("POWERBI_TENANT_ID")
+            if not self.client_id:
+                missing.append("POWERBI_CLIENT_ID")
+            if not self.client_secret:
+                missing.append("POWERBI_CLIENT_SECRET")
+
+            raise Exception(
+                f"Missing required environment variables: {', '.join(missing)}. "
+                "Please set these variables in your .env file or environment configuration."
+            )
+
+        auth_url = AUTH_URL_TEMPLATE.format(tenant_id=self.tenant_id)
+
+        data = {
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "scope": AUTH_SCOPE,
+            "grant_type": "client_credentials"
+        }
+
+        try:
+            logger.debug(f"Authenticating with Azure AD at {auth_url}")
+            response = await self.http_client.post(auth_url, data=data)
+            response.raise_for_status()
+
+            token_data = response.json()
+            self.access_token = token_data["access_token"]
+            expires_in = token_data.get("expires_in", 3600)
+            # Refresh before expiry to avoid race conditions
+            self.token_expires = datetime.now() + timedelta(seconds=expires_in - TOKEN_REFRESH_BUFFER)
+
+            logger.info(f"Successfully authenticated with PowerBI. Token expires in {expires_in}s")
+
+        except httpx.HTTPStatusError as e:
+            # Use centralized error handler
+            raise handle_http_error(e, "authentication") from e
+        except Exception as e:
+            logger.error(f"Authentication error: {e}")
+            raise Exception(f"Failed to authenticate with PowerBI: {str(e)}") from e
+
+    async def close(self) -> None:
+        """Close HTTP client and cleanup resources"""
+        await self.http_client.aclose()
+        logger.info("Authentication handler closed")

src/client.py

@@ -0,0 +1,259 @@
+"""
+PowerBI REST API client
+
+Handles all interactions with PowerBI REST API endpoints.
+"""
+
+import logging
+from typing import Any, Optional
+
+import httpx
+
+from .auth import PowerBIAuth
+from .constants import API_BASE_URL, API_TIMEOUT
+from .exceptions import handle_http_error
+
+logger = logging.getLogger(__name__)
+
+
+class PowerBIClient:
+    """PowerBI REST API client"""
+
+    def __init__(self, auth: PowerBIAuth):
+        """
+        Initialize PowerBI API client
+
+        Args:
+            auth: PowerBIAuth instance for handling authentication
+        """
+        self.auth = auth
+        self.http_client = httpx.AsyncClient(timeout=API_TIMEOUT)
+        logger.info("PowerBI API client initialized")
+
+    async def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        **kwargs
+    ) -> dict[str, Any]:
+        """
+        Make authenticated request to PowerBI API
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint path
+            **kwargs: Additional arguments for httpx request
+
+        Returns:
+            JSON response from API
+
+        Raises:
+            Exception: If API request fails with actionable error message
+        """
+        token = await self.auth.get_access_token()
+
+        headers = kwargs.get("headers", {})
+        headers["Authorization"] = f"Bearer {token}"
+        headers["Content-Type"] = "application/json"
+        kwargs["headers"] = headers
+
+        url = f"{API_BASE_URL}{endpoint}"
+
+        try:
+            logger.debug(f"{method} {url}")
+            response = await self.http_client.request(method, url, **kwargs)
+            response.raise_for_status()
+            return response.json()
+
+        except httpx.HTTPStatusError as e:
+            # Use centralized error handler
+            raise handle_http_error(e, "API request") from e
+
+        except httpx.TimeoutException as e:
+            logger.error(f"Request timeout for endpoint: {endpoint}")
+            raise Exception(
+                f"Request to PowerBI API timed out for endpoint: {endpoint}. "
+                "The operation took too long. Try reducing the scope of your query "
+                "or check PowerBI service status."
+            ) from e
+        except Exception as e:
+            if isinstance(e, Exception) and "PowerBI" in str(e):
+                raise
+            logger.error(f"Unexpected error: {e}")
+            raise Exception(f"Unexpected error while calling PowerBI API: {str(e)}") from e
+
+    async def get_workspaces(
+        self,
+        top: Optional[int] = None,
+        skip: Optional[int] = None
+    ) -> dict[str, Any]:
+        """
+        Get list of workspaces (groups)
+
+        Args:
+            top: Maximum number of workspaces to return (pagination)
+            skip: Number of workspaces to skip (pagination)
+
+        Returns:
+            Dictionary with 'value' key containing list of workspaces
+        """
+        params = {}
+        if top is not None:
+            params["$top"] = top
+        if skip is not None:
+            params["$skip"] = skip
+
+        logger.info(f"Fetching workspaces (top={top}, skip={skip})")
+        return await self._make_request("GET", "/groups", params=params)
+
+    async def get_datasets(
+        self,
+        workspace_id: Optional[str] = None
+    ) -> dict[str, Any]:
+        """
+        Get list of datasets from workspace or My workspace
+
+        Args:
+            workspace_id: Workspace (group) ID. If None, returns datasets from "My workspace"
+
+        Returns:
+            Dictionary with 'value' key containing list of datasets
+        """
+        if workspace_id:
+            endpoint = f"/groups/{workspace_id}/datasets"
+            logger.info(f"Fetching datasets from workspace {workspace_id}")
+        else:
+            endpoint = "/datasets"
+            logger.info("Fetching datasets from My workspace")
+
+        return await self._make_request("GET", endpoint)
+
+    async def get_dataset(
+        self,
+        dataset_id: str,
+        workspace_id: Optional[str] = None
+    ) -> dict[str, Any]:
+        """
+        Get details of a specific dataset
+
+        Args:
+            dataset_id: Dataset ID
+            workspace_id: Workspace (group) ID. If None, looks in "My workspace"
+
+        Returns:
+            Dataset details dictionary
+        """
+        if workspace_id:
+            endpoint = f"/groups/{workspace_id}/datasets/{dataset_id}"
+            logger.info(f"Fetching dataset {dataset_id} from workspace {workspace_id}")
+        else:
+            endpoint = f"/datasets/{dataset_id}"
+            logger.info(f"Fetching dataset {dataset_id} from My workspace")
+
+        return await self._make_request("GET", endpoint)
+
+    async def execute_queries(
+        self,
+        dataset_id: str,
+        queries: list[dict[str, str]],
+        workspace_id: Optional[str] = None
+    ) -> dict[str, Any]:
+        """
+        Execute DAX queries against a dataset
+
+        Args:
+            dataset_id: Dataset ID to query
+            queries: List of query dictionaries with 'query' key containing DAX expression
+            workspace_id: Workspace (group) ID. If None, uses "My workspace"
+
+        Returns:
+            Query results dictionary
+        """
+        if workspace_id:
+            endpoint = f"/groups/{workspace_id}/datasets/{dataset_id}/executeQueries"
+            logger.info(f"Executing {len(queries)} queries on dataset {dataset_id} in workspace {workspace_id}")
+        else:
+            endpoint = f"/datasets/{dataset_id}/executeQueries"
+            logger.info(f"Executing {len(queries)} queries on dataset {dataset_id} in My workspace")
+
+        payload = {"queries": queries}
+
+        return await self._make_request("POST", endpoint, json=payload)
+
+    async def get_refresh_history(
+        self,
+        dataset_id: str,
+        workspace_id: Optional[str] = None,
+        top: int = 5
+    ) -> dict[str, Any]:
+        """
+        Get refresh history for a dataset
+
+        Args:
+            dataset_id: Dataset ID
+            workspace_id: Workspace (group) ID. If None, uses "My workspace"
+            top: Number of refresh records to return (default: 5)
+
+        Returns:
+            Dictionary with 'value' containing refresh history records
+        """
+        if workspace_id:
+            endpoint = f"/groups/{workspace_id}/datasets/{dataset_id}/refreshes"
+            logger.info(f"Fetching refresh history for dataset {dataset_id} in workspace {workspace_id}")
+        else:
+            endpoint = f"/datasets/{dataset_id}/refreshes"
+            logger.info(f"Fetching refresh history for dataset {dataset_id} in My workspace")
+
+        params = {"$top": top}
+        return await self._make_request("GET", endpoint, params=params)
+
+    async def get_parameters(
+        self,
+        dataset_id: str,
+        workspace_id: Optional[str] = None
+    ) -> dict[str, Any]:
+        """
+        Get parameters for a dataset
+
+        Args:
+            dataset_id: Dataset ID
+            workspace_id: Workspace (group) ID. If None, uses "My workspace"
+
+        Returns:
+            Dictionary with 'value' containing parameter definitions
+        """
+        if workspace_id:
+            endpoint = f"/groups/{workspace_id}/datasets/{dataset_id}/parameters"
+            logger.info(f"Fetching parameters for dataset {dataset_id} in workspace {workspace_id}")
+        else:
+            endpoint = f"/datasets/{dataset_id}/parameters"
+            logger.info(f"Fetching parameters for dataset {dataset_id} in My workspace")
+
+        return await self._make_request("GET", endpoint)
+
+    async def get_reports(
+        self,
+        workspace_id: Optional[str] = None
+    ) -> dict[str, Any]:
+        """
+        Get reports from workspace or My workspace
+
+        Args:
+            workspace_id: Workspace (group) ID. If None, uses "My workspace"
+
+        Returns:
+            Dictionary with 'value' containing report list
+        """
+        if workspace_id:
+            endpoint = f"/groups/{workspace_id}/reports"
+            logger.info(f"Fetching reports from workspace {workspace_id}")
+        else:
+            endpoint = "/reports"
+            logger.info("Fetching reports from My workspace")
+
+        return await self._make_request("GET", endpoint)
+
+    async def close(self) -> None:
+        """Close HTTP client and cleanup resources"""
+        await self.http_client.aclose()
+        logger.info("PowerBI API client closed")

src/constants.py

@@ -0,0 +1,26 @@
+"""
+PowerBI MCP Server Constants
+
+Single source of truth for all configuration values, timeouts, and limits.
+"""
+
+# API Configuration
+API_BASE_URL = "https://api.powerbi.com/v1.0/myorg"
+AUTH_URL_TEMPLATE = "https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token"
+AUTH_SCOPE = "https://analysis.windows.net/powerbi/api/.default"
+
+# Timeouts (seconds)
+AUTH_TIMEOUT = 30.0
+API_TIMEOUT = 60.0
+TOKEN_REFRESH_BUFFER = 60
+
+# Response Limits
+CHARACTER_LIMIT = 25000
+MAX_ROWS_DISPLAY = 100
+MAX_WORKSPACES_TOP = 5000
+MIN_WORKSPACES_TOP = 1
+
+# Refresh History Limits
+REFRESH_HISTORY_MIN = 1
+REFRESH_HISTORY_MAX = 60
+REFRESH_HISTORY_DEFAULT = 5

src/exceptions.py

@@ -0,0 +1,96 @@
+"""
+Exception handling for PowerBI MCP Server
+
+Centralized error handling logic for HTTP errors and PowerBI-specific exceptions.
+"""
+
+import logging
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class PowerBIError(Exception):
+    """Base exception for PowerBI operations"""
+    pass
+
+
+class AuthenticationError(PowerBIError):
+    """Authentication failures"""
+    pass
+
+
+class APIError(PowerBIError):
+    """API request failures"""
+    pass
+
+
+def handle_http_error(error: httpx.HTTPStatusError, context: str = "API request") -> PowerBIError:
+    """
+    Convert httpx.HTTPStatusError to PowerBIError with actionable messages
+
+    Consolidates error handling from client.py and auth.py to provide
+    consistent, user-friendly error messages.
+
+    Args:
+        error: The HTTP status error from httpx
+        context: Context of the error ("API request", "authentication", etc.)
+
+    Returns:
+        PowerBIError subclass with detailed error message
+    """
+    # Extract error detail
+    error_detail = ""
+    try:
+        error_detail = error.response.json()
+    except Exception:
+        error_detail = error.response.text
+
+    status_code = error.response.status_code
+
+    # Map status codes to specific errors
+    if status_code == 401:
+        logger.error("Authentication failed (401)")
+        if context == "authentication":
+            return AuthenticationError(
+                f"PowerBI authentication failed with status {status_code}. "
+                "Please verify your POWERBI_TENANT_ID, POWERBI_CLIENT_ID, and "
+                f"POWERBI_CLIENT_SECRET are correct. Error details: {error_detail}"
+            )
+        else:
+            return AuthenticationError(
+                "Authentication failed (401). Your access token may have expired or "
+                "your service principal may not have the required permissions. "
+                "Ensure the service principal is enabled in PowerBI admin settings."
+            )
+
+    elif status_code == 403:
+        logger.error("Access forbidden (403)")
+        return APIError(
+            "Access forbidden (403). Your service principal does not have "
+            "permission to access this resource. Check PowerBI admin portal "
+            "settings and ensure proper workspace access is granted."
+        )
+
+    elif status_code == 404:
+        endpoint = error.request.url.path if hasattr(error.request, 'url') else "unknown"
+        logger.error(f"Resource not found (404) at endpoint: {endpoint}")
+        return APIError(
+            f"Resource not found (404) at endpoint: {endpoint}. "
+            "Please verify the workspace ID, dataset ID, or other identifiers are correct."
+        )
+
+    elif status_code == 429:
+        retry_after = error.response.headers.get("Retry-After", "60")
+        logger.warning(f"Rate limit exceeded (429). Retry after {retry_after}s")
+        return APIError(
+            f"Rate limit exceeded (429). Too many requests. "
+            f"Please wait {retry_after} seconds before retrying."
+        )
+
+    else:
+        logger.error(f"{context} failed with status {status_code}")
+        return APIError(
+            f"PowerBI {context} failed with status {status_code}. "
+            f"Error details: {error_detail}"
+        )