Merge pull request #25 from Countly/ar2rsawseen/main

Home page and analytics

Author: ar2rsawseen

.env.example

@@ -38,6 +38,13 @@ COUNTLY_SERVER_URL=https://api.count.ly
 # Default: 30000 (30 seconds)
 COUNTLY_TIMEOUT=30000
 
+# Analytics Tracking (optional)
+# Enable anonymous usage analytics to help improve the MCP server
+# All data is aggregated under device ID "mcp" - completely anonymous
+# NO authentication tokens, server URLs, or personal data is collected
+# Default: false (disabled)
+# ENABLE_ANALYTICS=true
+
 
 # ==============================================================================
 # AUTHENTICATION PRIORITY

.env.tools.example

@@ -25,39 +25,39 @@
 # These are read-only tools, typically should not be disabled
 # COUNTLY_TOOLS_CORE=R
 
-# Apps Management (list_apps, get_app_by_name, create_app, update_app, delete_app, reset_app)
+# Apps Management (apps_list, apps_get_by_name, apps_create, apps_update, apps_delete, apps_reset)
 # Example: Allow read and create, but not update or delete
 # COUNTLY_TOOLS_APPS=CR
 
-# Analytics & Dashboards (get_analytics_data, get_dashboard_data, get_events_data, get_slipping_away_users, etc.)
+# Analytics & Dashboards (get_analytics_data, dashboards_data, get_events_data, slipping_users, etc.)
 # Typically read-only
 # COUNTLY_TOOLS_ANALYTICS=R
 
-# Crash Analytics (list_crash_groups, view_crash, add/edit/delete comments, resolve, etc.)
+# Crash Analytics (crash_groups_list, crashes_get, add/edit/delete comments, resolve, etc.)
 # Example: Allow read and comment creation, but not editing or deleting
 # COUNTLY_TOOLS_CRASHES=CR
 
-# Notes Management (list_notes, create_note, delete_note)
+# Notes Management (notes_list, notes_create, notes_delete)
 # COUNTLY_TOOLS_NOTES=CRD
 
-# Events Configuration (create_event)
+# Events Configuration (events_create)
 # COUNTLY_TOOLS_EVENTS=C
 
-# Alerts Management (list_alerts, create_alert, delete_alert)
+# Alerts Management (alerts_list, alerts_create, alerts_delete)
 # COUNTLY_TOOLS_ALERTS=CRD
 
-# Views Analytics (get_views_table, get_view_segments, get_views_data)
+# Views Analytics (views_table, views_segments, views_data)
 # COUNTLY_TOOLS_VIEWS=R
 
-# Database Operations (query_database, list_databases, get_document, etc.)
+# Database Operations (databases_query, databases_list, databases_document, etc.)
 # Example: Read-only database access
 # COUNTLY_TOOLS_DATABASE=R
 
-# Dashboard User Management (get_all_dashboard_users)
+# Dashboard User Management (dashboard_users)
 # Returns dashboard/admin users who access the Countly dashboard
 # COUNTLY_TOOLS_DASHBOARD_USERS=R
 
-# App User Management (create_app_user, delete_app_user, export_app_users)
+# App User Management (apps_create_user, apps_delete_user, export_app_users)
 # Manages end-users of applications being tracked by Countly
 # COUNTLY_TOOLS_APP_USERS=CRD
 

.gitignore

@@ -1,6 +1,7 @@
 node_modules/
 build/
 dist/
+coverage/
 *.log
 .env
 .env.local

.well-known/mcp-manifest.json

@@ -0,0 +1,85 @@
+{
+    "name": "countly-mcp-server",
+    "version": "1.0.1",
+    "description": "Model Context Protocol server for Countly Analytics Platform",
+    "protocol": {
+        "version": "2025-06-18",
+        "name": "Model Context Protocol"
+    },
+    "endpoints": {
+        "mcp": "/mcp",
+        "health": "/health"
+    },
+    "transports": [
+        "stdio",
+        "http-sse"
+    ],
+    "capabilities": {
+        "tools": {
+            "count": 134,
+            "categories": 30,
+            "listChanged": true
+        },
+        "resources": {
+            "supported": true,
+            "subscribe": false,
+            "listChanged": false,
+            "types": [
+                "app-config",
+                "event-schemas",
+                "analytics-overview"
+            ],
+            "uri_scheme": "countly://"
+        },
+        "prompts": {
+            "supported": true,
+            "count": 8,
+            "listChanged": false,
+            "templates": [
+                "analyze_crash_trends",
+                "generate_engagement_report",
+                "compare_app_versions",
+                "user_retention_analysis",
+                "funnel_optimization",
+                "event_health_check",
+                "identify_churn_risk",
+                "performance_dashboard"
+            ]
+        },
+        "features": [
+            "analytics",
+            "crash-analytics",
+            "app-management",
+            "user-management",
+            "events",
+            "views",
+            "dashboards",
+            "alerts",
+            "hooks",
+            "database-operations",
+            "resources",
+            "prompts"
+        ]
+    },
+    "authentication": {
+        "methods": [
+            "environment-variables",
+            "http-headers",
+            "url-parameters",
+            "token-file"
+        ],
+        "required": true
+    },
+    "documentation": {
+        "readme": "https://github.com/countly/countly-mcp-server/blob/main/README.md",
+        "tools": "https://github.com/countly/countly-mcp-server/blob/main/TOOLS_CONFIGURATION.md",
+        "contributing": "https://github.com/countly/countly-mcp-server/blob/main/CONTRIBUTING.md"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/countly/countly-mcp-server"
+    },
+    "license": "MIT",
+    "vendor": "Countly",
+    "homepage": "https://count.ly"
+}

