@10ml/perfume-finder-mcp 2.3.4 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +114 -50
  2. package/dist/index.js +1 -1
  3. package/package.json +15 -21
package/README.md CHANGED
@@ -1,92 +1,156 @@
1
- # 10ML Perfume Finder (perfume MCP server, stdio)
1
+ # 10ML Perfume Finder: free perfume MCP server and perfume API
2
2
 
3
- 10ML Perfume Finder is the free perfume MCP server and fragrance API, powered by the 10ML Fragrance Index and curated by the fragrance editors of [10ML](https://10ml.com): 5,400+ designer, niche and Middle-Eastern perfumes and 249 houses (481 full editorial profiles with longevity, projection and perfumers, the rest as core profiles with notes, accords and character), 285 notes explained, editorial alternatives to famous perfumes, layering ideas and 164 guides in ten languages. In our 40-question benchmark of free perfume MCP servers (20 October 2026) it was the most accurate and the fastest: 39 of 40 correct, one call per question, median 232 ms.
4
-
5
- Free, read-only, no sign-in, no API key. This package runs the 10ML Fragrance Index over **stdio**, so desktop clients that start local commands (Claude Desktop, Cursor, Goose, Windsurf, Cline, Zed) can use it with one line. The same server is also reachable directly over Streamable HTTP at `https://mcp.10ml.com/mcp`, with nothing to install.
3
+ Free fragrance knowledge for AI assistants: 6,000+ perfumes and 249 houses from the 10ML Fragrance Index, with note pyramids, accords, similar scents and alternatives. No API key, no sign-up, read-only.
6
4
 
5
+ [![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)
7
6
  [![npm](https://img.shields.io/npm/v/@10ml/perfume-finder-mcp?color=002AFF)](https://www.npmjs.com/package/@10ml/perfume-finder-mcp)
8
- [![license](https://img.shields.io/npm/l/@10ml/perfume-finder-mcp?color=002AFF)](LICENSE)
9
7
 
10
- ## Quick start
8
+ This package (`@10ml/perfume-finder-mcp`) runs the 10ML Fragrance Index over **stdio**, for clients that start local commands. The same server answers directly over Streamable HTTP at `https://mcp.10ml.com/mcp`, with nothing to install.
9
+
10
+ ## Connect in 10 seconds
11
+
12
+ **Claude, ChatGPT and other clients that take a URL** (nothing to install): add the connector URL `https://mcp.10ml.com/mcp`. In Claude: Customize, Connectors, + Add, Add custom connector (no sign-in). In ChatGPT: Plugins, +, Add custom MCP server, authentication none (on the web for Business, Enterprise and Edu, and on Pro). In Claude Code:
11
13
 
12
14
  ```bash
13
- npx -y @10ml/perfume-finder-mcp
15
+ claude mcp add --transport http perfume-finder https://mcp.10ml.com/mcp
14
16
  ```
15
17
 
16
- ### Claude Desktop
18
+ **Claude Desktop, Cursor, Windsurf, Cline, Zed and other clients that start a local command** use this package:
19
+
20
+ ```bash
21
+ npx -y @10ml/perfume-finder-mcp
22
+ ```
17
23
 
18
- `Settings → Developer → Edit Config`, then add:
24
+ Claude Desktop (`Settings, Developer, Edit Config`) and Cursor (`~/.cursor/mcp.json`) take the same block:
19
25
 
20
26
  ```json
21
27
  {
22
28
  "mcpServers": {
23
29
  "perfume-finder": {
24
30
  "command": "npx",
25
- "args": ["-y", "@10ml/perfume-finder-mcp"]
31
+ "args": [
32
+ "-y",
33
+ "@10ml/perfume-finder-mcp"
34
+ ]
26
35
  }
27
36
  }
28
37
  }
29
38
  ```
30
39
 
31
- ### Cursor
40
+ Goose (`goose configure`, Add Extension, Command-line Extension): command `npx -y @10ml/perfume-finder-mcp`.
32
41
 
33
- `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
42
+ ## Why agents pick it
43
+
44
+ - Free, with no API key, no account and no sign-in.
45
+ - 15 read-only tools with output schemas, 6 prompts and resources, in ten languages.
46
+ - Curated by 10ML's fragrance editors: every perfume has its note pyramid (top, heart, base), accords, family, seasons and occasions.
47
+ - 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).
48
+
49
+ ## Tools (15, all read-only)
50
+
51
+ | Tool | What it does | Example question |
52
+ |---|---|---|
53
+ | `search_perfumes` | Find perfumes and fragrances by name, notes, accords, family, audience, season, occasion or style. | "A fresh citrus summer cologne for men" |
54
+ | `get_perfume` | The full profile of one perfume: note pyramid, accords, seasons, similar scents. | "What notes are in Delina?" |
55
+ | `compare_perfumes` | Two to four perfumes side by side: shared notes, differences, which is fresher or longer lasting. | "Delina or Layton for a winter evening?" |
56
+ | `find_similar_perfumes` | Perfumes that smell like one you love, or like a list of notes. Steer fresher, sweeter or darker. | "Smells like Sauvage but fresher" |
57
+ | `find_perfume_alternatives` | The editors' alternatives to a famous perfume, from other houses. | "An alternative to Baccarat Rouge 540" |
58
+ | `recommend_perfumes` | Picks from what you love, dislike and avoid, with the reason for each. | "I love Delina and vanilla, nothing too sweet, for winter evenings" |
59
+ | `perfumes_by_note` | Perfumes built around a note, strongest first. | "Perfumes with oud" |
60
+ | `explain_note` | What a note smells like, what it pairs with and where it leads. | "What does ambroxan smell like?" |
61
+ | `get_house` | A perfume house: country, style, what it is known for, signature perfumes. | "Tell me about Creed" |
62
+ | `list_houses` | Browse perfume houses by type or country. | "Which niche houses are from Italy?" |
63
+ | `explain_perfume_term` | Perfume vocabulary and the fragrance families. | "What is the difference between EDT and EDP?" |
64
+ | `suggest_layering` | Which notes or perfumes layer well, and how to spray them. | "How do I layer vanilla and citrus?" |
65
+ | `pick_for_occasion` | Perfumes for a season, an occasion, an audience and a style. | "A fresh summer office scent for men" |
66
+ | `find_gift` | Gift ideas from who it is for and what they love. | "A gift for a woman who loves Delina" |
67
+ | `search_guides` | 10ML perfume guides and articles to read or cite, in ten languages. | "How do I make perfume last longer?" |
68
+
69
+ ## REST quick start
70
+
71
+ The same index is available as plain JSON over GET (OpenAPI 3.1: https://mcp.10ml.com/openapi.json; output shown trimmed to the main fields):
72
+
73
+ ```bash
74
+ curl -s "https://mcp.10ml.com/api/v1/alternatives?perfume=Baccarat+Rouge+540&limit=2"
75
+ ```
34
76
 
35
77
  ```json
36
78
  {
37
- "mcpServers": {
38
- "perfume-finder": {
39
- "command": "npx",
40
- "args": ["-y", "@10ml/perfume-finder-mcp"]
79
+ "total": 6,
80
+ "original": {
81
+ "name": "Maison Francis Kurkdjian Baccarat Rouge 540",
82
+ "id": "maison-francis-kurkdjian-baccarat-rouge-540-edp"
83
+ },
84
+ "alternatives": [
85
+ {
86
+ "name": "Maison Alhambra Baroque Rouge Extrait",
87
+ "closeness": "very close",
88
+ "why": "Sugared amber, saffron and airy woods aim at the same luminous effect.",
89
+ "id": "maison-alhambra-baroque-rouge-extrait",
90
+ "house": "Maison Alhambra",
91
+ "source": "editors"
92
+ },
93
+ {
94
+ "name": "Dossier Ambery Saffron",
95
+ "closeness": "similar vibe",
96
+ "why": "Saffron and amber with sweet woods share the glowing amber idea.",
97
+ "id": "dossier-ambery-saffron",
98
+ "house": "Dossier",
99
+ "source": "editors"
41
100
  }
42
- }
101
+ ],
102
+ "source": "10ML Fragrance Index"
43
103
  }
44
104
  ```
45
105
 
46
- ### Goose
106
+ A typed client for it: `perfume-api` on [npm](https://www.npmjs.com/package/perfume-api) and [PyPI](https://pypi.org/project/perfume-api/).
47
107
 
48
- ```bash
49
- goose configure # Add Extension → Command-line Extension
50
- # command: npx -y @10ml/perfume-finder-mcp
51
- ```
108
+ ## Example answers
52
109
 
53
- Or in `~/.config/goose/config.yaml`:
54
-
55
- ```yaml
56
- extensions:
57
- perfume-finder:
58
- name: 10ML Fragrance Index
59
- type: stdio
60
- cmd: npx
61
- args: ["-y", "@10ml/perfume-finder-mcp"]
62
- enabled: true
63
- timeout: 300
64
- ```
110
+ **"What is a good alternative to Baccarat Rouge 540 from another house?"** (`find_perfume_alternatives`)
111
+ Maison Alhambra Baroque Rouge Extrait (Maison Alhambra), very close: Sugared amber, saffron and airy woods aim at the same luminous effect.
65
112
 
66
- ### Windsurf, Cline, Zed and other clients
113
+ **"A fresh citrus summer cologne for men."** (`search_perfumes`)
114
+ 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.
67
115
 
68
- Use the same `command` and `args` as above in the client's MCP settings. Clients that accept a URL can skip this package: `https://mcp.10ml.com/mcp` (Streamable HTTP, no authentication).
116
+ **"What does vanilla smell like?"** (`explain_note`)
117
+ vanilla, a gourmand note: Warm, creamy, sweet and comforting, like custard and cured pods. Pairs with tonka bean, amber, sandalwood, tobacco.
69
118
 
70
- ## What you can ask
119
+ ## Languages
71
120
 
72
- - "What smells like Baccarat Rouge 540, and what is a good alternative from another house?"
73
- - "A fresh summer office scent for men, and why each one fits."
74
- - "Explain ambroxan and which perfumes lead with it."
75
- - "How would I layer vanilla and citrus?"
76
- - "Compare Dior Sauvage and Tom Ford Ombre Leather."
121
+ Every tool takes `locale` (`en`, `de`, `fr`, `es`, `it`, `ro`, `el`, `hu`, `cs`, `pl`: English, German, French, Spanish, Italian, Romanian, Greek, Hungarian, Czech, Polish) for the 10ml.com links in the answer, and `response_format` (`concise` or `detailed`). Notes are understood in other languages too: "Vanille" finds vanilla.
77
122
 
78
- ## Tools (15, all read-only)
123
+ ## Limits and fair use
124
+
125
+ 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.
126
+
127
+ ## How it compares
128
+
129
+ 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).
130
+
131
+ ## FAQ
132
+
133
+ **What is a perfume MCP server?**
134
+ An MCP server lets an AI assistant such as Claude, ChatGPT or Cursor call tools. A perfume MCP server gives it perfume knowledge: notes, accords, similar scents, alternatives and houses. This one is free and needs no API key.
135
+
136
+ **Is there a free perfume API?**
137
+ Yes. The same index is available as plain JSON over HTTPS at https://mcp.10ml.com/api/v1 with an OpenAPI 3.1 description at https://mcp.10ml.com/openapi.json. No API key, no sign-up. The `perfume-api` packages on npm and PyPI wrap it in a typed client.
138
+
139
+ **Do I need an API key or an account?**
140
+ No. It is free, read-only and needs no key, account or sign-in.
79
141
 
80
- `search_perfumes`, `get_perfume`, `compare_perfumes`, `find_similar_perfumes`, `find_perfume_alternatives`, `recommend_perfumes`, `perfumes_by_note`, `explain_note`, `get_house`, `list_houses`, `explain_perfume_term`, `suggest_layering`, `pick_for_occasion`, `find_gift`, `search_guides` (`search_perfumes` with `iconic: true` lists the editors' iconic classics). Plus six prompts and the `tenml://` resources (families, glossary, notes, houses, about, one profile per perfume). Every tool takes `locale` (`en`, `de`, `fr`, `es`, `it`, `ro`, `el`, `hu`, `cs`, `pl`) and `response_format` (`concise` or `detailed`).
142
+ **How do I find a perfume similar to another one?**
143
+ Ask your assistant "what smells like Baccarat Rouge 540?" and it calls `find_similar_perfumes`, which ranks perfumes by shared notes, accords and style and says how close each one is (very close, similar vibe, same spirit). Over REST: `GET /api/v1/similar?perfume=Baccarat+Rouge+540`.
81
144
 
82
- Full documentation: [mcp.10ml.com](https://mcp.10ml.com) and [github.com/10ml-com/perfume-finder-mcp](https://github.com/10ml-com/perfume-finder-mcp).
145
+ **Is there a fragrance notes API?**
146
+ Yes. `GET /api/v1/notes/vanilla` explains a note (what it smells like, family, origin, pairings), and `GET /api/v1/perfumes?notes_include=vanilla,oud` lists perfumes built around notes. Every perfume profile carries its top, heart and base notes.
83
147
 
84
- ## How it works
148
+ ## Cite as
85
149
 
86
- The package starts a small stdio MCP server and passes each request to `https://mcp.10ml.com/mcp`, which answers it. It needs internet access and Node.js 18 or newer, and it stores nothing on your machine. Cite the answers as "the 10ML Fragrance Index".
150
+ Cite the answers as "the 10ML Fragrance Index", curated by the fragrance editors of [10ML](https://10ml.com).
87
151
 
88
- ## About 10ML
152
+ [mcp.10ml.com](https://mcp.10ml.com) · [10ml.com/perfume-mcp-server](https://10ml.com/perfume-mcp-server) · [Privacy](https://mcp.10ml.com/privacy) · [Terms](https://mcp.10ml.com/terms) · contact@10ml.com
89
153
 
90
- 10ML is a European perfume house of decants: original designer and niche fragrances in 3ml, 10ml and 30ml sizes, shipped across Europe. Explore at [10ml.com](https://10ml.com).
154
+ ## License
91
155
 
92
- [Privacy](https://mcp.10ml.com/privacy) · [Terms](https://mcp.10ml.com/terms) · contact@10ml.com · MIT license
156
+ MIT (the packages). Registry name: `com.10ml/perfume-finder`.
package/dist/index.js CHANGED
@@ -10,7 +10,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
10
10
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
11
11
  import { CallToolRequestSchema, CallToolResultSchema, CompleteRequestSchema, CompleteResultSchema, GetPromptRequestSchema, GetPromptResultSchema, ListPromptsRequestSchema, ListPromptsResultSchema, ListResourcesRequestSchema, ListResourcesResultSchema, ListResourceTemplatesRequestSchema, ListResourceTemplatesResultSchema, ListToolsRequestSchema, ListToolsResultSchema, ReadResourceRequestSchema, ReadResourceResultSchema, } from '@modelcontextprotocol/sdk/types.js';
12
12
  const REMOTE_URL = 'https://mcp.10ml.com/mcp';
13
- const PACKAGE_VERSION = '2.3.4';
13
+ const PACKAGE_VERSION = '2.5.0';
14
14
  async function main() {
15
15
  const remote = new Client({ name: '10ml-perfume-finder-stdio', version: PACKAGE_VERSION });
16
16
  await remote.connect(new StreamableHTTPClientTransport(new URL(REMOTE_URL)));
package/package.json CHANGED
@@ -1,36 +1,30 @@
1
1
  {
2
2
  "name": "@10ml/perfume-finder-mcp",
3
- "version": "2.3.4",
3
+ "version": "2.5.0",
4
4
  "mcpName": "com.10ml/perfume-finder",
5
- "description": "10ML Perfume Finder: the free perfume MCP server and fragrance API for AI assistants. 5,400+ perfumes and 249 houses from the 10ML Fragrance Index with note pyramids, accords, similar scents and alternatives. Stdio for Claude Desktop, Cursor, Goose and any MCP client.",
5
+ "description": "10ML Perfume Finder: the free perfume MCP server and fragrance API for AI assistants. 6,000+ perfumes and 249 houses from the 10ML Fragrance Index with note pyramids, accords, similar scents and alternatives. Stdio for Claude Desktop, Cursor, Goose and any MCP client.",
6
6
  "keywords": [
7
- "mcp",
8
- "mcp-server",
9
- "model-context-protocol",
10
7
  "perfume",
11
8
  "fragrance",
12
- "perfume-finder",
13
- "fragrance-notes",
14
- "claude",
15
- "cursor",
16
- "goose",
9
+ "cologne",
17
10
  "perfume-api",
18
11
  "fragrance-api",
19
- "fragrance-notes-api",
20
- "perfume-database",
21
12
  "perfume-mcp",
22
- "ai-assistant",
13
+ "fragrance-mcp",
14
+ "mcp",
15
+ "mcp-server",
16
+ "model-context-protocol",
17
+ "perfume-notes",
18
+ "fragrance-notes",
19
+ "scent",
20
+ "eau-de-parfum",
21
+ "perfume-recommendation",
22
+ "similar-perfumes",
23
+ "claude",
23
24
  "chatgpt",
24
- "fragrantica-alternative"
25
+ "cursor"
25
26
  ],
26
27
  "homepage": "https://mcp.10ml.com",
27
- "repository": {
28
- "type": "git",
29
- "url": "git+https://github.com/10ml-com/perfume-finder-mcp.git"
30
- },
31
- "bugs": {
32
- "url": "https://github.com/10ml-com/perfume-finder-mcp/issues"
33
- },
34
28
  "author": "10ML Team <contact@10ml.com> (https://10ml.com)",
35
29
  "license": "MIT",
36
30
  "type": "module",