Skip to content

Commit e4822a2

Browse files
0xdidi0xdidi
committed
Initial commit: Noteboxd MCP server
0 parents  commit e4822a2

20 files changed

Lines changed: 2178 additions & 0 deletions

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
name: Bug report
3+
about: Something isn't working
4+
labels: bug
5+
---
6+
7+
**What happened**
8+
A clear description of the bug.
9+
10+
**Tool & arguments**
11+
Which tool did you call, and with what arguments? (Never paste your real `nb_live_` key.)
12+
13+
**Response you got**
14+
The error or unexpected output.
15+
16+
**Environment**
17+
- MCP client (Claude Desktop, Cursor, VS Code, …) and version:
18+
- `@noteboxd/mcp` version:
19+
- Node version (`node -v`):

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
name: Feature request
3+
about: Suggest a tool or improvement
4+
labels: enhancement
5+
---
6+
7+
**What would you like?**
8+
Describe the tool, parameter, or behavior you want.
9+
10+
**Use case**
11+
What are you trying to build or ask your assistant?
12+
13+
**Notes**
14+
This package only wraps public `api.noteboxd.com/v1` endpoints. If you're requesting
15+
data that isn't in the public API yet, say so. It may need an API change first.

‎.github/workflows/ci.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
build:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: pnpm/action-setup@v4
14+
with:
15+
version: 10
16+
- uses: actions/setup-node@v4
17+
with:
18+
node-version: '22'
19+
cache: 'pnpm'
20+
- run: pnpm install --ignore-workspace --frozen-lockfile
21+
- run: pnpm typecheck
22+
- run: pnpm build

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
node_modules/
2+
dist/
3+
*.log
4+
.DS_Store
5+
.env
6+
.env.*

‎.npmignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
src/
2+
examples/
3+
.github/
4+
tsconfig.json
5+
.gitignore
6+
CONTRIBUTING.md
7+
*.log
8+
.DS_Store

