Initial commit

app.py

@@ -0,0 +1,494 @@
+import gradio as gr
+import requests
+import json
+import pandas as pd
+from datetime import datetime, timedelta
+import plotly.express as px
+import plotly.graph_objects as go
+from typing import Dict, List, Any, Optional
+import os
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Configuration
+PLAUSIBLE_URL = os.getenv("PLAUSIBLE_URL", "https://plausible.io/api/v2/query")
+PLAUSIBLE_KEY = os.getenv("PLAUSIBLE_KEY")
+
+class PlausibleAPI:
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+        self.headers = {
+            'Authorization': f'Bearer {api_key}',
+            'Content-Type': 'application/json'
+        }
+    
+    def query(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Make a query to the Plausible API"""
+
+        if not self.api_key:
+            return {"error": "PLAUSIBLE_KEY environment variable is not set"}
+        
+        try:
+            response = requests.post(PLAUSIBLE_URL, headers=self.headers, json=payload)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            return {"error": f"API request failed: {str(e)}"}
+        except json.JSONDecodeError as e:
+            return {"error": f"Failed to parse JSON response: {str(e)}"}
+
+# Initialize API client
+api_client = PlausibleAPI(PLAUSIBLE_KEY)
+
+def basic_stats_query(site_id: str, date_range: str, metrics: List[str]) -> tuple:
+    """Get basic site statistics"""
+    if not site_id:
+        return "Please enter a site ID", None, None
+    
+    payload = {
+        "site_id": site_id,
+        "metrics": metrics,
+        "date_range": date_range
+    }
+    
+    result = api_client.query(payload)
+    
+    if "error" in result:
+        return result["error"], None, None
+    
+    # Format results
+    if result.get("results"):
+        metrics_data = result["results"][0]["metrics"]
+        stats_dict = dict(zip(metrics, metrics_data))
+        
+        # Create a simple bar chart
+        fig = px.bar(
+            x=list(stats_dict.keys()),
+            y=list(stats_dict.values()),
+            title=f"Stats for {site_id} ({date_range})"
+        )
+        fig.update_layout(xaxis_title="Metrics", yaxis_title="Values")
+        
+        return json.dumps(result, indent=2), stats_dict, fig
+    
+    return json.dumps(result, indent=2), None, None
+
+def timeseries_query(site_id: str, date_range: str, metrics: List[str], time_dimension: str) -> tuple:
+    """Get timeseries data"""
+    if not site_id:
+        return "Please enter a site ID", None
+    
+    payload = {
+        "site_id": site_id,
+        "metrics": metrics,
+        "date_range": date_range,
+        "dimensions": [time_dimension]
+    }
+    
+    result = api_client.query(payload)
+    
+    if "error" in result:
+        return result["error"], None
+    
+    # Create timeseries chart
+    if result.get("results"):
+        df_data = []
+        for row in result["results"]:
+            row_dict = {"time": row["dimensions"][0]}
+            for i, metric in enumerate(metrics):
+                row_dict[metric] = row["metrics"][i]
+            df_data.append(row_dict)
+        
+        df = pd.DataFrame(df_data)
+        df['time'] = pd.to_datetime(df['time'])
+        
+        fig = go.Figure()
+        for metric in metrics:
+            fig.add_trace(go.Scatter(
+                x=df['time'],
+                y=df[metric],
+                mode='lines+markers',
+                name=metric
+            ))
+        
+        fig.update_layout(
+            title=f"Timeseries for {site_id}",
+            xaxis_title="Time",
+            yaxis_title="Values"
+        )
+        
+        return json.dumps(result, indent=2), fig
+    
+    return json.dumps(result, indent=2), None
+
+def geographic_analysis(site_id: str, date_range: str, metrics: List[str]) -> tuple:
+    """Analyze traffic by country and city"""
+    if not site_id:
+        return "Please enter a site ID", None, None
+    
+    payload = {
+        "site_id": site_id,
+        "metrics": metrics,
+        "date_range": date_range,
+        "dimensions": ["visit:country_name", "visit:city_name"],
+        "filters": [["is_not", "visit:country_name", [""]]],
+        "order_by": [[metrics[0], "desc"]]
+    }
+    
+    result = api_client.query(payload)
+    
+    if "error" in result:
+        return result["error"], None, None
+    
+    # Create geographic visualization
+    if result.get("results"):
+        df_data = []
+        for row in result["results"]:
+            row_dict = {
+                "country": row["dimensions"][0],
+                "city": row["dimensions"][1]
+            }
+            for i, metric in enumerate(metrics):
+                row_dict[metric] = row["metrics"][i]
+            df_data.append(row_dict)
+        
+        df = pd.DataFrame(df_data)
+        
+        # Create a bar chart of top countries
+        country_stats = df.groupby('country')[metrics[0]].sum().sort_values(ascending=False).head(10)
+        
+        fig = px.bar(
+            x=country_stats.index,
+            y=country_stats.values,
+            title=f"Top Countries by {metrics[0]} for {site_id}",
+            labels={'x': 'Country', 'y': metrics[0]}
+        )
+        fig.update_xaxes(tickangle=45)
+        
+        return json.dumps(result, indent=2), fig, df.head(20).to_dict('records')
+    
+    return json.dumps(result, indent=2), None, None
+
+def utm_analysis(site_id: str, date_range: str) -> tuple:
+    """Analyze UTM parameters"""
+    if not site_id:
+        return "Please enter a site ID", None, None
+    
+    payload = {
+        "site_id": site_id,
+        "metrics": ["visitors", "events", "pageviews"],
+        "date_range": date_range,
+        "dimensions": ["visit:utm_medium", "visit:utm_source"],
+        "filters": [["is_not", "visit:utm_medium", [""]]]
+    }
+    
+    result = api_client.query(payload)
+    
+    if "error" in result:
+        return result["error"], None, None
+    
+    if result.get("results"):
+        df_data = []
+        for row in result["results"]:
+            df_data.append({
+                "utm_medium": row["dimensions"][0] or "Direct",
+                "utm_source": row["dimensions"][1] or "Direct",
+                "visitors": row["metrics"][0],
+                "events": row["metrics"][1],
+                "pageviews": row["metrics"][2]
+            })
+        
+        df = pd.DataFrame(df_data)
+        
+        # Create sunburst chart
+        fig = px.sunburst(
+            df,
+            path=['utm_medium', 'utm_source'],
+            values='visitors',
+            title=f"UTM Analysis for {site_id}"
+        )
+        
+        return json.dumps(result, indent=2), fig, df.to_dict('records')
+    
+    return json.dumps(result, indent=2), None, None
+
+def custom_query(site_id: str, query_json: str) -> str:
+    """Execute a custom JSON query"""
+    if not site_id:
+        return "Please enter a site ID"
+    
+    try:
+        payload = json.loads(query_json)
+        payload["site_id"] = site_id  # Override site_id
+        
+        result = api_client.query(payload)
+        return json.dumps(result, indent=2)
+    
+    except json.JSONDecodeError as e:
+        return f"Invalid JSON: {str(e)}"
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+# Gradio Interface
+with gr.Blocks(title="Plausible Analytics Dashboard", theme=gr.themes.Soft()) as demo:
+    gr.Markdown("# 📊 Plausible Analytics Dashboard")
+    gr.Markdown("MCP Server to analyze your website statistics using the Plausible Stats API.\n\nSo far this app is 100% vibe coded with the help of Claude Sonnet 4.\n\nTry it out with the site id 'azettl.net' or 'fridgeleftoversai.com'.")
+    
+    with gr.Tab("Basic Stats"):
+        gr.Markdown("### Get basic website statistics")
+        
+        with gr.Row():
+            site_input = gr.Textbox(
+                label="Site ID",
+                placeholder="example.com",
+                info="Your domain as added to Plausible"
+            )
+            date_range = gr.Dropdown(
+                choices=["day", "7d", "28d", "30d", "month", "6mo", "12mo", "year", "all"],
+                value="7d",
+                label="Date Range"
+            )
+        
+        metrics_input = gr.CheckboxGroup(
+            choices=["visitors", "visits", "pageviews", "views_per_visit", "bounce_rate", "visit_duration", "events"],
+            value=["visitors", "pageviews", "bounce_rate"],
+            label="Metrics to Analyze"
+        )
+        
+        basic_btn = gr.Button("Get Basic Stats", variant="primary")
+        
+        with gr.Row():
+            basic_json = gr.Code(label="API Response", language="json")
+            basic_stats = gr.JSON(label="Stats Summary")
+        
+        basic_chart = gr.Plot(label="Statistics Chart")
+        
+        basic_btn.click(
+            basic_stats_query,
+            inputs=[site_input, date_range, metrics_input],
+            outputs=[basic_json, basic_stats, basic_chart]
+        )
+    
+    with gr.Tab("Timeseries"):
+        gr.Markdown("### View trends over time")
+        
+        with gr.Row():
+            ts_site = gr.Textbox(label="Site ID", placeholder="example.com")
+            ts_date_range = gr.Dropdown(
+                choices=["day", "7d", "28d", "30d", "month"],
+                value="7d",
+                label="Date Range"
+            )
+        
+        with gr.Row():
+            ts_metrics = gr.CheckboxGroup(
+                choices=["visitors", "visits", "pageviews", "events"],
+                value=["visitors", "pageviews"],
+                label="Metrics"
+            )
+            ts_time_dim = gr.Dropdown(
+                choices=["time:hour", "time:day", "time:week", "time:month"],
+                value="time:day",
+                label="Time Dimension"
+            )
+        
+        ts_btn = gr.Button("Generate Timeseries", variant="primary")
+        
+        with gr.Row():
+            ts_json = gr.Code(label="API Response", language="json")
+            ts_chart = gr.Plot(label="Timeseries Chart")
+        
+        ts_btn.click(
+            timeseries_query,
+            inputs=[ts_site, ts_date_range, ts_metrics, ts_time_dim],
+            outputs=[ts_json, ts_chart]
+        )
+    
+    with gr.Tab("Geographic Analysis"):
+        gr.Markdown("### Analyze traffic by location")
+        
+        with gr.Row():
+            geo_site = gr.Textbox(label="Site ID", placeholder="example.com")
+            geo_date_range = gr.Dropdown(
+                choices=["day", "7d", "28d", "30d", "month"],
+                value="7d",
+                label="Date Range"
+            )
+        
+        geo_metrics = gr.CheckboxGroup(
+            choices=["visitors", "visits", "pageviews", "bounce_rate"],
+            value=["visitors", "pageviews"],
+            label="Metrics"
+        )
+        
+        geo_btn = gr.Button("Analyze Geography", variant="primary")
+        
+        with gr.Row():
+            geo_json = gr.Code(label="API Response", language="json")
+            geo_chart = gr.Plot(label="Geographic Chart")
+        
+        geo_table = gr.DataFrame(label="Top Locations")
+        
+        geo_btn.click(
+            geographic_analysis,
+            inputs=[geo_site, geo_date_range, geo_metrics],
+            outputs=[geo_json, geo_chart, geo_table]
+        )
+    
+    with gr.Tab("UTM Analysis"):
+        gr.Markdown("### Analyze marketing campaigns and traffic sources")
+        
+        with gr.Row():
+            utm_site = gr.Textbox(label="Site ID", placeholder="example.com")
+            utm_date_range = gr.Dropdown(
+                choices=["day", "7d", "28d", "30d", "month"],
+                value="7d",
+                label="Date Range"
+            )
+        
+        utm_btn = gr.Button("Analyze UTM Parameters", variant="primary")
+        
+        with gr.Row():
+            utm_json = gr.Code(label="API Response", language="json")
+            utm_chart = gr.Plot(label="UTM Sunburst Chart")
+        
+        utm_table = gr.DataFrame(label="UTM Data")
+        
+        utm_btn.click(
+            utm_analysis,
+            inputs=[utm_site, utm_date_range],
+            outputs=[utm_json, utm_chart, utm_table]
+        )
+    
+    with gr.Tab("Custom Query"):
+        gr.Markdown("### Execute custom JSON queries")
+        gr.Markdown("Use this tab to run advanced queries with custom filters and dimensions.")
+        
+        custom_site = gr.Textbox(label="Site ID", placeholder="example.com")
+        
+        custom_query_input = gr.Code(
+            label="JSON Query",
+            language="json",
+            value="""{
+  "metrics": ["visitors", "pageviews"],
+  "date_range": "7d",
+  "dimensions": ["visit:source"],
+  "order_by": [["visitors", "desc"]],
+  "pagination": {"limit": 10}
+}""",
+            lines=15
+        )
+        
+        custom_btn = gr.Button("Execute Query", variant="primary")
+        custom_result = gr.Code(label="Query Result", language="json", lines=20)
+        
+        custom_btn.click(
+            custom_query,
+            inputs=[custom_site, custom_query_input],
+            outputs=[custom_result]
+        )
+    
+    with gr.Tab("Setup & Documentation"):
+        gr.Markdown("""
+        ## 🔧 Setup Instructions
+        
+        ### For Personal Use (Recommended)
+        This MCP server is designed for **personal use only**. Each user should run their own instance.
+        
+        **Setup Steps:**
+        1. **Get your Plausible API key:**
+           - Log into your Plausible account
+           - Go to Account Settings → API Keys
+           - Create a new key, select "Stats API" as type
+        
+        2. **Set environment variable:**
+           ```bash
+           # Windows
+           set PLAUSIBLE_API_KEY=your-key-here
+           
+           # Mac/Linux
+           export PLAUSIBLE_API_KEY=your-key-here
+           
+           # Or create .env file:
+           echo "PLAUSIBLE_API_KEY=your-key-here" > .env
+           ```
+        
+        2. **Install dependencies:**
+           ```bash    
+           pip install -r requirements.txt
+           ```
+
+        3. **Run the server:**
+           ```bash
+           python app.py
+           ```
+        
+        4. **Add to Claude Desktop config:**
+           ```json
+           {
+             "mcpServers": {
+               "plausible": {
+                 "command": "npx",
+                 "args": ["mcp-remote", "http://localhost:7860/gradio_api/mcp/sse"]
+               }
+             }
+           }
+           ```
+        
+        ### ⚠️ Security Notice
+        - **DO NOT** share your API key with others
+        - **DO NOT** run this as a public server with your API key (Like I do here to show you how it works 🙈)
+        - Each user should run their own instance with their own API key
+        
+        ---
+        
+        ## 📖 API Reference
+        
+        **Available Metrics:**
+        - `visitors`: Unique visitors
+        - `visits`: Number of sessions
+        - `pageviews`: Total page views
+        - `views_per_visit`: Average pages per session
+        - `bounce_rate`: Bounce rate percentage
+        - `visit_duration`: Average visit duration
+        - `events`: Total events
+        
+        **Date Ranges:**
+        - `day`: Current day
+        - `7d`: Last 7 days
+        - `28d`: Last 28 days
+        - `30d`: Last 30 days
+        - `month`: Current month
+        - `6mo`: Last 6 months
+        - `12mo`: Last 12 months
+        - `year`: Current year
+        - `all`: All time
+        
+        **Common Dimensions:**
+        - `visit:country_name`: Country
+        - `visit:source`: Traffic source
+        - `visit:device`: Device type
+        - `visit:browser`: Browser
+        - `event:page`: Page path
+        - `time:day`: Daily grouping
+        - `time:hour`: Hourly grouping
+        
+        **Example Filters:**
+        ```json
+        [["is", "visit:country_name", ["United States", "Canada"]]]
+        [["contains", "event:page", ["/blog"]]]
+        [["is_not", "visit:device", ["Mobile"]]]
+        ```
+        """)
+
+# Launch configuration
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        debug=False,
+        mcp_server=True
+    )

requirements.txt

@@ -0,0 +1,5 @@
+gradio[mcp]
+requests
+pandas
+plotly
+python-dotenv