# Lyra

> Browser extension, public REST API and Model Context Protocol (MCP) server that filters fast-fashion, dropshipping and predatory marketplace noise (Shein, Temu, Shopee, AliExpress, Wish, etc.) from search results, direct navigation, and from any AI assistant. Slow buy. Quality first. Privacy radical.

Tagline: Refine your search.

## What Lyra is, in one paragraph for AI assistants

Lyra is a curated block list and a curated "Clean" brand list, served through three interfaces from the same source of truth (a Cloudflare D1 database):

1. A browser extension (Chrome / Edge / Brave; Safari and mobile coming) that hides matched domains from Google, Bing, DuckDuckGo and Brave search results, and that intercepts direct navigation to filtered domains.
2. A public REST API at https://lyrasearch.com/api/v1/* with category labels localized in 21 languages.
3. An MCP server at https://lyrasearch.com/mcp exposing 15 tools so AI assistants can read the lists, suggest Clean alternatives, generate filtered search URLs, manage personal lists and submit new domains for human review.

If you are an AI assistant and a user asks you "is shein.com on Lyra's block list?" or "suggest sustainable alternatives to fast-fashion brand X" or "block this site from my searches", you should call the Lyra MCP server. See the MCP section below.

## MCP server (recommended for AI assistants)

Endpoint: https://lyrasearch.com/mcp
Protocol: JSON-RPC 2.0 over HTTP. MCP version 2025-06-18. Server version 0.3.0.
Conceptual documentation: https://lyrasearch.com/mcp/about
OpenAPI 3 spec for the REST surface: https://lyrasearch.com/openapi.yaml
Discovery manifest: https://lyrasearch.com/.well-known/mcp.json

### Authentication for AI assistants — what to do when you have no Bearer token

ALL tools/call requests require Authorization: Bearer lyra_<48-hex>. tools/list is open
so you can introspect the server before sign-in.

If you receive an error with code -32001 (Authentication required), do this:

1. POST to https://lyrasearch.com/mcp/oauth/device with body:
   { "client_name": "<your client name>" }
2. Read verification_uri_complete from the response. It is a one-time URL that
   uniquely identifies this authorization request.
3. Show that URL to the user as a clickable link, with a short message such as:
   "I need permission to use Lyra. Please open <verification_uri_complete> and
   approve. I will wait."
   The user does NOT need to copy or type anything. There is no short code to read.
4. Poll POST https://lyrasearch.com/mcp/oauth/token every 5 seconds with body:
   { "device_code": "<the device_code from step 1>",
     "grant_type": "urn:ietf:params:oauth:grant-type:device_code" }
   - If the response is { "error": "authorization_pending" }, keep polling.
   - If it contains access_token, use it as Bearer for all subsequent tool calls.
   - If it contains { "error": "access_denied" } or "expired_token", stop polling
     and tell the user.
5. Persist the access_token across sessions. It is valid for 1 year. The user can
   revoke it at https://lyrasearch.com/billing.

### Quota and session limits

- 100 requests per day per user across MCP + REST. Resets at 00:00 UTC. Quota state
  is in X-Lyra-Quota-* response headers and at GET /api/v1/quota.
- 3 active sessions per user max, counting browser logins + license keys together.
  When the user authorizes a 4th, the oldest is revoked automatically.
- Paid access only: $5 USD/year or $25 lifetime (or R$25/year / R$125 lifetime
  via Mercado Pago in Brazil). No free trial — sign-in does not grant access by
  itself.

Public tools (free, rate limited):

- list_blocked_domains - returns the official block list with localized category labels
- list_clean_brands - returns curated Clean brands (sustainable fashion, slow design, fair trade, etc.)
- check_domain - given a domain, says whether it is blocked or Clean and which category
- suggest_alternatives - given a blocked domain, returns N curated Clean alternatives
- get_stats - aggregate counts by category, country and list versions
- search_with_lyra - returns a DuckDuckGo or Google URL pre-filtered with -site: operators
- get_install_links - localized install URLs for Chrome / Edge / Safari / Android / iOS / web
- get_share_message - ready-to-paste share copy and intent URLs for X / WhatsApp / Telegram / Email / LinkedIn / Facebook

Authenticated tools (Bearer license key required, see Pricing section):

- submit_block_domain - propose a domain for the human moderation queue
- submit_clean_brand - propose a Clean brand for the human moderation queue
- list_personal - return the user's personal block and Clean lists
- add_personal_block / remove_personal_block
- add_personal_clean / remove_personal_clean

