# oganvil-mcp

A minimal [Model Context Protocol](https://modelcontextprotocol.io) server for the **oganvil** OG image API — generate 1200×630 social preview images from a title and tag line, straight from your AI editor or agent.

Zero dependencies. Node 18+. Speaks MCP over stdio, so it works with Claude Desktop, Claude Code, Cursor, Windsurf, or any MCP-capable client.

## Tools

| Tool | Arguments | Returns |
|---|---|---|
| `generate_og_image` | `title` (required), `tag`, `format` (`png`\|`svg`) | The 1200×630 image (PNG/SVG) plus a hosted render URL |
| `get_quota` | — | Current usage for the configured key (no quota consumed) |

Identical renders (same title + tag + format) are served from cache and **never billed twice**.

## Install & run

```bash
# no install needed — run straight from source
node src/index.js
```

### Claude Desktop / Claude Code / Cursor / Windsurf

Add to your MCP client config (`claude_desktop_config.json`, `.cursor/mcp.json`, …):

```json
{
  "mcpServers": {
    "oganvil": {
      "command": "node",
      "args": ["/absolute/path/to/oganvil-mcp/src/index.js"],
      "env": {
        "OGANVIL_API_KEY": "oganvil-demo-key"
      }
    }
  }
}
```

`oganvil-demo-key` is a public free key: 10 renders/day per IP, no signup. For the permanent free tier (50 unique images/month, no card) grab a key at <https://oganvil.rowu.workers.dev/signup>.

## Configuration

| Env var | Default | Meaning |
|---|---|---|
| `OGANVIL_API_KEY` | `oganvil-demo-key` | Your API key (free key from `/signup`, or a paid key) |
| `OGANVIL_API_URL` | `https://oganvil.rowu.workers.dev` | API base URL |

## Example session

```
→ initialize
← {"serverInfo":{"name":"oganvil-mcp","version":"0.1.0"}}

→ tools/call generate_og_image {"title":"Ship faster","tag":"oganvil","format":"png"}
← image/png 1200x630 (28 KB) + hosted URL https://oganvil.rowu.workers.dev/api/render?title=Ship+faster&tag=oganvil
```

Verified output from this repo's source: PNG signature `89504e47`, dimensions `1200 x 630`, ~28 KB.

## Also available over HTTP

If your client speaks remote MCP (Streamable HTTP), you don't need this package at all — the hosted server is at:

```
POST https://oganvil.rowu.workers.dev/mcp
Authorization: Bearer oganvil-demo-key
```

Two tools there: `generate_og_image`, `get_quota`.

## REST API

```
GET https://oganvil.rowu.workers.dev/api/render?title=Hello&tag=World&format=png
```

Free tier: 50 unique images/month, no credit card. Paid: $5/mo (500 images) and $29/mo (5,000 images).

## License

MIT