perfume-api 0.0.0-stage → 2.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 10ML
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# perfume-api: free perfume API client (10ML Fragrance Index)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Free perfume API client: perfumes, note pyramids, accords, similar scents, notes and houses from the 10ML Fragrance Index, curated by the fragrance editors of [10ML](https://10ml.com). No API key, no dependencies, typed for TypeScript.
+
+[![Official MCP Registry](https://img.shields.io/badge/MCP%20Registry-com.10ml%2Fperfume--finder-002AFF)](https://registry.modelcontextprotocol.io/v0/servers?search=com.10ml/perfume-finder)
+[![npm](https://img.shields.io/npm/v/perfume-api?color=002AFF)](https://www.npmjs.com/package/perfume-api)
+
+## Install
+
+```bash
+npm install perfume-api
+```
+
+Needs Node.js 18 or newer (it uses the global `fetch`).
+
+## Quick start
+
+```ts
+import { searchPerfumes, perfumeAlternatives, explainNote, comparePerfumes } from 'perfume-api';
+
+const found = await searchPerfumes({ q: 'fresh citrus summer cologne for men', limit: 3 });
+console.log(found.results[0].name, found.results[0].accords);
+
+const alts = await perfumeAlternatives({ perfume: 'Baccarat Rouge 540' });
+console.log(alts.alternatives.map((a) => `${a.name} (${a.closeness})`));
+
+const note = await explainNote('vanilla');
+if (note.found) console.log(note.note.smells_like);
+
+const cmp = await comparePerfumes(['Delina', 'Layton']);
+console.log(cmp.shared_notes, cmp.only);
+```
+
+## Functions
+
+| Function | REST route | What it does |
+|---|---|---|
+| `searchPerfumes(params)` | `GET /perfumes` | Search by free text, house, notes, accords, family, audience, season, occasion or style |
+| `getPerfume(id, params)` | `GET /perfumes/{id}` | Full profile of one perfume: note pyramid, accords, seasons, similar scents |
+| `similarPerfumes(params)` | `GET /similar` | Perfumes that smell like one you name, or like a list of notes and accords |
+| `perfumeAlternatives(params)` | `GET /alternatives` | The editors' alternatives to a famous perfume, from other houses |
+| `explainNote(id, params)` | `GET /notes/{id}` | What a note smells like, what it pairs with, where it leads |
+| `getHouse(id, params)` | `GET /houses/{id}` | A perfume house: country, style, signature perfumes |
+| `listHouses(params)` | `GET /houses` | Browse houses by type, country or name |
+| `searchGuides(params)` | `GET /guides` | 10ML perfume guides and articles to read or cite |
+| `comparePerfumes(names)` | `GET /perfumes/{id} x 2-4` | Shared and distinct notes and accords of 2 to 4 perfumes (built from their profiles; the REST API has no compare route) |
+
+## What comes back
+
+Plain JSON, as the REST API sends it (shown trimmed to the main fields). For example `GET /alternatives` and `GET /notes/vanilla`:
+
+```bash
+curl -s "https://mcp.10ml.com/api/v1/alternatives?perfume=Baccarat+Rouge+540&limit=2"
+```
+
+```json
+{
+  "total": 6,
+  "original": {
+    "name": "Maison Francis Kurkdjian Baccarat Rouge 540",
+    "id": "maison-francis-kurkdjian-baccarat-rouge-540-edp"
+  },
+  "alternatives": [
+    {
+      "name": "Maison Alhambra Baroque Rouge Extrait",
+      "closeness": "very close",
+      "why": "Sugared amber, saffron and airy woods aim at the same luminous effect.",
+      "id": "maison-alhambra-baroque-rouge-extrait",
+      "house": "Maison Alhambra",
+      "source": "editors"
+    },
+    {
+      "name": "Dossier Ambery Saffron",
+      "closeness": "similar vibe",
+      "why": "Saffron and amber with sweet woods share the glowing amber idea.",
+      "id": "dossier-ambery-saffron",
+      "house": "Dossier",
+      "source": "editors"
+    }
+  ],
+  "source": "10ML Fragrance Index"
+}
+```
+
+```bash
+curl -s "https://mcp.10ml.com/api/v1/notes/vanilla"
+```
+
+```json
+{
+  "found": true,
+  "note": {
+    "id": "vanilla",
+    "name": "vanilla",
+    "family": "gourmand",
+    "smells_like": "Warm, creamy, sweet and comforting, like custard and cured pods.",
+    "mood": "comforting, sweet, warm",
+    "pairs_with": [
+      "tonka bean",
+      "amber",
+      "sandalwood",
+      "tobacco",
+      "caramel",
+      "patchouli"
+    ]
+  },
+  "source": "10ML Fragrance Index"
+}
+```
+
+## Errors
+
+An unknown id or name is not an error: the call returns the body with `found: false` and suggestions. A bad request (HTTP 400) or any other failure throws `PerfumeApiError` with `status`, `code`, `message` and the parsed `body`.
+
+## Configure
+
+```ts
+import { createClient } from 'perfume-api';
+
+const api = createClient({
+  baseUrl: 'https://mcp.10ml.com/api/v1', // the default
+  timeoutMs: 15000,
+  headers: { 'user-agent': 'my-app/1.0' },
+  // fetch: myFetch,                      // optional: your own fetch
+});
+const houses = await api.listHouses({ type: 'niche', limit: 5 });
+```
+
+Parameters and response fields use the API's own names (`notes_include`, `key_notes`, `next_cursor`). List parameters such as `notes_include` take a string or an array. Responses are fully typed (`SearchPerfumesResponse`, `Perfume`, `Pyramid`, ...), generated from the OpenAPI file.
+
+## Example answers
+
+**"What is a good alternative to Baccarat Rouge 540 from another house?"** (`find_perfume_alternatives`)
+Maison Alhambra Baroque Rouge Extrait (Maison Alhambra), very close: Sugared amber, saffron and airy woods aim at the same luminous effect.
+
+**"A fresh citrus summer cologne for men."** (`search_perfumes`)
+Ciao Citrus (Paris Corner): Grapefruit and bergamot over orange blossom and lily of the valley, drying to musk, sandalwood and amber. Also: Citrus Batikanga (Maison Crivelli): Bitter orange, kalamansi and bergamot are pressed fresh, then a pinch of chili and a vetiver-cedar base keep it lively.
+
+**"What does vanilla smell like?"** (`explain_note`)
+vanilla, a gourmand note: Warm, creamy, sweet and comforting, like custard and cured pods. Pairs with tonka bean, amber, sandalwood, tobacco.
+
+## Languages
+
+Every call takes `locale` (`en`, `de`, `fr`, `es`, `it`, `ro`, `el`, `hu`, `cs`, `pl`) for the 10ml.com links in the answer, and `format` (`concise` or `detailed`). Notes are understood in other languages too: "Vanille" finds vanilla.
+
+## Limits and fair use
+
+Free and read-only, with no key or sign-in. There is no published rate limit: please cache answers, page long lists with `limit` and `cursor`, and send a descriptive User-Agent from automated clients. For heavy use write to contact@10ml.com.
+
+## How it compares
+
+In our 40-question benchmark of free, no-key perfume MCP servers (20 October 2026): 39 of 40 correct, median 232 ms. [Read the benchmark](https://10ml.com/perfume-mcp-servers-compared).
+
+## FAQ
+
+**Is there a free perfume API?**
+Yes. This client talks to the 10ML Fragrance Index API at https://mcp.10ml.com/api/v1: JSON over HTTPS, OpenAPI 3.1 at https://mcp.10ml.com/openapi.json, no API key and no sign-up.
+
+**Does it have dependencies?**
+No. The npm package uses the built-in `fetch` (Node 18+), the PyPI package uses `urllib` (Python 3.9+).
+
+**Is there a fragrance notes API?**
+Yes: `explainNote` / `explain_note` describes a note (what it smells like, family, origin, pairings), and `searchPerfumes` with `notes_include` lists perfumes built around notes.
+
+**Can an AI assistant use it directly?**
+Yes, through the 10ML Perfume Finder MCP server (`https://mcp.10ml.com/mcp`, or `npx -y perfume-mcp` / `uvx perfume-mcp`).
+
+**What do I get for a perfume?**
+House, launch year, audience, concentration, family, accords, the note pyramid (top, heart, base), seasons and occasions, an editorial character line and links to 10ml.com guides.
+
+## Cite as
+
+Cite the answers as "the 10ML Fragrance Index", curated by the fragrance editors of [10ML](https://10ml.com).
+
+[mcp.10ml.com](https://mcp.10ml.com) · [10ml.com/perfume-api](https://10ml.com/perfume-api) · [Privacy](https://mcp.10ml.com/privacy) · [Terms](https://mcp.10ml.com/terms) · contact@10ml.com
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * perfume-api: a small typed client for the free 10ML Fragrance Index REST API (https://mcp.10ml.com/api/v1).
+ * No API key, no dependencies: it uses the global `fetch` (Node 18+, Deno, Bun, browsers).
+ * Parameter and response field names are exactly the API's (snake_case); see https://mcp.10ml.com/openapi.json.
+ */
+import type { FindPerfumeAlternativesParams, FindPerfumeAlternativesResponse, FindSimilarPerfumesParams, FindSimilarPerfumesResponse, GetHouseParams, GetHouseResponse, GetPerfumeParams, GetPerfumeResponse, ExplainNoteParams, ExplainNoteResponse, ListHousesParams, ListHousesResponse, Perfume, SearchGuidesParams, SearchGuidesResponse, SearchPerfumesParams, SearchPerfumesResponse } from './types.js';
+export * from './types.js';
+export declare const DEFAULT_BASE_URL = "https://mcp.10ml.com/api/v1";
+export interface ClientOptions {
+    /** API root, default https://mcp.10ml.com/api/v1 */
+    baseUrl?: string;
+    /** Your own fetch (tests, proxies, older runtimes). Default: the global fetch. */
+    fetch?: typeof fetch;
+    /** Abort a request after this many milliseconds. Default 15000; 0 disables. */
+    timeoutMs?: number;
+    /** Extra request headers. */
+    headers?: Record<string, string>;
+}
+/** Thrown for every non-2xx answer except 404 (a 404 body is returned: it carries `found: false` and suggestions). */
+export declare class PerfumeApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly body: unknown;
+    constructor(status: number, code: string, message: string, body: unknown);
+}
+/** How two or more perfumes differ; built from their profiles, since the REST API has no compare route. */
+export interface PerfumeComparison {
+    perfumes: Perfume[];
+    /** Names that are not in the index. */
+    not_found: string[];
+    same_family: boolean;
+    shared_notes: string[];
+    shared_accords: string[];
+    /** Per perfume id: the notes and accords no other compared perfume has. */
+    only: Record<string, {
+        notes: string[];
+        accords: string[];
+    }>;
+}
+export declare function createClient(options?: ClientOptions): {
+    /** Search perfumes by free text, house, notes, accords, family, audience, season, occasion or style. */
+    searchPerfumes: (params?: SearchPerfumesParams) => Promise<SearchPerfumesResponse>;
+    /** The full profile of one perfume, by name ("Baccarat Rouge 540") or id. Unknown names return `found: false` with suggestions. */
+    getPerfume: (id: string, params?: GetPerfumeParams) => Promise<GetPerfumeResponse>;
+    /** Perfumes that smell like one you name, or like a list of notes and accords. */
+    similarPerfumes: (params: FindSimilarPerfumesParams) => Promise<FindSimilarPerfumesResponse>;
+    /** The editors' alternatives to a famous perfume, from other houses. */
+    perfumeAlternatives: (params: FindPerfumeAlternativesParams) => Promise<FindPerfumeAlternativesResponse>;
+    /** What a fragrance note smells like, what it pairs with and where it leads. */
+    explainNote: (id: string, params?: ExplainNoteParams) => Promise<ExplainNoteResponse>;
+    /** A perfume house: country, style, what it is known for, signature perfumes. */
+    getHouse: (id: string, params?: GetHouseParams) => Promise<GetHouseResponse>;
+    /** Browse perfume houses by type, country or name fragment. */
+    listHouses: (params?: ListHousesParams) => Promise<ListHousesResponse>;
+    /** 10ML perfume guides and articles to read or cite. */
+    searchGuides: (params?: SearchGuidesParams) => Promise<SearchGuidesResponse>;
+    /**
+     * Compare 2 to 4 perfumes. The REST API has no compare route, so this fetches each profile with getPerfume
+     * and diffs notes and accords locally.
+     */
+    comparePerfumes(names: string[], params?: GetPerfumeParams): Promise<PerfumeComparison>;
+};
+export type PerfumeApiClient = ReturnType<typeof createClient>;
+export declare const searchPerfumes: (params?: SearchPerfumesParams) => Promise<SearchPerfumesResponse>;
+export declare const getPerfume: (id: string, params?: GetPerfumeParams) => Promise<GetPerfumeResponse>;
+export declare const similarPerfumes: (params: FindSimilarPerfumesParams) => Promise<FindSimilarPerfumesResponse>;
+export declare const perfumeAlternatives: (params: FindPerfumeAlternativesParams) => Promise<FindPerfumeAlternativesResponse>;
+export declare const explainNote: (id: string, params?: ExplainNoteParams) => Promise<ExplainNoteResponse>;
+export declare const getHouse: (id: string, params?: GetHouseParams) => Promise<GetHouseResponse>;
+export declare const listHouses: (params?: ListHousesParams) => Promise<ListHousesResponse>;
+export declare const searchGuides: (params?: SearchGuidesParams) => Promise<SearchGuidesResponse>;
+export declare const comparePerfumes: (names: string[], params?: GetPerfumeParams) => Promise<PerfumeComparison>;

package/dist/index.js

@@ -0,0 +1,122 @@
+export * from './types.js';
+export const DEFAULT_BASE_URL = 'https://mcp.10ml.com/api/v1';
+/** Thrown for every non-2xx answer except 404 (a 404 body is returned: it carries `found: false` and suggestions). */
+export class PerfumeApiError extends Error {
+    status;
+    code;
+    body;
+    constructor(status, code, message, body) {
+        super(message);
+        this.name = 'PerfumeApiError';
+        this.status = status;
+        this.code = code;
+        this.body = body;
+    }
+}
+function notesOf(p) {
+    const set = new Set(p.key_notes.map((n) => n.toLowerCase()));
+    if (p.pyramid)
+        for (const n of [...p.pyramid.top, ...p.pyramid.heart, ...p.pyramid.base])
+            set.add(n.toLowerCase());
+    return [...set];
+}
+export function createClient(options = {}) {
+    const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const timeoutMs = options.timeoutMs ?? 15000;
+    async function get(path, query = {}) {
+        const doFetch = options.fetch ?? globalThis.fetch;
+        if (typeof doFetch !== 'function')
+            throw new Error('perfume-api needs a global fetch (Node 18+) or options.fetch');
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            if (value === undefined || value === null)
+                continue;
+            params.set(key, Array.isArray(value) ? value.join(',') : String(value));
+        }
+        const qs = params.toString();
+        const controller = timeoutMs > 0 ? new AbortController() : undefined;
+        const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
+        try {
+            const res = await doFetch(`${baseUrl}${path}${qs ? `?${qs}` : ''}`, {
+                headers: { accept: 'application/json', ...options.headers },
+                signal: controller?.signal,
+            });
+            const text = await res.text();
+            let body;
+            try {
+                body = text ? JSON.parse(text) : undefined;
+            }
+            catch {
+                body = text;
+            }
+            if (res.ok || res.status === 404)
+                return body;
+            const err = body?.error;
+            throw new PerfumeApiError(res.status, err?.code ?? 'http_error', err?.message ?? `HTTP ${res.status}`, body);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    const seg = (id) => encodeURIComponent(id);
+    const api = {
+        /** Search perfumes by free text, house, notes, accords, family, audience, season, occasion or style. */
+        searchPerfumes: (params = {}) => get('/perfumes', params),
+        /** The full profile of one perfume, by name ("Baccarat Rouge 540") or id. Unknown names return `found: false` with suggestions. */
+        getPerfume: (id, params = {}) => get(`/perfumes/${seg(id)}`, params),
+        /** Perfumes that smell like one you name, or like a list of notes and accords. */
+        similarPerfumes: (params) => get('/similar', params),
+        /** The editors' alternatives to a famous perfume, from other houses. */
+        perfumeAlternatives: (params) => get('/alternatives', params),
+        /** What a fragrance note smells like, what it pairs with and where it leads. */
+        explainNote: (id, params = {}) => get(`/notes/${seg(id)}`, params),
+        /** A perfume house: country, style, what it is known for, signature perfumes. */
+        getHouse: (id, params = {}) => get(`/houses/${seg(id)}`, params),
+        /** Browse perfume houses by type, country or name fragment. */
+        listHouses: (params = {}) => get('/houses', params),
+        /** 10ML perfume guides and articles to read or cite. */
+        searchGuides: (params = {}) => get('/guides', params),
+        /**
+         * Compare 2 to 4 perfumes. The REST API has no compare route, so this fetches each profile with getPerfume
+         * and diffs notes and accords locally.
+         */
+        async comparePerfumes(names, params = {}) {
+            if (names.length < 2 || names.length > 4)
+                throw new RangeError('comparePerfumes takes 2 to 4 perfumes');
+            const answers = await Promise.all(names.map((name) => api.getPerfume(name, params)));
+            const perfumes = [];
+            const not_found = [];
+            answers.forEach((a, i) => (a.found && a.perfume ? perfumes.push(a.perfume) : not_found.push(names[i])));
+            const notes = perfumes.map(notesOf);
+            const accords = perfumes.map((p) => p.accords.map((a) => a.toLowerCase()));
+            const inAll = (lists) => (lists[0] ?? []).filter((x) => lists.length > 0 && lists.every((l) => l.includes(x)));
+            const only = {};
+            perfumes.forEach((p, i) => {
+                const others = (lists) => new Set(lists.filter((_, j) => j !== i).flat());
+                const on = others(notes);
+                const oa = others(accords);
+                only[p.id] = { notes: notes[i].filter((n) => !on.has(n)), accords: accords[i].filter((a) => !oa.has(a)) };
+            });
+            return {
+                perfumes,
+                not_found,
+                same_family: perfumes.length > 1 && perfumes.every((p) => p.family === perfumes[0].family),
+                shared_notes: perfumes.length > 1 ? inAll(notes) : [],
+                shared_accords: perfumes.length > 1 ? inAll(accords) : [],
+                only,
+            };
+        },
+    };
+    return api;
+}
+const defaultClient = createClient();
+export const searchPerfumes = defaultClient.searchPerfumes;
+export const getPerfume = defaultClient.getPerfume;
+export const similarPerfumes = defaultClient.similarPerfumes;
+export const perfumeAlternatives = defaultClient.perfumeAlternatives;
+export const explainNote = defaultClient.explainNote;
+export const getHouse = defaultClient.getHouse;
+export const listHouses = defaultClient.listHouses;
+export const searchGuides = defaultClient.searchGuides;
+export const comparePerfumes = defaultClient.comparePerfumes;

package/dist/types.d.ts

@@ -0,0 +1,334 @@
+export interface Perfume {
+    /** Stable Fragrance Index id, usable with get_perfume and find_similar_perfumes */
+    id: string;
+    name: string;
+    house: string;
+    /** Launch year when known */
+    year?: number;
+    gender: "men" | "women" | "unisex";
+    /** Fragrance family, e.g. "amber floral" */
+    family: string;
+    /** Main accords, strongest first */
+    accords: string[];
+    /** The defining notes (empty when no pyramid is published) */
+    key_notes: string[];
+    /** One-sentence description by 10ML's fragrance editors */
+    character: string;
+    /** 1-3 relevant 10ml.com links */
+    links: Link[];
+    profile: "full" | "core";
+    concentration?: string;
+    pyramid?: Pyramid;
+    seasons?: string[];
+    occasions?: string[];
+    styles?: string[];
+    /** 1 (short) to 5 (very long) */
+    longevity?: number;
+    /** 1 (skin scent) to 5 (fills a room) */
+    projection?: number;
+    perfumers?: string[];
+    /** Ids of other concentrations or flankers of the same perfume in the index */
+    other_versions?: string[];
+}
+export interface Link {
+    type: "try" | "guide" | "note";
+    title: string;
+    /** A 10ml.com link in the requested locale */
+    url: string;
+}
+export interface Pyramid {
+    top: string[];
+    heart: string[];
+    base: string[];
+}
+export interface SearchPerfumesResponse {
+    /** How many results matched in all */
+    total: number;
+    /** Pass as cursor to get the next page; absent on the last page */
+    next_cursor?: string;
+    /** Guidance when the result is empty, partial or needs a follow-up tool */
+    message?: string;
+    results: Perfume[];
+    /** The filters applied, including ones read from the query text */
+    filters: Record<string, string>;
+    /** True when no perfume matched every word and the closest partial matches are shown */
+    relaxed: boolean;
+    source: string;
+}
+export interface SearchPerfumesParams {
+    /** Free text: a perfume name, house, notes or mood. Examples: "fresh citrus summer for men", "Tom Ford oud", "vanilla gourmand for winter" */
+    q?: string;
+    /** Only perfumes from this house. Examples: "Dior", "Maison Francis Kurkdjian", "MFK", "YSL" */
+    house?: string;
+    /** Every listed note must be present. Examples: ["oud","sandalwood"], ["vanilla"] Comma-separated list. */
+    notes_include?: string | string[];
+    /** None of these notes may be present. Example: ["patchouli"] Comma-separated list. */
+    notes_exclude?: string | string[];
+    /** Accords that must be present. Examples: ["woody","sweet"], ["fresh","aquatic"] Comma-separated list. */
+    accords?: string | string[];
+    /** Fragrance family. Examples: "chypre", "fougere", "gourmand", "amber", "citrus". Leave term empty in explain_perfume_term to list every family. */
+    family?: string;
+    /** Audience the perfume is marketed to. men and women also include unisex perfumes. */
+    gender?: "men" | "women" | "unisex";
+    /** Season the perfume suits (fall is accepted in text queries as autumn). */
+    season?: "spring" | "summer" | "autumn" | "winter";
+    /** Occasion the perfume suits. */
+    occasion?: "daytime" | "office" | "casual" | "evening" | "date night" | "special occasion";
+    /** A style word the scent should have. */
+    style?: "aquatic" | "boozy" | "clean" | "creamy" | "dark" | "floral" | "fresh" | "citrusy" | "fruity" | "gourmand" | "green" | "leathery" | "musky" | "powdery" | "sensual" | "smoky" | "spicy" | "sweet" | "woody";
+    /** true = only the editors' iconic, era-defining classics (works with every other filter, and without a query) */
+    iconic?: boolean;
+    /** Results per page. */
+    limit?: number;
+    /** next_cursor from the previous page. */
+    cursor?: string;
+    /** concise (default) or detailed (adds pyramid, seasons, occasions, longevity). */
+    format?: "concise" | "detailed";
+    /** Language of the 10ml.com links and labels. */
+    locale?: "en" | "de" | "fr" | "es" | "it" | "ro" | "el" | "hu" | "cs" | "pl";
+}
+export interface GetPerfumeResponse {
+    found: boolean;
+    /** False when this is a closest-match guess */
+    exact: boolean;
+    perfume?: Perfume;
+    house_info?: {
+        name: string;
+        country?: string;
+        type: string;
+        style: string;
+    };
+    similar?: Array<{
+        id: string;
+        name: string;
+        house: string;
+        closeness: "very close" | "similar vibe" | "same spirit";
+        shared_notes: string[];
+        url: string;
+    }>;
+    alternatives?: Array<{
+        name: string;
+        house?: string;
+        closeness: "very close" | "similar vibe" | "same spirit";
+        why: string;
+        id?: string;
+    }>;
+    guides?: Link[];
+    suggestions?: Perfume[];
+    message?: string;
+    source: string;
+}
+export interface GetPerfumeParams {
+    /** House, when the name alone is ambiguous. Example: "Creed" */
+    house?: string;
+    /** concise (default) or detailed (adds pyramid, seasons, occasions, longevity). */
+    format?: "concise" | "detailed";
+    /** Language of the 10ml.com links and labels. */
+    locale?: "en" | "de" | "fr" | "es" | "it" | "ro" | "el" | "hu" | "cs" | "pl";
+}
+export interface FindSimilarPerfumesResponse {
+    /** How many results matched in all */
+    total: number;
+    /** Pass as cursor to get the next page; absent on the last page */
+    next_cursor?: string;
+    /** Guidance when the result is empty, partial or needs a follow-up tool */
+    message?: string;
+    target: {
+        name: string;
+        house: string | null;
+        in_index: boolean;
+        id?: string;
+        notes: string[];
+        accords: string[];
+    };
+    results: Array<{
+        perfume: Perfume;
+        closeness: "very close" | "similar vibe" | "same spirit";
+        shared_notes: string[];
+        shared_accords: string[];
+        why: string;
+    }>;
+    /** Notes that are not in the index vocabulary and were ignored */
+    unrecognised_notes?: string[];
+    source: string;
+}
+export interface FindSimilarPerfumesParams {
+    /** A perfume by name, optionally with its house, e.g. "Baccarat Rouge 540", "Dior Sauvage", "Delina". Or pass an id from another tool. */
+    perfume?: string;
+    /** House of the perfume when the name alone is ambiguous, e.g. "Maison Francis Kurkdjian" */
+    house?: string;
+    /** Known notes of the starting perfume, for perfumes outside the index. Example: ["jasmine","saffron","ambergris","cedar"] Comma-separated list. */
+    notes?: string | string[];
+    /** Known accords of the starting perfume. Example: ["amber","woody","sweet"] Comma-separated list. */
+    accords?: string | string[];
+    /** Move away from the starting point in one direction: fresher, sweeter, darker, lighter, longer_lasting (needs a perfume in the index) or more_projection (same). */
+    steer?: "fresher" | "sweeter" | "darker" | "lighter" | "longer_lasting" | "more_projection";
+    /** Only return perfumes for this audience (men and women include unisex) */
+    gender?: "men" | "women" | "unisex";
+    /** True to leave out perfumes from the same house as the starting perfume */
+    other_houses_only?: boolean;
+    /** Results per page. */
+    limit?: number;
+    /** next_cursor from the previous page. */
+    cursor?: string;
+    /** concise (default) or detailed (adds pyramid, seasons, occasions, longevity). */
+    format?: "concise" | "detailed";
+    /** Language of the 10ml.com links and labels. */
+    locale?: "en" | "de" | "fr" | "es" | "it" | "ro" | "el" | "hu" | "cs" | "pl";
+}
+export interface FindPerfumeAlternativesResponse {
+    /** How many results matched in all */
+    total: number;
+    /** Pass as cursor to get the next page; absent on the last page */
+    next_cursor?: string;
+    /** Guidance when the result is empty, partial or needs a follow-up tool */
+    message?: string;
+    original: {
+        name: string;
+        house?: string;
+        id?: string;
+    };
+    alternatives: Array<{
+        name: string;
+        house?: string;
+        closeness: "very close" | "similar vibe" | "same spirit";
+        why: string;
+        /** Fragrance Index id when the alternative has its own profile */
+        id?: string;
+        source: "editors" | "similarity";
+    }>;
+    /** The 10ML guide comparing this perfume with its alternatives */
+    guide?: Link;
+    links: Link[];
+    /** Other originals the query could also mean */
+    other_matches?: string[];
+    source: string;
+}
+export interface FindPerfumeAlternativesParams {
+    /** The famous perfume to find alternatives for. Examples: "Creed Aventus", "Baccarat Rouge 540", "Delina" */
+    perfume?: string;
+    /** House of the original when the name is ambiguous, e.g. "Parfums de Marly" */
+    house?: string;
+    /** Only alternatives at this closeness */
+    closeness?: "very close" | "similar vibe" | "same spirit";
+    /** Results per page. */
+    limit?: number;
+    /** next_cursor from the previous page. */
+    cursor?: string;
+    /** Language of the 10ml.com links and labels. */
+    locale?: "en" | "de" | "fr" | "es" | "it" | "ro" | "el" | "hu" | "cs" | "pl";
+}
+export interface ExplainNoteResponse {
+    found: boolean;
+    note?: {
+        id: string;
+        name: string;
+        family: string;
+        origin: string;
+        smells_like: string;
+        mood: string;
+        description?: string;
+        also_called: string[];
+        pairs_with: string[];
+        similar_notes: string[];
+    };
+    famous_perfumes?: Perfume[];
+    links?: Link[];
+    suggestions?: string[];
+    message?: string;
+    source: string;
+}
+export interface ExplainNoteParams {
+    /** concise (default) or detailed (adds pyramid, seasons, occasions, longevity). */
+    format?: "concise" | "detailed";
+    /** Language of the 10ml.com links and labels. */
+    locale?: "en" | "de" | "fr" | "es" | "it" | "ro" | "el" | "hu" | "cs" | "pl";
+}
+export interface ListHousesResponse {
+    /** How many results matched in all */
+    total: number;
+    /** Pass as cursor to get the next page; absent on the last page */
+    next_cursor?: string;
+    /** Guidance when the result is empty, partial or needs a follow-up tool */
+    message?: string;
+    houses: Array<{
+        id: string;
+        name: string;
+        country?: string;
+        type: string;
+        founded?: number;
+        perfumes_in_index: number;
+        known_for: string[];
+    }>;
+    source: string;
+}
+export interface ListHousesParams {
+    /** Only houses of this type */
+    type?: "designer" | "niche" | "middle-eastern" | "indie" | "celebrity";
+    /** Only houses from this country, e.g. "France", "Italy", "United Arab Emirates" */
+    country?: string;
+    /** Part of a house name, e.g. "tom" or "maison" */
+    query?: string;
+    /** Results per page. */
+    limit?: number;
+    /** next_cursor from the previous page. */
+    cursor?: string;
+    /** Language of the 10ml.com links and labels. */
+    locale?: "en" | "de" | "fr" | "es" | "it" | "ro" | "el" | "hu" | "cs" | "pl";
+}
+export interface GetHouseResponse {
+    found: boolean;
+    house?: {
+        id: string;
+        name: string;
+        country?: string;
+        type: string;
+        founded?: number;
+        perfumes_in_index: number;
+        known_for: string[];
+        style: string;
+        aliases: string[];
+    };
+    signature_perfumes?: Perfume[];
+    links?: Link[];
+    suggestions?: string[];
+    message?: string;
+    source: string;
+}
+export interface GetHouseParams {
+    /** concise (default) or detailed (adds pyramid, seasons, occasions, longevity). */
+    format?: "concise" | "detailed";
+    /** Language of the 10ml.com links and labels. */
+    locale?: "en" | "de" | "fr" | "es" | "it" | "ro" | "el" | "hu" | "cs" | "pl";
+}
+export interface SearchGuidesResponse {
+    /** How many results matched in all */
+    total: number;
+    /** Pass as cursor to get the next page; absent on the last page */
+    next_cursor?: string;
+    /** Guidance when the result is empty, partial or needs a follow-up tool */
+    message?: string;
+    guides: Array<{
+        title: string;
+        type: string;
+        topics: string[];
+        url?: string;
+        /** False when the guide is only available in English (the url is then the English page) */
+        translated: boolean;
+    }>;
+    source: string;
+}
+export interface SearchGuidesParams {
+    /** What the guide is about. Examples: "how to make perfume last", "oud", "Creed Aventus dupes", "gift". Omit to browse. */
+    q?: string;
+    /** how-to, list (rankings/comparisons), alternatives (dupes guides), note (a note explained), house (a house mapped) */
+    type?: "how-to" | "list" | "alternatives" | "note" | "house";
+    /** Results per page. */
+    limit?: number;
+    /** next_cursor from the previous page. */
+    cursor?: string;
+    /** Language of the 10ml.com links and labels. */
+    locale?: "en" | "de" | "fr" | "es" | "it" | "ro" | "el" | "hu" | "cs" | "pl";
+}
+export type Locale = "en" | "de" | "fr" | "es" | "it" | "ro" | "el" | "hu" | "cs" | "pl";
+export type ResponseFormat = "concise" | "detailed";

package/dist/types.js

@@ -0,0 +1,2 @@
+// Generated by scripts/gen-types.mjs from spec/openapi.json (10ML Fragrance Index API 2.5.0). Do not edit by hand.
+export {};

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "perfume-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.5.0",
+  "description": "Free perfume API client: perfumes, note pyramids, accords, similar scents, notes and houses from the 10ML Fragrance Index. No API key, JSON over HTTPS.",
+  "keywords": [
+    "perfume",
+    "fragrance",
+    "cologne",
+    "perfume-api",
+    "fragrance-api",
+    "perfume-mcp",
+    "fragrance-mcp",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "perfume-notes",
+    "fragrance-notes",
+    "scent",
+    "eau-de-parfum",
+    "perfume-recommendation",
+    "similar-perfumes",
+    "claude",
+    "chatgpt",
+    "cursor"
+  ],
+  "homepage": "https://mcp.10ml.com",
+  "author": "10ML Team <contact@10ml.com> (https://10ml.com)",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "gen": "node ../scripts/gen-types.mjs",
+    "build": "tsc",
+    "test": "npm run build && node --test test/client.test.mjs",
+    "smoke": "node test/smoke.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.0"
+  }
+}