# kumori plugins

kumori for agents: **image + style in → sticker out.**

This repo packages kumori's remote MCP server and sticker skill as a portable
[Agent Plugins 1.0.0](https://agent-plugins.org) plugin, alongside generated
setup for today's clients. Send a photo, pick one of kumori's curated styles,
and get a die-cut sticker back — there is no prompt anywhere in the grammar.

- product: [kumori.camera](https://kumori.camera)
- docs: [docs.kumori.camera](https://docs.kumori.camera)
- endpoint: `https://mcp.kumori.camera/` (Streamable HTTP, kumori-owned OAuth)

## What's inside

| Surface | Files |
| --- | --- |
| Agent Plugins 1.0.0 portable core | `plugin.json`, `mcp.json`, `skills/` |
| Claude Code plugin | `.claude-plugin/`, `.mcp.json` |
| Codex plugin | `.codex-plugin/`, `.agents/plugins/marketplace.json` |
| Cursor plugin | `.cursor-plugin/` |
| Per-client setup snippets | `clients/` |
| MCP Registry | `server.json` |
| Vendored spec schemas | `schemas/1.0.0/` |

## Tools

| Tool | What it does |
| --- | --- |
| `kumori_get_info` | Session context: credit balance, generation stats, compact style catalog. Call first. |
| `kumori_list_filters` | The live style catalog — slugs, names, descriptions. |
| `kumori_prepare_upload` | Pre-signed upload URL for large local images (>4MB). |
| `kumori_generate_image` | One image + one style slug → sticker. Exactly one image source; no prompt. |
| `kumori_check_generation` | Poll progress; returns `image_url` and `share_url` when complete. |

The `kumori-stickers` skill teaches agents the full mechanical loop:
image door → style pick → generate → poll → deliver the file plus the
public share page.

## Install

<!-- AUTO-GENERATED:INSTALL START -->

### Codex CLI

Copy this kumori setup to `~/.codex/config.toml`. OAuth-capable clients authorize on first use; call `kumori_get_info` after connecting.

```toml
[mcp_servers.kumori]
url = "https://mcp.kumori.camera/"
```

### Claude Code

Copy this kumori setup to `your Claude Code MCP setup`. OAuth-capable clients authorize on first use; call `kumori_get_info` after connecting.

```sh
claude mcp add --scope user --transport http kumori 'https://mcp.kumori.camera/'
```

### Cursor

Copy this kumori setup to `~/.cursor/mcp.json`. OAuth-capable clients authorize on first use; call `kumori_get_info` after connecting.

```json
{
  "mcpServers": {
    "kumori": {
      "type": "http",
      "url": "https://mcp.kumori.camera/"
    }
  }
}
```

### Windsurf

Copy this kumori setup to `~/.codeium/windsurf/mcp_config.json`. OAuth-capable clients authorize on first use; call `kumori_get_info` after connecting.

```json
{
  "mcpServers": {
    "kumori": {
      "serverUrl": "https://mcp.kumori.camera/"
    }
  }
}
```

### VS Code

Copy this kumori setup to `.vscode/mcp.json`. OAuth-capable clients authorize on first use; call `kumori_get_info` after connecting.

```json
{
  "servers": {
    "kumori": {
      "type": "http",
      "url": "https://mcp.kumori.camera/"
    }
  }
}
```

### Any Streamable HTTP client

For any MCP client that speaks Streamable HTTP with OAuth. Probe the endpoint and its authorization metadata; the client completes the kumori-owned OAuth flow interactively.

```sh
# The endpoint requires OAuth end to end - even initialize answers 401
# until the client authorizes. Probe the server and its OAuth metadata:
curl --fail-with-body --silent --show-error 'https://mcp.kumori.camera/'
curl --fail-with-body --silent --show-error 'https://mcp.kumori.camera/.well-known/oauth-protected-resource'
```

### Any agent (npx skills)

Install the kumori sticker skill. This does not connect MCP by itself; also use one of the client setup paths above unless your agent already has the kumori plugin.

```sh
npx skills add creative-int/kumori-plugins
```

### Claude Code (plugin)

Add the marketplace and install the kumori plugin. Call `kumori_get_info` and complete the kumori-owned OAuth flow when Claude prompts.

```sh
/plugin marketplace add creative-int/kumori-plugins
/plugin install kumori@kumori
```

### Codex (plugin)

Add this repository as a Codex plugin marketplace, install kumori with `codex plugin add`, then call `kumori_get_info` and complete OAuth.

```sh
codex plugin marketplace add creative-int/kumori-plugins
codex plugin add kumori@kumori
```

### Cursor (plugin)

Install kumori from the Cursor plugin marketplace, then call `kumori_get_info` and complete OAuth when Cursor prompts.

```sh
Cursor → Settings → Plugins → Add marketplace → creative-int/kumori-plugins
```

### Agent Plugins (portable)

Any client that implements the [Agent Plugins specification](https://agent-plugins.org) can load this repository directly as a plugin: `plugin.json` is the portable manifest, `mcp.json` declares the remote MCP server, and `skills/` holds the sticker skill. No client-specific setup is required.

### Quickstart: authorize and make a sticker

Every install path converges on the same remote MCP server and kumori-owned OAuth flow:

1. Call `kumori_get_info`. OAuth-capable clients open the kumori authorization flow on first use; the connection requests `generate read`. The response carries your credit balance and a compact style catalog.
2. Pick ONE style slug — from `kumori_get_info` or the full `kumori_list_filters` catalog. The style is the only creative decision; there is no prompt.
3. Call `kumori_generate_image` with `filter_slug` plus exactly one image source: `input_image_url` (preferred when the image has any URL), `input_image_data` (base64, up to 4MB), or `input_key` (from `kumori_prepare_upload`, for large local files).
4. Poll `kumori_check_generation` every 2-3 seconds until `completed` (typical generation: 45-60s), or pass `wait=true` to block.
5. Deliver the result: save `image_url` when your client has a filesystem, and share `share_url` — the public page for the finished sticker.

Each generation spends one credit; failed generations refund automatically.

<!-- AUTO-GENERATED:INSTALL END -->

## Development

`kumori.config.ts` is the single source of truth; every manifest and the
install block above are generated:

```sh
pnpm install
pnpm generate
pnpm verify
```

`tooling/smoke.ts` validates the portable files against the Agent Plugins
1.0.0 rules — closed field sets, plugin naming, HTTPS remote URL, and skill
frontmatter — so conformance drift fails CI.

## License

[MIT](./LICENSE). `schemas/1.0.0/` is vendored verbatim from
[agentplugins/agent-plugins-spec](https://github.com/agentplugins/agent-plugins-spec)
under Apache-2.0.