CHANGELOG.md

@@ -5,6 +5,192 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2025-11-12
+
+### Added
+- **MCP Resources Support**: Implemented full resources capability for providing read-only context to AI assistants
+  - `resources/list`: List all available resources across applications
+  - `resources/read`: Read specific resource content by URI
+  - Resource types: app configuration (`countly://app/{id}/config`), event schemas (`countly://app/{id}/events`), analytics overview (`countly://app/{id}/overview`)
+  - Resources provide AI context without requiring tool calls, improving efficiency
+
+- **MCP Prompts Support**: Implemented full prompts capability with 8 pre-built analysis templates
+  - `prompts/list`: List all available prompt templates
+  - `prompts/get`: Get specific prompt with arguments
+  - Prompt templates:
+    * `analyze_crash_trends`: Analyze crash and error patterns over time
+    * `generate_engagement_report`: Comprehensive user engagement analysis
+    * `compare_app_versions`: Compare performance metrics between versions
+    * `user_retention_analysis`: Analyze retention patterns and cohort behavior
+    * `funnel_optimization`: Conversion funnel analysis with optimization suggestions
+    * `event_health_check`: Event tracking implementation quality check
+    * `identify_churn_risk`: Find users showing signs of decreased engagement
+    * `performance_dashboard`: Comprehensive application performance overview
+  - Prompts can be exposed as slash commands in MCP clients for guided workflows
+
+- **Hooks Module** (6 tools): Webhook and automation management based on `hooks` plugin
+  - `hooks_list`: List all webhooks/hooks configured for an app
+  - `hooks_test`: Test hook configuration with mock data before creating
+  - `hooks_create`: Create webhooks with multiple trigger types (IncomingDataTrigger, APIEndPointTrigger, InternalEventTrigger, ScheduledTrigger) and effects (HTTPEffect, EmailEffect, CustomCodeEffect)
+  - `hooks_update`: Update existing webhook configurations
+  - `hooks_delete`: Delete webhooks by ID
+  - `hooks_internal_triggers_get`: Get list of 23 available internal Countly events for triggers
+
+- **Times of Day Module** (1 tool): User behavior pattern analysis based on `times-of-day` plugin
+  - `times_of_day`: Analyze when users are most active throughout the day/week in their local time
+
+- **Dashboards Module** (8 tools): Custom dashboard management based on `dashboards` plugin
+  - `dashboards_list`: List all available dashboards
+  - `dashboards_data`: Get widgets and data for specific dashboard
+  - `dashboards_create`: Create dashboards with sharing, auto-refresh, and themes
+  - `dashboards_update`: Update dashboard configuration
+  - `dashboards_delete`: Delete dashboards
+  - `dashboards_widget_add`: Add widgets with full configuration
+  - `dashboards_update_widget`: Update widget position/size in grid layout
+  - `dashboards_widget_remove`: Remove widgets from dashboard
+
+- **Email Reports Module** (7 tools): Periodic email report management based on `reports` plugin
+  - `email_reports_list`: List all configured email reports
+  - `email_reports_core_create`: Create reports with analytics, events, crashes, and star-rating metrics
+  - `email_reports_dashboard_create`: Create reports for specific dashboards
+  - `email_reports_update`: Update report configuration
+  - `email_reports_preview`: Preview reports before sending
+  - `email_reports_send`: Manually trigger report sending
+  - `email_reports_delete`: Delete report configurations
+
+- **Server Logs Module** (2 tools): Server log file access based on `errorlogs` plugin
+  - `server_logs_files_list`: List available log files (api, dashboard, jobs)
+  - `server_logs_contents`: View log file contents (non-Docker deployments only)
+
+- **Datapoint Module** (3 tools): Data point monitoring for billing/capacity planning based on `server-stats` plugin
+  - `datapoints_stats`: Get overall data point collection statistics
+  - `get_top_apps_by_datapoints`: Rank apps by data point usage
+  - `datapoints_punch_card`: Hourly load pattern visualization
+
+- **Filtering Rules Module** (4 tools): Request blocking management based on `blocks` plugin
+  - `filtering_rules_list`: List all configured blocking rules
+  - `filtering_rules_create`: Create rules to block requests by IP, version, or properties
+  - `filtering_rules_update`: Update existing blocking rules
+  - `filtering_rules_delete`: Delete blocking rules
+
+- **Compliance Hub Module** (4 tools): Data consent and privacy management based on `compliance-hub` plugin
+  - `list_consents`: List all consent features configured for an app
+  - `get_consent_history`: Get change history for a specific consent feature
+  - `export_user_data`: Request data export for a specific user
+  - `anonymize_user`: Anonymize user data while preserving analytics
+
+- **SDKs Module** (2 tools): SDK version monitoring based on `sdks` plugin
+  - `get_sdks_list`: List SDK versions used by apps
+  - `get_sdks_stats`: Get detailed SDK usage statistics
+
+- **Logger Module** (1 tool): System log viewing based on `logger` plugin
+  - `get_logger_data`: Retrieve and filter system logs
+
+- **AB Testing Module** (8 tools): A/B test experiment management based on `ab-testing` plugin
+  - `list_experiments`: List all A/B testing experiments
+  - `get_experiment`: Get detailed experiment information
+  - `create_experiment`: Create new experiments with control/variant groups
+  - `update_experiment`: Update experiment configuration
+  - `start_experiment`: Start running an experiment
+  - `stop_experiment`: Stop a running experiment
+  - `finish_experiment`: Mark experiment as finished
+  - `delete_experiment`: Delete experiments
+
+- **Remote Config Module** (8 tools): Remote configuration management based on `remote-config` plugin
+  - `list_remote_config_parameters`: List all parameters
+  - `get_remote_config_parameter`: Get specific parameter details
+  - `create_remote_config_parameter`: Create new parameters
+  - `remote_config_parameters_update`: Update parameters
+  - `remote_config_parameters_delete`: Delete parameters
+  - `list_remote_config_conditions`: List targeting conditions
+  - `create_remote_config_condition`: Create targeting conditions
+  - `remote_config_conditions_delete`: Delete conditions
+
+- **Retention Module** (1 tool): User retention analysis based on `retention_segments` plugin
+  - `retention_data`: Analyze user retention cohorts over time
+
+- **Live Users Module** (6 tools): Real-time concurrent user monitoring based on `concurrent_users` plugin
+  - `live_users`: Get current concurrent users
+  - `get_live_user_details`: Get detailed information about live users
+  - `get_live_cities`: See cities with active users
+  - `get_live_countries`: See countries with active users
+  - `get_live_durations`: Analyze session durations of live users
+  - `get_live_sources`: See traffic sources of live users
+
+- **Formulas Module** (6 tools): Custom metric formula management based on `formulas` plugin
+  - `formulas_list`: List all configured formulas
+  - `get_formula`: Get specific formula details
+  - `create_formula`: Create custom metric formulas
+  - `update_formula`: Update formula configuration
+  - `formulas_delete`: Delete formulas
+  - `get_formula_data`: Get calculated formula data
+
+- **Funnels Module** (7 tools): Conversion funnel analysis based on `funnels` plugin
+  - `funnels_list`: List all configured funnels
+  - `funnels_data`: Get funnel conversion data
+  - `funnels_step_users`: Get users who reached a specific step
+  - `funnels_dropoff_users`: Get users who dropped off between steps
+  - `funnels_create`: Create conversion funnels with multiple steps
+  - `funnels_update`: Update funnel configuration
+  - `funnels_delete`: Delete funnels
+
+- **Cohorts Module** (8 tools): User cohort management based on `cohorts` plugin
+  - `cohorts_list`: List all cohorts
+  - `cohorts_data`: Get cohort data over a period
+  - `cohorts_create`: Create user cohorts with conditions
+  - `cohorts_update`: Update cohort configuration
+  - `cohorts_delete`: Delete cohorts
+  - `cohorts_details_users`: Get users in a cohort
+  - `recalculate_cohort`: Trigger cohort recalculation
+  - `cohorts_details_user_count`: Get current user count
+
+- **User Profiles Module** (4 tools): App user profile management based on `users` plugin
+  - `search_user_profiles`: Search users with filters and sorting
+  - `get_user_profile`: Get detailed user profile
+  - `export_user_profiles`: Export user data to CSV
+  - `get_user_profile_schema`: Get available user properties
+
+- **Drill Module** (5 tools): Advanced query and segmentation based on `drill` plugin
+  - `drill_query`: Execute custom drill queries
+  - `get_drill_meta`: Get available drill properties
+  - `get_drill_bookmarks`: List saved drill queries
+  - `drill_bookmarks_create`: Save drill queries
+  - `drill_bookmarks_delete`: Delete saved queries
+
+- **Core Module Enhancements** (2 additional tools):
+  - `jobs_list`: List background jobs with pagination and sorting
+  - `job_runs`: Get execution history for specific jobs
+
+- **Analytics Module Enhancements** (4 additional tools):
+  - `user_loyalty`: Analyze user loyalty and session count distribution
+  - `session_durations`: Analyze session duration patterns
+  - `session_frequency`: Analyze time between user sessions
+  - `slipping_users`: Identify users becoming inactive
+
+### Changed
+- **Tool Count**: Expanded from 27 tools to 132 tools across 30 categories
+- **Plugin Coverage**: Added support for 21 additional Countly plugins
+- **Plugin Availability**: Automatically check plugin availability for specific tools, ensuring only compatible tools are exposed based on server configuration
+- **URL Parameter Authentication**: Added support for passing Server URL and auth token as URL parameters for flexible authentication
+- **Analytics Tracking**: Added comprehensive anonymous usage analytics with opt-out capability
+- **Error Handling**: Improved API error messages and formatting throughout all modules
+- **Testing**: Expanded test suite with 223 tests including analytics, transport, and tool configuration tests
+- **Documentation**: Updated README with all new modules and tool descriptions
+- **Configuration**: Added plugin-based tool filtering and availability checks
+- **Home Page**: Added informational home page with basic project information and links
+- **Server Discovery**: Added `.well-known/mcp-manifest.json` endpoint for automated server discovery and capability detection
+
+### Fixed
+- **Security Updates**: Updated SECURITY.md with vulnerability levels and reward structure
+- **URL Handling**: Improved URL parameter support for server URL and auth token
+
+### Testing
+- Added 748 new analytics tests covering tracking, sessions, events, and error handling
+- Added 141 core tools tests for new job management features
+- Added 399 error handler tests for improved error scenarios
+- Added comprehensive transport integration tests for stdio and HTTP/SSE modes
+- Updated tool configuration tests to cover all 30 categories and 132 tools
+
 ## [1.0.1] - 2025-11-07
 
 ### Added

