# OneSignal MCP Server Refactoring Summary
## Overview
This document summarizes the analysis of the OneSignal MCP server implementation against the official OneSignal REST API documentation and provides a comprehensive refactoring plan.
## 1. Missing API Endpoints Analysis
### High Priority Missing Endpoints
#### Messaging
- **Email-specific endpoint** - Send emails with HTML content and templates
- **SMS-specific endpoint** - Send SMS/MMS messages
- **Transactional Messages** - Immediate delivery messages without scheduling
#### Live Activities (iOS)
- **Start Live Activity** - Initialize iOS Live Activities
- **Update Live Activity** - Update running Live Activities
- **End Live Activity** - Terminate Live Activities
#### Template Management
- **Update Template** - Modify existing templates
- **Delete Template** - Remove templates
- **Copy Template** - Duplicate templates across apps
#### API Key Management
- **Delete API Key** - Remove API keys
- **Update API Key** - Modify API key permissions
- **Rotate API Key** - Generate new key while maintaining permissions
#### Analytics & Export
- **View Outcomes** - Track conversion metrics
- **Export Subscriptions CSV** - Export user data
- **Export Audience Activity CSV** - Export event data
#### Player/Device Management (Legacy)
- **Add Player** - Register new devices
- **Edit Player** - Update device information
- **Edit Tags with External User ID** - Bulk tag updates
- **Delete Player Record** - Remove device records
## 2. Refactored Architecture
### New Module Structure
```
onesignal_refactored/
├── __init__.py
├── config.py # App configuration management
├── api_client.py # API request handling
├── tools/
│ ├── __init__.py
│ ├── messages.py # All messaging endpoints
│ ├── templates.py # Template management
│ ├── live_activities.py # iOS Live Activities
│ ├── analytics.py # Outcomes and exports
│ ├── users.py # User management
│ ├── devices.py # Device/player management
│ ├── segments.py # Segment management
│ ├── apps.py # App management
│ └── subscriptions.py # Subscription management
└── server.py # Main MCP server entry point
```
### Key Improvements
#### 1. Centralized Configuration (`config.py`)
- `AppConfig` dataclass for app configurations
- `AppManager` class for managing multiple apps
- Environment variable loading
- Automatic organization API key detection
#### 2. Unified API Client (`api_client.py`)
- `OneSignalAPIClient` class with centralized request handling
- Automatic authentication method selection
- Consistent error handling with custom exceptions
- Request/response logging
#### 3. Modular Tool Organization
Each module focuses on a specific API domain:
- Better code organization
- Easier maintenance
- Clear separation of concerns
- Reduced code duplication
### 3. New Features Implementation
#### Email Sending
```python
async def send_email(
subject: str,
body: str,
email_body: Optional[str] = None,
segments: Optional[List[str]] = None,
include_emails: Optional[List[str]] = None,
external_ids: Optional[List[str]] = None,
template_id: Optional[str] = None
) -> Dict[str, Any]
```
#### SMS Sending
```python
async def send_sms(
message: str,
phone_numbers: Optional[List[str]] = None,
segments: Optional[List[str]] = None,
external_ids: Optional[List[str]] = None,
media_url: Optional[str] = None
) -> Dict[str, Any]
```
#### Transactional Messages
```python
async def send_transactional_message(
channel: str,
content: Dict[str, str],
recipients: Dict[str, Any],
template_id: Optional[str] = None,
custom_data: Optional[Dict[str, Any]] = None
) -> Dict[str, Any]
```
#### Live Activities
```python
async def start_live_activity(...)
async def update_live_activity(...)
async def end_live_activity(...)
```
#### Analytics & Outcomes
```python
async def view_outcomes(...)
async def export_players_csv(...)
async def export_audience_activity_csv(...)
```
## 4. Migration Guide
### Step 1: Create New Directory Structure
```bash
mkdir -p onesignal_refactored/tools
```
### Step 2: Implement Core Modules
1. Copy `config.py` for app configuration
2. Copy `api_client.py` for API requests
3. Implement tool modules based on provided templates
### Step 3: Update MCP Server Registration
```python
# In server.py
from mcp.server.fastmcp import FastMCP
from .tools import messages, templates, live_activities, analytics
mcp = FastMCP("onesignal-server")
# Register all tools
@mcp.tool()
async def send_email(...):
return await messages.send_email(...)
# Continue for all tools...
```
### Step 4: Test Implementation
1. Test each new endpoint individually
2. Verify error handling
3. Check authentication switching
4. Validate response formatting
## 5. Benefits of Refactoring
1. **Better Maintainability** - Modular structure makes updates easier
2. **Reduced Duplication** - Shared API client eliminates repeated code
3. **Enhanced Error Handling** - Consistent error messages and logging
4. **Feature Completeness** - Support for all major OneSignal features
5. **Improved Testing** - Easier to unit test individual modules
6. **Better Documentation** - Clear module boundaries and responsibilities
## 6. Future Enhancements
1. **Async/Await Optimization** - Better concurrency handling
2. **Response Caching** - Cache frequently accessed data
3. **Batch Operations** - Support bulk operations where applicable
4. **Webhook Support** - Add webhook configuration endpoints
5. **In-App Messaging** - Support for in-app message management
6. **Rate Limiting** - Implement client-side rate limiting
7. **Retry Logic** - Automatic retry for failed requests
## Implementation Priority
1. **Phase 1** - Core refactoring (config, api_client)
2. **Phase 2** - Missing messaging endpoints (email, SMS, transactional)
3. **Phase 3** - Template and Live Activity completion
4. **Phase 4** - Analytics and export functionality
5. **Phase 5** - Legacy player/device endpoints
This refactoring will transform the OneSignal MCP server into a comprehensive, maintainable solution that supports all major OneSignal API features.