powerbi-mcp 0.1.0__py3-none-any.whl

src/tools/datasets.py

@@ -0,0 +1,355 @@
+"""
+Dataset management tools
+
+Tools for listing and inspecting PowerBI datasets.
+"""
+
+import json
+import logging
+from typing import Optional
+
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context
+
+from ..models import ResponseFormat, DetailLevel
+from ..formatters import (
+    format_datasets_markdown,
+    format_dataset_markdown,
+    format_refresh_history_markdown,
+    format_parameters_markdown,
+    truncate_response
+)
+from ..validation import validate_refresh_top
+from ..constants import REFRESH_HISTORY_DEFAULT
+
+logger = logging.getLogger(__name__)
+
+
+def register_dataset_tools(mcp: FastMCP) -> None:
+    """Register dataset-related tools with the MCP server"""
+
+    @mcp.tool()
+    async def get_datasets(
+        workspace_id: Optional[str] = None,
+        format: str = "markdown",
+        detail: str = "concise",
+        ctx: Context = None
+    ) -> str:
+        """
+        Get list of datasets from a specific workspace or My workspace.
+
+        Datasets in PowerBI contain the data model, including tables, columns, relationships,
+        and measures. This tool retrieves all datasets accessible in the specified workspace.
+
+        Use this when you need to:
+        - List all datasets in a workspace
+        - Find a dataset ID for querying
+        - Discover available data sources
+        - Check dataset refresh status and configuration
+
+        Parameters:
+        - workspace_id (optional): Workspace (group) ID. If not provided, returns datasets from "My workspace"
+        - format: Response format - "json" or "markdown" (default: "markdown")
+        - detail: Detail level - "concise" or "detailed" (default: "concise")
+
+        Returns:
+        List of datasets with their IDs, names, and optionally detailed metadata including
+        refresh status, storage mode, and configuration details.
+
+        Example usage:
+        - Get datasets from specific workspace: workspace_id="abc123..."
+        - Get datasets from My workspace: (omit workspace_id)
+        - Get detailed info: detail="detailed"
+
+        Error handling:
+        - If workspace_id not found, verify the ID is correct using get_workspaces
+        - For permission errors, ensure service principal has read access to the workspace
+        - Empty list means no datasets in the workspace or no access
+        """
+        try:
+            format_type = ResponseFormat(format.lower())
+            detail_level = DetailLevel(detail.lower())
+
+            # Get client from context
+            client = ctx.request_context.lifespan_context["client"]
+
+            if workspace_id:
+                await ctx.info(f"Fetching datasets from workspace {workspace_id}")
+            else:
+                await ctx.info("Fetching datasets from My workspace")
+
+            # Fetch datasets from API
+            result = await client.get_datasets(workspace_id=workspace_id)
+            datasets = result.get("value", [])
+
+            await ctx.info(f"Found {len(datasets)} datasets")
+
+            # Format response
+            if format_type == ResponseFormat.MARKDOWN:
+                response = format_datasets_markdown(datasets, detail_level)
+            else:
+                response = json.dumps(datasets, indent=2)
+
+            return truncate_response(response)
+
+        except ValueError as e:
+            error_msg = f"Invalid parameter value: {str(e)}"
+            await ctx.error(error_msg)
+            return f"Error: {error_msg}"
+        except Exception as e:
+            error_msg = str(e)
+            await ctx.error(f"Failed to get datasets: {error_msg}")
+            return f"Error executing get_datasets: {error_msg}"
+
+    @mcp.tool()
+    async def get_dataset(
+        dataset_id: str,
+        workspace_id: Optional[str] = None,
+        format: str = "json",
+        ctx: Context = None
+    ) -> str:
+        """
+        Get detailed information about a specific dataset.
+
+        Retrieves comprehensive metadata about a PowerBI dataset including configuration,
+        refresh settings, and data source information.
+
+        Use this when you need to:
+        - Get detailed metadata about a specific dataset
+        - Check dataset configuration and capabilities
+        - Verify dataset refresh settings
+        - Understand dataset storage mode and requirements
+
+        Parameters:
+        - dataset_id (required): The unique identifier of the dataset
+        - workspace_id (optional): Workspace (group) ID. Omit for datasets in "My workspace"
+        - format: Response format - "json" or "markdown" (default: "json")
+
+        Returns:
+        Detailed dataset information including:
+        - Dataset name and ID
+        - Configuration details
+        - Refresh capabilities and requirements
+        - Storage mode
+        - Creation date
+        - Identity requirements
+
+        Example usage:
+        - Get dataset from My workspace: dataset_id="dataset123"
+        - Get dataset from specific workspace: dataset_id="dataset123", workspace_id="workspace456"
+
+        Error handling:
+        - If dataset_id not found (404), verify the ID using get_datasets
+        - For permission errors, ensure service principal has read access
+        - Check workspace_id matches the workspace containing the dataset
+        """
+        try:
+            if not dataset_id:
+                return "Error: dataset_id is required"
+
+            format_type = ResponseFormat(format.lower())
+
+            # Get client from context
+            client = ctx.request_context.lifespan_context["client"]
+
+            if workspace_id:
+                await ctx.info(f"Fetching dataset {dataset_id} from workspace {workspace_id}")
+            else:
+                await ctx.info(f"Fetching dataset {dataset_id} from My workspace")
+
+            # Fetch dataset from API
+            result = await client.get_dataset(
+                dataset_id=dataset_id,
+                workspace_id=workspace_id
+            )
+
+            await ctx.info(f"Retrieved dataset: {result.get('name', 'Unknown')}")
+
+            # Format response
+            if format_type == ResponseFormat.JSON:
+                response = json.dumps(result, indent=2)
+            else:
+                response = format_dataset_markdown(result)
+
+            return truncate_response(response)
+
+        except ValueError as e:
+            error_msg = f"Invalid parameter value: {str(e)}"
+            await ctx.error(error_msg)
+            return f"Error: {error_msg}"
+        except Exception as e:
+            error_msg = str(e)
+            await ctx.error(f"Failed to get dataset: {error_msg}")
+            return f"Error executing get_dataset: {error_msg}"
+
+    @mcp.tool()
+    async def get_refresh_history(
+        dataset_id: str,
+        workspace_id: Optional[str] = None,
+        top: int = REFRESH_HISTORY_DEFAULT,
+        format: str = "markdown",
+        ctx: Context = None
+    ) -> str:
+        """
+        Get refresh history for a PowerBI dataset.
+
+        Shows recent refresh operations including:
+        - Status (Completed, Failed, Unknown)
+        - Start and end times
+        - Request ID and refresh type
+        - Error messages (for failed refreshes)
+
+        Useful for monitoring data freshness and troubleshooting refresh failures.
+
+        Parameters:
+        - dataset_id (required): The dataset ID
+        - workspace_id (optional): Workspace ID. Omit for datasets in "My workspace"
+        - top: Number of refresh records to return (default: 5, max: 60)
+        - format: Response format - "markdown" or "json" (default: "markdown")
+
+        Returns:
+        Formatted refresh history with status, timestamps, and error details for failed refreshes.
+
+        Example usage:
+        - Get last 5 refreshes: dataset_id="abc123"
+        - Get last 10 refreshes: dataset_id="abc123", top=10
+        - Check specific workspace: dataset_id="abc123", workspace_id="workspace456"
+
+        Error handling:
+        - If dataset_id not found, verify the ID using get_datasets
+        - For permission errors, ensure service principal has read access
+        """
+        try:
+            if not dataset_id:
+                return "Error: dataset_id is required"
+
+            # Validate top parameter
+            validate_refresh_top(top)
+            format_type = ResponseFormat(format.lower())
+
+            # Get client from context
+            client = ctx.request_context.lifespan_context["client"]
+
+            if workspace_id:
+                await ctx.info(f"Fetching refresh history for dataset {dataset_id} from workspace {workspace_id}")
+            else:
+                await ctx.info(f"Fetching refresh history for dataset {dataset_id} from My workspace")
+
+            # Fetch refresh history from API
+            result = await client.get_refresh_history(
+                dataset_id=dataset_id,
+                workspace_id=workspace_id,
+                top=top
+            )
+            refresh_history = result.get("value", [])
+
+            await ctx.info(f"Retrieved {len(refresh_history)} refresh records")
+
+            # Get dataset name for formatting
+            dataset_info = await client.get_dataset(dataset_id=dataset_id, workspace_id=workspace_id)
+            dataset_name = dataset_info.get("name", dataset_id)
+
+            # Format response
+            if format_type == ResponseFormat.MARKDOWN:
+                response = format_refresh_history_markdown(refresh_history, dataset_name)
+            else:
+                response = json.dumps(refresh_history, indent=2)
+
+            return truncate_response(response)
+
+        except ValueError as e:
+            error_msg = f"Invalid parameter value: {str(e)}"
+            await ctx.error(error_msg)
+            return f"Error: {error_msg}"
+        except Exception as e:
+            error_msg = str(e)
+            await ctx.error(f"Failed to get refresh history: {error_msg}")
+            return f"Error executing get_refresh_history: {error_msg}"
+
+    @mcp.tool()
+    async def get_parameters(
+        dataset_id: str,
+        workspace_id: Optional[str] = None,
+        format: str = "markdown",
+        detail: str = "concise",
+        ctx: Context = None
+    ) -> str:
+        """
+        Get parameters defined in a PowerBI dataset.
+
+        Returns parameter definitions including:
+        - Name and data type
+        - Current value
+        - Whether parameter is required
+        - Suggested values (if defined)
+
+        Useful for discovering available parameters before querying parameterized datasets.
+
+        Note: Not supported for datasets with SQL, Oracle, Teradata, SAP HANA DirectQuery
+        connections or datasets modified via XMLA endpoint.
+
+        Parameters:
+        - dataset_id (required): The dataset ID
+        - workspace_id (optional): Workspace ID. Omit for datasets in "My workspace"
+        - format: Response format - "markdown" or "json" (default: "markdown")
+        - detail: Detail level - "concise" or "detailed" (default: "concise")
+
+        Returns:
+        Formatted parameter information with names, types, values, and suggested values.
+
+        Example usage:
+        - Get all parameters: dataset_id="abc123"
+        - Get detailed info: dataset_id="abc123", detail="detailed"
+        - Check specific workspace: dataset_id="abc123", workspace_id="workspace456"
+
+        Error handling:
+        - If dataset_id not found, verify the ID using get_datasets
+        - "Not supported" errors indicate dataset type limitations
+        - Empty result means no parameters are defined
+        """
+        try:
+            if not dataset_id:
+                return "Error: dataset_id is required"
+
+            format_type = ResponseFormat(format.lower())
+            detail_level = DetailLevel(detail.lower())
+
+            # Get client from context
+            client = ctx.request_context.lifespan_context["client"]
+
+            if workspace_id:
+                await ctx.info(f"Fetching parameters for dataset {dataset_id} from workspace {workspace_id}")
+            else:
+                await ctx.info(f"Fetching parameters for dataset {dataset_id} from My workspace")
+
+            # Fetch parameters from API
+            result = await client.get_parameters(
+                dataset_id=dataset_id,
+                workspace_id=workspace_id
+            )
+            parameters = result.get("value", [])
+
+            await ctx.info(f"Retrieved {len(parameters)} parameters")
+
+            # Get dataset name for formatting
+            dataset_info = await client.get_dataset(dataset_id=dataset_id, workspace_id=workspace_id)
+            dataset_name = dataset_info.get("name", dataset_id)
+
+            # Format response
+            if format_type == ResponseFormat.MARKDOWN:
+                response = format_parameters_markdown(parameters, dataset_name, detail_level)
+            else:
+                response = json.dumps(parameters, indent=2)
+
+            return truncate_response(response)
+
+        except ValueError as e:
+            error_msg = f"Invalid parameter value: {str(e)}"
+            await ctx.error(error_msg)
+            return f"Error: {error_msg}"
+        except Exception as e:
+            error_msg = str(e)
+            await ctx.error(f"Failed to get parameters: {error_msg}")
+            return f"Error executing get_parameters: {error_msg}"
+
+    logger.info("Dataset tools registered")

