youcam-mcp
# youcam-mcp
[](https://github.com/chainwright/youcam-mcp/actions/workflows/ci.yml)
An MCP server that lets an AI agent use the [YouCam API](https://yce.perfectcorp.com/) from Perfect Corp. It covers clothes try-on, hairstyles, hair colour and skin-tone reading. A written policy decides what the agent may do with your key and your units.
**Unofficial.** This is not affiliated with or endorsed by Perfect Corp. It's a sample we built on their public API.
```
50,000 generated calls · 31,836 hostile · 31,836 refused · 0 invariant violations
live: 1 real hair-colour render, 1 unit, result checked
```

## Why a policy
Giving an agent an API key also hands it a wallet and a URL fetcher. YouCam units cost money. An image tool that downloads whatever URL it's given will happily fetch `http://169.254.169.254/` for whoever wrote the text the agent is reading. Usually nobody means harm. The agent is just trying to finish the task, and the boundary is in its way.
So this server enforces what it allows in code, below the tools, and tests that from the hostile side. The rules are in [POLICY.md](POLICY.md). In short:
| | |
|---|---|
| **Tools** | six, each mapped to a documented YouCam endpoint; any can be switched off |
| **Images** | https URLs on your allowlist only, or refs to images already uploaded in this session; never local paths |
| **Network** | every resolved address must be public; the connection is made to the checked address; no redirects; timeouts and a byte cap |
| **Content** | JPEG/PNG identified from the bytes, with the declared type matching; per-tool size limits checked before upload |
| **Units** | per-session and per-day budgets, booked before a task starts, returned only when a task fails |
| **Secrets** | key sent only to the API host; redacted from every result and log line |
| **Refusals** | ordinary tool results with a reason code, so the agent can read them and change course |
## Tools
| Tool | YouCam API | Units |
|---|---|---|
| `try_on_clothes` | AI Clothes, `cloth-v4` | 2 |
| `try_hairstyle` | AI Hairstyle Generator v2.1 (template or reference photo) | 2 |
| `try_hair_color` | AI Hair Color (10 presets or any `#RRGGBB`) | 1 |
| `analyze_skin_tone` | AI Facial Color Tones Analyzer | 20 |
| `get_task_status` | task polling, by a ref this server issued | 0 |
| `list_hairstyle_templates` | hairstyle template list | 0 |
YouCam charges units only when a task succeeds. Paid tools wait up to `wait_seconds` (60 by default) for the result. If it isn't ready by then, they return a `task_ref` to poll later. Every result reports the budget:
```json
{"status": "success", "tool": "try_hair_color", "units_charged": 1,
"result_url": "https://yce-us.s3-accelerate.amazonaws.com/…",
"image_refs": {"person_image": "img_…"},
"budget": {"session_used": 1, "session_budget": 30, "day_used": 1, "day_budget": 60}}
```
A refusal looks like this:
```json
{"refused": true, "code": "url_ip_literal", "reason": "Image URLs must use a host name, not an IP address."}
```
## Quickstart
You need Python 3.9 or newer. There are no dependencies.
```bash
git clone https://github.com/chainwright/youcam-mcp
cd youcam-mcp
python3 -m pip install . # installs the `youcam-mcp` command
cp examples/policy.example.json policy.json
# edit policy.json: put the hosts your images live on in "image_hosts"
```
Get an API key from the [YouCam API console](https://yce.makeupar.com/api-console/en/api-keys/). The server uses the v2 Bearer key only, so you don't need the RSA secret key.
**Claude Code**
```bash
claude mcp add youcam -e YOUCAM_API_KEY=your-key -- youcam-mcp --policy /abs/path/policy.json
```
**Claude Desktop** (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"youcam": {
"command": "youcam-mcp",
"args": ["--policy", "/abs/path/policy.json"],
"env": { "YOUCAM_API_KEY": "your-key" }
}
}
}
```
To run it without installing, use `"command": "python3", "args": ["-m", "youcam_mcp", "--policy", "…"]` with `"PYTHONPATH": "/abs/path/youcam-mcp/src"` in `env`.
Policy file (all keys optional; unknown keys are an error):
```json
{
"image_hosts": ["images.example.com", "*.your-cdn.example"],
"session_unit_budget": 30,
"daily_unit_budget": 60,
"min_account_units": 100,
"max_image_bytes": 5000000,
"tools": ["try_on_clothes", "try_hairstyle", "try_hair_color",
"analyze_skin_tone", "get_task_status", "list_hairstyle_templates"]
}
```
The defaults are deliberately strict. With no `image_hosts`, every image URL is refused, and the server says so on startup.
## Tested from the hostile side
```bash
python3 -m unittest discover -s tests # 66 tests, no network
python3 tests/fuzz_harness.py -n 50000 # seeded, reproducible
```
The unit tests cover the cases we thought of. The fuzz harness generates the ones we didn't. It sends each call through the real JSON-RPC entry point and the real transport; only the socket is replaced, by a recorder that also plays a deliberately hostile YouCam. That fake API echoes the key back in error messages, puts prompt-injection text in template titles, returns results on foreign hosts and gets stuck on slow tasks.
It throws:
- local paths and traversal;
- SSRF URLs: IP literals, decimal and hex hosts, `@` and `#` tricks, other schemes and ports;
- allowlisted names whose DNS answers with private, loopback, metadata, CGNAT or IPv4-mapped addresses;
- bad images: oversized, not images, lying content types, redirects, wrong dimensions;
- prompt-injection text in every typed field;
- bursts of 20-unit calls against a 30-unit budget;
- malformed JSON-RPC.
Then it checks invariants:
- **I1** A hostile input that can be judged offline is refused with zero DNS lookups and zero connections.
- **I2** No connection is ever made to a non-public address, whatever DNS says.
- **I3** The Authorization header goes to the YouCam API host and nowhere else.
- **I4** Hostile image content never reaches the YouCam API and never costs a unit.
- **I5** Session and daily usage never exceed their budgets, and the units the API bills never exceed what the ledger booked.
- **I6** The API key never appears in a response or a log line.
- **I7** Every request gets exactly one well-formed response, and every refusal has a documented code.
- **I8** Text from the API comes back bounded, with no control or bidi characters.
- **I9** A refusal never echoes the hostile input back.
```
youcam-mcp fuzz run: 50000 cases, seed 20261108, 4167 sessions, 1389 days
class generated success refused reached no-net other
-------------------------------------------------------------------
benign 13415 9980 445 0 445 2990
traversal 5190 0 5190 5190 5190 0
ssrf_literal 7273 0 7273 7273 7273 0
ssrf_dns 4086 0 4086 4082 4 0
bad_image 4990 0 4990 4400 590 0
injection 6156 0 6156 6156 6156 0
budget 1553 0 497 0 497 1056
upstream 3196 597 1408 1318 90 1191
malformed_rpc 4141 0 4141 4141 4141 0
-------------------------------------------------------------------
total 50000 10577 34186 32560 24386 5237
hostile cases: 31836 (31836 refused, 0 not refused; 31242 reached their target rule)
units billed by the fake API: 32108 (budgets: 30/session, 60/day; max in one day 60)
control runs (one defence switched off; each must be caught):
DNS address check off (I2) caught
budget checks off (I5) caught
key redaction off (I6) caught
URL allowlist check off (I1) caught
RESULT: PASS: no invariant violated.
```
How to read the table:
- **`reached`** counts cases refused by the rule they were aimed at, not by a budget that had already run out. A fuzz run where everything bounces off the budget looks green and tests nothing. That happened in our first run: only 116 of 280 DNS cases ever reached the DNS check. We rebalanced the sessions until the column said otherwise.
- **`ssrf_dns`** cases do a lookup by design, so they don't count under `no-net`. They show zero connections, which I2 checks.
- **The control runs** each switch one defence off and confirm the harness notices. If a control isn't caught, the run fails, because a harness that can't see a broken defence proves nothing when it's green.
CI runs the unit tests, the fixed-seed 50,000-case harness and a second run with a fresh seed, on Python 3.9, 3.11 and 3.12.
## Live check
`tests/test_live_smoke.py` makes real calls. It's skipped unless both `YOUCAM_API_KEY` and `YOUCAM_LIVE_SMOKE=1` are set, so having the key in your shell can't spend money by accident. Its budget is capped at 3 units, and a run spends 1.
Our run on 8 Nov 2026:
| Step | Result |
|---|---|
| Template list | 3 templates (free) |
| SSRF call | refused, `url_ip_literal` |
| Local-path call | refused, `url_scheme` |
| 20-unit call against a 3-unit budget | refused, `budget_session` |
| Hair colour, preset Copper Red | `success`, 768×1024 PNG on `yce-us.s3-accelerate.amazonaws.com` |
| Account balance | 773 → 772 (1 unit), 11 s end to end |

The person is the AI-generated demo model from our [Before It Falls](https://before-it-falls.netlify.app) build. No real person's photo was used.
The terminal recording above ([cast](demo/demo.cast), [text](demo/demo_transcript.txt)) is a scripted MCP client running against the real server and the real API.
[demo/claude_code_session.txt](demo/claude_code_session.txt) is a real agent, Claude Code in headless mode, using the server. It lists templates, gets the local-path refusal, and asks for an allowlisted URL instead of retrying.
The server was also exercised with the official MCP Inspector CLI.
## Honest limits
- **Unofficial.** API names and costs are taken from docs.perfectcorp.com as of November 2026, and may change.
- **Not a security audit.** The test suite shows how the server behaves against the inputs it generates; it isn't a guarantee. If you find a gap, please open an issue.
- **Pictures aren't judged.** The server checks format and size, not what a photo shows or whether the person in it agreed. YouCam applies its own NSFW filter to results.
- **stdio only.** There's no remote HTTP transport and no OAuth. One server process means one session budget.
- **Interrupted tasks keep their units booked.** If the server stops while a task is still running, those units stay counted for the day. This is the safe direction, but it can over-count.
- **Storage hosts are explicit.** Only the two hosts seen in live runs are allowed by default. An account in another region may get results on a different bucket host; those are withheld until you add the host to `storage_hosts`.
- **DNS has no timeout of its own.** A very slow resolver can hold a call past `fetch_timeout_s`.
- **Four features, not the whole API.** Other YouCam features follow the same pattern and can be added as tools.
## Layout
```
src/youcam_mcp/
policy.py the rules: URL checks, image sniffing, policy file
net.py the only code that opens sockets (address check, no redirects, caps)
budget.py unit ledger, per session and per day
youcam.py API client and redaction
tools.py tool schemas and the order checks run in
server.py JSON-RPC over stdio
tests/ unit tests, fake network, fuzz harness, opt-in live smoke
demo/ recording, transcript, agent session, before/after
```
## License
MIT. See [LICENSE](LICENSE).
---
Built by [AutoMate AI](https://automate-ai.live), the practice of Elite Product LLC. We build agent integrations, MCP servers and showcase apps on other companies' APIs, and test them from the hostile side first. Our two earlier YouCam builds are [Said in Colour](https://said-in-colour.netlify.app) and [Before It Falls](https://before-it-falls.netlify.app).
TDQS
Scored across 6 tools
Each tool maps to a distinct operation: clothes try-on, hairstyle try-on, hair recolouring, skin-tone analysis, task polling, and template listing. The only plausible confusion is try_hairstyle vs try_hair_color, but the descriptions clearly separate style substitution from colouring.
All names are snake_case verb_noun (try_hairstyle, try_hair_color, analyze_skin_tone, get_task_status, list_hairstyle_templates). try_on_clothes inserts a preposition and breaks the otherwise uniform try_<noun> pattern, a minor deviation.
Six tools is a tight, well-scoped set with no redundant entries and each tool earning its place. It sits slightly on the thin side for a multi-capability rendering service, but nothing feels padded.
The async render/poll lifecycle is covered via get_task_status plus a template lister for hairstyles, and styling, colouring, and analysis are all present. However, try_hair_color accepts a 'preset' value while no tool lists available presets (unlike hairstyles), and there is no way to check unit balance or quota, which will cause dead ends.