analytics_metrics_details_list

Instructions

    List details of provided metrics.

    Returns all metrics that can be used as columns in analytics_query_execute.

    Args:
        website_id: UUID of the website/app to get metrics for
        metrics: list of metric names

    Returns:
        The list of all available metrics with details
    

Implementation Reference

• src/piwik_pro_mcp/tools/analytics/query.py:369-393 (handler)

  The analytics_metrics_details_list function is the core handler for this MCP tool. It is decorated with @mcp.tool and accepts a website_id (UUID) and list of metric names, then fetches metric details from the Piwik PRO API and returns a MetricsDetailsList model with regular_metrics and calculated_metrics.

  @mcp.tool(annotations=ToolAnnotations(title="Piwik PRO: List Metrics Details", readOnlyHint=True))
  def analytics_metrics_details_list(website_id: str, metrics: list[str]) -> MetricsDetailsList:
      """
      List details of provided metrics.
  
      Returns all metrics that can be used as columns in analytics_query_execute.
  
      Args:
          website_id: UUID of the website/app to get metrics for
          metrics: list of metric names
  
      Returns:
          The list of all available metrics with details
      """
      client = create_piwik_client()
      regular_metrics, calculated_metrics = [], []
      for metric in client.analytics.list_metrics(website_id).root:
          if metric.column_id == "calculated_metric" and metric.calculated_metric_id in metrics:
              calculated_metrics.append(metric)
          elif metric.column_id in metrics:
              regular_metrics.append(metric)
  
      return MetricsDetailsList(metrics=regular_metrics, calculated_metrics=calculated_metrics).model_dump(
          exclude_none=True
      )  # type: ignore

• src/piwik_pro_mcp/tools/analytics/models.py:79-83 (schema)

  The MetricsDetailsList Pydantic model is the response schema for the tool. It contains two fields: 'metrics' (list of ColumnDefinition) and 'calculated_metrics' (list of ColumnDefinition).

  class MetricsDetailsList(BaseModel):
      """Response for analytics_list_details_metrics tool."""
  
      metrics: list[ColumnDefinition]
      calculated_metrics: list[ColumnDefinition]

• src/piwik_pro_mcp/tools/analytics/__init__.py:35-51 (registration)

  The register_analytics_tools function in __init__.py calls register_query_tools(mcp), which is the function that registers the analytics_metrics_details_list tool via the @mcp.tool decorator.

  def register_analytics_tools(mcp: FastMCP) -> None:
      """
      Register all Analytics tools with the MCP server.
  
      This includes:
      - User annotations tools
      - Goals tools
      - Query tools
      - Custom dimensions tools (unified standard and product dimensions)
  
      Args:
          mcp: FastMCP server instance
      """
      register_annotations_tools(mcp)
      register_goals_tools(mcp)
      register_query_tools(mcp)
      register_custom_dimensions_tools(mcp)

• src/piwik_pro_mcp/tools/analytics/query.py:15-17 (helper)

  The create_piwik_client helper is imported from piwik_pro_mcp.common.utils and used within the tool handler to instantiate the Piwik PRO API client for fetching metric data.

  from piwik_pro_mcp.common.utils import create_piwik_client, fetch_json_from_url
  
  from .models import DimensionsDetailsList, DimensionsList, MetricsDetailsList, MetricsList, QueryExecuteResponse