# fraglet.com

> The consumer platform for fraglets: portable, user-owned slices of taste. Users create fraglets in specific domains (music, food, travel, hobbies), compose them into **jackets** (named personas for different moods or situations), and share them across services. This site hosts the canonical MCP server for agents acting on behalf of fraglet users.

## What an agent can do here

If you are helping a user who has a fraglet.com account, you can load their taste into your session in one tool call — no questionnaire. You can also help them create new fraglets, refine existing ones, and compose them into jackets. And you can discover which other services accept fraglets, so a taste profile built here pays off everywhere in the ecosystem.

The authoritative guide for agents is **[/skill.md](https://fraglet.com/skill.md)** — read that first. This file is the compact index.

## Connect via MCP

- MCP endpoint: `https://fraglet.com/mcp/` (Streamable HTTP, MCP protocol 2025-06-18)
- Auth: **static per-user Bearer token**, not OAuth. The user generates theirs on [fraglet.com/account](https://fraglet.com/account). Send as `Authorization: Bearer <token>` on every request.
- Unauthenticated discovery:
  - `GET https://fraglet.com/mcp/info` — single-call summary of transport, auth, protocol, and where to get a token. The fastest way for a fresh client to orient itself.
  - `GET https://fraglet.com/.well-known/oauth-protected-resource/mcp` — RFC 9728 Protected Resource Metadata. 401 responses from the MCP endpoint also include `WWW-Authenticate: Bearer resource_metadata="..."` pointing here.
- **No OAuth flow.** fraglet.com does not run an authorization server. Clients must provide a valid per-user bearer token in the initial request — there is no dynamic client registration or token exchange. With a valid token, `mcp-remote` and similar clients work as-is, since the first POST to `/mcp/` succeeds and no OAuth flow is triggered. If the token is missing or expired, clients fall into an OAuth re-auth path; fraglet.com returns well-formed OAuth error JSON (not HTML 404) at `/register`, `/token`, and `/authorize` so client error parsers don't crash.
- Claude Desktop config uses `npx mcp-remote` to bridge HTTP → stdio. See skill.md or [fraglet.com/mcp-setup](https://fraglet.com/mcp-setup) for the exact block.
- Local stdio mode also supported: `python -m fraglets_mcp` with `FRAGLET_API_KEY` env var (developer key, not user MCP token).

## MCP tools

Fraglet lifecycle:
- `list_my_fraglets(domain?)` — list the user's fraglets, optionally filtered
- `get_fraglet(fraglet_id, include_embedding?)` — fetch one
- `discover_fraglets(domain?, category?, limit?)` — browse open fraglets from other users
- `create_fraglet(title, brief, detail, domain, category?, tags?, visibility?)` — create new
- `refine_fraglet(fraglet_id, feedback)` — iterative improvement
- `review_fraglets()` — LLM-ready review of all the user's fraglets
- `update_fraglet_visibility(fraglet_id, visibility, confirm_open?)` — change private / selective / open; open requires two-step confirm
- `associate_with_fraglet(fraglet_id)` — adopt someone else's fraglet into the user's collection
- `combine_fraglets(fraglet_ids)` — merge multiple fraglets into a combined view
- `import_memory_export(export_text)` — bulk-convert an LLM memory export into fraglets

Skill-based (no server-side LLM — you do the reasoning):
- `select_fraglets(intent, jacket_id?, jacket_strict?)` — returns the user's fraglets plus guidance on picking the right ones at the right detail level
- `taste_services(services)` — returns the user's fraglets alongside service descriptions plus guidance on evaluating fit. Max 10 services per call.

Cross-service sharing (preferred over making fraglets open):
- `grant_service_access(fraglet_id, service_name)` — let a specific service read a `selective` fraglet
- `revoke_service_access(fraglet_id, service_name)`

Jackets (named fraglet collections, used as personas):
- `create_jacket(name, description, fraglet_ids?)`
- `list_my_jackets()`
- `get_jacket(jacket_id)`
- `discover_jackets(limit?)`
- `associate_with_jacket(jacket_id, follow?)` — follow=true keeps in sync, false snapshots
- `adapt_jacket(jacket_id, ...)` — fork with modifications (required once a jacket has other associations)
- `manage_jacket_fraglets(jacket_id, add_ids?, remove_ids?)` — edit contents

Ecosystem discovery:
- `discover_services()` — list services that accept fraglets (MostMaker, LabCurate, etc.) with their supported domains

## MCP resources

- `fraglets://mine` — the user's fraglets as a loadable resource
- `fraglets://mine/{domain}` — filtered by domain
- `fraglets://import-prompt` — guidance for exporting fraglets from other LLM memory systems

## Web API (agents can also call these directly)

- `GET /api/auth/me` — check auth status
- `GET /api/my-fraglets` — list user's fraglets (JSON)
- `GET /api/discover` — discover open fraglets (JSON)
- `POST /api/pick` — server-side picker (LLM runs on our side, returns recommendations)
- `POST /api/taste` — server-side taster (LLM runs on our side, returns service verdicts)
- `POST /api/fraglet/<id>` — create/patch fraglet
- `POST /api/fraglet/<id>/share-link` — creator-only; mints a signed share-link URL for human sharing of private fraglets
- `GET /f/<id>` — public fraglet detail page; accepts `?s=<sig>` capability for private or selective fraglets
- `GET /api/shared-fraglet/<id>?s=` — JSON used by the public detail page; no auth
- `GET /api/mcp-config` — authenticated: returns the user's MCP config JSON

Prefer MCP tools over REST endpoints where possible. The REST endpoints exist for the web UI; the MCP tools are shaped for agents.

## Key rules for agents

1. **Always get user approval** for create, edit, delete, and visibility changes. Especially for `open` — it is permanent and globally discoverable.
2. **Prefer `selective` + `grant_service_access`** over `open` when a specific service needs read access. Selective sharing is the designed path for cross-service use.
3. **Memory boundaries**: when tasting, picking, or recommending, evaluate only against the fraglet data the tool returned. Do not use conversation history or prior knowledge about the user. Do not absorb fraglet content into your model of the user — they may be wearing a jacket or browsing someone else's.
4. **Writing style**: concrete and specific. Name things. No filler, no clichés, no superlatives. The `detail` field is embedded for vector matching — pack it with specifics.
5. **Jackets are moods, not categories**. A jacket cuts across domains. Don't assume stereotypical groupings.
6. **Typical flow**: `taste_services` → you assess fit → `select_fraglets` with context → present the selected fraglets to the service that scored well.

## Ecosystem

- [fraglet.org](https://fraglet.org/llms.txt) — format spec, developer API, ecosystem registry (services.json)
- [mostmaker.com](https://mostmaker.com/llms.txt) — London taste-matched recommendations (restaurants, gigs, Proms)
- [labcurate.com](https://labcurate.com/llms.txt) — UK testing lab capability advisor

---

last-verified: 2026-04-11
source-of-truth: fraglets_mcp/server.py (tools + resources), fraglet_web/app/routes.py (web API), fraglet_web/app/templates/skill.md (authoritative agent guide)