brilliant-directories-mcp 6.3.3 → 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.
Files changed (2) hide show
  1. package/README.md +115 -48
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -8,88 +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 — 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
-
18
- ## 30-Second Quickstart
19
-
20
- Open a terminal (Mac: Terminal.app · Windows: PowerShell · Linux: your shell). Paste:
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
- 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.
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
- **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:
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
- > "List members on my BD site"
48
+ ---
31
49
 
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.
50
+ ## Setup by Platform
34
51
 
35
- ### Updates are automatic
52
+ Every method below uses this config block — keep it handy. Replace `YOUR_KEY` and `https://your-site.com` with your values:
36
53
 
37
- Once set up, you get new MCP versions automatically the next time you fully-quit-and-reopen your AI app. No reinstall needed.
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
+ ```
38
64
 
39
- ### What you can ask the AI to do
65
+ ---
40
66
 
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"*. 164 operations across members, posts, leads, reviews, pages, menus, widgets, and more.
67
+ ### Cursor (recommended path)
42
68
 
43
- > ⚠️ **The AI can also DELETE and MODIFY live data** — members, posts, pages, tags, etc. Writes go directly to your live site with no undo. Before running bulk or destructive operations, test on ONE record first, and consider taking a backup. If you're unsure, ask the AI to *preview* (list/show) before it *acts*.
69
+ **GUI method (easiest — no terminal needed):**
44
70
 
45
- ### For AI agents / scripts (non-interactive)
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).
46
81
 
47
- If an AI agent is guiding you, it can have you paste a single command with everything prefilled:
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.
48
83
 
49
- ```bash
50
- npx brilliant-directories-mcp --setup --url https://your-site.com --api-key YOUR_KEY --client cursor
51
- ```
84
+ ---
52
85
 
53
- This runs the full setup end-to-end with no prompts. Replace `cursor` with `claude-desktop`, `windsurf`, `claude-code`, or `print` (prints the JSON config instead of writing a file).
86
+ ### Claude Desktop
54
87
 
55
- ---
88
+ **GUI method:**
56
89
 
57
- ## Setup by Platform
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.
58
95
 
59
- ### Claude Code / Cursor / Windsurf / Cline (MCP)
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).
60
97
 
61
- **Easiest path: use the wizard** from the [30-Second Quickstart](#30-second-quickstart) above — it handles all of this automatically.
98
+ ---
62
99
 
63
- 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).
100
+ ### Claude Code
64
101
 
65
- **Claude Code** — paste this one line in your terminal (Mac: Terminal.app · Windows: PowerShell):
102
+ Terminal only (Claude Code has no MCP GUI). Paste in **Terminal.app** (Mac) or **PowerShell** (Windows):
66
103
 
67
104
  ```bash
68
105
  claude mcp add bd-api -- npx brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com
69
106
  ```
70
107
 
71
- Then fully quit and reopen Claude Code.
108
+ Replace `YOUR_KEY` and `https://your-site.com` with your values. Then close and reopen Claude Code.
72
109
 
73
- **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.
110
+ ---
74
111
 
75
- **Windsurf** — same JSON format; the file is `~/.codeium/windsurf/mcp_config.json` on Mac/Linux, `%USERPROFILE%\.codeium\windsurf\mcp_config.json` on Windows.
112
+ ### Windsurf
76
113
 
77
- **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.
114
+ **GUI method:**
78
115
 
79
- ```json
80
- {
81
- "mcpServers": {
82
- "bd-api": {
83
- "command": "npx",
84
- "args": ["-y", "brilliant-directories-mcp", "--api-key", "YOUR_KEY", "--url", "https://your-site.com"]
85
- }
86
- }
87
- }
88
- ```
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
+ ---
89
124
 
90
- After saving, **fully quit and reopen** the app (not just close the window — Mac `Cmd+Q`; Windows right-click taskbar → Quit).
125
+ ### Cline (VS Code extension)
91
126
 
92
- Then ask your AI: *"List all members on my BD site"* or *"Create a new member with email john@example.com"*
127
+ **GUI method:**
128
+
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.
93
136
 
94
137
  ---
95
138
 
@@ -162,6 +205,30 @@ curl -X PUT -H "X-Api-Key: YOUR_KEY" \
162
205
 
163
206
  ---
164
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
+
165
232
  ## Troubleshooting
166
233
 
167
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:
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.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": {