mcp-soprism/README.md

Model Context Protocol implementation for Soprism

# 🔍 Soprism MCP Server

This server, based on the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol), allows **Claude** or any other MCP-compatible client to interact with the [Soprism API](https://soprism.com), providing powerful **audience insights and analytics data** for marketing and audience research.

## ✨ Features

- 🔐 Authentication with Auth0 using Device Authorization Flow
- 👤 Get user information and profile details
- 📊 Manage and retrieve user projects
- 📈 Get detailed project analytics and audience insights
- 🔄 Compare target and benchmark audiences with statistical analysis
- 🗺️ Access geographic distribution data for audiences

---

## 🚀 Prerequisites

Before using this server, ensure you have:

- **Node.js** (v18 or higher)
- **Claude Desktop App**
- **Soprism Account** with API access

---

## 📦 Installation

```bash
npm install
npm run build
```

## 🖥️ Local Installation

### Using the Setup Script

For convenient local installation, you can use our setup script, which automates the download, installation, and configuration process for the Soprism MCP (and optionally other MCPs as well):

1. **Use the provided setup script**:
   ```bash
   chmod +x setup-mcps.sh
   ```

2. **Run the script**:
   ```bash
   ./setup-mcps.sh
   ```

3. **Interactive Setup**:
   - The script will display a menu where you can select which MCPs to install
   - Select "Soprism MCP" or "All MCPs" if you want to install multiple MCPs
   - The script will automatically:
     - Download the repository from GitLab
     - Install dependencies
     - Build the project
     - Configure Claude Desktop to use the local MCP

4. **Verification**:
   - After installation, the script will show the location of your Claude Desktop configuration file
   - Check that the Soprism MCP is properly configured by opening Claude Desktop

### Manual Local Installation

If you prefer to install manually:

1. **Clone the repository**:
   ```bash
   git clone https://gitlab.com/soprismp/mcp-soprism.git
   cd mcp-soprism
   ```

2. **Install dependencies and build**:
   ```bash
   npm install
   npm run build
   ```

3. **Configure Claude Desktop** (see the "Configuring Claude Desktop" section for details)

## 🚢 Smithery Deployment & Installation

### Deploying to Smithery

To deploy this MCP to [Smithery](https://smithery.ai):

1. **GitHub Repository Requirement**:
   - **Important**: Smithery requires your MCP code to be hosted in a GitHub repository

2. **Deployment Steps**:
   - Log into Smithery and select "Deploy a new MCP server"
   - Connect your GitHub account if you haven't already
   - Select the repository containing your Soprism MCP
   - Configure authentication and environment variables in Smithery
   - Specify resource requirements (memory, CPU)
   - Set up monitoring and logging

3. **Smithery Integration**:
   - Register the MCP with Smithery's service registry
   - Configure access permissions
   - Test the integration with Claude

### Installing from Smithery

Once the MCP has been successfully deployed to Smithery, you can install it for use with Claude Desktop:

```bash
npx -y @smithery/cli@latest install soprism-mcp --client claude
```

This command will download and configure the MCP server for use with Claude Desktop.

## 🔧 Configuring Claude Desktop

1. Open the configuration file for Claude Desktop:

   - **MacOS:**
     ```bash
     code ~/Library/Application\ Support/Claude/claude_desktop_config.json
     ```
   - **Windows:**
     ```bash
     code %AppData%\Claude\claude_desktop_config.json
     ```

2. Add or update the following configuration:

   ```json
   "mcpServers": {
     "soprism": {
       "command": "/path/to/node",
       "args": [
         "/ABSOLUTE/PATH/TO/build/index.js"
       ]
     }
   }
   ```

3. Save the file and restart Claude Desktop.

## 💻 Usage

### Running the Server

You can run the server in two modes:

#### 1. **STDIO Mode** (default)

```bash
node build/index.js
```

**STDIO Mode Details:**
- **Communication Method**: Uses standard input/output streams for direct process-to-process communication
- **Primary Use Case**: Direct integration with Claude Desktop, where Claude spawns the MCP as a child process
- **How It Works**: 
  - Claude sends requests to the MCP through stdin
  - MCP processes the requests and returns responses through stdout
  - Creates a direct pipe between Claude and the MCP server
- **Benefits**:
  - Lower latency (no network overhead)
  - Simpler local setup
  - No need to manage network ports
  - Default mode for Claude Desktop integration

#### 2. **SSE Mode** (Server-Sent Events)

```bash
node build/index.js sse
```

**SSE Mode Details:**
- **Communication Method**: Creates an HTTP server that uses the SSE protocol
- **Primary Use Case**: Browser-based or remote integrations where network access is required
- **How It Works**:
  - Runs a web server on a specific port
  - Clients connect via HTTP
  - Server pushes updates to clients using the SSE protocol
  - Allows multiple clients to connect simultaneously
- **Benefits**:
  - Can be accessed over a network
  - Works with browser applications
  - Supports multiple concurrent clients
  - Better for distributed systems where the MCP runs on a different machine

**Which Mode to Choose:**
- Use **STDIO mode** for Claude Desktop integration (recommended for most users)
- Use **SSE mode** for web applications, remote access, or when integrating with non-Claude clients

## 🧩 How the MCP Works

### Architecture Overview

The Soprism MCP acts as a bridge between Claude and the Soprism API:

1. Claude → MCP Server → Soprism API → Audience Data
2. Claude makes tool calls to the MCP Server
3. MCP authenticates and makes the appropriate API requests
4. Results are returned to Claude in a structured format

### How Tools Interact with Claude

When Claude needs to access Soprism data:

1. Claude identifies which tool to use based on user queries (e.g., "Get my projects")
2. Claude makes a tool call to the MCP with appropriate parameters
3. The MCP processes the request, handles authentication, and calls the Soprism API
4. The response is formatted and returned to Claude
5. Claude interprets the data and presents insights to the user

### Authentication Flow

The Soprism MCP uses Auth0's Device Authorization Flow:

1. User initiates authentication by using the `soprism-initiate-device-auth` tool
2. MCP generates a device code and URL for the user to visit
3. User visits the URL and enters the code to authenticate
4. Auth0 returns access and refresh tokens to the MCP
5. MCP stores these tokens and uses them for subsequent API requests
6. Tokens are automatically refreshed when they expire

---

## 🛠️ Available Tools

### 🔑 Authentication Tools

- **soprism-initiate-device-auth**
  - **Description**: Starts the device authorization flow with Auth0, generating a URL and code for the user to authenticate in their browser.
  - **Parameters**: _None_
  - **Response**: Authentication instructions and device code information.

### 👤 User Information Tools

- **soprism-get-current-user**
  - **Description**: Retrieves information about the currently authenticated user, including profile data, email, and account details.
  - **Parameters**: _None_
  - **Response**: User profile information in JSON format.

### 📂 Project Management Tools

- **soprism-get-projects**
  - **Description**: Retrieves all projects for a user with filtering, sorting, and pagination capabilities. Supports searching by name or content.
  - **Parameters**:
    - `userId` _(number)_: ID of the user
    - `filter` _(string, optional)_: Search term to filter projects
    - `page` _(number, optional)_: Page number for pagination (default: 1)
    - `perPage` _(number, optional)_: Number of items per page (default: 20)
    - `sort` _(string, optional)_: Sort order for results (default: 'create-desc')
  - **Response**: List of projects in JSON format.

- **soprism-get-project-details**
  - **Description**: Gets detailed information about a specific project, including audiences, metrics, and configurations.
  - **Parameters**:
    - `projectId` _(number)_: ID of the project to retrieve
  - **Response**: Detailed project information in JSON format.

### 📊 Analytics Tools

- **soprism-get-project-stats**
  - **Description**: Retrieves comparative statistics between target and benchmark audiences, with detailed breakdowns by criteria types including demographics, interests, and behaviors.
  - **Parameters**:
    - `targetAudienceId` _(number)_: ID of the target audience
    - `benchmarkAudienceId` _(number)_: ID of the benchmark audience
    - `criteriaTypes` _(string, optional)_: Types of criteria to include (comma-separated)
    - `normalized` _(boolean, optional)_: Whether to normalize the data (default: true)
    - `limit` _(number, optional)_: Maximum number of items per criteria type (default: 200)
  - **Response**: Comparative audience statistics in JSON format.

- **soprism-get-criteria-types**
  - **Description**: Returns information about all available criteria types for Soprism stats, including descriptions.
  - **Parameters**: _None_
  - **Response**: List of available criteria types with descriptions.

- **soprism-get-map-stats**
  - **Description**: Retrieves geographic distribution data for comparing audiences across different regions.
  - **Parameters**:
    - `targetAudienceId` _(number)_: ID of the target audience
    - `benchmarkAudienceId` _(number)_: ID of the benchmark audience
    - `version` _(number, optional)_: API version to use (default: 2)
    - `limit` _(number, optional)_: Maximum number of geographic locations to return (default: 200)
  - **Response**: Geographic distribution data in JSON format.

---

## 🔄 How the Tools Interact with the Soprism API

Each tool in the MCP interacts with specific endpoints of the Soprism API:

- **User Information**: Connects to `/user` endpoints to retrieve user profiles
- **Project Management**: Uses `/users/{userId}/projects` and `/projects/{projectId}` endpoints
- **Analytics**: Leverages specialized endpoints like `/audiences/criterion/{targetId}/{benchmarkId}` for comparative stats

The MCP handles:
- Authentication token management
- Request formatting and parameter handling
- Error handling and retries
- Response parsing and transformation for Claude-friendly formats

---

## 💡 Predefined Prompts

While this MCP currently doesn't include predefined prompts, they can be a powerful way to enhance the user experience by providing specialized instructions for Claude on how to use the tools effectively.

### What Are Predefined Prompts?

Predefined prompts are pre-written instructions for Claude that:
- Guide the AI through complex workflows with the MCP tools
- Provide structured approaches to common analysis tasks
- Include specific knowledge about how to interpret Soprism data
- Create consistent, optimized experiences for particular use cases

### How Predefined Prompts Work

1. **Structure**: Prompts are defined in the MCP and registered with Claude
2. **Invocation**: Users can call these prompts by name (e.g., "Use the soprism-analysis prompt")
3. **Execution**: Claude loads the prompt instructions and follows them to complete the task
4. **Parameters**: Prompts can accept parameters to customize their behavior

### Example Predefined Prompts for Soprism

Here are some examples of predefined prompts that could be implemented:

#### 1. `soprism-audience-analysis`

A comprehensive prompt for analyzing target audiences compared to benchmarks:

```
I'll help you analyze your audience data using Soprism. First, I'll need:

1. Your target audience ID
2. A benchmark audience ID for comparison

I'll analyze:
- Key demographic differences
- Unique interests and behaviors
- Geographic distribution patterns
- Recommended marketing approaches based on findings

Let's start by authenticating with Soprism...
```

#### 2. `soprism-project-explorer`

A prompt to help users explore and understand their Soprism projects:

```
I'll help you explore your Soprism projects. I can:

1. List all your projects
2. Find projects by keywords or topics
3. Summarize project details
4. Compare multiple projects
5. Extract key insights from specific projects

What would you like to explore first?
```

#### 3. `soprism-insight-generator`

A prompt focused on generating actionable marketing insights:

```
I'll generate strategic marketing insights based on your Soprism data by:

1. Identifying the most distinctive characteristics of your audience
2. Discovering unexpected patterns and correlations
3. Suggesting content themes and messaging approaches
4. Recommending targeting strategies
5. Comparing performance against industry benchmarks

To begin, I'll need the ID of the project you want to analyze...
```

### Implementing Predefined Prompts

To add predefined prompts to this MCP:

1. Create a `prompts` directory in the project
2. Add prompt files (e.g., `audience-analysis.prompt`)
3. Register the prompts in the MCP server:

```typescript
// Example implementation in src/prompts/index.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import fs from 'fs';
import path from 'path';

export function registerPrompts(server: McpServer) {
  const promptsDir = path.join(__dirname, 'prompts');
  const promptFiles = fs.readdirSync(promptsDir);
  
  promptFiles.forEach(file => {
    const promptName = path.basename(file, '.prompt');
    const promptContent = fs.readFileSync(path.join(promptsDir, file), 'utf8');
    
    server.prompt(
      `soprism-${promptName}`,
      `Soprism tool for ${promptName.replace('-', ' ')}`,
      promptContent
    );
  });
}
```

4. Update the `src/index.ts` file to register prompts:

```typescript
import { registerPrompts } from './prompts/index.js';

// Existing code...
registerTools(server);
registerPrompts(server); // Add this line
```

Predefined prompts can significantly enhance the usability of the Soprism MCP by providing specialized workflows for common tasks and analyses.

---