brilliant-directories-mcp 6.3.0 → 6.3.2

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 (2) hide show
  1. package/README.md +42 -15
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -8,9 +8,16 @@ Give any AI agent full access to your Brilliant Directories site with one API ke
8
8
 
9
9
  Manage **members, posts (single-image and multi-image), leads, reviews, top and sub categories, email templates, pages (homepage, landing pages), 301 redirects, smart lists, widgets, menus, forms, tags, membership plans**, and more — across every resource BD exposes via its REST API.
10
10
 
11
+ ## Before you start — 2 things you need
12
+
13
+ 1. **Node.js installed.** If you've never run a terminal command before, install it from [nodejs.org](https://nodejs.org) (pick the "LTS" version, click through the installer). This is a one-time setup.
14
+ 2. **Your BD API key.** In your BD admin: sidebar → **Developer Hub** → **Generate API Key** → copy it.
15
+
16
+ You'll also need your BD site URL — use the FULL url with `https://` and NO trailing slash. Example: `https://mysite.com` (correct). Not `mysite.com`, not `https://mysite.com/`.
17
+
11
18
  ## 30-Second Quickstart
12
19
 
13
- **One command. Answer two questions. Done.**
20
+ Open a terminal (Mac: Terminal.app · Windows: PowerShell · Linux: your shell). Paste:
14
21
 
15
22
  ```bash
16
23
  npx brilliant-directories-mcp --setup
@@ -18,10 +25,20 @@ npx brilliant-directories-mcp --setup
18
25
 
19
26
  The wizard asks for your BD site URL and API key, tests the connection, asks which app you use (Cursor / Claude Desktop / Windsurf / Claude Code), and writes the config for you. No JSON editing.
20
27
 
21
- Restart your app, then ask your AI:
28
+ **Fully quit and reopen your AI app** (not just close the window — fully quit: Mac `Cmd+Q`, Windows right-click taskbar → Quit). Then ask your AI:
29
+
22
30
  > "List members on my BD site"
23
31
 
24
- Get your API key from **BD Admin > Developer Hub > Generate API Key**.
32
+ **Success looks like:** the AI returns a table or list of member names/emails.
33
+ **Failure looks like:** the AI says "I don't have access to that" or "no tools available." If that happens, jump to [Troubleshooting](#troubleshooting) below.
34
+
35
+ ### Updates are automatic
36
+
37
+ Once set up, you get new MCP versions automatically the next time you fully-quit-and-reopen your AI app. No reinstall needed.
38
+
39
+ ### What you can ask the AI to do
40
+
41
+ Once connected, your AI can read AND write to your BD site. Examples: *"list all members who signed up this month"*, *"create a new member named Jane Doe with email jane@...,"* *"add a blog post by member 42 titled Welcome,"* *"show me unpaid invoices,"* *"add Jane to the VIP tag."* If the AI can do something on the site, it can probably do it via your agent now — 164 operations across members, posts, leads, reviews, pages, menus, widgets, and more.
25
42
 
26
43
  ### For AI agents / scripts (non-interactive)
27
44
 
@@ -39,20 +56,23 @@ This runs the full setup end-to-end with no prompts. Replace `cursor` with `clau
39
56
 
40
57
  ### Claude Code / Cursor / Windsurf / Cline (MCP)
41
58
 
