@hangarx/helix-mcp/README.md

Model Context Protocol server providing comprehensive analytics and business intelligence tools for the Helix SDK

# Helix MCP Server

A Model Context Protocol (MCP) server providing comprehensive analytics and business intelligence tools for the Helix SDK.

## Features

- **35+ Analytics Tools** - Complete business intelligence suite
- **Real-time Insights** - Live metrics and performance indicators
- **AI-Powered Recommendations** - Actionable growth strategies
- **Multi-Transport Support** - STDIO, SSE, and HTTP-Stream
- **MCP Inspector v0.16.7 Compatible** - Full debugging and testing support

## Installation

### NPM Package
```bash
npm install @helix/mcp-server
```

### From Source
```bash
git clone https://github.com/3-Elements-Design/helix-analytics-sdk.git
cd helix-analytics-sdk/mcp-server
npm install
npm run build
```

## Quick Start

### 1. Environment Setup
Create a `.env` file:
```bash
HELIX_API_URL=https://helix-sdk-ha4shte2cq-uc.a.run.app
HELIX_API_KEY=your_api_key_here
HELIX_COMPANY_ID=your_company_id_here
MCP_TRANSPORT=stdio
PORT=3001
```

### 2. Start Server
```bash
# STDIO Transport (recommended for MCP Inspector)
npm run start

# Or with specific transport
MCP_TRANSPORT=sse npm run start
MCP_TRANSPORT=http-stream npm run start
```

### 3. Use with MCP Inspector
```bash
# Launch Inspector
npm run inspect

# Or manually
npx @modelcontextprotocol/inspector@0.16.7 node dist/index.js
```

## Available Tools

### 🧠 Enhanced Analytics (NEW)
- **`get_engagement_metrics`** - User engagement dashboard with DAU/WAU/MAU
- **`get_top_events`** - Most popular events with frequency analysis
- **`get_traffic_sources`** - UTM attribution and marketing performance
- **`get_growth_metrics`** - Growth rate analysis with trends
- **`get_enhanced_funnel`** - Conversion funnel with drop-off analysis
- **`get_user_flows`** - User journey mapping and optimization
- **`detect_anomalies`** - Statistical anomaly detection
- **`get_revenue_attribution`** - Revenue attribution by channel
- **`get_user_segments`** - Behavioral segmentation
- **`get_realtime_dashboard`** - Live metrics dashboard

### 📊 Standard Analytics
- **`get_analytics`** - Comprehensive analytics data
- **`get_analytics_metrics`** - Company performance metrics
- **`get_ttv_analysis`** - Time to Value analysis
- **`get_analytics_events`** - Raw event data with pagination
- **`get_advanced_analytics`** - Advanced analytics suite
- **`get_funnel_analysis`** - Funnel analysis
- **`get_cohort_analysis`** - Cohort retention analysis
- **`get_ttv_deterministic`** - Deterministic TTV analysis

### 🎯 Growth & Recommendations
- **`get_recommendations`** - AI-generated growth recommendations
- **`generate_recommendations`** - Create new recommendations
- **`search_recommendations`** - Search existing recommendations

### 🔍 Search & Memory
- **`global_search`** - Vector search across all data
- **`search_analytics`** - Search analytics events
- **`search_conversations`** - Search conversation history
- **`search_memory`** - Search vector memory store
- **`get_memory_context`** - Enhanced conversation context
- **`store_conversation_memory`** - Store conversation insights

### 🏢 Data Management
- **`get_data_sources`** - List connected data sources
- **`add_data_source`** - Connect new data source
- **`test_data_source`** - Test data source connection
- **`trigger_data_sync`** - Manual data synchronization
- **`get_companies`** - List available companies

### ⚙️ System & Performance
- **`get_system_health`** - System health status
- **`initialize_client_context`** - Client context optimization
- **`get_agent_performance_metrics`** - Performance metrics
- **`generate_optimized_system_message`** - Enhanced system messages
- **`clear_performance_cache`** - Cache management

### 🌤️ Weather Services
- **`get_current_weather`** - Current weather data
- **`get_weather_forecast`** - Weather forecast

## Usage Examples

### User Engagement Analysis
```javascript
{
  "tool": "get_engagement_metrics",
  "arguments": {
    "companyId": "34e7e6cc-64d9-4710-b418-ef6208eae9d2",
    "days": 30
  }
}
```

### Growth Rate Analysis
```javascript
{
  "tool": "get_growth_metrics",
  "arguments": {
    "companyId": "34e7e6cc-64d9-4710-b418-ef6208eae9d2"
  }
}
```

### Conversion Funnel Analysis
```javascript
{
  "tool": "get_enhanced_funnel",
  "arguments": {
    "companyId": "34e7e6cc-64d9-4710-b418-ef6208eae9d2",
    "events": "page_view,signup_start,signup_complete,purchase",
    "days": 30
  }
}
```

## Configuration

### Environment Variables
- **`HELIX_API_URL`** - Helix API endpoint URL
- **`HELIX_API_KEY`** - API authentication key
- **`HELIX_COMPANY_ID`** - Default company ID (optional)
- **`MCP_TRANSPORT`** - Transport type (stdio|sse|http-stream)
- **`PORT`** - Server port for HTTP transports
- **`WEATHER_API_KEY`** - OpenWeather API key (optional)

### Transport Types
- **STDIO** - Direct process communication (best for Inspector)
- **SSE** - Server-Sent Events for web applications
- **HTTP-Stream** - RESTful API for maximum compatibility

## Development

### Scripts
```bash
npm run build      # Build TypeScript
npm run dev        # Development with watch
npm run start      # Start server
npm run inspect    # Launch MCP Inspector
npm test          # Run tests
```

### Adding Custom Tools
1. Add tool definition in `setupToolHandlers()`
2. Implement method in `HelixMCPServer` class
3. Add to switch statement in tool call handler
4. Test with Inspector

## Business Intelligence

### For Startups
- **Growth Metrics** - Essential DAU/MAU and growth rates
- **Resource Optimization** - Focus on highest-impact channels
- **Product Intelligence** - User behavior insights
- **Investor Readiness** - Comprehensive metrics for fundraising

### For Enterprises
- **Advanced Attribution** - Multi-touch revenue attribution
- **Customer Intelligence** - Behavioral segmentation
- **Operational Excellence** - Real-time monitoring
- **Competitive Advantage** - Advanced analytics capabilities

## Support

- **Documentation**: [MCP Inspector Guide](./MCP_INSPECTOR_GUIDE.md)
- **Issues**: [GitHub Issues](https://github.com/3-Elements-Design/helix-analytics-sdk/issues)
- **Repository**: [GitHub](https://github.com/3-Elements-Design/helix-analytics-sdk)

## License

MIT License - see [LICENSE](../LICENSE) for details.

---

**Transform your analytics data into actionable business intelligence with the Helix MCP Server.**