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.
- package/README.md +42 -15
- 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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
69
|
+
Then fully quit and reopen Claude Code.
|
|
49
70
|
|
|
50
|
-
|
|
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
|
-
**
|
|
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
|
-
-
|
|
157
|
-
-
|
|
158
|
-
-
|
|
159
|
-
-
|
|
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.
|
|
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": {
|