npm package: @orchid-automation/playkit
Description: PlayKit MCP Server - Clay expertise for Claude Code
Author: Orchid Automation
Latest version: 0.1.1

# @orchid-automation/playkit

PlayKit MCP Server - Clay expertise for Claude Code.

14 tools for Clay workflow design, integration lookup, AI prompt generation, and more.

## Quick Start

### With Claude Code (recommended)

```bash
# Add PlayKit to Claude Code (opens browser for auth)
claude mcp add playkit -- npx -y @orchid-automation/playkit

# Or with API key directly
claude mcp add playkit -e PLAYKIT_API_KEY=pk_live_xxx -- npx -y @orchid-automation/playkit
```

### Standalone

```bash
# Run with OAuth (opens browser)
npx @orchid-automation/playkit

# Run with API key
npx @orchid-automation/playkit --api-key pk_live_xxx

# Or set environment variable
PLAYKIT_API_KEY=pk_live_xxx npx @orchid-automation/playkit
```

## Usage Options

```
Usage: playkit [options]

Options:
  -k, --api-key <key>   API key (or set PLAYKIT_API_KEY env var)
  -l, --login           Force new OAuth login flow
  --logout              Clear saved credentials and exit
  -s, --server <url>    PlayKit server URL (default: https://mcp.playkit.sh)
  -t, --timeout <ms>    Tool call timeout in ms (default: 300000 = 5 min)
  -V, --version         Output version number
  -h, --help            Display help
```

## Available Tools

### Core Tools (10)

| Tool | Description |
|------|-------------|
| `ask_clay` | Grounded Q&A with intent routing (fast facts + RAG) |
| `brainstorm_play` | Creative play ideation with parallel I/O |
| `get_integration` | JSON-first integration lookup |
| `query_integrations` | Filter 215 integrations by capability |
| `design_workflow` | Multi-table architecture (60-90% credit savings) |
| `write_outreach` | Personalized cold email/LinkedIn sequences |
| `claygent_prompts` | Human-like AI prompts with step-by-step logic |
| `build_table` | Generate Clay table schemas with waterfalls |
| `compare_providers` | Compare data providers using graph data |
| `clay_knowledge_stats` | Knowledge base statistics |

### Async Job Tools (4)

For long-running operations that exceed typical timeouts:

| Tool | Description |
|------|-------------|
| `start_clay_job` | Start a tool as background job (returns job_id) |
| `get_job_status` | Poll for job status and results |
| `cancel_clay_job` | Cancel a running job |
| `list_clay_jobs` | List recent jobs with filters |

**Usage pattern:**
```
1. start_clay_job("brainstorm_play", '{"use_case": "..."}')
   → {"job_id": "job_abc123", "status": "pending"}

2. get_job_status("job_abc123")  # poll every 5-10s
   → {"status": "running", "elapsed_seconds": 15.2}

3. get_job_status("job_abc123")  # when done
   → {"status": "completed", "result": "...", "elapsed_seconds": 45.8}
```

## Authentication

PlayKit uses Polar license keys for authentication. You can:

1. **OAuth flow** (easiest): Run `npx @orchid-automation/playkit` and it opens your browser
2. **API key**: Pass via `--api-key` flag or `PLAYKIT_API_KEY` env var
3. **Cached token**: After OAuth, token is saved to `~/.playkit/token.json`

Get a license key at: https://polar.sh/orchidautomation

## Configuration

Environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `PLAYKIT_API_KEY` | Your Polar license key | - |
| `PLAYKIT_SERVER_URL` | Server URL | `https://mcp.playkit.sh` |
| `MCP_TIMEOUT` | Tool call timeout (ms) | `300000` (5 min) |
| `HTTP_TIMEOUT` | HTTP request timeout (ms) | `120000` (2 min) |

## License

MIT