Skip to main content
Glama
README.md
# Obscura

Obscura is a remote MCP server on Cloudflare, served at `https://obscura.sweetretry.dev`, that lets Claude Code generate images, video and audio through ByteDance Ark and Tu-zi, with a task log and a cost audit. Built on [void-starter](https://github.com/SweetRetry/void-starter); the model catalog comes from olio-void's `packages/model-providers`, without chat models or credits.

## What it does

- **MCP tools** at `/mcp` (Streamable HTTP): `list_models`, `get_model_guide` (the prompt-writing guide of a model whose syntax lives in the prompt, such as Midjourney; also an MCP resource at `obscura://guides/<model id>`), `generate` (a client that supports elicitation on protocol 2026-07-28 is sent the quote to confirm before anything is billed), `get_task`, `view_output` (scaled previews of image outputs, so Claude can look at what it made), `list_tasks` (searchable log), `cost_report`.
- **Standard MCP auth.** OAuth 2.1 with PKCE, dynamic client registration and RFC 9728 discovery, served by Better Auth's `mcp()` plugin. Access tokens are JWTs bound to `/mcp`.
- **Allowlisted admins.** Sign-in is Google only, and only the addresses in the `ADMIN_EMAILS` secret get an account or a session. Each admin sees its own tasks and costs.
- **Tasks.** Each request is a row in D1 that moves queued → running → succeeded | partial | failed (`confirming` while a lost run may still deliver). A queue sends each task to its provider, and a cron advances open tasks every minute.
- **Outputs in R2.** Every delivered file is copied to R2 at once and served at `/f/<random id>.<ext>`.
- **Cost audit.** Each task records its quote at submit, its cost for what delivered, provider-reported tokens, the price it used, and runs that may have been billed without delivering. Prices are catalog list prices in USD (CNY at a pinned rate), not invoices.
- **Web.** `/sign-in`, `/consent`, and `/` with the cost audit and a searchable generation log.

## Use it from Claude Code

```sh
claude mcp add --transport http --scope user obscura https://obscura.sweetretry.dev/mcp
```

Then `/mcp` in Claude Code, pick `obscura`, authenticate, continue with Google and allow.

## Develop

```sh
pnpm install
# apps/web/.env: BETTER_AUTH_SECRET, BETTER_AUTH_URL=http://localhost:5173, GOOGLE_CLIENT_ID,
# GOOGLE_CLIENT_SECRET, ADMIN_EMAILS, ARK_API_KEY, TUZI_API_KEY
pnpm --filter web exec void db migrate
pnpm dev
```

## Deploy

```sh
pnpm --filter web exec void secret sync <file with the server values>
pnpm run deploy
```

The Google client needs `https://obscura.sweetretry.dev/api/auth/callback/google` and `http://localhost:5173/api/auth/callback/google` as authorized redirect URIs. See [docs/deployment.md](docs/deployment.md).

## Brand

The mark and the logo are hand-painted with atelier (works `009-obscura-mark`, `010-obscura-mark-small` for favicon sizes, `011-obscura-logo`). The files in `apps/web/public` are its renders, scaled down and compressed.

## Layout

```text
apps/web/src/routes/mcp.ts                 MCP endpoint
apps/web/src/server/mcp.server.ts          the tools
apps/web/src/server/auth/                  Better Auth + MCP token check
apps/web/src/server/generation/            provider calls, task state machine, pricing, views
apps/web/queues/generations.ts             sends queued tasks to providers
apps/web/crons/generations.ts              advances open tasks
packages/model-providers/                  model catalog, params, prices, provider adapters
```