src/tools/queries.py

@@ -0,0 +1,125 @@
+"""
+Query execution tools
+
+Tools for executing DAX queries against PowerBI datasets.
+"""
+
+import json
+import logging
+from typing import Optional
+
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context
+
+from ..models import ResponseFormat
+from ..formatters import format_query_results_markdown, truncate_response
+from ..validation import validate_dax_query
+
+logger = logging.getLogger(__name__)
+
+
+def register_query_tools(mcp: FastMCP) -> None:
+    """Register query-related tools with the MCP server"""
+
+    @mcp.tool()
+    async def query_dataset(
+        dataset_id: str,
+        dax_query: str,
+        workspace_id: Optional[str] = None,
+        format: str = "markdown",
+        ctx: Context = None
+    ) -> str:
+        """
+        Execute DAX (Data Analysis Expressions) queries against a PowerBI dataset.
+
+        This tool allows you to query dataset tables using DAX, PowerBI's formula language.
+        DAX queries can retrieve data, perform calculations, and apply filters.
+
+        Use this when you need to:
+        - Retrieve data from dataset tables
+        - Perform calculations and aggregations
+        - Filter and analyze dataset data
+        - Get specific rows or aggregated results
+
+        DAX Query Syntax:
+        - Basic table query: EVALUATE TableName
+        - Filtered query: EVALUATE FILTER(TableName, TableName[Column] = "Value")
+        - Aggregation: EVALUATE SUMMARIZE(TableName, TableName[Column], "Total", SUM(TableName[Amount]))
+        - Top N: EVALUATE TOPN(10, TableName, TableName[Column], DESC)
+
+        Parameters:
+        - dataset_id (required): The unique identifier of the dataset to query
+        - dax_query (required): DAX query to execute (must start with EVALUATE)
+        - workspace_id (optional): Workspace (group) ID. Omit for "My workspace"
+        - format: Response format - "json" or "markdown" (default: "markdown")
+
+        Returns:
+        Query results as a table with rows and columns. Markdown format presents results
+        as formatted tables. Results are limited to 100 rows in markdown view.
+
+        Example queries:
+        1. Get all rows: "EVALUATE 'Sales'"
+        2. Filter data: "EVALUATE FILTER('Sales', 'Sales'[Year] = 2024)"
+        3. Aggregate: "EVALUATE SUMMARIZE('Sales', 'Sales'[Category], "Total", SUM('Sales'[Amount]))"
+        4. Top 10: "EVALUATE TOPN(10, 'Sales', 'Sales'[Amount], DESC)"
+
+        Error handling:
+        - For syntax errors, check your DAX query starts with EVALUATE
+        - If table/column not found, use get_dataset to see available schema
+        - For large result sets, add filters or use TOPN to limit rows
+        - Timeout errors suggest simplifying the query or adding filters
+        """
+        try:
+            if not dataset_id:
+                return "Error: dataset_id is required"
+
+            if not dax_query:
+                return "Error: dax_query is required"
+
+            # Validate DAX query
+            try:
+                validate_dax_query(dax_query)
+            except ValueError as e:
+                return f"Error: {str(e)}"
+
+            format_type = ResponseFormat(format.lower())
+
+            # Get client from context
+            client = ctx.request_context.lifespan_context["client"]
+
+            if workspace_id:
+                await ctx.info(f"Executing query on dataset {dataset_id} in workspace {workspace_id}")
+            else:
+                await ctx.info(f"Executing query on dataset {dataset_id} in My workspace")
+
+            await ctx.report_progress(0.3, 1.0, "Executing DAX query...")
+
+            # Execute query
+            queries = [{"query": dax_query}]
+            result = await client.execute_queries(
+                dataset_id=dataset_id,
+                queries=queries,
+                workspace_id=workspace_id
+            )
+
+            await ctx.report_progress(1.0, 1.0, "Query completed")
+            await ctx.info("Query executed successfully")
+
+            # Format response
+            if format_type == ResponseFormat.MARKDOWN:
+                response = format_query_results_markdown(result)
+            else:
+                response = json.dumps(result, indent=2)
+
+            return truncate_response(response)
+
+        except ValueError as e:
+            error_msg = f"Invalid parameter value: {str(e)}"
+            await ctx.error(error_msg)
+            return f"Error: {error_msg}"
+        except Exception as e:
+            error_msg = str(e)
+            await ctx.error(f"Failed to execute query: {error_msg}")
+            return f"Error executing query_dataset: {error_msg}"
+
+    logger.info("Query tools registered")