42
- **Option A — `npx` (recommended, no install needed):**
59
+ **Easiest path: use the wizard** from the [30-Second Quickstart](#30-second-quickstart) above — it handles all of this automatically.
60
+
61
+ If you prefer to wire things up by hand, here's how per app. Replace `YOUR_KEY` with your BD API key and `https://your-site.com` with your BD site URL (include `https://`, no trailing slash).
62
+
63
+ **Claude Code** — paste this one line in your terminal (Mac: Terminal.app · Windows: PowerShell):
43
64
 
44
65
  ```bash
45
66
  claude mcp add bd-api -- npx brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com
46
67
  ```
47
68
 
48
- **Option B — Global install:**
69
+ Then fully quit and reopen Claude Code.
49
70
 
50
- ```bash
51
- npm install -g brilliant-directories-mcp
52
- claude mcp add bd-api -- brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com
53
- ```
71
+ **Cursor** — open the MCP config file at `~/.cursor/mcp.json` (create it if missing: on Mac/Linux `mkdir -p ~/.cursor && touch ~/.cursor/mcp.json`; on Windows that path is `%USERPROFILE%\.cursor\mcp.json`). Paste the block below into the file, then save. Fully quit and reopen Cursor.
54
72
 
55
- **Cursor / Windsurf / Cline** — add to your MCP config file (`~/.cursor/mcp.json`, etc.):
73
+ **Windsurf** — same JSON format; the file is `~/.codeium/windsurf/mcp_config.json` on Mac/Linux, `%USERPROFILE%\.codeium\windsurf\mcp_config.json` on Windows.
74
+
75
+ **Cline** — same JSON format; the file is `~/Library/Application Support/Cline/MCP/cline_mcp_settings.json` on Mac, `%APPDATA%\Cline\MCP\cline_mcp_settings.json` on Windows.
56
76
 
57
77
  ```json
58
78
  {
@@ -65,6 +85,8 @@ claude mcp add bd-api -- brilliant-directories-mcp --api-key YOUR_KEY --url http
65
85
  }
66
86
  ```
67
87
 
88
+ After saving, **fully quit and reopen** the app (not just close the window — Mac `Cmd+Q`; Windows right-click taskbar → Quit).
89
+
68
90
  Then ask your AI: *"List all members on my BD site"* or *"Create a new member with email john@example.com"*
69
91
 
70
92
  ---
@@ -111,6 +133,8 @@ n8n will prompt for your BD site URL and API key on import. No file editing requ
111
133
 
112
134
  ### curl / Any HTTP Client
113
135
 
136
+ Paste these in a terminal (Mac: Terminal.app · Windows: PowerShell). Replace `YOUR_KEY` and `https://your-site.com` with real values.
137
+
114
138
  ```bash
115
139
  # Verify your API key
116
140
  curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/token/verify
@@ -138,7 +162,7 @@ curl -X PUT -H "X-Api-Key: YOUR_KEY" \
138
162
 
139
163
  ## Troubleshooting
140
164
 
141
- **Verify your setup with one command:**
165
+ **Verify your setup with one command.** Paste in a terminal (Mac: Terminal.app · Windows: PowerShell). Replace `YOUR_KEY` and `https://your-site.com` with real values:
142
166
  ```bash
143
167
  npx brilliant-directories-mcp --verify --api-key YOUR_KEY --url https://your-site.com
144
168
  ```
@@ -153,10 +177,13 @@ Logs every API request and response to stderr (your API key is automatically red
153
177
  > Drop `--verify` to start the full MCP stdio server with debug logging — it will appear to hang in a regular terminal because MCP servers run forever over stdio, waiting for an AI client to connect. Use `--debug --verify` for one-shot debugging from a shell.
154
178
 
155
179
  **Common issues:**
156
- - `401 Unauthorized` — API key is wrong, revoked, or lacks permission for the endpoint
157
- - `404 Not Found` — site URL is wrong (check for typos; `https://` is auto-added if missing)
158
- - `429 Too Many Requests` — rate limit hit (100 req/60s default); back off or increase limit in BD admin
159
- - `Unknown tool` (from Claude) — the MCP server didn't load the OpenAPI spec; reinstall with `npm install -g brilliant-directories-mcp`
180
+ - **AI says "no tools" or "I don't have access"** — you didn't fully quit and reopen your AI app after setup. Fully quit (Mac `Cmd+Q`; Windows right-click taskbar → Quit), then reopen.
181
+ - **`401 Unauthorized`** — API key is wrong, revoked, or lacks permission for the endpoint. Regenerate in BD Admin → Developer Hub.
182
+ - **`403 API Key does not have permission to access this endpoint`** — this specific endpoint isn't granted on your key. Edit the key in BD Admin → Developer Hub and enable the missing endpoint (the error names it).
183
+ - **`404 Not Found`** — your site URL is wrong. Must include `https://` and NO trailing slash. Correct: `https://mysite.com`. Wrong: `mysite.com` or `https://mysite.com/`.
184
+ - **`429 Too Many Requests`** — rate limit hit (100 req/60s default). Wait 60 seconds, or email BD support to raise your site's limit up to 1,000/min.
185
+ - **`Unknown tool` (from Claude)** — the MCP server didn't load the OpenAPI spec; reinstall with `npm install -g brilliant-directories-mcp`.
186
+ - **`npx: command not found`** — Node.js isn't installed. Install from [nodejs.org](https://nodejs.org) (pick LTS).
160
187
 
161
188
  ---
162
189
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "brilliant-directories-mcp",
3
3
  "mcpName": "io.github.brilliantdirectories/brilliant-directories-mcp",
4
- "version": "6.3.0",
4
+ "version": "6.3.2",
5
5
  "description": "Official MCP server for Brilliant Directories — manage members, posts, leads, reviews, and more.",
6
6
  "main": "index.js",
7
7
  "bin": {