CONTRIBUTING.md

@@ -161,10 +161,10 @@ export const userManagementToolDefinitions = [
 // 4. Add to handlers map
 export const userManagementToolHandlers = {
   'get_all_users': 'getAllUsers',
-  'create_app_user': 'createAppUser',
-  'delete_app_user': 'deleteAppUser',
+  'apps_create_user': 'createAppUser',
+  'apps_delete_user': 'deleteAppUser',
   'export_app_users': 'exportAppUsers',
-  'get_slipping_away_users': 'getSlippingAwayUsers',
+  'slipping_users': 'getSlippingAwayUsers',
   'get_active_users': 'getActiveUsers', // Add here
 } as const;
 
@@ -187,10 +187,10 @@ That's it! The tool is now automatically discovered and routed by the main serve
 **CRITICAL**: When adding a new tool, you **MUST** update the CRUD permissions configuration in `src/lib/tools-config.ts`. This allows administrators to control access to your tool through environment variables.
 
 Each tool must be classified with one of these CRUD operations:
-- **C (Create)** - Tools that create new resources (e.g., `create_app`, `create_note`, `add_crash_comment`)
-- **R (Read)** - Tools that read/retrieve data (e.g., `list_apps`, `get_dashboard_data`, `view_crash`)
-- **U (Update)** - Tools that modify existing resources (e.g., `update_app`, `edit_crash_comment`, `resolve_crash`)
-- **D (Delete)** - Tools that delete resources (e.g., `delete_app`, `delete_note`, `reset_app`)
+- **C (Create)** - Tools that create new resources (e.g., `apps_create`, `notes_create`, `crashes_comment_add`)
+- **R (Read)** - Tools that read/retrieve data (e.g., `apps_list`, `dashboards_data`, `crashes_get`)
+- **U (Update)** - Tools that modify existing resources (e.g., `apps_update`, `crashes_comment_update`, `crashes_resolve`)
+- **D (Delete)** - Tools that delete resources (e.g., `apps_delete`, `notes_delete`, `apps_reset`)
 
 **Example: Adding the `get_active_users` tool**
 
@@ -202,10 +202,10 @@ export const TOOL_CATEGORIES: Record<string, { operations: Record<string, CrudOp
 
   users: {
     operations: {
-      'create_app_user': 'C',
-      'delete_app_user': 'D',
+      'apps_create_user': 'C',
+      'apps_delete_user': 'D',
       'export_app_users': 'R',
-      'get_slipping_away_users': 'R',
+      'slipping_users': 'R',
       'get_all_users': 'R',
       'get_active_users': 'R',  // ADD YOUR TOOL HERE with appropriate CRUD operation
     }