# Userology MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes the **Userology UX research platform** as tools and resources for any MCP-compatible AI client — Claude Desktop, Cursor, Windsurf, and more.

## What It Does

This server wraps the Userology researcher-service REST API, giving AI assistants the ability to:

- **Create & manage studies** — Draft, launch, copy, and configure UX research studies
- **Build interview guides** — AI-generate, edit, and rephrase interview guides
- **Manage sections/tasks** — Add prototype testing, concept testing, voice interview, and live product research sections
- **Access analytics** — Get qualitative insights, quantitative metrics, Q&A analysis, and full study reports
- **Use Synthesis Studio** — Have AI-powered conversations to explore research findings
- **View session data** — Access participant lists, session transcripts, and recordings
- **Analyze Figma prototypes** — Extract screen context from Figma files

## Quick Start

### 1. Install

```bash
cd userology-mcp-server
pip install -e .
```

### 2. Configure

Copy `.env.example` to `.env` and fill in your credentials:

```bash
cp .env.example .env
```

Required variables:
| Variable | Description |
|----------|-------------|
| `USEROLOGY_API_BASE_URL` | Researcher-service API URL (default: `https://dev.userology.info/researcher/api`) |
| `USEROLOGY_TENANT_ID` | Your organization's tenant ID |
| `USEROLOGY_ID_TOKEN` | Firebase JWT token (interactive mode) |

### 3. Add to Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "userology": {
      "command": "userology-mcp",
      "env": {
        "USEROLOGY_TENANT_ID": "your-tenant-id",
        "USEROLOGY_ID_TOKEN": "your-token"
      }
    }
  }
}
```

### 4. Test with MCP Inspector

```bash
npx @modelcontextprotocol/inspector userology-mcp
```

## Available Tools (45 total)

### Study Management (9 tools)
`create_study` · `create_study_from_description` · `get_study` · `list_studies` · `update_study_name` · `update_study_details` · `update_study_status` · `copy_study` · `delete_study`

### Section/Task Management (7 tools)
`create_section` · `get_sections` · `get_section` · `update_section` · `delete_section` · `copy_section` · `reorder_section`

### Interview Guides (4 tools)
`get_interview_guides` · `update_interview_guide` · `generate_guide` · `rephrase_guide`

### Analytics & Reports (11 tools)
`get_analytics_status` · `generate_analytics` · `get_qualitative_insights` · `get_quantitative_data` · `get_qna_analysis` · `get_study_summary` · `get_study_insights` · `get_study_report` · `generate_study_report` · `get_session_report` · `get_ui_annotations`

### Synthesis Studio (6 tools)
`create_synthesis_chat` · `list_synthesis_chats` · `get_synthesis_chat` · `send_synthesis_message` · `delete_synthesis_chat` · `share_synthesis_chat`

### Session & Participant Data (7 tools)
`get_participants` · `get_session` · `get_session_recordings` · `get_sessions_report` · `get_participant_sessions_report` · `get_study_tags` · `update_study_tags`

### Figma Integration (1 tool)
`get_figma_context`

## Resources

| URI | Description |
|-----|-------------|
| `userology://studies` | List all studies |
| `userology://study/{id}` | Study details |
| `userology://study/{id}/guides` | Interview guides |
| `userology://study/{id}/analytics` | Analytics status |

## Architecture

```
MCP Client (Claude / Cursor / etc.)
       │ MCP Protocol (stdio)
       ▼
userology-mcp-server
       │ HTTPS
       ▼
researcher-service (existing Userology backend)
```

## License

MIT