gumroad-operations

Files (1)

• SKILL.md

SKILL.md (first lines)

# Gumroad Operations

Use this skill when Purse asks to manage Gumroad products, sales, subscriptions/subscribers, offer codes, licenses, webhooks, analytics, daily reports, or agent/MCP integration.

## Project paths

- Project root: `/Users/pharma6/hermes-gumroad-mcp`
- CLI wrapper: `/Users/pharma6/bin/gumroad`
- MCP wrapper: `/Users/pharma6/hermes-gumroad-mcp/scripts/run-mcp.sh`
- Webhook receiver: `/Users/pharma6/hermes-gumroad-mcp/scripts/run-webhook.sh`
- Daily report: `/Users/pharma6/hermes-gumroad-mcp/scripts/daily-report.sh`
- Runbook: `/Users/pharma6/hermes-gumroad-mcp/README.md`
- Secrets: `/Users/pharma6/hermes-gumroad-mcp/.env` — never read or expose values.

## Installed integrations

- Hermes MCP server: `gumroad`; test with `hermes mcp test gumroad`.
- Claude Code local MCP server: `gumroad`; test with `claude mcp list` from project root.
- Cursor project config: `/Users/pharma6/hermes-gumroad-mcp/.cursor/mcp.json`.
- Daily Hermes cron exists: job ID `d2a0d729d1e1`. It can be resumed/running once `/Users/pharma6/hermes-gumroad-mcp/.env` has a real `GUMROAD_ACCESS_TOKEN`.

Restart Hermes/new session required for MCP tools to appear in active chats.

## CLI commands

```bash
export PATH="/opt/homebrew/bin:/Users/pharma6/bin:$PATH"
gumroad doctor --json
gumroad user get --json
gumroad products list --json
# IMPORTANT: products are paginated. If output has next_page_key, keep fetching:
gumroad request GET /products --query '{"page_key":"NEXT_PAGE_KEY"}' --json
gumroad products get PRODUCT_ID --json
gumroad sales list --limit 5 --json
gumroad sales summary --after YYYY-MM-DD --before YYYY-MM-DD --json
gumroad offer-codes list PRODUCT_ID --json
gumroad subscribers list --product-id PRODUCT_ID --json
gumroad webhooks list --json
gumroad webhooks list --resource-name sale --json
gumroad licenses verify --product-permalink PERMALINK --license-key LICENSE_KEY --json
```

Mutation commands require both:

1. `.env` has `GUMROAD_ALLOW_MUTATIONS=true`
2. command has exact confirmation, e.g. `--confirm offer-codes.create`

Examples:

```bash
gumroad offer-codes create PRODUCT_ID --name LAUNCH50 --amount-off 50 --offer-type percent --confirm offer-codes.create --json
gumroad products disable PRODUCT_ID --confirm products.disable --json
gumroad sales refund SALE_ID --amount-cents 500 --confirm sales.refund --json
```

Refunds and product changes are money/business-impacting. Confirm with Purse in-session before executing unless he explicitly gave the exact action and confirmation.

## MCP tools

The MCP server exposes 24 tools, prefixed `gumroad_`, including:

- user/products/sales: `gumroad_get_user`, `gumroad_list_products`, `gumroad_get_product`, `gumroad_list_sales`, `gumroad_sales_summary`, `gumroad_get_sale`
- offer codes: `gumroad_list_offer_codes`, `gumroad_create_offer_code`, `gumroad_update_offer_code`, `gumroad_delete_offer_code`
- subscribers/licenses: `gumroad_list_subscribers`, `gumroad_get_subscriber`, `gumroad_verify_license`, `gumroad_license_action`
- webhooks: `gumroad_list_webhooks`, `gumroad_create_webhook`, `gumroad_delete_webhook`
- future-proof: `gumroad_raw_request`

Use read-only tools first. Mutating tools have internal env/confirm gates.

## Token setup

If live calls fail with missing token, ask Purse for the Gumroad access token. Store it only in `/Users/pharma6/hermes-gumroad-mcp/.env` as `GUMROAD_ACCESS_TOKEN=...`; never hardcode it into configs or messages.

## Verification after token

```bash
gumroad doctor --json
gumroad user get --json
gumroad products list --json
gumroad sales list --limit 5 --json
gumroad sales summary --limit 50 --json
gumroad webhooks list --json
hermes mcp test gumroad
```

Then test Claude Code:

```bash
cd /Users/pharma6/hermes-gumroad-mcp
claude -p "Use gumroad MCP. Call gumroad_doctor, gumroad_list_products, gumroad_list_sales limit 5, and gumroad_sales_summary. Summarize results. Do not mutate anything."
```

## Webhooks

Local receiver is verified:

```bash
./scripts/run-webhook.sh
curl http://127.0.0.1:8787/health
```

Logs: `/Users/pharma6/hermes-gumroad-mcp/logs/webhooks.jsonl`

Gumroad requires `resource_name` when querying resource subscriptions. The wrapper queries all supported names by default (`sale`, `refund`, `dispute`, `cancellation`, `subscription_updated`) and supports `gumroad webhooks list --resource-name sale --json` for a single resource.

Do not create public Gumroad webhook subscriptions until there is an HTTPS URL/tunnel/domain and `GUMROAD_WEBHOOK_SECRET` is set.

## Storefront/homepage redesign

When Purse says the Gumroad homepage/profile is blank, newsletter-only, or needs redesign, use `references/storefront-redesign-workflow.md` before acting. Key points: inspect the public page with browser rendering, not only curl; compare public output against `gumroad user get --json` and paginated product listings; profile/homepage edits are dashboard/browser work because `PUT/PATCH/POST /user` returned 404; never publish drafts or change prices during a redesign unless explicitly instructed.

**Gumroad cannot host custom-designed landing pages** — no custom CSS, hero images, font choices, or layout controls. The storefront is locked to Gumroad's template (headline, bio, featured products, subscribe form). If Purse wants a custom design:

1. Build a self-contained HTML page locally
2. **Show Purse a full-page screenshot BEFORE deploying** — use agent-browser to render the HTML file locally and screenshot it
3. Only deploy once approved
4. Deploy externally (Vercel, Netlify, GitHub Pages) — not on Gumroad
5. Link "Buy Now" CTAs to individual Gumroad product checkout URLs
6. Optionally point a custom domain (e.g. store.fluxio.ai) at the hosted page

From percymcn/agent-cookbook, MIT.

More from percymcn/agent-cookbook