# OpenPanel Plugin Design - Phase H
> **MCP Plugin for OpenPanel Analytics Management (Self-Hosted)**
**Version**: v1.0.0 (Design)
**Priority**: Highest
**Estimated Tools**: 72-78
---
## Why OpenPanel over Plausible?
### Comparison Summary
| Feature | Plausible | OpenPanel | Winner |
|---------|-----------|-----------|--------|
| Web Analytics | Yes | Yes | Tie |
| Product Analytics | No | Yes (Funnels, Cohorts) | OpenPanel |
| User Profiles | No | Yes | OpenPanel |
| A/B Testing | No | Yes | OpenPanel |
| Retention Analysis | No | Yes | OpenPanel |
| Session Recording | No | Yes | OpenPanel |
| Multi-platform | Web only | Web, Mobile, Server | OpenPanel |
| API Completeness | Stats API only | Track + Export + Management | OpenPanel |
| Custom Dashboards | Limited | Full flexibility | OpenPanel |
| Self-Hosted | Yes | Yes | Tie |
| Privacy (GDPR) | Yes | Yes | Tie |
**Decision**: **OpenPanel** - More comprehensive analytics with Product Analytics features that Plausible lacks.
### Key OpenPanel Advantages
1. **Product Analytics** - Funnels, cohorts, user profiles, retention
2. **A/B Testing** - Built-in variant testing
3. **Multi-platform** - Web, iOS, Android, Server-side SDKs
4. **Comprehensive API** - Track, Export, and Management APIs
5. **Custom Dashboards** - Flexible chart creation
6. **Self-Hosted on Coolify** - Full data control
Sources:
- [OpenPanel](https://openpanel.dev/)
- [OpenPanel GitHub](https://github.com/Openpanel-dev/openpanel)
- [Coolify OpenPanel Docs](https://coolify.io/docs/services/openpanel)
---
## Overview
Plugin for managing **OpenPanel Self-Hosted** instances deployed on Coolify.
### Architecture Overview
```
┌─────────────────────────────────────────────────────────────────┐
│ OpenPanel Self-Hosted Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ OpenPanel Stack │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ Next.js Dashboard (:3000) │ │
│ │ └── tRPC API (internal management) │ │
│ │ │ │
│ │ Fastify Event API (:3333) │ │
│ │ └── /track - Event ingestion │ │
│ │ └── /export - Data export │ │
│ │ │ │
│ │ PostgreSQL - Metadata & config │ │
│ │ ClickHouse - Event storage (high-volume) │ │
│ │ Redis - Cache, pub/sub, queues │ │
│ │ BullMQ - Job processing │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## Authentication
### API Authentication
```
┌─────────────────────────────────────────────────────────────────┐
│ OpenPanel Authentication │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Required Headers: │
│ ├── openpanel-client-id: YOUR_CLIENT_ID │
│ └── openpanel-client-secret: YOUR_CLIENT_SECRET │
│ │
│ Client Modes: │
│ ├── write - Can send events (tracking) │
│ ├── read - Can read data (export) │
│ └── root - Full access (management + read + write) │
│ │
│ For Self-Hosted: Create clients via Dashboard or API │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### Environment Variables
```bash
# OpenPanel Self-Hosted Instance (Required)
OPENPANEL_SITE1_URL=https://analytics.example.com
OPENPANEL_SITE1_CLIENT_ID=your-client-id
OPENPANEL_SITE1_CLIENT_SECRET=your-client-secret
OPENPANEL_SITE1_PROJECT_ID=your-project-id # Required for Export/Read APIs
OPENPANEL_SITE1_ALIAS=myanalytics
# Optional: Multiple Instances
OPENPANEL_SITE2_URL=https://analytics-staging.example.com
OPENPANEL_SITE2_CLIENT_ID=client-id-staging
OPENPANEL_SITE2_CLIENT_SECRET=client-secret-staging
OPENPANEL_SITE2_PROJECT_ID=staging-project-id
OPENPANEL_SITE2_ALIAS=staging
```
**Finding Your Project ID:**
1. Log in to your OpenPanel Dashboard
2. Go to Project Settings
3. Copy the Project ID
**Note:**
- `CLIENT_ID` and `CLIENT_SECRET` are used for authentication
- `PROJECT_ID` is required for Export/Read APIs (get_event_count, export_events, etc.)
- Track APIs (identify_user, track_event) work without PROJECT_ID
---
## API Endpoints
### Track API (Fastify - /api)
Primary endpoint for event ingestion:
```
POST /track
Headers:
openpanel-client-id: YOUR_CLIENT_ID
openpanel-client-secret: YOUR_CLIENT_SECRET
x-client-ip: CLIENT_IP (optional, for geo)
user-agent: USER_AGENT (optional, for device info)
```
**Operation Types:**
| Type | Description | Use Case |
|------|-------------|----------|
| `track` | Track custom event | Page view, button click, purchase |
| `identify` | Identify user | Set user profile properties |
| `increment` | Increment property | Visit count, purchase count |
| `decrement` | Decrement property | Credits used, inventory |
| `alias` | Alias profile ID | Link anonymous to authenticated |
### Export API (Fastify - /export)
```
GET /export/events
- Retrieve raw event data
- Filters: projectId, profileId, event, start, end
- Pagination: page, limit
- Includes: profile, meta
GET /export/charts
- Retrieve aggregated chart data
- Events with breakdowns
- Intervals: minute, hour, day, week, month
- Ranges: 30min, today, 7d, 30d, 6m, 12m, etc.
```
### Dashboard tRPC API (Next.js - /api/trpc)
Internal API for dashboard management:
```
Projects:
- project.list, project.get, project.create, project.update, project.delete
Dashboards:
- dashboard.list, dashboard.get, dashboard.create, dashboard.update, dashboard.delete
Charts:
- chart.create, chart.update, chart.delete
Clients:
- client.list, client.create, client.delete, client.regenerate
Funnels:
- funnel.list, funnel.get, funnel.create, funnel.update, funnel.delete
Reports:
- report.overview, report.retention, report.paths
Users/Profiles:
- profile.list, profile.get, profile.events
```
---
## Plugin Architecture
### Project Structure
```
plugins/openpanel/
├── __init__.py # Export: OpenPanelPlugin, OpenPanelClient
├── plugin.py # Main OpenPanelPlugin class
├── client.py # OpenPanelClient (unified client)
└── handlers/
├── __init__.py
├── events.py # Event tracking (10 tools)
├── export.py # Data export (10 tools)
├── projects.py # Project management (8 tools)
├── dashboards.py # Dashboard management (10 tools)
├── funnels.py # Funnel analytics (8 tools)
├── profiles.py # User profiles (8 tools)
├── clients.py # API client management (6 tools)
├── reports.py # Analytics reports (8 tools)
└── system.py # Health & stats (6 tools)
```
### Client Architecture
```python
class OpenPanelClient:
"""
Unified client for OpenPanel Self-Hosted APIs
Handles both Track/Export API (Fastify) and
Dashboard tRPC API (Next.js) where available.
"""
def __init__(
self,
base_url: str, # e.g., https://analytics.example.com
client_id: str, # Client ID for authentication
client_secret: str, # Client Secret for authentication
):
self.base_url = base_url.rstrip('/')
self.api_url = f"{self.base_url}/api"
self.client_id = client_id
self.client_secret = client_secret
def _get_headers(self, include_ip: str = None) -> Dict[str, str]:
"""Get authentication headers"""
headers = {
"Content-Type": "application/json",
"openpanel-client-id": self.client_id,
"openpanel-client-secret": self.client_secret
}
if include_ip:
headers["x-client-ip"] = include_ip
return headers
async def track(
self,
event_type: str,
payload: Dict[str, Any],
client_ip: str = None
) -> Dict[str, Any]:
"""Send tracking request to /track endpoint"""
...
async def export_events(
self,
project_id: str,
**filters
) -> Dict[str, Any]:
"""Export events from /export/events"""
...
```
---
## Tool Categories
### 1. Events Handler (10 tools)
Event tracking and ingestion operations.
| Tool | Type | Scope | Description |
|------|------|-------|-------------|
| `track_event` | track | write | Track custom event with properties |
| `track_page_view` | track | write | Track page view event |
| `track_screen_view` | track | write | Track screen view (mobile) |
| `identify_user` | identify | write | Identify user with profile data |
| `set_user_properties` | identify | write | Update user properties |
| `increment_property` | increment | write | Increment numeric property |
| `decrement_property` | decrement | write | Decrement numeric property |
| `alias_user` | alias | write | Link two profile IDs |
| `track_revenue` | track | write | Track revenue/purchase event |
| `track_batch` | track | write | Track multiple events in batch |
```python
# Example: track_event
{
"name": "track_event",
"method_name": "track_event",
"description": "Track a custom event with properties. Events can have any custom properties.",
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Event name (e.g., 'button_clicked', 'purchase_completed')"
},
"properties": {
"type": "object",
"description": "Custom properties for the event"
},
"profile_id": {
"type": "string",
"description": "User/profile ID to associate with event"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Event timestamp (ISO 8601, defaults to now)"
}
},
"required": ["name"]
},
"scope": "write"
}
```
### 2. Export Handler (10 tools)
Data export and retrieval operations.
| Tool | Type | Scope | Description |
|------|------|-------|-------------|
| `export_events` | GET | read | Export raw event data |
| `export_events_csv` | GET | read | Export events as CSV |
| `export_chart_data` | GET | read | Export aggregated chart data |
| `get_event_count` | GET | read | Get event counts with filters |
| `get_unique_users` | GET | read | Get unique user count |
| `get_page_views` | GET | read | Get page view statistics |
| `get_top_pages` | GET | read | Get top pages by views |
| `get_top_referrers` | GET | read | Get top traffic sources |
| `get_geo_data` | GET | read | Get geographic distribution |
| `get_device_data` | GET | read | Get device/browser breakdown |
```python
# Example: export_events
{
"name": "export_events",
"method_name": "export_events",
"description": "Export raw event data with filters and pagination",
"schema": {
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project ID to export from"
},
"event": {
"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}],
"description": "Event name(s) to filter"
},
"profile_id": {
"type": "string",
"description": "Filter by user/profile ID"
},
"start": {
"type": "string",
"format": "date",
"description": "Start date (YYYY-MM-DD)"
},
"end": {
"type": "string",
"format": "date",
"description": "End date (YYYY-MM-DD)"
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 1000
},
"page": {
"type": "integer",
"default": 1
},
"includes": {
"type": "array",
"items": {"type": "string", "enum": ["profile", "meta"]},
"description": "Additional data to include"
}
},
"required": ["project_id"]
},
"scope": "read"
}
```
### 3. Projects Handler (8 tools)
Project management operations.
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_projects` | GET | read | List all projects |
| `get_project` | GET | read | Get project details |
| `create_project` | POST | admin | Create new project |
| `update_project` | PUT | admin | Update project settings |
| `delete_project` | DELETE | admin | Delete project |
| `get_project_stats` | GET | read | Get project statistics |
| `get_project_settings` | GET | read | Get project configuration |
| `update_project_settings` | PUT | admin | Update project configuration |
### 4. Dashboards Handler (10 tools)
Dashboard and chart management.
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_dashboards` | GET | read | List all dashboards |
| `get_dashboard` | GET | read | Get dashboard with charts |
| `create_dashboard` | POST | write | Create new dashboard |
| `update_dashboard` | PUT | write | Update dashboard |
| `delete_dashboard` | DELETE | write | Delete dashboard |
| `add_chart` | POST | write | Add chart to dashboard |
| `update_chart` | PUT | write | Update chart configuration |
| `delete_chart` | DELETE | write | Remove chart from dashboard |
| `duplicate_dashboard` | POST | write | Clone existing dashboard |
| `share_dashboard` | POST | write | Generate shareable link |
### 5. Funnels Handler (8 tools)
Funnel analysis operations.
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_funnels` | GET | read | List all funnels |
| `get_funnel` | GET | read | Get funnel with conversion data |
| `create_funnel` | POST | write | Create new funnel |
| `update_funnel` | PUT | write | Update funnel steps |
| `delete_funnel` | DELETE | write | Delete funnel |
| `get_funnel_conversion` | GET | read | Get conversion rates |
| `get_funnel_breakdown` | GET | read | Get breakdown by segment |
| `compare_funnels` | GET | read | Compare multiple funnels |
```python
# Example: create_funnel
{
"name": "create_funnel",
"method_name": "create_funnel",
"description": "Create a funnel to track user journey through steps",
"schema": {
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project ID"
},
"name": {
"type": "string",
"description": "Funnel name"
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"event": {"type": "string"},
"filters": {"type": "array"}
},
"required": ["name", "event"]
},
"description": "Funnel steps (events in sequence)",
"minItems": 2
},
"window_days": {
"type": "integer",
"default": 14,
"description": "Conversion window in days"
}
},
"required": ["project_id", "name", "steps"]
},
"scope": "write"
}
```
### 6. Profiles Handler (8 tools)
User profile management.
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_profiles` | GET | read | List user profiles |
| `get_profile` | GET | read | Get profile details |
| `search_profiles` | GET | read | Search profiles by property |
| `get_profile_events` | GET | read | Get events for profile |
| `get_profile_sessions` | GET | read | Get sessions for profile |
| `delete_profile` | DELETE | admin | Delete profile data (GDPR) |
| `merge_profiles` | POST | admin | Merge duplicate profiles |
| `export_profile_data` | GET | read | Export all profile data (GDPR) |
### 7. Clients Handler (6 tools)
API client/key management.
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_clients` | GET | read | List API clients |
| `get_client` | GET | read | Get client details |
| `create_client` | POST | admin | Create new API client |
| `delete_client` | DELETE | admin | Delete API client |
| `regenerate_secret` | POST | admin | Regenerate client secret |
| `update_client_mode` | PUT | admin | Update client permissions |
### 8. Reports Handler (8 tools)
Analytics and reporting.
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `get_overview_report` | GET | read | Get overview statistics |
| `get_retention_report` | GET | read | Get retention analysis |
| `get_cohort_report` | GET | read | Get cohort analysis |
| `get_paths_report` | GET | read | Get user flow paths |
| `get_realtime_stats` | GET | read | Get real-time visitors |
| `get_ab_test_results` | GET | read | Get A/B test results |
| `create_report` | POST | write | Create scheduled report |
| `export_report` | GET | read | Export report as PDF/CSV |
### 9. System Handler (6 tools)
System health and management.
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `health_check` | GET | read | Check service health |
| `get_instance_info` | GET | read | Get instance information |
| `get_usage_stats` | GET | read | Get usage statistics |
| `get_storage_stats` | GET | read | Get storage usage (ClickHouse) |
| `test_connection` | GET | read | Test API connection |
| `get_rate_limit_status` | GET | read | Check rate limit status |
---
## Tool Summary
| Handler | Tools | Description |
|---------|-------|-------------|
| Events | 10 | Event tracking & ingestion |
| Export | 10 | Data export & retrieval |
| Projects | 8 | Project management |
| Dashboards | 10 | Dashboard & chart management |
| Funnels | 8 | Funnel analysis |
| Profiles | 8 | User profile management |
| Clients | 6 | API client management |
| Reports | 8 | Analytics & reporting |
| System | 6 | Health & instance info |
| **Total** | **74** | |
---
## Implementation Phases
### Phase H.1: Core (Required)
**Goal**: Basic event tracking and data export
1. **OpenPanelPlugin** class
2. **OpenPanelClient** (unified)
3. **Events Handler** (10 tools)
4. **Export Handler** (10 tools)
5. **System Handler** (6 tools)
**Tools**: 26
### Phase H.2: Analytics (Recommended)
**Goal**: Advanced analytics features
1. **Reports Handler** (8 tools)
2. **Funnels Handler** (8 tools)
3. **Profiles Handler** (8 tools)
**Tools**: 24 (Total: 50)
### Phase H.3: Management (Complete)
**Goal**: Full dashboard and project management
1. **Projects Handler** (8 tools)
2. **Dashboards Handler** (10 tools)
3. **Clients Handler** (6 tools)
**Tools**: 24 (Total: 74)
---
## Export API Reference
### Event Segmentation Types
| Segment | Description |
|---------|-------------|
| `event` | Count total events |
| `user` | Count unique users |
| `session` | Count unique sessions |
| `user_average` | Average per user |
| `one_event_per_user` | First event per user |
| `property_sum` | Sum of property values |
| `property_average` | Average of property values |
| `property_min` | Minimum property value |
| `property_max` | Maximum property value |
### Filter Operators
| Operator | Description |
|----------|-------------|
| `is` | Exact match |
| `isNot` | Not equal |
| `contains` | Contains substring |
| `doesNotContain` | Does not contain |
| `startsWith` | Starts with |
| `endsWith` | Ends with |
| `regex` | Regular expression |
| `isNull` | Is null/undefined |
| `isNotNull` | Is not null |
### Breakdown Dimensions
| Dimension | Description |
|-----------|-------------|
| `country` | Country |
| `region` | Region/State |
| `city` | City |
| `device` | Device type |
| `browser` | Browser name |
| `os` | Operating system |
| `referrer` | Traffic source |
| `path` | Page path |
### Date Ranges
```
30min, lastHour, today, yesterday
7d, 30d, 6m, 12m
monthToDate, lastMonth
yearToDate, lastYear
```
---
## Error Handling
### HTTP Status Codes
| Code | Description | Action |
|------|-------------|--------|
| 200 | Success | Return data |
| 400 | Bad Request | Validate input |
| 401 | Unauthorized | Check credentials |
| 403 | Forbidden | Check client mode |
| 404 | Not Found | Resource doesn't exist |
| 429 | Rate Limited | Implement backoff |
| 500 | Server Error | Retry with backoff |
### Rate Limiting
```
Limit: 100 requests per 10 seconds per client
Backoff: Exponential (1s, 2s, 4s, 8s...)
Headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699999999
```
---
## Security Considerations
### Client Secret Protection
```
┌─────────────────────────────────────────────────────────────────┐
│ Client Security │
├─────────────────────────────────────────────────────────────────┤
│ │
│ write mode client: │
│ ├── Can send events only │
│ ├── Cannot read data │
│ └── Safe for client-side (with domain restrictions) │
│ │
│ read mode client: │
│ ├── Can export data │
│ ├── Cannot send events │
│ └── Server-side only │
│ │
│ root mode client: │
│ ├── Full access │
│ ├── Can manage projects, clients │
│ └── ⚠️ Server-side only - Never expose! │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### Best Practices
1. **Use appropriate client mode** - write for tracking, read for export
2. **Never expose root clients** - Server-side only
3. **Implement rate limiting** - Respect API limits
4. **GDPR compliance** - Use profile deletion tools
5. **Audit data exports** - Log who exports what
---
## Example Usage
### Track Event
```json
{
"tool": "track_event",
"args": {
"site": "myanalytics",
"name": "purchase_completed",
"properties": {
"product_id": "prod_123",
"amount": 99.99,
"currency": "USD",
"category": "electronics"
},
"profile_id": "user_456"
}
}
```
### Identify User
```json
{
"tool": "identify_user",
"args": {
"site": "myanalytics",
"profile_id": "user_456",
"properties": {
"firstName": "John",
"lastName": "Doe",
"email": "john@example.com",
"plan": "premium",
"company": "Acme Inc"
}
}
}
```
### Export Events
```json
{
"tool": "export_events",
"args": {
"site": "myanalytics",
"project_id": "proj_abc",
"event": "purchase_completed",
"start": "2025-11-01",
"end": "2025-11-30",
"limit": 100,
"includes": ["profile"]
}
}
```
### Create Funnel
```json
{
"tool": "create_funnel",
"args": {
"site": "myanalytics",
"project_id": "proj_abc",
"name": "Checkout Flow",
"steps": [
{"name": "View Product", "event": "product_viewed"},
{"name": "Add to Cart", "event": "cart_added"},
{"name": "Start Checkout", "event": "checkout_started"},
{"name": "Complete Purchase", "event": "purchase_completed"}
],
"window_days": 7
}
}
```
### Get Retention Report
```json
{
"tool": "get_retention_report",
"args": {
"site": "myanalytics",
"project_id": "proj_abc",
"start_event": "signup_completed",
"return_event": "app_opened",
"period": "week",
"cohorts": 12
}
}
```
---
## Coolify Deployment Notes
### OpenPanel Services
```yaml
# OpenPanel services in Coolify
services:
dashboard: # Next.js - port 3000
api: # Fastify Event API - port 3333
worker: # BullMQ worker
postgres: # PostgreSQL - metadata
clickhouse: # ClickHouse - events
redis: # Redis - cache/queue
```
### Environment Variables (Coolify)
```bash
# Required
NEXT_PUBLIC_DASHBOARD_URL=https://analytics.example.com
DATABASE_URL=postgresql://...
CLICKHOUSE_URL=http://clickhouse:8123
REDIS_URL=redis://redis:6379
# Optional
RESEND_API_KEY=re_...
OPENAI_API_KEY=sk-... # For AI features
ANTHROPIC_API_KEY=sk-...
```
### Finding Credentials
1. **URL**: Coolify Dashboard → Project → OpenPanel → Domain
2. **Client ID/Secret**: OpenPanel Dashboard → Settings → Clients
---
## Endpoint Registration
### Endpoint Config
```python
# core/endpoints/config.py
EndpointType.OPENPANEL: EndpointConfig(
path="/openpanel",
name="OpenPanel Analytics",
description="OpenPanel product analytics management (events, funnels, dashboards)",
endpoint_type=EndpointType.OPENPANEL,
plugin_types=["openpanel"],
require_master_key=False,
allowed_scopes={"read", "write", "admin"},
tool_blacklist={
"manage_api_keys_create",
"manage_api_keys_delete",
"oauth_register_client",
"oauth_revoke_client",
},
max_tools=80,
),
```
---
## Testing Checklist
### Unit Tests
- [ ] OpenPanelClient authentication
- [ ] Track API operations (track, identify, increment)
- [ ] Export API operations (events, charts)
- [ ] Error handling for all endpoints
- [ ] Rate limiting behavior
### Integration Tests
- [ ] Track event and verify in export
- [ ] Create funnel and get conversion data
- [ ] Create dashboard with charts
- [ ] Profile identification and merging
- [ ] GDPR data export and deletion
---
## Comparison with Other Plugins
| Aspect | Supabase | n8n | OpenPanel |
|--------|----------|-----|-----------|
| Primary Focus | Database/Backend | Automation | Analytics |
| Auth Method | JWT Keys | API Key | Client ID/Secret |
| Main APIs | PostgREST, GoTrue | REST API | Track, Export |
| Tools | 70 | 56 | 74 |
| Phases | 3 | 1 | 3 |
---
## References
- [OpenPanel Documentation](https://openpanel.dev/docs)
- [OpenPanel GitHub](https://github.com/Openpanel-dev/openpanel)
- [Track API Reference](https://openpanel.dev/docs/api/track)
- [Export API Reference](https://openpanel.dev/docs/api/export)
- [Coolify OpenPanel](https://coolify.io/docs/services/openpanel)
---
**Created**: 2025-11-30
**Author**: Claude AI Assistant
**Status**: Design Phase
