# Zocialeye MCP Server

Model Context Protocol (MCP) server for the Zocialeye social media analytics API. This server provides AI assistants with access to comprehensive social media campaign analytics, including sentiment analysis, influencer tracking, and content insights across multiple platforms.

## Features

This MCP server provides access to Zocialeye's comprehensive social media analytics capabilities through the following tools:

- **get_campaign_categories**: Get all available categories for a specific campaign
- **get_campaign_keywords**: Get all available keywords for a specific campaign  
- **get_campaign_wordcloud**: Get word cloud data with sentiment analysis for a specific campaign
- **get_campaign_messages**: Get messages/posts with filtering and sentiment analysis for a specific campaign
- **get_campaign_summary**: Get summary statistics and metrics for a specific campaign
- **get_campaign_influencers**: Get top influencers and engagement metrics for a specific campaign

### Supported Platforms
- Facebook
- X (Twitter)
- Instagram
- TikTok
- YouTube
- Forums
- Blogs
- News sites

### Analytics Capabilities
- **Sentiment Analysis**: Positive, negative, and neutral sentiment classification
- **Content Filtering**: Filter by categories, groups, channels, and sentiment
- **Time-based Analysis**: Flexible date range filtering with hourly/daily summaries
- **Engagement Metrics**: Track engagement rates, influencer performance, and content reach
- **Word Cloud Generation**: Visual representation of trending topics and keywords

## Usage

### Setup with Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "zocialeye": {
      "command": "node",
      "args": ["/path/to/zocialeye-mcp/dist/index.js"],
      "env": {
        "ZOCIALEYE_API_KEY": "your-api-key-here",
        "ZOCIALEYE_CAMPAIGN_ID": "your-campaign-id"
      }
    }
  }
}
```

### Required Environment Variables
- `ZOCIALEYE_API_KEY`: Your Zocialeye API key (required)
- `ZOCIALEYE_CAMPAIGN_ID`: Your campaign ID (required)

## Available Tools

### get_campaign_categories
Get all available categories for a specific campaign. Categories help organize and filter social media content by topics, brands, or themes.

**Parameters:**
- No parameters required. Uses ZOCIALEYE_CAMPAIGN_ID environment variable.

**Returns:** Array of category objects with category name and group information.

### get_campaign_keywords
Get all available keywords for a specific campaign. Keywords are the tracked terms used to identify relevant social media content.

**Parameters:**
- No parameters required. Uses ZOCIALEYE_CAMPAIGN_ID environment variable.

**Returns:** Array of keyword strings.

### get_campaign_wordcloud
Get word cloud data with sentiment analysis for a specific campaign. Provides visual representation of trending topics and keywords with sentiment classification.

**Parameters:**
- `date_start` (optional): Start period in ISO 8601 format (e.g., "2023-12-01T00:00:00Z"). Defaults to 1 month ago.
- `date_end` (optional): End period in ISO 8601 format (e.g., "2023-12-31T23:59:59Z"). Defaults to current time.
- `group_by` (optional): Grouping method - "category", "group", "sentiment", "keywords", or "all". Default: "all".
- `filter` (optional): Filter object with properties:
  - `categories`: Array of category names to filter by
  - `sentiment`: Sentiment filter - "positive", "negative", or "neutral"
  - `group`: Group name to filter by
  - `channel`: Platform filter - "facebook", "x", "instagram", "tiktok", "forum", "blog", "news", "youtube"

**Returns:** Word cloud data with frequency and sentiment information.

### get_campaign_messages
Get messages/posts with filtering and sentiment analysis for a specific campaign. Supports pagination and sorting.

**Parameters:**
- `date_start` (optional): Start period in ISO 8601 format. Defaults to 1 month ago.
- `date_end` (optional): End period in ISO 8601 format. Defaults to current time.
- `total` (optional): Maximum number of messages to return (max 50).
- `from` (optional): Starting position for pagination (default: 0).
- `sort_by` (optional): Sorting options:
  - `type`: "engagement", "collected_at", or "post_time_human"
  - `order`: "desc" or "asc"
- `group_by` (optional): Grouping method - "category", "group", "sentiment", "keywords", "channel", or "all". Default: "all".
- `filter` (optional): Same filter options as wordcloud tool.

**Returns:** Array of message objects with content, metadata, and sentiment analysis.

### get_campaign_summary
Get summary statistics and metrics for a specific campaign. Provides time-series data for campaign performance analysis.

**Parameters:**
- `date_start` (optional): Start period in ISO 8601 format. Defaults to 1 month ago.
- `date_end` (optional): End period in ISO 8601 format. Defaults to current time.
- `duration` (optional): Summary granularity - "hour" or "day". Default: "day".
- `group_by` (optional): Grouping method - "category", "group", "sentiment", "keyword", or "all". Default: "all".
- `filter` (optional): Same filter options as other tools.

**Returns:** Time-series summary data with metrics per time period.

### get_campaign_influencers
Get top influencers and engagement metrics for a specific campaign. Identifies key content creators and their performance.

**Parameters:**
- `date_start` (optional): Start period in ISO 8601 format. Defaults to 1 month ago.
- `date_end` (optional): End period in ISO 8601 format. Defaults to current time.
- `group_by` (optional): Grouping method - "category", "group", "sentiment", "keyword", or "all". Default: "all".
- `filter` (optional): Same filter options as other tools.

**Returns:** Array of influencer objects with engagement metrics and performance data.

## Usage Examples

### Basic Campaign Analysis
```bash
# Get campaign categories
get_campaign_categories

