Piwik PRO MCP Server

Instructions

    This will make all tags, triggers, and variables in the draft version
    active on your website.

    Args:
        app_id: UUID of the app

    Returns:
        Dictionary containing operation response including:
        - Operation status and details
        - Information about the published version
    

Implementation Reference

• src/piwik_pro_mcp/tools/tag_manager/versions.py:149-164 (handler)

  MCP handler function decorated with @mcp.tool that invokes the publish logic.

  @mcp.tool(annotations={"title": "Piwik PRO: Publish Draft Version"})
  def versions_publish_draft(app_id: str) -> PublishStatusResponse:
      """Publish the draft version to make it live.
  
      This will make all tags, triggers, and variables in the draft version
      active on your website.
  
      Args:
          app_id: UUID of the app
  
      Returns:
          Dictionary containing operation response including:
          - Operation status and details
          - Information about the published version
      """
      return publish_draft_version(app_id)

• src/piwik_pro_mcp/tools/tag_manager/versions.py:52-96 (helper)

  Core helper function implementing the API call to publish the draft version, handling both sync and async responses.

  def publish_draft_version(app_id: str) -> PublishStatusResponse:
      try:
          client = create_piwik_client()
          response = client.tag_manager.publish_draft_version(app_id)
  
          # Handle successful response
          # For async operations (202), response contains version and operation info
          # For sync operations (204), response is None
          if response and isinstance(response, dict):
              # Extract operation info for async publish operations
              operation_id = None
              version_id = None
  
              if "data" in response:
                  version_id = response["data"].get("id")
                  if "relationships" in response["data"] and "operation" in response["data"]["relationships"]:
                      operation_data = response["data"]["relationships"]["operation"].get("data", {})
                      operation_id = operation_data.get("id")
  
              message = "Draft version publish initiated"
              if operation_id:
                  message += f" (Operation ID: {operation_id})"
  
              return PublishStatusResponse(
                  status="success",
                  message=message,
                  version_info={
                      "version_id": version_id,
                      "operation_id": operation_id,
                      "is_async": True,
                      "full_response": response,
                  },
              )
          else:
              # Handle sync operations (204 No Content)
              return PublishStatusResponse(
                  status="success",
                  message="Draft version published successfully",
                  version_info={"is_async": False},
              )
      except BadRequestError as e:
          raise RuntimeError(f"Failed to publish draft version: {e.message}")
      except Exception as e:
          raise RuntimeError(f"Failed to publish draft version: {str(e)}")

• src/piwik_pro_mcp/tools/tag_manager/models.py:149-155 (schema)

  Pydantic model defining the output schema for the publish operation response.

  class PublishStatusResponse(BaseModel):
      """Response for version publishing operations."""
  
      status: str = Field(..., description="Operation status")
      message: str = Field(..., description="Operation details")
      version_info: Dict[str, Any] = Field(default_factory=dict, description="Information about the published version")

• src/piwik_pro_mcp/tools/tag_manager/versions.py:98-165 (registration)

  Registration function that defines all version-related tools including the publish draft tool using @mcp.tool decorators.

  def register_version_tools(mcp: FastMCP) -> None:
      """Register all version management tools with the MCP server."""
  
      @mcp.tool(annotations={"title": "Piwik PRO: List Versions", "readOnlyHint": True})
      def versions_list(
          app_id: str,
          limit: int = 10,
          offset: int = 0,
      ) -> TagManagerListResponse:
          """List versions for an app in Piwik PRO Tag Manager.
  
          Args:
              app_id: UUID of the app
              limit: Maximum number of versions to return (default: 10)
              offset: Number of versions to skip (default: 0)
  
          Returns:
              Dictionary containing version list and metadata including:
              - data: List of version objects with id, name, version_type, and timestamps
              - meta: Metadata with pagination information
          """
          return list_versions(app_id=app_id, limit=limit, offset=offset)
  
      @mcp.tool(annotations={"title": "Piwik PRO: Get Draft Version", "readOnlyHint": True})
      def versions_get_draft(app_id: str) -> TagManagerSingleResponse:
          """Get draft version for an app.
  
          Args:
              app_id: UUID of the app
  
          Returns:
              Dictionary containing draft version details including:
              - data: Draft version object with all tags, triggers, variables
              - Version configuration and metadata
          """
          return get_draft_version(app_id)
  
      @mcp.tool(annotations={"title": "Piwik PRO: Get Published Version", "readOnlyHint": True})
      def versions_get_published(app_id: str) -> TagManagerSingleResponse:
          """Get published version for an app.
  
          Args:
              app_id: UUID of the app
  
          Returns:
              Dictionary containing published version details including:
              - data: Published version object with all active tags, triggers, variables
              - Version configuration and metadata
          """
          return get_published_version(app_id)
  
      @mcp.tool(annotations={"title": "Piwik PRO: Publish Draft Version"})
      def versions_publish_draft(app_id: str) -> PublishStatusResponse:
          """Publish the draft version to make it live.
  
          This will make all tags, triggers, and variables in the draft version
          active on your website.
  
          Args:
              app_id: UUID of the app
  
          Returns:
              Dictionary containing operation response including:
              - Operation status and details
              - Information about the published version
          """
          return publish_draft_version(app_id)

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

  Top-level tool registration call invoking register_version_tools(mcp).

  register_tag_tools(mcp)
  register_trigger_tools(mcp)
  register_variable_tools(mcp)
  register_version_tools(mcp)