‎CONTRIBUTING.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Contributing
2+
3+
This is a thin MCP client over the public [Noteboxd API](https://developers.noteboxd.com).
4+
5+
## Development
6+
7+
```bash
8+
pnpm install --ignore-workspace
9+
cp .env.example .env # add your NOTEBOXD_API_KEY
10+
node --env-file=.env --import tsx src/index.ts # or: NOTEBOXD_API_KEY=... pnpm dev
11+
pnpm build
12+
pnpm typecheck
13+
```
14+
15+
To test against a client, point it at `node dist/index.js` with `NOTEBOXD_API_KEY` set.
16+
17+
## Scope
18+
19+
This package only wraps public `api.noteboxd.com/v1` endpoints. Please keep it that way:
20+
21+
- No internal routes, service tokens, or scraping.
22+
- Each tool maps to one public endpoint. If the API adds an endpoint, add a matching tool in `src/tools.ts`.
23+
- Tools stay read-only.
24+
25+
## Releasing
26+
27+
1. Bump the version in `package.json`, `src/config.ts`, and `server.json`.
28+
2. `pnpm build`
29+
3. `npm publish`
30+
4. Update `server.json` in the MCP registry. Before submitting, add back the `$schema` field
31+
(`https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json`).
32+
33+
## Issues
34+
35+
Include the tool name, the arguments, and the response you got. Do not paste your real API key.

‎LICENSE‎

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

‎README.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Noteboxd MCP
2+
3+
A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an AI assistant
4+
(Claude, ChatGPT, Cursor, and other MCP clients) query the
5+
[Noteboxd](https://www.noteboxd.com) fragrance encyclopedia: fragrances, notes, accords,
6+
brands, perfumers, community reviews, and charts.
7+
8+
[![npm version](https://img.shields.io/npm/v/@noteboxd/mcp?color=2b54d4)](https://www.npmjs.com/package/@noteboxd/mcp)
9+
[![license](https://img.shields.io/npm/l/@noteboxd/mcp?color=2b54d4)](./LICENSE)
10+
11+
Once connected, you can ask things like:
12+
13+
- "I own Oud Wood and Aventus. What else should I try for cold-weather formal wear?"
14+
- "Compare Bleu de Chanel and Dior Sauvage."
15+
- "What are reviewers saying about Baccarat Rouge 540?"
16+
17+
The assistant answers from Noteboxd's data instead of guessing.
18+
19+
## Quickstart
20+
21+
1. Create an API key at [developers.noteboxd.com](https://developers.noteboxd.com). The free tier is 50 calls/day and needs no card.
22+
2. Add the server to your MCP client (see below).
23+
3. Ask your assistant about fragrance.
24+
25+
```bash
26+
NOTEBOXD_API_KEY=nb_live_your_key npx -y @noteboxd/mcp
27+
```
28+
29+
## Install
30+
31+
Every client uses the same command (`npx -y @noteboxd/mcp`) with your key in `NOTEBOXD_API_KEY`.
32+
33+
### Claude Desktop / Claude Code
34+
35+
Add to `claude_desktop_config.json`:
36+
37+
```json
38+
{
39+
"mcpServers": {
40+
"noteboxd": {
41+
"command": "npx",
42+
"args": ["-y", "@noteboxd/mcp"],
43+
"env": { "NOTEBOXD_API_KEY": "nb_live_your_key" }
44+
}
45+
}
46+
}
47+
```
48+
49+
### Cursor
50+
51+
[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000000)](cursor://anysphere.cursor-deeplink/mcp/install?name=noteboxd&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBub3RlYm94ZC9tY3AiXSwiZW52Ijp7Ik5PVEVCT1hEX0FQSV9LRVkiOiJuYl9saXZlX1lPVVJfS0VZIn19)
52+
53+
Then set your real key. Or add the JSON block above to `~/.cursor/mcp.json`.
54+
55+
### VS Code
56+
57+
```json
58+
{
59+
"servers": {
60+
"noteboxd": {
61+
"command": "npx",
62+
"args": ["-y", "@noteboxd/mcp"],
63+
"env": { "NOTEBOXD_API_KEY": "nb_live_your_key" }
64+
}
65+
}
66+
}
67+
```
68+
69+
### Hosted alternative
70+
71+
Noteboxd also runs a hosted MCP server at `https://mcp.noteboxd.com/mcp` (Streamable HTTP, with
72+
OAuth sign-in) if you would rather not run anything locally. This package is the local,
73+
open-source option.
74+
75+
## Tools
76+
77+
All tools are read-only and return JSON. Each call is authenticated with your key and counts
78+
against your Noteboxd developer plan (the free tier covers 50 calls/day).
79+
80+
### Search and discovery
81+
| Tool | Description |
82+
| --- | --- |
83+
| `search` | Search across fragrances, brands, notes, perfumers, collections |
84+
| `search_fragrances` | Filter fragrances by query, brand, note, family, or price range |
85+
| `trending` | Trending searches and most-worn fragrances |
86+
| `list_charts`, `get_chart` | Chart rankings and leaderboards |
87+
88+
### Fragrances
89+
| Tool | Description |
90+
| --- | --- |
91+
| `get_fragrance` | Full profile: notes, accords, perfumer, community score |
92+
| `get_fragrance_reviews` | Paginated community reviews |
93+
| `get_similar_fragrances` | Fragrances with a similar accord profile |
94+
| `get_wearing_stats` | Wearing counts over recent windows |
95+
| `compare_fragrances` | Two fragrances compared side by side |
96+
| `get_review_digest` | Short summary of a fragrance's reviews |
97+
| `batch_get_fragrances` | Up to 50 fragrances by id in one call |
98+
| `enrich_fragrance` | Profile plus notes, accords, reviews, and similar in one call |
99+
100+
### Brands, perfumers, notes
101+
| Tool | Description |
102+
| --- | --- |
103+
| `get_brand`, `list_brand_fragrances` | Brand profile and catalogue |
104+
| `get_perfumer` | Perfumer profile and top creations |
105+
| `list_notes`, `get_note` | Browse notes and single-note profiles |
106+
| `list_accords` | List accord families |
107+
108+
## Configuration
109+
110+
| Variable | Required | Description |
111+
| --- | --- | --- |
112+
| `NOTEBOXD_API_KEY` | yes | Your `nb_live_` key from [developers.noteboxd.com](https://developers.noteboxd.com) |
113+
| `NOTEBOXD_API_BASE_URL` | no | Override the API origin (default `https://api.noteboxd.com`) |
114+
115+
You can also pass the key with `--api-key nb_live_...`.
116+
117+
## How it works
118+
119+
This is a thin local server. It speaks MCP to your client over stdio and forwards each tool call
120+
to `api.noteboxd.com/v1` using your key. It stores no data and holds no credentials beyond the key
121+
you provide.
122+
123+
```
124+
AI client --stdio--> noteboxd-mcp --HTTPS + your key--> api.noteboxd.com/v1
125+
```
126+
127+
## Examples
128+
129+
See [`examples/`](./examples) for runnable code: curl, TypeScript, and Python.
130+
131+
## Pricing
132+
133+
The server is free and open source. API usage follows your Noteboxd developer plan: a free tier
134+
(50 calls/day), then pay-as-you-go per call. Most reads are $0.01; the AI tools cost a few cents.
135+
See [developers.noteboxd.com/pricing](https://developers.noteboxd.com/pricing).
136+
137+
## License
138+
139+
[MIT](./LICENSE)

‎examples/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Examples
2+
3+
Runnable snippets for the Noteboxd API. Each needs a free API key from
4+
[developers.noteboxd.com](https://developers.noteboxd.com):
5+
6+
```bash
7+
export NOTEBOXD_API_KEY=nb_live_your_key
8+
```
9+
10+
| File | Shows |
11+
| --- | --- |
12+
| [`curl.sh`](./curl.sh) | Raw REST calls |
13+
| [`typescript/recommend-agent.ts`](./typescript/recommend-agent.ts) | A small "what to try next" recommender |
14+
| [`python/quickstart.py`](./python/quickstart.py) | Search and fetch a profile in Python |
15+
16+
The MCP server itself needs no code. Point your client at `@noteboxd/mcp` (see the [root README](../README.md)).

‎examples/curl.sh‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#!/usr/bin/env bash
2+
# Raw REST calls against the public Noteboxd API.
3+
# Usage: NOTEBOXD_API_KEY=nb_live_... ./curl.sh
4+
set -euo pipefail
5+
6+
: "${NOTEBOXD_API_KEY:?Set NOTEBOXD_API_KEY (get one at https://developers.noteboxd.com)}"
7+
BASE="${NOTEBOXD_API_BASE_URL:-https://api.noteboxd.com}"
8+
AUTH=(-H "Authorization: Bearer ${NOTEBOXD_API_KEY}")
9+
10+
echo "# Universal search for 'oud'"
11+
curl -s "${AUTH[@]}" "${BASE}/v1/search?q=oud&limit=5"
12+
echo
13+
14+
echo "# Woody fragrances (filtered browse, cursor paginated)"
15+
curl -s "${AUTH[@]}" "${BASE}/v1/fragrances?note=oud&limit=5"
16+
echo
17+
18+
echo "# A note profile"
19+
curl -s "${AUTH[@]}" "${BASE}/v1/notes/oud"
20+
echo
21+
22+
echo "# Trending right now"
23+
curl -s "${AUTH[@]}" "${BASE}/v1/trending?limit=5"
24+
echo

0 commit comments

Comments
 (0)