# Never Gonna Give You Up — for agents

A daily motivational-image app and public catalog.

- **Site:** https://nevergonna.pierware.com/
- **This page:** https://nevergonna.pierware.com/agents
- **MCP (Model Context Protocol):** https://nevergonna.pierware.com/mcp
- **Catalog size:** ~353 images

## What the product does

Every morning, users get a fresh image — motivational, funny, or feel-good — on **Mac**, **iPhone**, and **Android**.

- Mobile: a scheduled notification (default 6:00; user-configurable).
- macOS: shows a picture after a long away period (sleep / lock / screensaver).
- Web: browse a stack of images on the homepage, open permalinks at `/i/{slug}`, and search captions at `/search`.

Images are hosted on a public CDN. Permalinks and search expose OCR text and short descriptions when available.

## Human URLs

| Path | Purpose |
|------|---------|
| `/` | Landing page with image stack |
| `/i/{slug}` | Permalink for one image (SEO + share) |
| `/search?q=…` | Search UI; add `format=json` for JSON |
| `/random` | 302 redirect to a random image URL |
| `/privacy.html` | Privacy policy |
| `/support` | Human support page (email behind captcha) |
| `/agents` | This Markdown document |
| `/mcp` | Streamable HTTP MCP endpoint (POST JSON-RPC) |

Search JSON example: `https://nevergonna.pierware.com/search?q=coffee&format=json`

## MCP endpoint

**URL:** `https://nevergonna.pierware.com/mcp`  
**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports)  
**Methods:** `POST` (JSON-RPC 2.0 body). `OPTIONS` for CORS.  
**Server name:** `nevergonna-mcp`  
**CORS:** `Access-Control-Allow-Origin: *`

No API key is required. Same origin as the website; no separate daemon or port.

### Client config examples

**Claude Desktop / MCP config (HTTP):**

```json
{
  "mcpServers": {
    "nevergonna": {
      "url": "https://nevergonna.pierware.com/mcp"
    }
  }
}
```

**curl smoke test (initialize):**

```bash
curl -sS -X POST 'https://nevergonna.pierware.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
```

Then call `tools/list` or `tools/call` the same way.

### Tools

| Tool | Arguments | Returns |
|------|-----------|---------|
| `get_random_image` | optional `tag` (string) | One image: id, url, permalink, ocr, description, … |
| `search_images` | `query` (required), optional `limit` (default 5) | Matching images from OCR/descriptions |
| `get_image_by_id` | `id` (permalink slug) | That image’s metadata |
| `list_images` | optional `page` (default 1), `limit` (default 20) | Paginated catalog |

### Resources

| URI | Description |
|-----|-------------|
| `motivation://latest` | JSON metadata + link for the most recently added analyzed image |

### Typical agent workflow

1. Connect to `https://nevergonna.pierware.com/mcp`.
2. Prefer `get_random_image` for a surprise pick, or `search_images` when the user names a theme.
3. Show humans the `permalink` (`/i/{slug}`) and/or the direct image `url`.
4. Use `get_image_by_id` when you already have a slug; use `motivation://latest` for “what’s new.”

## Related HTTP APIs (non-MCP)

- `GET /random` — redirect to a random image file URL (`X-Image-Filename` header).
- `GET /search?q=…&format=json` — same catalog search as the MCP `search_images` tool.

## Contact / owner

PierWare — https://nevergonna.pierware.com/ · https://pierware.com