# @ojodotso/mcp-server

oJo turns an HTML template and your JSON data into a PDF or PNG at a hosted link,
from the REST API, any MCP client or the editor. This package is oJo's
[Model Context Protocol](https://modelcontextprotocol.io) server. Live previews are free and need
no account; an oJo API key adds hosted PNG and PDF links and reusable templates through the user's
own account. Transport is local **stdio**; the API boundary is HTTP to
`https://api.ojo.so/v1` only.

Most clients can connect to `https://mcp.ojo.so/mcp` directly and sign in, without installing
anything: see <https://ojo.so/docs/mcp-server>. This package is the local alternative.

## Quick start — no account needed

Point your MCP client at the package. With no API key the server starts in
**preview-only mode**: `create_preview_link` renders HTML into a live,
full-resolution image preview, free and unlimited, with no oJo account.

```json
{
  "mcpServers": {
    "ojo": {
      "command": "npx",
      "args": ["-y", "@ojodotso/mcp-server"]
    }
  }
}
```

```bash
claude mcp add ojo -- npx -y @ojodotso/mcp-server
```

### Adding a key

A key unlocks the permanent PNG or PDF URL — the thing you can put in an email, a
social card or an API response — plus reusable templates. Create one at
<https://ojo.so/dashboard/api> and pass it as `OJO_API_KEY`:

```json
{
  "mcpServers": {
    "ojo": {
      "command": "npx",
      "args": ["-y", "@ojodotso/mcp-server"],
      "env": { "OJO_API_KEY": "sk_..." }
    }
  }
}
```

```bash
claude mcp add ojo -e OJO_API_KEY=sk_... -- npx -y @ojodotso/mcp-server
```

Works the same for Claude Desktop, Cursor, and Claude Code.

## Tools

Only `create_preview_link` is registered without an API key; the rest talk to
the oJo API, so advertising them keyless would offer tools that can only fail.

| Tool | Purpose | Credit | Needs a key |
|------|---------|--------|-------------|
| `create_preview_link` | Build a free, full-resolution `/preview` link for an HTML/Handlebars draft. | — | no |
| `generate_image_from_html` | Render plain HTML (with inline CSS) to a PNG; returns its public URL. | 1 | yes |
| `generate_image_from_template` | Render an existing template, optionally overriding variables via `modify`. | 1 | yes |
| `generate_pdf_from_html` | Render plain HTML (with inline CSS) to a PDF of up to 100 pages, A4 unless a CSS `@page` rule sets the size; returns its public URL, page count and credits spent. A longer document is refused and costs nothing. | 1 per 20 pages | yes |
| `generate_pdf_from_template` | Render an existing template to a PDF, optionally overriding variables via `modify`, or build one PDF of up to 100 pages from many templates and HTML with `pages`. | 1 per 20 pages | yes |
| `list_templates` | List the templates available to the account. | — | yes |
| `get_template` | Fetch one template's HTML and variable defaults. | — | yes |
| `create_template` | Create a reusable template from plain HTML/Handlebars. | — | yes |
| `update_template` | Replace a template's HTML, and its variable defaults when given, under the same ID. Overwrites: API renders use the new version at once. | — | yes |

### The design loop

Iterate with `create_preview_link`, then render. It returns an
`https://ojo.so/preview#draft=…` URL that renders the draft live in the browser
through the **same engine as the final PNG**, at full resolution. The draft is
gzipped into the URL *hash*, so it never reaches a server and nothing is stored
— the link is self-contained and shareable with a human reviewer. For a PDF the
preview shows the screen rendering, not the page breaks.

Both image tools also accept `inspect: true`, which returns a 512px-wide
downscaled thumbnail alongside the URL. That is a confirmation that the render
succeeded, not a design surface — it is too small to judge layout or typography.

## Guiding prompt

`author_ojo_template` — teaches the Handlebars helper catalog, the **Template
Variables** (schema/defaults) vs **Modify Payload** (per-render data) model,
viewport conventions, and the preview-first design loop.

## Configuration

- `OJO_API_KEY` (optional) — your oJo API key. Without it the server runs in
  preview-only mode; with it the full tool surface is registered.
- `OJO_API_BASE_URL` (optional) — defaults to `https://api.ojo.so/v1`.
- `OJO_WEB_BASE_URL` (optional) — the web app that serves `/preview` for
  `create_preview_link`. Defaults to `https://ojo.so`; point it at a local
  `http://localhost:3000` when developing against a self-hosted web app.

## Develop

```bash
pnpm install
pnpm build
pnpm test
pnpm check
```