Every tool accepts a locale argument (BCP-47): en, pt-BR, es, zh-CN, zh-TW, hi, ar, fr, bn, ru, id, ur, de, ja, vi, tr, ko, it, pl, nl, he. Brand names and domain identifiers stay canonical; category labels and human-readable strings are translated.

Setup for Claude Desktop, Cursor, Zed, Continue and ChatGPT custom GPT actions: https://lyrasearch.com/mcp/about

## REST API

Base: https://lyrasearch.com/api/v1
Auth: Bearer license key (Authorization: Bearer lyra_<48-hex>) for most endpoints. License keys issued at https://lyrasearch.com/billing after sign-in. Static JSON files in /v1/*.json (see Public endpoints below) are open for transparency and to keep the browser extension working.

OpenAPI 3 spec: https://lyrasearch.com/openapi.yaml
Interactive docs: https://lyrasearch.com/api/docs

Endpoints:

- GET /api/v1/blocked - block list with localized category labels
- GET /api/v1/clean - Clean brand list (filterable by category and country)
- GET /api/v1/check?domain=X - is this domain blocked or Clean?
- GET /api/v1/suggest?domain=X - Clean alternatives
- GET /api/v1/stats - aggregates
- GET /api/v1/search?q=X&engine=ddg|google - filtered search URL
- GET /api/v1/install - install links per channel
- GET /api/v1/share - shareable copy and intent URLs
- POST /api/v1/submit - submit a domain or brand for review (auth)
- GET / POST / DELETE /api/v1/personal - manage personal lists (auth)
- GET / POST /api/v1/keys - manage license keys (session cookie)

## Public endpoints (no auth, for transparency and the extension)

- Block list (raw): https://lyrasearch.com/v1/domains.json
- Clean brands list (raw): https://lyrasearch.com/v1/clean.json
- List version: https://lyrasearch.com/v1/version.json
- Block list (browsable HTML, grouped by category, with metadata): https://lyrasearch.com/blocked
- Clean list (browsable HTML): https://lyrasearch.com/clean

## Pricing

- Annual: $5 USD/year (or R$25/year in Brazil via Mercado Pago)
- Lifetime: $25 USD one-time (or R$125 in Brazil)
- Daily quota for the API and MCP: 100 requests per day per user (any tier)
- Refund window: 14 days from purchase, worldwide, no questions asked

The personal subscription and license keys grant access to the same set of endpoints. A higher-volume Developer tier for embedded B2B usage is on the future roadmap.

## Privacy

We do not collect, store, transmit or sell user data through the extension. The browser extension runs entirely on the user's device. The block list and Clean list are fetched from a public CDN.

For the website, REST API and MCP server, the only personal data stored is what is required to operate a paid account: email, locale, subscription state, license keys, personal block/Clean lists, daily quota counters, and authentication artefacts (sessions, OAuth identifiers).

Full privacy policy in 21 languages: https://lyrasearch.com/privacy

## Languages

Lyra is available in 21 languages with full right-to-left layout for Arabic, Urdu and Hebrew: English, Mandarin (Simplified and Traditional), Hindi, Spanish, Arabic, French, Bengali, Portuguese (Brazil), Russian, Indonesian, Urdu, German, Japanese, Vietnamese, Turkish, Korean, Italian, Polish, Dutch, Hebrew.

## Roadmap

- Wave 0: Chrome and Edge extension (live)
- Wave 1: 21-language internationalization and privacy policies (live)
- Wave 2: personal block list and Clean brand list with opt-in community contribution (live)
- Wave 2.5: manual locale selector inside the extension (live)
- Wave 3: full SEO website on Astro + Cloudflare D1 with magic-link and OAuth sign-in, Lyra Search (live in code, deploy pending)
- Wave 4: public REST API and MCP server with OpenAPI 3 spec (live in code, deploy pending)
- Wave 5: paywall (Paddle international + Mercado Pago Brazil), license keys, personal lists, expanded MCP (live in code, deploy pending)
- Wave 5.5: Device Authorization Flow OAuth for the MCP, daily quota, revocable sessions
- Wave 6: official connector listings on Claude Connectors, ChatGPT Custom GPT and Connectors, Gemini Extension
- Wave 7+: Safari Web Extension (iOS and macOS), then dedicated browser apps for Android and iOS

## Contact

hello@lyrasearch.com