# Get campaign keywords  
get_campaign_keywords

# Get word cloud for last 30 days
get_campaign_wordcloud
```

### Advanced Filtering and Analysis
```bash
# Get positive sentiment messages from Instagram
get_campaign_messages({
  "filter": {
    "sentiment": "positive",
    "channel": "instagram"
  },
  "total": 20,
  "sort_by": {
    "type": "engagement",
    "order": "desc"
  }
})

# Get daily summary for specific categories
get_campaign_summary({
  "duration": "day",
  "group_by": "category",
  "filter": {
    "categories": ["BrandA", "BrandB"]
  }
})

# Get influencers with high engagement
get_campaign_influencers({
  "group_by": "sentiment",
  "filter": {
    "sentiment": "positive"
  }
})
```

### Time-based Analysis
```bash
# Analyze campaign performance for specific date range
get_campaign_summary({
  "date_start": "2023-12-01T00:00:00Z",
  "date_end": "2023-12-31T23:59:59Z",
  "duration": "day"
})

# Get hourly breakdown for recent activity
get_campaign_summary({
  "date_start": "2023-12-20T00:00:00Z",
  "date_end": "2023-12-21T23:59:59Z",
  "duration": "hour"
})
```

## Troubleshooting

### Common Issues

**Campaign ID Required Error**
- Ensure `ZOCIALEYE_CAMPAIGN_ID` environment variable is set
- Verify the campaign ID exists in your Zocialeye account

**API Authentication Error**
- Check that `ZOCIALEYE_API_KEY` is correctly set
- Verify the API key has proper permissions for the campaign

**Date Format Errors**
- Use ISO 8601 format for dates: "2023-12-01T00:00:00Z"
- Ensure dates are within valid ranges (not too far in the past/future)

**Filter Parameter Issues**
- Check that filter values match available options (e.g., valid sentiment values)
- Ensure category names match those returned by `get_campaign_categories`

## GitHub Pages Login Portal

This repository also includes a GitHub Pages login portal for obtaining ZOCIALEYE_API_KEY tokens. The login page matches the WISESIGHT branding and design.

### Accessing the Login Portal

Once deployed to GitHub Pages, users can access the login portal at:
`https://yourusername.github.io/zocialeye-mcp`

### Features

- **Clean, Modern Design**: Matches WISESIGHT branding with professional UI
- **Secure Token Generation**: Uses the official `/generate-token` API endpoint
- **Token Display & Copy**: Easy token retrieval with one-click copy functionality
- **Error Handling**: Comprehensive error messages for failed authentication
- **Responsive Design**: Works on desktop and mobile devices

### Deployment

The login portal is automatically deployed to GitHub Pages when you push to the main branch. The deployment is handled by GitHub Actions workflow.

#### Manual Deployment

You can also deploy manually using:

```bash
npm install
npm run deploy
```

This will:
1. Build the MCP server
2. Deploy the login portal to GitHub Pages

### Getting Your API Key

1. Visit the deployed GitHub Pages URL
2. Enter your Zocialeye username and password
3. Click "Login" to generate your API token
4. Copy the generated token for use with the MCP server

### Security Notes

- The login portal uses HTTPS for secure communication
- Credentials are only sent to the official Zocialeye API
- No credentials are stored or logged by the portal
- Tokens are displayed only after successful authentication

## License

MIT License