TATUAT.RO — server MCP
Catalogul tatuat.ro — echipament de tatuaj și piercing — disponibil
pentru ChatGPT, Claude și orice agent AI. Caută produse, verifică stocul real, calculează
transportul și generează un link de comandă, direct din conversație.
🟢 Live:
https://api.tatuat.ro/mcp · transport streamable HTTP · fără autentificare
> English — MCP server exposing the TATUAT.RO catalog (tattoo &
> piercing supplies, Romania) to AI agents. Live at https://api.tatuat.ro/mcp, streamable
> HTTP, no auth required. Six tools: product search, category browsing, product detail,
> real-time stock, shipping calculator, and a signed checkout link. Prices in RON.
> Read-only except the checkout link — the purchase is completed on tatuat.ro.
Ce poate face un agent
| Tool | Ce face |
|---|---|
search_products |
Caută după nume, brand sau tip de produs. Întoarce preț în RON, disponibilitate și link direct la fișă. |
browse_category |
O pagină de produse dintr-o categorie (sau din tot catalogul), cu sortare. |
get_product |
Fișa completă: descriere, preț efectiv, preț dinainte de reducere, brand, variante cu preț și stoc propriu. |
get_stock |
Disponibilitatea reală pentru o cantitate cerută. Patru stări: integral, parțial, pe comandă, indisponibil. |
calculate_shipping |
Cost de transport, pragul de transport gratuit și cadourile atinse la prag. |
create_checkout |
Link semnat către coșul de pe tatuat.ro. Valabil 15 minute. |
Primele cinci sunt read-only — nu scriu nimic. Al șaselea generează doar un link; nu
plasează comanda și nu atinge baza de date.
Exemplu
> — Am nevoie de cartușe 0.30 RL, vreo 20 de bucăți. Cât mă costă cu transport?
Agentul apelează search_products → get_stock → calculate_shipping, răspunde cu prețul
real și cu cât mai trebuie până la transport gratuit, apoi create_checkout dă linkul pe
care clientul finalizează comanda pe tatuat.ro.
Cum îl conectezi
Claude Code```bash
claude mcp add --transport http tatuat https://api.tatuat.ro/mcp
**Claude Desktop** — Settings → Connectors → Add custom connector → `https://api.tatuat.ro/mcp`
**Orice client MCP** — endpoint streamable HTTP, protocol `2025-06-18`, fără token.
## Prețuri și monedă
Prețul contractual e **RON**, etichetat explicit în fiecare răspuns. Magazinul are și prețuri
în HUF (rată fixă), dar nu se expun aici: un preț fără etichetă de monedă, citit de un model,
e exact felul în care un client ajunge să creadă că plătește altă sumă.
La produsele cu variante (mărimi, configurații) prețul întors e **minimul dintre variante**,
marcat `price_from: true` ca agentul să spună „de la X RON", nu „X RON".
## Ce NU face
- **Nu scrie nimic** în baza de date. Niciun tool nu mutează stare.
- **Nu ține coș pe server.** Coșul trăiește pe tatuat.ro.
- **Nu autentifică utilizatori.** OAuth e fază ulterioară.
- **Nu procesează plăți.** Checkout-ul se finalizează pe tatuat.ro — cerință explicită OpenAI
pentru plugin-uri („external checkout").
- **Linkul de checkout nu conține prețuri.** Transportă doar intenția (produs, variantă,
cantitate); prețul final se calculează și se confirmă pe site.
---
# Pentru dezvoltatori
## Rute
| Rută | Metode | Ce face |
|---|---|---|
| `/mcp` | POST, GET, DELETE | Endpointul MCP. Toate trei delegate pachetului, ca 405-ul să vină de la protocol, nu de la Next. |
| `/.well-known/mcp-server-card.json` | GET | Cartea de vizită a serverului. |
| `/.well-known/openai-apps-challenge` | GET | Verificarea proprietății domeniului. Întoarce **doar** tokenul din `OPENAI_APPS_CHALLENGE_TOKEN`; **404** dacă lipsește. |
## Allowlist de gazde
Marginea HTTP validează `Host` și `Origin` împotriva unei allowlist **statice** din
`MCP_ALLOWED_HOSTS` (implicit `api.tatuat.ro`). Lista nu se derivă niciodată din cererea
însăși — o allowlist construită din propriul header `Host` ar accepta trivial o pagină de
DNS rebinding.
Consecințe care **arată ca defecțiuni, dar sunt intenționate**:
- Un URL de preview Vercel primește 403 — nu e în allowlist. Adaugă hostul în
`MCP_ALLOWED_HOSTS` pentru acel environment; nu relaxa validarea.
- `Host` absent → 403 (`missing_host`), fail-closed: clienții MCP trimit mereu `Host`.
- `Origin` absent → **trece**. Polaritate opusă față de `Host`: clienții non-browser nu
trimit `Origin`, iar a-i respinge ar rupe exact clientul pentru care există serverul. Un
`Origin` prezent dar de pe alt host, sau literalul `null`, primește 403.
- Validarea e port-agnostică și normalizează majusculele.
Refuzul are formă JSON-RPC cu status 403, nu HTML — un client MCP îl poate parsa.
## Variabile de mediu
Numele sunt în `.env.example`, fără valori. Valorile vin din env-ul
proiectului Vercel în producție și din macOS Keychain la setup local — niciodată din repo.
| Variabilă | Obligatorie | Notă |
|---|---|---|
| `SUPABASE_URL` | da | PostgREST, server-to-server |
| `SUPABASE_ANON_KEY` | da | Cheia **anon**, nu `service_role`: tot ce citesc tool-urile e deja public prin RLS |
| `AGENT_CHECKOUT_SECRET` | pentru `create_checkout` | Aceeași valoare și în proiectul site-ului |
| `MCP_ALLOWED_HOSTS` | nu | Implicit `api.tatuat.ro`. Listă separată prin virgulă |
| `TATUAT_SITE_URL` | nu | Implicit `https://tatuat.ro` |
| `OPENAI_APPS_CHALLENGE_TOKEN` | la submission | Dat de portalul OpenAI |
## Arhitectură
- **Logica în `.mjs`, glue-ul în `.ts`.** `app/**/route.ts` sunt delegări pure, fără nicio
decizie: repo-ul nu are teste pe `.ts`, deci un `.ts` nu are voie să conțină ceva care
poate greși. Tot ce decide ceva e în `src/**/*.mjs`, acoperit de `node --test`.
- **Fără `@supabase/supabase-js`.** Acces direct pe PostgREST cu `fetch` — CORS e o
restricție de browser, nu se aplică server-to-server.
- **Rate limiting singleton la nivel de modul.** `createMcpHandler` rulează factory-ul pe
fiecare cerere; o găleată creată în factory s-ar reseta de fiecare dată. Plafonul e
per-instanță de funcție, deci „best effort", nu global.
- **RO-only deliberat.** `p_lang` nu se trimite, deci produsele doar-Ungaria nu apar.
Fail-closed.
- **Proiect separat de magazin**, ca un tool schimbat să nu ceară redeploy al site-ului.
## Comenzi```bash
npm run test # node --test pe src/mcp, src/mcp/tools, src/well-known
npm run typecheck # tsc --noEmit — vede și .mjs (checkJs + include)
npm run test:critical # ambele
npm run dev # Next dev pe :3000
npm run build # next build
Gardă înainte de push```bash
git config core.hooksPath .githooks
```
Activează .githooks/pre-push, care rulează test:critical
și oprește push-ul dacă pică ceva. O singură dată pe clonă. Ocolire, când chiar
trebuie: git push --no-verify.
npm run typecheck acoperă și fișierele .mjs (checkJs: true plus "**/*.mjs" în
include). Fără acele două linii, gate-ul privea zero fișiere și trecea mereu.
Magazinul: tatuat.ro — echipament profesional de tatuaj și piercing.