src/tools/workspaces.py

@@ -0,0 +1,185 @@
+"""
+Workspace management tools
+
+Tools for listing and managing PowerBI workspaces.
+"""
+
+import json
+import logging
+from typing import Optional
+
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context
+
+from ..models import ResponseFormat, DetailLevel
+from ..formatters import (
+    format_workspaces_markdown,
+    format_reports_markdown,
+    truncate_response
+)
+from ..constants import MAX_WORKSPACES_TOP, MIN_WORKSPACES_TOP
+
+logger = logging.getLogger(__name__)
+
+
+def register_workspace_tools(mcp: FastMCP) -> None:
+    """Register workspace-related tools with the MCP server"""
+
+    @mcp.tool()
+    async def get_workspaces(
+        top: Optional[int] = None,
+        skip: Optional[int] = None,
+        format: str = "markdown",
+        detail: str = "concise",
+        ctx: Context = None
+    ) -> str:
+        """
+        Get list of PowerBI workspaces (also called groups) accessible to the service principal.
+
+        This tool retrieves all workspaces that the configured service principal has access to.
+        Workspaces are containers for dashboards, reports, datasets, and dataflows in PowerBI.
+
+        Use this when you need to:
+        - Discover available workspaces
+        - Find a workspace ID for further operations
+        - List all accessible PowerBI workspaces
+
+        Parameters:
+        - top (optional): Maximum number of workspaces to return (1-5000, for pagination)
+        - skip (optional): Number of workspaces to skip (for pagination)
+        - format: Response format - "json" or "markdown" (default: "markdown")
+        - detail: Detail level - "concise" or "detailed" (default: "concise")
+
+        Returns:
+        List of workspaces with their IDs, names, and optionally detailed metadata.
+
+        Example usage:
+        - Get first 10 workspaces: top=10
+        - Get concise markdown list: format="markdown", detail="concise"
+        - Get detailed JSON: format="json", detail="detailed"
+
+        Error handling:
+        - If authentication fails, check your service principal credentials
+        - If no workspaces returned, ensure service principal has workspace access
+        - For permission errors, verify service principal is enabled in PowerBI admin portal
+        """
+        try:
+            # Validate parameters
+            if top is not None and (top < MIN_WORKSPACES_TOP or top > MAX_WORKSPACES_TOP):
+                return f"Error: 'top' parameter must be between {MIN_WORKSPACES_TOP} and {MAX_WORKSPACES_TOP}"
+
+            if skip is not None and skip < 0:
+                return "Error: 'skip' parameter must be non-negative"
+
+            format_type = ResponseFormat(format.lower())
+            detail_level = DetailLevel(detail.lower())
+
+            # Get client from context
+            client = ctx.request_context.lifespan_context["client"]
+
+            await ctx.info(f"Fetching workspaces (top={top}, skip={skip})")
+
+            # Fetch workspaces from API
+            result = await client.get_workspaces(top=top, skip=skip)
+            workspaces = result.get("value", [])
+
+            await ctx.info(f"Found {len(workspaces)} workspaces")
+
+            # Format response
+            if format_type == ResponseFormat.MARKDOWN:
+                response = format_workspaces_markdown(workspaces, detail_level)
+            else:
+                response = json.dumps(workspaces, indent=2)
+
+            return truncate_response(response)
+
+        except ValueError as e:
+            error_msg = f"Invalid parameter value: {str(e)}"
+            await ctx.error(error_msg)
+            return f"Error: {error_msg}"
+        except Exception as e:
+            error_msg = str(e)
+            await ctx.error(f"Failed to get workspaces: {error_msg}")
+            return f"Error executing get_workspaces: {error_msg}"
+
+    @mcp.tool()
+    async def get_reports(
+        workspace_id: Optional[str] = None,
+        format: str = "markdown",
+        detail: str = "concise",
+        ctx: Context = None
+    ) -> str:
+        """
+        Get PowerBI reports from a workspace.
+
+        Returns report information including:
+        - Report name and ID
+        - Web URL for viewing
+        - Embed URL for embedding
+        - Associated dataset ID
+
+        Useful for discovering available reports and getting report URLs.
+
+        Parameters:
+        - workspace_id (optional): Workspace ID. Omit to get reports from "My workspace"
+        - format: Response format - "json" or "markdown" (default: "markdown")
+        - detail: Detail level - "concise" or "detailed" (default: "concise")
+
+        Returns:
+        List of reports with their IDs, names, and optionally URLs and dataset IDs.
+
+        Example usage:
+        - Get reports from My workspace: (omit workspace_id)
+        - Get reports from specific workspace: workspace_id="abc123"
+        - Get detailed info with URLs: detail="detailed"
+
+        Error handling:
+        - If workspace_id not found, verify the ID using get_workspaces
+        - For permission errors, ensure service principal has read access
+        - Empty list means no reports in the workspace or no access
+        """
+        try:
+            format_type = ResponseFormat(format.lower())
+            detail_level = DetailLevel(detail.lower())
+
+            # Get client from context
+            client = ctx.request_context.lifespan_context["client"]
+
+            if workspace_id:
+                await ctx.info(f"Fetching reports from workspace {workspace_id}")
+            else:
+                await ctx.info("Fetching reports from My workspace")
+
+            # Fetch reports from API
+            result = await client.get_reports(workspace_id=workspace_id)
+            reports = result.get("value", [])
+
+            await ctx.info(f"Found {len(reports)} reports")
+
+            # Get workspace name for formatting
+            workspace_name = "My workspace"
+            if workspace_id:
+                workspaces_result = await client.get_workspaces()
+                workspaces = workspaces_result.get("value", [])
+                workspace = next((w for w in workspaces if w.get("id") == workspace_id), None)
+                if workspace:
+                    workspace_name = workspace.get("name", workspace_id)
+
+            # Format response
+            if format_type == ResponseFormat.MARKDOWN:
+                response = format_reports_markdown(reports, workspace_name, detail_level)
+            else:
+                response = json.dumps(reports, indent=2)
+
+            return truncate_response(response)
+
+        except ValueError as e:
+            error_msg = f"Invalid parameter value: {str(e)}"
+            await ctx.error(error_msg)
+            return f"Error: {error_msg}"
+        except Exception as e:
+            error_msg = str(e)
+            await ctx.error(f"Failed to get reports: {error_msg}")
+            return f"Error executing get_reports: {error_msg}"
+
+    logger.info("Workspace tools registered")