social listening

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

# Install dependencies
npm install

# Build the server
npm run build

# Run tests
npm test

Adding new features

1. Implement new functionality in src/
2. Add tests in tests/
3. Build and test locally
4. Submit a pull request

Troubleshooting

1. Webhook errors: Ensure your webhook endpoint is accessible and supports HTTPS
2. API key issues: Verify your Syften API key is correctly set in the configuration
3. Database errors: Check if the data directory exists and is writable

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License - see LICENSE file for details