Social Listening MCP Server

A Model Context Protocol (MCP) server that provides social listening capabilities through Syften's API. This server enables AI-powered analysis of social mentions, with support for real-time notifications via webhooks.

Features

- Real-time social mention monitoring
- AI-powered content categorization
- Webhook notifications for important mentions
- Historical data backfilling
- Trend analysis and reporting
- Natural language query support

Prerequisites

1. Node.js (v16 or later)
2. A Syften account with API access
3. Claude Desktop app or VSCode with Claude extension

Installation

1. Clone the repository:

git clone https://github.com/fred-em/social-listening.git

cd social-listening

2. Install dependencies:

npm install

3. Build the server:

npm run build

Configuration

1. Syften API Setup

1. Log in to your Syften account
2. Go to Settings > API Access
3. Generate an API key if you haven't already
4. Copy your API key for the next step

2. Claude Desktop Configuration

Add the server configuration to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "social-listening": {
      "command": "node",
      "args": ["/absolute/path/to/social-listening/build/index.js"],
      "env": {
        "SYFTEN_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. VSCode Configuration (Optional)

If you're using VSCode with the Claude extension, add the configuration to /Users/YOUR_USERNAME/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json:

{
  "mcpServers": {
    "social-listening": {
      "command": "node",
      "args": ["/absolute/path/to/social-listening/build/index.js"],
      "env": {
        "SYFTEN_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

1. configure_ai_filter

Configure AI filtering settings for mention analysis.

{
  "enabled": true,
  "min_confidence": 0.7,
  "categories": ["spam", "support", "feedback", "bug_report", "feature_request"],
  "webhook_url": "https://your-webhook.com/endpoint",
  "webhook_secret": "your-secret-token"
}

2. setup_webhook

Configure webhook endpoint for real-time notifications.

{
  "endpoint_url": "https://your-webhook.com/endpoint",
  "secret_token": "your-secret-token",
  "enabled": true
}

3. backfill_month

Backfill mentions for a specific month.

{
  "year": 2024,
  "month": 2
}

4. sync_latest

Sync new mentions since last update.

{}

5. analyze_trends

Analyze mention trends over time.

{
  "start_date": "2024-01-01",
  "end_date": "2024-02-01",
  "group_by": "day",
  "tags": ["feature", "bug"]
}

6. get_top_sources

Get top mention sources/authors.

{
  "start_date": "2024-01-01",
  "end_date": "2024-02-01",
  "limit": 10
}

7. nlp_prompt

Process natural language queries.

{
  "prompt": "show me feedback mentions from last week"
}

8. get_ai_filtered_mentions

Get mentions processed by AI filtering.

{
  "start_date": "2024-01-01",
  "end_date": "2024-02-01",
  "min_confidence": 0.8,
  "categories": ["feedback", "bug_report"],
  "limit": 50
}

Example Usage in Claude

Here are some example prompts you can use with Claude:

1. Configure AI filtering:

Configure the social listening AI filter to detect bug reports and feature requests with 80% confidence.

2. Set up webhook notifications:

Set up a webhook for the social listening server to send notifications to https://my-server.com/webhook with the secret token "my-secret".

3. Analyze trends:

Show me the trend of bug reports and feature requests from last month.

4. Get filtered mentions:

Show me all high-confidence bug reports from the past week.

5. Natural language queries:

What kind of feedback have we received about the new feature launch?

Webhook Integration

When configuring webhooks, the server will send notifications in this format:

{
  "mention_url": "https://example.com/post",
  "ai_score": 0.95,
  "ai_categories": ["bug_report", "feature_request"],
  "timestamp": "2024-02-12T15:30:00Z"
}

Headers included with webhook requests:
- Content-Type: application/json
- X-Webhook-Secret: your-secret-token

Development

Building from source

```bash