Void Media MCP
by SweetRetry
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
```
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues