npm package: @jordanmbluhm/hls-proto
Description: HLS prototype MCP server
Latest version: 1.0.0

# Recurly MCP Server — Headless Recurly with Claude

A mock MCP (Model Context Protocol) server that exposes 98 Recurly subscription management tools to Claude Desktop. All tools return realistic hardcoded data for **StreamAI**, a fictional mid-market streaming merchant.

## StreamAI at a glance

- **MRR**: $2,142,000
- **Active subscribers**: 87,420
- **Plans**: Starter ($9.99/mo), Pro ($24.99/mo), Enterprise ($149/mo)
- **Key problem**: Cohort 3 (month 3–4) churning at 18% vs 11% baseline
- **Active campaign**: Q1 cancel-save with 30% discount variant leading at 34% retention

## Quick start

```bash
# Install dependencies
npm install

# Build
npm run build

# Test that the server starts (ctrl+c to stop)
npm start
```

## Configure Claude Desktop

Add the following to your Claude Desktop config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "recurly": {
      "command": "/Users/jbluhm/.volta/bin/node",
      "args": ["/Users/jbluhm/Desktop/mcp-future/dist/index.js"]
    }
  }
}
```

> **Note**: The full path to `node` is required because Claude Desktop doesn't inherit your shell's PATH (e.g., Volta, nvm). Run `which node` in your terminal to find yours.

Restart Claude Desktop after saving the config. You should see "recurly" appear in the MCP server list.

## Tool domains (98 total)

| Domain | Tools | Examples |
|--------|-------|---------|
| **A — Subscriber & Billing** | 20 | `get_account`, `cancel_subscription`, `create_coupon` |
| **B — Revenue Intelligence** | 18 | `get_merchant_health_summary`, `run_pricing_simulation`, `forecast_revenue` |
| **C — Retention & Campaigns** | 16 | `create_campaign`, `get_cancel_save_performance`, `get_win_back_candidates` |
| **D — Agentic Workflows** | 12 | `create_agent_task`, `get_hitl_pending_approvals`, `simulate_agent_run` |
| **E — Next-Gen Billing** | 14 | `ingest_usage_event`, `create_micro_access_pass`, `get_billing_model_recommendation` |
| **F — Platform & Integrations** | 10 | `get_integration_status`, `process_agent_checkout`, `get_audit_log` |
| **G — Agentic Commerce (B2A)** | 8 | `get_agent_purchase_negotiations`, `get_subscriber_self_service_actions` |

## Example prompts to try

Once connected in Claude Desktop:

- "How is StreamAI doing? Give me the full health summary."
- "Show me the high-risk Pro subscribers in month 3–4 and what we can do about them."
- "What would happen if we raised the Pro price to $27.99 for new subscribers?"
- "Create a cancel-save campaign for the cohort 3 churn problem."
- "What are the pending approvals from the retention agent?"
- "Show me Jane Doe's account and tell me if we should intervene."

## Development

```bash
# Watch mode (recompiles on save)
npm run dev
```

## Project structure

```
src/
  index.ts              # Entry point — creates server, registers domains, connects stdio
  mock-data.ts           # Shared StreamAI constants (merchant, accounts, plans, benchmarks)
  helpers.ts             # textResult(), makeActionLog(), wrapDryRun()
  domains/
    a-subscriber-billing.ts
    b-revenue-intelligence.ts
    c-retention-campaigns.ts
    d-agentic-workflows.ts
    e-next-gen-billing.ts
    f-platform-integrations.ts
    g-agentic-commerce.ts
```