brilliant-directories-mcp 6.3.2 → 6.3.4
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 +148 -62
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,86 +8,131 @@ 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 —
|
|
12
|
-
|
|
13
|
-
1. **Node.js installed.**
|
|
14
|
-
2. **Your BD API key.**
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
11
|
+
## Before you start — 3 things you need
|
|
12
|
+
|
|
13
|
+
1. **Node.js installed.** MCP runs on Node — it's a one-time install from [nodejs.org](https://nodejs.org) (pick the "LTS" version, double-click the installer, click Next through the prompts). 60 seconds.
|
|
14
|
+
2. **Your BD API key.** BD Admin sidebar → **Developer Hub** → **Generate API Key** → copy it.
|
|
15
|
+
3. **Your BD site URL.** Include `https://`, no trailing slash. ✅ `https://mysite.com` · ❌ `mysite.com` · ❌ `https://mysite.com/`
|
|
16
|
+
|
|
17
|
+
## Table of Contents
|
|
18
|
+
|
|
19
|
+
- [Setup by Platform](#setup-by-platform)
|
|
20
|
+
- [Cursor](#cursor-recommended-path)
|
|
21
|
+
- [Claude Desktop](#claude-desktop)
|
|
22
|
+
- [Claude Code](#claude-code)
|
|
23
|
+
- [Windsurf](#windsurf)
|
|
24
|
+
- [Cline (VS Code extension)](#cline-vs-code-extension)
|
|
25
|
+
- [ChatGPT (GPT Actions)](#chatgpt-gpt-actions)
|
|
26
|
+
- [n8n](#n8n)
|
|
27
|
+
- [Make / Zapier](#make--zapier)
|
|
28
|
+
- [curl / any HTTP client](#curl--any-http-client)
|
|
29
|
+
- [What you can ask the AI](#what-you-can-ask-the-ai)
|
|
30
|
+
- [Updates are automatic](#updates-are-automatic)
|
|
31
|
+
- [Troubleshooting](#troubleshooting)
|
|
32
|
+
- [FAQ](#faq)
|
|
33
|
+
- [Authentication, Rate Limits, Pagination, Filtering, Sorting, Resources](#authentication)
|
|
34
|
+
- [Support](#support)
|
|
35
|
+
|
|
36
|
+
## 30-Second Quickstart (try this first)
|
|
37
|
+
|
|
38
|
+
Open a terminal (Mac: **Terminal.app** · Windows: **PowerShell** · Linux: your shell). Paste:
|
|
21
39
|
|
|
22
40
|
```bash
|
|
23
41
|
npx brilliant-directories-mcp --setup
|
|
24
42
|
```
|
|
25
43
|
|
|
26
|
-
|
|
44
|
+
A wizard asks for your URL + API key, tests the connection, asks which app you use, and writes the config file automatically. If it works, **fully quit and reopen your AI app** and [skip to "What you can ask the AI"](#what-you-can-ask-the-ai).
|
|
27
45
|
|
|
28
|
-
|
|
46
|
+
If the wizard errors, hangs, or your AI still says "no tools available" after restart, use the per-platform step-by-step below — it's the same outcome, just done by hand.
|
|
29
47
|
|
|
30
|
-
|
|
31
|
-
|
|
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.
|
|
48
|
+
---
|
|
34
49
|
|
|
35
|
-
|
|
50
|
+
## Setup by Platform
|
|
36
51
|
|
|
37
|
-
|
|
52
|
+
Every method below uses this config block — keep it handy. Replace `YOUR_KEY` and `https://your-site.com` with your values:
|
|
38
53
|
|
|
39
|
-
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"mcpServers": {
|
|
57
|
+
"bd-api": {
|
|
58
|
+
"command": "npx",
|
|
59
|
+
"args": ["-y", "brilliant-directories-mcp", "--api-key", "YOUR_KEY", "--url", "https://your-site.com"]
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
```
|
|
40
64
|
|
|
41
|
-
|
|
65
|
+
---
|
|
42
66
|
|
|
43
|
-
###
|
|
67
|
+
### Cursor (recommended path)
|
|
44
68
|
|
|
45
|
-
|
|
69
|
+
**GUI method (easiest — no terminal needed):**
|
|
46
70
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
71
|
+
1. Open Cursor.
|
|
72
|
+
2. **Settings menu**:
|
|
73
|
+
- Mac: menu bar → **Cursor → Settings → Cursor Settings**
|
|
74
|
+
- Windows / Linux: **File → Preferences → Cursor Settings**
|
|
75
|
+
- (Or Command Palette: `Cmd/Ctrl + Shift + P` → type "Open MCP Settings")
|
|
76
|
+
3. Click **Tools & MCP** in the left sidebar.
|
|
77
|
+
4. Click **New MCP Server**.
|
|
78
|
+
5. Paste the config block above. Replace `YOUR_KEY` and `https://your-site.com` with your values.
|
|
79
|
+
6. Click Save.
|
|
80
|
+
7. **Fully quit and reopen Cursor** (menu bar → Quit; or Mac `Cmd+Q`; or Windows right-click the taskbar icon → Quit).
|
|
50
81
|
|
|
51
|
-
|
|
82
|
+
**File method (fallback):** edit `~/.cursor/mcp.json` (Mac/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows). Paste the config block, save, fully quit and reopen Cursor.
|
|
52
83
|
|
|
53
84
|
---
|
|
54
85
|
|
|
55
|
-
|
|
86
|
+
### Claude Desktop
|
|
56
87
|
|
|
57
|
-
|
|
88
|
+
**GUI method:**
|
|
58
89
|
|
|
59
|
-
|
|
90
|
+
1. Open Claude Desktop.
|
|
91
|
+
2. From the **menu bar** (top of screen on Mac, top of app window on Windows): **Settings → Developer tab → Edit Config**. (This opens the config file in your default text editor.)
|
|
92
|
+
3. Paste the config block above into the file. Save.
|
|
93
|
+
4. **Fully quit and reopen Claude Desktop** (Mac `Cmd+Q`; Windows right-click taskbar icon → Quit).
|
|
94
|
+
5. **Verify:** open a new chat. Look at the bottom-right of the input box for a hammer 🔨 icon with a number. That's the tool count. Click it to see the BD tools listed.
|
|
60
95
|
|
|
61
|
-
|
|
96
|
+
Config file path (in case you want to edit directly): `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
|
|
97
|
+
|
|
98
|
+
---
|
|
62
99
|
|
|
63
|
-
|
|
100
|
+
### Claude Code
|
|
101
|
+
|
|
102
|
+
Terminal only (Claude Code has no MCP GUI). Paste in **Terminal.app** (Mac) or **PowerShell** (Windows):
|
|
64
103
|
|
|
65
104
|
```bash
|
|
66
105
|
claude mcp add bd-api -- npx brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com
|
|
67
106
|
```
|
|
68
107
|
|
|
69
|
-
Then
|
|
108
|
+
Replace `YOUR_KEY` and `https://your-site.com` with your values. Then close and reopen Claude Code.
|
|
70
109
|
|
|
71
|
-
|
|
110
|
+
---
|
|
72
111
|
|
|
73
|
-
|
|
112
|
+
### Windsurf
|
|
74
113
|
|
|
75
|
-
**
|
|
114
|
+
**GUI method:**
|
|
76
115
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
116
|
+
1. Open Windsurf.
|
|
117
|
+
2. Click **Windsurf - Settings** at bottom-right (or Command Palette: `Cmd/Ctrl + Shift + P` → "Open Windsurf Settings").
|
|
118
|
+
3. Go to **Cascade** section → find **Model Context Protocol (MCP)** → enable it.
|
|
119
|
+
4. In the **Cascade panel**, click the **MCPs icon** (top-right) → **Configure** (opens the config file).
|
|
120
|
+
5. Paste the config block above. Save.
|
|
121
|
+
6. **Fully quit and reopen Windsurf.**
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
### Cline (VS Code extension)
|
|
87
126
|
|
|
88
|
-
|
|
127
|
+
**GUI method:**
|
|
89
128
|
|
|
90
|
-
|
|
129
|
+
1. Open VS Code with Cline installed.
|
|
130
|
+
2. Click the **Cline icon** in the sidebar to open the Cline panel.
|
|
131
|
+
3. Click the **MCP Servers icon** in Cline's top navigation bar.
|
|
132
|
+
4. Click **Configure MCP Servers** (opens the config file in VS Code).
|
|
133
|
+
5. Paste the config block above. Save.
|
|
134
|
+
6. Back in the MCP Servers panel, you should see `bd-api` — toggle it **on** if not already.
|
|
135
|
+
7. Reload the Cline panel (or close/reopen VS Code) if the tools don't appear.
|
|
91
136
|
|
|
92
137
|
---
|
|
93
138
|
|
|
@@ -160,6 +205,30 @@ curl -X PUT -H "X-Api-Key: YOUR_KEY" \
|
|
|
160
205
|
|
|
161
206
|
---
|
|
162
207
|
|
|
208
|
+
## What you can ask the AI
|
|
209
|
+
|
|
210
|
+
Once connected, your AI can **read AND write** to your BD site. Example prompts:
|
|
211
|
+
|
|
212
|
+
- *"List all members who signed up this month"*
|
|
213
|
+
- *"Create a new member named Jane Doe with email jane@example.com"*
|
|
214
|
+
- *"Add a blog post by member 42 titled 'Welcome to our directory'"*
|
|
215
|
+
- *"Show me unpaid invoices"*
|
|
216
|
+
- *"Add Jane to the VIP tag"*
|
|
217
|
+
- *"Set up a new landing page at /promo with a hero section"*
|
|
218
|
+
|
|
219
|
+
164 operations across members, posts, leads, reviews, pages, menus, widgets, email templates, categories, and more.
|
|
220
|
+
|
|
221
|
+
**What success looks like:** the AI returns the data you asked for, or confirms the action with a new ID.
|
|
222
|
+
**What failure looks like:** the AI says "I don't have access to that," "no tools available," or "unknown function." → jump to [Troubleshooting](#troubleshooting).
|
|
223
|
+
|
|
224
|
+
> ⚠️ **The AI can also DELETE and MODIFY live data.** Writes go directly to your live site — no undo. Before running bulk or destructive operations, test on ONE record first. Consider a backup. If unsure, ask the AI to *preview* (list/show) before it *acts*.
|
|
225
|
+
|
|
226
|
+
## Updates are automatic
|
|
227
|
+
|
|
228
|
+
Once set up, you get new MCP versions automatically the next time you fully quit and reopen your AI app. No reinstall needed.
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
163
232
|
## Troubleshooting
|
|
164
233
|
|
|
165
234
|
**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:
|
|
@@ -232,7 +301,7 @@ Multiple filters:
|
|
|
232
301
|
GET /api/v2/user/get?property[]=city&property_value[]=Los Angeles&property[]=state_code&property_value[]=CA
|
|
233
302
|
```
|
|
234
303
|
|
|
235
|
-
Operators: `=`, `LIKE`,
|
|
304
|
+
Operators: `=`, `>`, `<`, `>=`, `<=`. Additional operators (`LIKE`, `!=`, `in`, `not_in`, `not_like`, `is_null`, `is_not_null`, `between`) are in QA and rolling out across endpoints shortly. For now, stick with `=` for string match, or enumerate and filter client-side.
|
|
236
305
|
|
|
237
306
|
## Sorting
|
|
238
307
|
|
|
@@ -288,18 +357,7 @@ curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/user/fields
|
|
|
288
357
|
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/data_posts/fields?form_name=my-form
|
|
289
358
|
```
|
|
290
359
|
|
|
291
|
-
##
|
|
292
|
-
|
|
293
|
-
| File | Purpose |
|
|
294
|
-
|------|---------|
|
|
295
|
-
| [`openapi/bd-api.json`](openapi/bd-api.json) | OpenAPI 3.1 spec (single source of truth) |
|
|
296
|
-
| [`mcp/index.js`](mcp/index.js) | MCP server for Claude/Cursor |
|
|
297
|
-
| [`mcp/package.json`](mcp/package.json) | npm package definition |
|
|
298
|
-
| [`docs/*.md`](docs/) | Raw API endpoint documentation |
|
|
299
|
-
| [`LICENSE`](LICENSE) | MIT License |
|
|
300
|
-
| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
|
|
301
|
-
|
|
302
|
-
### Stable asset URLs
|
|
360
|
+
## Stable asset URLs
|
|
303
361
|
|
|
304
362
|
For tools that import specs by URL (ChatGPT Actions, n8n, Postman):
|
|
305
363
|
|
|
@@ -315,7 +373,35 @@ https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp
|
|
|
315
373
|
- API key permissions control which endpoints are accessible
|
|
316
374
|
- Treat your API key like a password
|
|
317
375
|
|
|
376
|
+
## FAQ
|
|
377
|
+
|
|
378
|
+
**Does this cost anything?**
|
|
379
|
+
The MCP server is free (MIT license, open source). Your AI agent's subscription (Claude, Cursor, etc.) is separate. API calls to your BD site count against your site's rate limit but don't cost extra.
|
|
380
|
+
|
|
381
|
+
**Is my data sent to Anthropic / OpenAI / third parties?**
|
|
382
|
+
Your BD site data passes from your BD site directly to the AI client on your machine, then to the AI provider you use (Anthropic, OpenAI, etc.) as part of your conversation with the AI. The MCP server itself doesn't relay data anywhere else — no telemetry, no third-party servers in between.
|
|
383
|
+
|
|
384
|
+
**Can I connect more than one BD site?**
|
|
385
|
+
Yes. Add multiple entries under `mcpServers` with different names (e.g. `bd-site-a`, `bd-site-b`), each with its own API key and URL. Your AI will see tools from both.
|
|
386
|
+
|
|
387
|
+
**Can my team share one key, or should everyone have their own?**
|
|
388
|
+
Each person should generate their own API key (BD Admin → Developer Hub). Keys are per-user so revoking one doesn't break anyone else.
|
|
389
|
+
|
|
390
|
+
**How do I disconnect / remove the MCP?**
|
|
391
|
+
- Claude Code: `claude mcp remove bd-api`
|
|
392
|
+
- Cursor / Windsurf / Cline: delete the `bd-api` entry from the MCP config JSON file, save, fully quit and reopen the app.
|
|
393
|
+
|
|
394
|
+
**How do I undo something the AI did?**
|
|
395
|
+
BD's API doesn't have a universal undo. For members, prefer `updateUser active=3` (Canceled) over `deleteUser` — it's reversible. For destructive operations, back up first or test on one record.
|
|
396
|
+
|
|
397
|
+
**Can I try this safely on a test site before production?**
|
|
398
|
+
Yes. Generate a separate API key on a BD staging/dev site, set that URL + key in your MCP config. Once you trust the workflow, switch to production.
|
|
399
|
+
|
|
400
|
+
**How do I know which endpoints my API key has permission for?**
|
|
401
|
+
Check your key in BD Admin → Developer Hub. When you hit `403 API Key does not have permission to access this endpoint`, the error names the denied endpoint — enable it on the key, save, retry.
|
|
402
|
+
|
|
318
403
|
## Support
|
|
319
404
|
|
|
320
|
-
-
|
|
321
|
-
-
|
|
405
|
+
- **Bug reports / feature requests:** https://github.com/brilliantdirectories/brilliant-directories-mcp/issues
|
|
406
|
+
- **BD Support:** https://support.brilliantdirectories.com
|
|
407
|
+
- **API Docs:** https://support.brilliantdirectories.com/support/solutions/articles/12000108045
|
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.4",
|
|
5
5
|
"description": "Official MCP server for Brilliant Directories — manage members, posts, leads, reviews, and more.",
|
|
6
6
|
"main": "index.js",
|
|
7
7
|
"bin": {
|