Metadata-Version: 2.4
Name: roxels-mcp
Version: 0.4.2
Summary: MCP server for Roxels — let AI agents create interview templates, configure webhooks, embed widgets, and run interviews via voice conversation
Project-URL: Homepage, https://roxels.ai
Project-URL: Repository, https://github.com/trebu-org/interviewer
Author-email: Roxels <team@roxels.ai>
License-Expression: MIT
Keywords: ai,interviews,mcp,model-context-protocol,onboarding,roxels
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# Roxels MCP Server

> **Under construction.** Roxels is in early access. The platform, docs site, and some features are actively being built. Everything in this MCP server works against the live API, but expect rough edges and breaking changes as we iterate. If you run into issues, reach out to us directly.

mcp-name: ai.roxels/roxels-mcp

---

## What is Roxels?

Roxels is an AI-powered interview platform. You define **what you want to learn** (a template with goals and extraction schemas), and Roxels conducts a voice conversation with your user to collect that information — structured data, not just transcripts.

Think of it as a programmable phone call: you configure the interview, embed it in your app or share a link, and get structured JSON back via webhooks or API.

## What does this MCP server do?

This MCP server lets **AI agents** (Claude Code, Claude Desktop, Cursor, or any MCP-compatible client) manage and integrate Roxels programmatically. Instead of clicking through a dashboard, your AI assistant can:

- **Create interview templates** by opening a voice conversation with the Roxels setup assistant — describe what you want, and a fully configured template is created automatically
- **Configure data extraction** — define output schemas, set up webhooks, choose what structured data to collect
- **Generate embed code** — get ready-to-paste HTML/JS snippets for embedding interviews in your app
- **Monitor interviews** — list interviews, read transcripts, view extracted findings
- **Manage everything via API** — CRUD on templates, persons, embed keys, and output configurations

### For developers

If you're integrating Roxels into your product, this MCP server turns a multi-step manual setup into a single AI-assisted session:

1. Install the MCP → your AI assistant gets access to 16 Roxels tools
2. Tell your AI "set up a customer feedback interview with a webhook to our API"
3. The AI creates the template, configures the webhook + schema, generates embed code, and hands you a working integration

No dashboard, no docs to read, no copy-pasting config.

### For AI agents

This server exposes the Roxels platform as structured tools with typed parameters and detailed descriptions. Key capabilities:

| Tool | What it does |
|------|-------------|
| `create_template_interactive` | Opens a browser to a voice conversation that creates a template — the fastest way to configure an interview |
| `configure_output` | Adds webhook, structured extraction, email, or Excel outputs to a template |
| `get_embed_code` | Returns a ready-to-paste HTML/JS snippet for embedding the interview widget |
| `get_template_schema` | Returns the full schema reference so you know what values are valid |
| `create_embed_key` | Generates a publishable client-side key for the embed widget |
| `list_templates` / `get_template` | Browse and inspect existing templates |
| `list_interviews` / `get_interview` | View interview results, transcripts, and extracted data |

All 16 tools have detailed docstrings. Call `get_template_schema` first to understand the data model.

## Setup

### 1. Get an API key

Sign up at [app.roxels.ai](https://app.roxels.ai), go to **Settings → API Keys**, and create a key.

### 2. Install

```bash
pip install roxels-mcp
```

Or run directly with uvx:
```bash
uvx roxels-mcp
```

### 3. Configure your MCP client

**Claude Code** (`~/.claude/settings.json` or project `.mcp.json`):
```json
{
  "mcpServers": {
    "roxels": {
      "command": "roxels-mcp",
      "env": {
        "ROXELS_API_KEY": "sk-your-key-here"
      }
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "roxels": {
      "command": "uvx",
      "args": ["roxels-mcp"],
      "env": {
        "ROXELS_API_KEY": "sk-your-key-here"
      }
    }
  }
}
```

### 4. Verify

Ask your AI assistant: *"Use the whoami tool to check my Roxels connection."*

## Environment variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ROXELS_API_KEY` | Yes | — | Your Roxels API key (`sk-...`) |
| `ROXELS_API_URL` | No | `https://api.roxels.ai` | API base URL (override for self-hosted or development) |

## Example: Full integration in one session

```
You: "Set up a customer onboarding interview that collects company name,
      employee count, and main pain points. Send results to our webhook
      at https://api.myapp.com/webhooks/roxels with our auth header.
      Then give me the embed code."

AI assistant:
  1. Calls create_template_interactive → opens browser, you talk to the AI
  2. Calls configure_output → adds webhook with schema + headers
  3. Calls create_embed_key → generates a publishable key
  4. Calls get_embed_code → returns the HTML/JS snippet
  5. Done — paste the snippet, interviews are live
```

## Security

- **API keys** (`sk-...`) authenticate all requests. Keep them server-side.
- **Embed keys** (`rk-...`) are safe for client-side code — scoped to one template, can only create sessions.
- The MCP server validates all URLs before opening your browser (only `app.roxels.ai` origins are trusted).
- All traffic is HTTPS. No data is stored locally.

## Tools reference

| Group | Tool | Description |
|-------|------|-------------|
| Templates | `list_templates` | List all active templates |
| | `get_template` | Get template details (goals, settings, outputs) |
| | `create_template` | Create a template programmatically |
| | `update_template` | Update template fields |
| | `create_template_interactive` | Create a template via voice conversation (opens browser) |
| | `modify_template_interactive` | Modify a template via voice conversation (opens browser) |
| Interviews | `list_interviews` | List interviews with filters |
| | `get_interview` | Get full results (summary, findings, transcript) |
| | `list_persons` | List persons (interviewees) |
| | `create_person` | Create a person record |
| Integration | `configure_output` | Add/replace outputs (webhook, structured, email, excel, report) |
| | `get_embed_config` | Get the embed widget SDK reference |
| | `create_embed_key` | Generate a publishable embed key |
| | `get_embed_code` | Generate a ready-to-paste embed snippet |
| Utilities | `get_template_schema` | Get the full schema reference for templates and outputs |
| | `whoami` | Verify API key and connection |

## License

MIT
