brilliant-directories-mcp 1.0.0
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/LICENSE +21 -0
- package/README.md +280 -0
- package/index.js +478 -0
- package/package.json +47 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Brilliant Directories
|
|
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.
|
package/README.md
ADDED
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
# Brilliant Directories API — Universal AI Integration
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/brilliant-directories-mcp)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](https://modelcontextprotocol.io)
|
|
6
|
+
|
|
7
|
+
Give any AI agent full access to your BD site with one API key.
|
|
8
|
+
|
|
9
|
+
**154 endpoints** across 28 resources: members, leads, posts, reviews, categories, email templates, smart lists, widgets, menus, forms, membership plans, and more.
|
|
10
|
+
|
|
11
|
+
## 30-Second Quickstart
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
# 1. Verify your credentials work (no install — uses npx)
|
|
15
|
+
npx brilliant-directories-mcp --verify --api-key YOUR_KEY --url https://your-site.com
|
|
16
|
+
|
|
17
|
+
# 2. Connect to Claude Code
|
|
18
|
+
claude mcp add bd-api -- npx brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com
|
|
19
|
+
|
|
20
|
+
# 3. Ask Claude: "List all members on my BD site"
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
That's it. Get your API key from **BD Admin > Settings > API Keys > Create New Key**.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Setup by Platform
|
|
28
|
+
|
|
29
|
+
### Claude Code / Cursor / Windsurf / Cline (MCP)
|
|
30
|
+
|
|
31
|
+
**Option A — `npx` (recommended, no install needed):**
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
claude mcp add bd-api -- npx brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
**Option B — Global install:**
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install -g brilliant-directories-mcp
|
|
41
|
+
claude mcp add bd-api -- brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
**Cursor / Windsurf / Cline** — add to your MCP config file (`~/.cursor/mcp.json`, etc.):
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"mcpServers": {
|
|
49
|
+
"bd-api": {
|
|
50
|
+
"command": "npx",
|
|
51
|
+
"args": ["-y", "brilliant-directories-mcp", "--api-key", "YOUR_KEY", "--url", "https://your-site.com"]
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Then ask your AI: *"List all members on my BD site"* or *"Create a new member with email john@example.com"*
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
### ChatGPT (GPT Actions)
|
|
62
|
+
|
|
63
|
+
1. In your GPT: **Configure > Actions > Create new action**
|
|
64
|
+
2. Under **Schema**, choose **Import from URL** and paste:
|
|
65
|
+
```
|
|
66
|
+
https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/openapi/bd-api.json
|
|
67
|
+
```
|
|
68
|
+
3. When prompted for `bd_site_url`, enter your BD site (e.g., `https://mysite.com`)
|
|
69
|
+
4. Set Authentication: **API Key**, Auth Type: **Custom**, Header Name: `X-Api-Key`, paste your key
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
### n8n
|
|
74
|
+
|
|
75
|
+
**Option A — Import OpenAPI spec (recommended):**
|
|
76
|
+
|
|
77
|
+
Import the spec URL as a custom API definition:
|
|
78
|
+
```
|
|
79
|
+
https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/openapi/bd-api.json
|
|
80
|
+
```
|
|
81
|
+
n8n will prompt for your BD site URL and API key on import. No file editing required.
|
|
82
|
+
|
|
83
|
+
**Option B — Plain HTTP Request node:**
|
|
84
|
+
|
|
85
|
+
1. Create a new workflow, add an **HTTP Request** node
|
|
86
|
+
2. Set:
|
|
87
|
+
- Method: `GET`
|
|
88
|
+
- URL: `https://your-site.com/api/v2/user/get`
|
|
89
|
+
- Header: `X-Api-Key: YOUR_KEY`
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
### Make / Zapier
|
|
94
|
+
|
|
95
|
+
**Make:** Create a custom app using the OpenAPI spec, or use HTTP module with `X-Api-Key` header.
|
|
96
|
+
|
|
97
|
+
**Zapier:** If you already have the BD Zapier app, it uses the same underlying API. For new endpoints, use Webhooks by Zapier with the `X-Api-Key` header.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
### curl / Any HTTP Client
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
# Verify your API key
|
|
105
|
+
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/token/verify
|
|
106
|
+
|
|
107
|
+
# List members
|
|
108
|
+
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/user/get?limit=10
|
|
109
|
+
|
|
110
|
+
# Create a member
|
|
111
|
+
curl -X POST -H "X-Api-Key: YOUR_KEY" \
|
|
112
|
+
-d "email=new@example.com&password=secret123&subscription_id=1&first_name=Jane&last_name=Doe" \
|
|
113
|
+
https://your-site.com/api/v2/user/create
|
|
114
|
+
|
|
115
|
+
# Search members
|
|
116
|
+
curl -X POST -H "X-Api-Key: YOUR_KEY" \
|
|
117
|
+
-d "q=dentist&address=Los Angeles&limit=10" \
|
|
118
|
+
https://your-site.com/api/v2/user/search
|
|
119
|
+
|
|
120
|
+
# Update a member
|
|
121
|
+
curl -X PUT -H "X-Api-Key: YOUR_KEY" \
|
|
122
|
+
-d "user_id=42&company=New Company Name" \
|
|
123
|
+
https://your-site.com/api/v2/user/update
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Troubleshooting
|
|
129
|
+
|
|
130
|
+
**Verify your setup with one command:**
|
|
131
|
+
```bash
|
|
132
|
+
npx brilliant-directories-mcp --verify --api-key YOUR_KEY --url https://your-site.com
|
|
133
|
+
```
|
|
134
|
+
Prints `OK` if credentials work, `FAIL` with the error otherwise. Good first step for any connectivity issue.
|
|
135
|
+
|
|
136
|
+
**Debug mode — see exactly what's happening:**
|
|
137
|
+
```bash
|
|
138
|
+
npx brilliant-directories-mcp --debug --verify --api-key YOUR_KEY --url https://your-site.com
|
|
139
|
+
```
|
|
140
|
+
Logs every API request and response to stderr (your API key is automatically redacted), then exits. Useful when something isn't working and you want to share output with BD support.
|
|
141
|
+
|
|
142
|
+
> 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.
|
|
143
|
+
|
|
144
|
+
**Common issues:**
|
|
145
|
+
- `401 Unauthorized` — API key is wrong, revoked, or lacks permission for the endpoint
|
|
146
|
+
- `404 Not Found` — site URL is wrong (check for typos; `https://` is auto-added if missing)
|
|
147
|
+
- `429 Too Many Requests` — rate limit hit (100 req/60s default); back off or increase limit in BD admin
|
|
148
|
+
- `Unknown tool` (from Claude) — the MCP server didn't load the OpenAPI spec; reinstall with `npm install -g brilliant-directories-mcp`
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Authentication
|
|
153
|
+
|
|
154
|
+
All requests require the `X-Api-Key` header:
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
X-Api-Key: your-api-key-here
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
API keys are scoped by permission — you control which endpoints each key can access.
|
|
161
|
+
|
|
162
|
+
## Rate Limits
|
|
163
|
+
|
|
164
|
+
**Default:** 100 requests per 60 seconds per API key.
|
|
165
|
+
**On request:** up to 1,000 requests per minute — contact the Brilliant Directories support team to have your site's limit raised (any value between 100 and 1,000/min).
|
|
166
|
+
|
|
167
|
+
> The limit is set server-side by BD, not a self-service setting in your admin. If you expect heavy API usage, email BD support before bulk operations and ask for a temporary or permanent increase.
|
|
168
|
+
|
|
169
|
+
When exceeded, the API returns `HTTP 429 Too Many Requests`. The MCP server surfaces this as an actionable error for your AI agent — it will know to back off or recommend requesting a higher limit.
|
|
170
|
+
|
|
171
|
+
**Plan bulk operations:** if you're asking your agent to import/update hundreds of records, either (a) request a higher limit from BD support first, or (b) tell the agent to pace itself (e.g., *"import these 500 members, pausing to respect the 100/min rate limit"*).
|
|
172
|
+
|
|
173
|
+
## Pagination
|
|
174
|
+
|
|
175
|
+
All list endpoints support pagination:
|
|
176
|
+
|
|
177
|
+
| Parameter | Description |
|
|
178
|
+
|-----------|-------------|
|
|
179
|
+
| `limit` | Records per page (default 25, max 100) |
|
|
180
|
+
| `page` | Cursor token from `next_page` in previous response |
|
|
181
|
+
|
|
182
|
+
Response includes: `total`, `current_page`, `total_pages`, `next_page`, `prev_page`
|
|
183
|
+
|
|
184
|
+
## Filtering
|
|
185
|
+
|
|
186
|
+
All list endpoints support filtering:
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
GET /api/v2/user/get?property=city&property_value=Los Angeles&property_operator==
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Multiple filters:
|
|
193
|
+
```
|
|
194
|
+
GET /api/v2/user/get?property[]=city&property_value[]=Los Angeles&property[]=state_code&property_value[]=CA
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Operators: `=`, `LIKE`, `>`, `<`, `>=`, `<=`
|
|
198
|
+
|
|
199
|
+
## Sorting
|
|
200
|
+
|
|
201
|
+
```
|
|
202
|
+
GET /api/v2/user/get?order_column=last_name&order_type=ASC
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## Available Resources
|
|
206
|
+
|
|
207
|
+
| Resource | Base Path | Operations |
|
|
208
|
+
|----------|-----------|------------|
|
|
209
|
+
| Users/Members | `/api/v2/user/` | list, get, create, update, delete, search, login, transactions, subscriptions |
|
|
210
|
+
| Reviews | `/api/v2/users_reviews/` | list, get, create, update, delete, search |
|
|
211
|
+
| Clicks | `/api/v2/users_clicks/` | list, get, create, update, delete |
|
|
212
|
+
| Leads | `/api/v2/leads/` | list, get, create, match, update, delete |
|
|
213
|
+
| Lead Matches | `/api/v2/lead_matches/` | list, get, create, update, delete |
|
|
214
|
+
| Posts | `/api/v2/data_posts/` | list, get, create, update, delete, search, fields |
|
|
215
|
+
| Portfolio Groups | `/api/v2/users_portfolio_groups/` | list, get, create, update, delete, search, fields |
|
|
216
|
+
| Portfolio Photos | `/api/v2/users_portfolio/` | list, get, create, update, delete |
|
|
217
|
+
| Post Types | `/api/v2/data_categories/` | list, get, create, update, delete, custom_fields |
|
|
218
|
+
| Categories | `/api/v2/category/` | list, get, create, update, delete |
|
|
219
|
+
| Category Groups | `/api/v2/category_group/` | list, get, create, update, delete |
|
|
220
|
+
| Services | `/api/v2/list_services/` | list, get, create, update, delete |
|
|
221
|
+
| User Services | `/api/v2/rel_services/` | list, get, create, update, delete |
|
|
222
|
+
| User Photos | `/api/v2/users_photo/` | list, get, create, update, delete |
|
|
223
|
+
| User Metadata | `/api/v2/users_meta/` | list, get, create, update, delete |
|
|
224
|
+
| Tags | `/api/v2/tags/` | list, get, create, update, delete |
|
|
225
|
+
| Tag Groups | `/api/v2/tag_groups/` | list, get, create, update, delete |
|
|
226
|
+
| Tag Types | `/api/v2/tag_types/` | list, get, create, update, delete |
|
|
227
|
+
| Tag Relationships | `/api/v2/rel_tags/` | list, get, create, update, delete |
|
|
228
|
+
| Widgets | `/api/v2/data_widgets/` | list, get, create, update, delete, render |
|
|
229
|
+
| Email Templates | `/api/v2/email_templates/` | list, get, create, update, delete |
|
|
230
|
+
| Forms | `/api/v2/form/` | list, get, create, update, delete |
|
|
231
|
+
| Form Fields | `/api/v2/form_fields/` | list, get, create, update, delete |
|
|
232
|
+
| Membership Plans | `/api/v2/subscription_types/` | list, get, create, update, delete |
|
|
233
|
+
| Menus | `/api/v2/menus/` | list, get, create, update, delete |
|
|
234
|
+
| Menu Items | `/api/v2/menu_items/` | list, get, create, update, delete |
|
|
235
|
+
| Unsubscribe | `/api/v2/unsubscribe_list/` | list, get, create, update, delete |
|
|
236
|
+
| Smart Lists | `/api/v2/smart_lists/` | list, get, create, update, delete |
|
|
237
|
+
|
|
238
|
+
## Field Discovery
|
|
239
|
+
|
|
240
|
+
Some endpoints support dynamic field discovery:
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
# Get all available user fields
|
|
244
|
+
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/user/fields
|
|
245
|
+
|
|
246
|
+
# Get custom fields for a specific post type
|
|
247
|
+
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/data_posts/fields?form_name=my-form
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
## Files
|
|
251
|
+
|
|
252
|
+
| File | Purpose |
|
|
253
|
+
|------|---------|
|
|
254
|
+
| [`openapi/bd-api.json`](openapi/bd-api.json) | OpenAPI 3.1 spec (single source of truth) |
|
|
255
|
+
| [`mcp/index.js`](mcp/index.js) | MCP server for Claude/Cursor |
|
|
256
|
+
| [`mcp/package.json`](mcp/package.json) | npm package definition |
|
|
257
|
+
| [`docs/*.md`](docs/) | Raw API endpoint documentation |
|
|
258
|
+
| [`LICENSE`](LICENSE) | MIT License |
|
|
259
|
+
| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
|
|
260
|
+
|
|
261
|
+
### Stable asset URLs
|
|
262
|
+
|
|
263
|
+
For tools that import specs by URL (ChatGPT Actions, n8n, Postman):
|
|
264
|
+
|
|
265
|
+
```
|
|
266
|
+
https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/openapi/bd-api.json
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
## Security
|
|
270
|
+
|
|
271
|
+
- API keys are never embedded in the package
|
|
272
|
+
- All requests go directly from the user's machine to their BD site
|
|
273
|
+
- No data passes through third-party servers
|
|
274
|
+
- API key permissions control which endpoints are accessible
|
|
275
|
+
- Treat your API key like a password
|
|
276
|
+
|
|
277
|
+
## Support
|
|
278
|
+
|
|
279
|
+
- BD Support: https://support.brilliantdirectories.com
|
|
280
|
+
- API Docs: https://support.brilliantdirectories.com/support/solutions/articles/12000108045
|
package/index.js
ADDED
|
@@ -0,0 +1,478 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Brilliant Directories MCP Server
|
|
5
|
+
*
|
|
6
|
+
* Exposes all BD API v2 endpoints as MCP tools.
|
|
7
|
+
* Reads the OpenAPI spec and auto-generates tool definitions.
|
|
8
|
+
*
|
|
9
|
+
* Usage:
|
|
10
|
+
* brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com
|
|
11
|
+
*
|
|
12
|
+
* Or via env vars:
|
|
13
|
+
* BD_API_KEY=YOUR_KEY BD_API_URL=https://your-site.com brilliant-directories-mcp
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
|
|
17
|
+
const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
|
|
18
|
+
const {
|
|
19
|
+
CallToolRequestSchema,
|
|
20
|
+
ListToolsRequestSchema,
|
|
21
|
+
} = require("@modelcontextprotocol/sdk/types.js");
|
|
22
|
+
const fs = require("fs");
|
|
23
|
+
const path = require("path");
|
|
24
|
+
const https = require("https");
|
|
25
|
+
const http = require("http");
|
|
26
|
+
const { URL } = require("url");
|
|
27
|
+
|
|
28
|
+
// Read package version once at startup (keeps User-Agent + server init in sync with package.json)
|
|
29
|
+
const PACKAGE_VERSION = (() => {
|
|
30
|
+
try {
|
|
31
|
+
return require("./package.json").version;
|
|
32
|
+
} catch {
|
|
33
|
+
return "unknown";
|
|
34
|
+
}
|
|
35
|
+
})();
|
|
36
|
+
|
|
37
|
+
// ---------------------------------------------------------------------------
|
|
38
|
+
// Config
|
|
39
|
+
// ---------------------------------------------------------------------------
|
|
40
|
+
|
|
41
|
+
function parseArgs() {
|
|
42
|
+
const args = process.argv.slice(2);
|
|
43
|
+
const config = {
|
|
44
|
+
apiKey: process.env.BD_API_KEY || "",
|
|
45
|
+
apiUrl: process.env.BD_API_URL || "",
|
|
46
|
+
verify: false,
|
|
47
|
+
help: false,
|
|
48
|
+
debug: process.env.BD_DEBUG === "1" || process.env.BD_DEBUG === "true",
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
for (let i = 0; i < args.length; i++) {
|
|
52
|
+
if ((args[i] === "--api-key" || args[i] === "--apiKey") && args[i + 1]) {
|
|
53
|
+
config.apiKey = args[++i];
|
|
54
|
+
} else if ((args[i] === "--url" || args[i] === "--api-url") && args[i + 1]) {
|
|
55
|
+
config.apiUrl = args[++i];
|
|
56
|
+
} else if (args[i] === "--verify") {
|
|
57
|
+
config.verify = true;
|
|
58
|
+
} else if (args[i] === "--debug") {
|
|
59
|
+
config.debug = true;
|
|
60
|
+
} else if (args[i] === "--help" || args[i] === "-h") {
|
|
61
|
+
config.help = true;
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
if (config.help) {
|
|
66
|
+
printHelp();
|
|
67
|
+
process.exit(0);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
// Normalize URL: strip trailing slash, ensure protocol
|
|
71
|
+
config.apiUrl = config.apiUrl.replace(/\/+$/, "");
|
|
72
|
+
if (config.apiUrl && !/^https?:\/\//i.test(config.apiUrl)) {
|
|
73
|
+
config.apiUrl = "https://" + config.apiUrl;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
if (!config.apiKey) {
|
|
77
|
+
console.error("Error: API key required. Use --api-key YOUR_KEY or set BD_API_KEY env var.");
|
|
78
|
+
console.error("Run with --help for usage.");
|
|
79
|
+
process.exit(1);
|
|
80
|
+
}
|
|
81
|
+
if (!config.apiUrl) {
|
|
82
|
+
console.error("Error: Site URL required. Use --url https://your-site.com or set BD_API_URL env var.");
|
|
83
|
+
console.error("Run with --help for usage.");
|
|
84
|
+
process.exit(1);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
return config;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function printHelp() {
|
|
91
|
+
console.log(`brilliant-directories-mcp — MCP server for the Brilliant Directories API
|
|
92
|
+
|
|
93
|
+
Usage:
|
|
94
|
+
brilliant-directories-mcp --api-key KEY --url URL
|
|
95
|
+
brilliant-directories-mcp --verify --api-key KEY --url URL
|
|
96
|
+
BD_API_KEY=KEY BD_API_URL=URL brilliant-directories-mcp
|
|
97
|
+
|
|
98
|
+
Options:
|
|
99
|
+
--api-key KEY Your BD API key (or set BD_API_KEY env var)
|
|
100
|
+
--url URL Your BD site URL, e.g. https://mysite.com (or BD_API_URL env var)
|
|
101
|
+
--verify Test credentials against /api/v2/token/verify and exit
|
|
102
|
+
--debug Log every HTTP request + response to stderr (or set BD_DEBUG=1)
|
|
103
|
+
--help, -h Show this help
|
|
104
|
+
|
|
105
|
+
Get an API key: BD Admin > Settings > API Keys > Create New Key
|
|
106
|
+
Docs: https://github.com/brilliantdirectories/brilliant-directories-mcp`);
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
// ---------------------------------------------------------------------------
|
|
110
|
+
// OpenAPI spec → MCP tools
|
|
111
|
+
// ---------------------------------------------------------------------------
|
|
112
|
+
|
|
113
|
+
function loadSpec() {
|
|
114
|
+
const specPath = path.join(__dirname, "..", "openapi", "bd-api.json");
|
|
115
|
+
if (!fs.existsSync(specPath)) {
|
|
116
|
+
console.error(`Error: OpenAPI spec not found at ${specPath}`);
|
|
117
|
+
process.exit(1);
|
|
118
|
+
}
|
|
119
|
+
return JSON.parse(fs.readFileSync(specPath, "utf8"));
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Convert OpenAPI path operations to MCP tool definitions.
|
|
124
|
+
* Each operation becomes one tool with:
|
|
125
|
+
* - name: operationId
|
|
126
|
+
* - description: summary + description
|
|
127
|
+
* - inputSchema: merged path params + query params + requestBody properties
|
|
128
|
+
*/
|
|
129
|
+
function buildTools(spec) {
|
|
130
|
+
const tools = [];
|
|
131
|
+
const toolMap = {}; // operationId → { method, path, params, bodyProps }
|
|
132
|
+
const seenIds = new Map(); // operationId → "METHOD path" for duplicate detection
|
|
133
|
+
|
|
134
|
+
for (const [urlPath, methods] of Object.entries(spec.paths)) {
|
|
135
|
+
for (const [method, op] of Object.entries(methods)) {
|
|
136
|
+
if (!op.operationId) continue;
|
|
137
|
+
|
|
138
|
+
// Self-defense: duplicate operationIds would silently overwrite each other in toolMap.
|
|
139
|
+
// Fail loudly on startup instead of mysterious "tool not found" errors later.
|
|
140
|
+
const location = `${method.toUpperCase()} ${urlPath}`;
|
|
141
|
+
if (seenIds.has(op.operationId)) {
|
|
142
|
+
console.error(`Error: duplicate operationId "${op.operationId}" in OpenAPI spec.`);
|
|
143
|
+
console.error(` First seen at: ${seenIds.get(op.operationId)}`);
|
|
144
|
+
console.error(` Also found at: ${location}`);
|
|
145
|
+
console.error(`Each endpoint must have a unique operationId. Fix openapi/bd-api.json.`);
|
|
146
|
+
process.exit(1);
|
|
147
|
+
}
|
|
148
|
+
seenIds.set(op.operationId, location);
|
|
149
|
+
|
|
150
|
+
const properties = {};
|
|
151
|
+
const required = [];
|
|
152
|
+
|
|
153
|
+
// Path parameters
|
|
154
|
+
if (op.parameters) {
|
|
155
|
+
for (const param of op.parameters) {
|
|
156
|
+
// Resolve $ref if needed
|
|
157
|
+
const p = param.$ref
|
|
158
|
+
? resolveRef(spec, param.$ref)
|
|
159
|
+
: param;
|
|
160
|
+
|
|
161
|
+
if (p.in === "path") {
|
|
162
|
+
properties[p.name] = p.schema || { type: "string" };
|
|
163
|
+
if (p.description) properties[p.name].description = p.description;
|
|
164
|
+
required.push(p.name);
|
|
165
|
+
} else if (p.in === "query" && !["limit", "page", "property", "property_value", "property_operator", "order_column", "order_type"].includes(p.name)) {
|
|
166
|
+
// Non-standard query params (like form_name)
|
|
167
|
+
properties[p.name] = p.schema || { type: "string" };
|
|
168
|
+
if (p.description) properties[p.name].description = p.description;
|
|
169
|
+
if (p.required) required.push(p.name);
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
// Standard pagination/filter params for GET list endpoints
|
|
175
|
+
if (method === "get" && op.parameters) {
|
|
176
|
+
const hasLimit = op.parameters.some(
|
|
177
|
+
(p) => (p.name === "limit" || (p.$ref && p.$ref.includes("/limit")))
|
|
178
|
+
);
|
|
179
|
+
if (hasLimit) {
|
|
180
|
+
properties.limit = { type: "integer", description: "Records per page (default 25, max 100)" };
|
|
181
|
+
properties.page = { type: "string", description: "Pagination cursor (use next_page from previous response)" };
|
|
182
|
+
properties.property = { type: "string", description: "Field name to filter by" };
|
|
183
|
+
properties.property_value = { type: "string", description: "Value to filter by" };
|
|
184
|
+
properties.property_operator = { type: "string", description: "Filter operator: =, LIKE, >, <, >=, <=" };
|
|
185
|
+
properties.order_column = { type: "string", description: "Column to sort by" };
|
|
186
|
+
properties.order_type = { type: "string", description: "Sort direction: ASC or DESC" };
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
// Request body properties
|
|
191
|
+
let bodyProps = {};
|
|
192
|
+
if (op.requestBody) {
|
|
193
|
+
const content = op.requestBody.content;
|
|
194
|
+
const schema = content?.["application/x-www-form-urlencoded"]?.schema;
|
|
195
|
+
if (schema && schema.properties) {
|
|
196
|
+
for (const [key, val] of Object.entries(schema.properties)) {
|
|
197
|
+
properties[key] = { ...val };
|
|
198
|
+
}
|
|
199
|
+
if (schema.required) {
|
|
200
|
+
for (const r of schema.required) {
|
|
201
|
+
if (!required.includes(r)) required.push(r);
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
bodyProps = schema.properties;
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
const tool = {
|
|
209
|
+
name: op.operationId,
|
|
210
|
+
description: [op.summary, op.description].filter(Boolean).join(" — "),
|
|
211
|
+
inputSchema: {
|
|
212
|
+
type: "object",
|
|
213
|
+
properties,
|
|
214
|
+
},
|
|
215
|
+
};
|
|
216
|
+
if (required.length > 0) {
|
|
217
|
+
tool.inputSchema.required = required;
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
tools.push(tool);
|
|
221
|
+
toolMap[op.operationId] = {
|
|
222
|
+
method: method.toUpperCase(),
|
|
223
|
+
path: urlPath,
|
|
224
|
+
bodyProps,
|
|
225
|
+
};
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
return { tools, toolMap };
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
function resolveRef(spec, ref) {
|
|
233
|
+
const parts = ref.replace("#/", "").split("/");
|
|
234
|
+
let obj = spec;
|
|
235
|
+
for (const part of parts) {
|
|
236
|
+
obj = obj[part];
|
|
237
|
+
}
|
|
238
|
+
return obj;
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
// ---------------------------------------------------------------------------
|
|
242
|
+
// HTTP client
|
|
243
|
+
// ---------------------------------------------------------------------------
|
|
244
|
+
|
|
245
|
+
function makeRequest(config, method, urlPath, queryParams, bodyParams) {
|
|
246
|
+
return new Promise((resolve, reject) => {
|
|
247
|
+
const fullUrl = new URL(urlPath, config.apiUrl);
|
|
248
|
+
|
|
249
|
+
// Add query params
|
|
250
|
+
if (queryParams) {
|
|
251
|
+
for (const [key, val] of Object.entries(queryParams)) {
|
|
252
|
+
if (val !== undefined && val !== null && val !== "") {
|
|
253
|
+
fullUrl.searchParams.set(key, String(val));
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
const isHttps = fullUrl.protocol === "https:";
|
|
259
|
+
const transport = isHttps ? https : http;
|
|
260
|
+
|
|
261
|
+
let bodyStr = "";
|
|
262
|
+
if (bodyParams && Object.keys(bodyParams).length > 0) {
|
|
263
|
+
bodyStr = new URLSearchParams(
|
|
264
|
+
Object.entries(bodyParams).filter(([, v]) => v !== undefined && v !== null && v !== "")
|
|
265
|
+
).toString();
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
const options = {
|
|
269
|
+
hostname: fullUrl.hostname,
|
|
270
|
+
port: fullUrl.port || (isHttps ? 443 : 80),
|
|
271
|
+
path: fullUrl.pathname + fullUrl.search,
|
|
272
|
+
method: method,
|
|
273
|
+
headers: {
|
|
274
|
+
"X-Api-Key": config.apiKey,
|
|
275
|
+
"Accept": "application/json",
|
|
276
|
+
"User-Agent": `brilliant-directories-mcp/${PACKAGE_VERSION} (node/${process.version})`,
|
|
277
|
+
},
|
|
278
|
+
};
|
|
279
|
+
|
|
280
|
+
if (bodyStr) {
|
|
281
|
+
options.headers["Content-Type"] = "application/x-www-form-urlencoded";
|
|
282
|
+
options.headers["Content-Length"] = Buffer.byteLength(bodyStr);
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
if (config.debug) {
|
|
286
|
+
// Redact API key from logged headers
|
|
287
|
+
const safeHeaders = { ...options.headers, "X-Api-Key": "***REDACTED***" };
|
|
288
|
+
console.error(`[debug] → ${method} ${fullUrl.href}`);
|
|
289
|
+
console.error(`[debug] headers: ${JSON.stringify(safeHeaders)}`);
|
|
290
|
+
if (bodyStr) console.error(`[debug] body: ${bodyStr}`);
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
const req = transport.request(options, (res) => {
|
|
294
|
+
let data = "";
|
|
295
|
+
res.on("data", (chunk) => (data += chunk));
|
|
296
|
+
res.on("end", () => {
|
|
297
|
+
if (config.debug) {
|
|
298
|
+
console.error(`[debug] ← ${res.statusCode} ${method} ${fullUrl.href}`);
|
|
299
|
+
console.error(`[debug] body: ${data.length > 500 ? data.slice(0, 500) + "...[truncated]" : data}`);
|
|
300
|
+
}
|
|
301
|
+
try {
|
|
302
|
+
resolve({ status: res.statusCode, body: JSON.parse(data) });
|
|
303
|
+
} catch {
|
|
304
|
+
resolve({ status: res.statusCode, body: data });
|
|
305
|
+
}
|
|
306
|
+
});
|
|
307
|
+
});
|
|
308
|
+
|
|
309
|
+
req.on("error", (err) => {
|
|
310
|
+
if (config.debug) console.error(`[debug] ✗ ${method} ${fullUrl.href} — ${err.message}`);
|
|
311
|
+
reject(err);
|
|
312
|
+
});
|
|
313
|
+
req.setTimeout(30000, () => {
|
|
314
|
+
req.destroy();
|
|
315
|
+
reject(new Error("Request timed out after 30s"));
|
|
316
|
+
});
|
|
317
|
+
|
|
318
|
+
if (bodyStr) req.write(bodyStr);
|
|
319
|
+
req.end();
|
|
320
|
+
});
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
// ---------------------------------------------------------------------------
|
|
324
|
+
// Main
|
|
325
|
+
// ---------------------------------------------------------------------------
|
|
326
|
+
|
|
327
|
+
async function runVerify(config) {
|
|
328
|
+
try {
|
|
329
|
+
const result = await makeRequest(config, "GET", "/api/v2/token/verify", null, null);
|
|
330
|
+
if (result.status >= 200 && result.status < 300 && result.body?.status === "success") {
|
|
331
|
+
console.log(`OK — credentials verified against ${config.apiUrl}`);
|
|
332
|
+
if (result.body.data) {
|
|
333
|
+
console.log(JSON.stringify(result.body.data, null, 2));
|
|
334
|
+
}
|
|
335
|
+
process.exit(0);
|
|
336
|
+
} else {
|
|
337
|
+
console.error(`FAIL — HTTP ${result.status}`);
|
|
338
|
+
console.error(typeof result.body === "string" ? result.body : JSON.stringify(result.body, null, 2));
|
|
339
|
+
process.exit(2);
|
|
340
|
+
}
|
|
341
|
+
} catch (err) {
|
|
342
|
+
console.error(`FAIL — ${err.message}`);
|
|
343
|
+
process.exit(2);
|
|
344
|
+
}
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
async function main() {
|
|
348
|
+
const config = parseArgs();
|
|
349
|
+
|
|
350
|
+
if (config.verify) {
|
|
351
|
+
await runVerify(config);
|
|
352
|
+
return;
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
const spec = loadSpec();
|
|
356
|
+
const { tools, toolMap } = buildTools(spec);
|
|
357
|
+
|
|
358
|
+
const server = new Server(
|
|
359
|
+
{
|
|
360
|
+
name: "brilliant-directories-mcp",
|
|
361
|
+
version: PACKAGE_VERSION,
|
|
362
|
+
},
|
|
363
|
+
{
|
|
364
|
+
capabilities: {
|
|
365
|
+
tools: {},
|
|
366
|
+
},
|
|
367
|
+
instructions: [
|
|
368
|
+
`Brilliant Directories API — ${spec.paths ? Object.keys(spec.paths).length : 0} endpoints for managing BD-powered membership/directory sites.`,
|
|
369
|
+
``,
|
|
370
|
+
`Rate limit: 100 requests per 60 seconds per API key (default). Customers can request a higher limit from Brilliant Directories support (any value between 100 and 1,000/min) — this is not a self-service setting in the BD admin.`,
|
|
371
|
+
``,
|
|
372
|
+
`For bulk operations (imports, mass updates, batch exports), pace requests below the configured limit. On HTTP 429, back off at least 60 seconds before retrying.`,
|
|
373
|
+
``,
|
|
374
|
+
`Before large jobs, optionally call verifyApiKey to confirm credentials and check current rate-limit headroom.`,
|
|
375
|
+
``,
|
|
376
|
+
`Pagination uses cursor tokens (page + limit params; default 25, max 100). Do not assume numeric page offsets.`,
|
|
377
|
+
``,
|
|
378
|
+
`Destructive operations (delete/update) apply to live production data. Confirm with the user before running bulk deletes or mass updates.`,
|
|
379
|
+
].join("\n"),
|
|
380
|
+
}
|
|
381
|
+
);
|
|
382
|
+
|
|
383
|
+
// List tools
|
|
384
|
+
server.setRequestHandler(ListToolsRequestSchema, async () => {
|
|
385
|
+
return { tools };
|
|
386
|
+
});
|
|
387
|
+
|
|
388
|
+
// Call tool
|
|
389
|
+
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
390
|
+
const { name, arguments: args } = request.params;
|
|
391
|
+
|
|
392
|
+
const toolDef = toolMap[name];
|
|
393
|
+
if (!toolDef) {
|
|
394
|
+
return {
|
|
395
|
+
content: [{ type: "text", text: `Unknown tool: ${name}` }],
|
|
396
|
+
isError: true,
|
|
397
|
+
};
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
try {
|
|
401
|
+
// Build URL path with path params substituted
|
|
402
|
+
let urlPath = toolDef.path;
|
|
403
|
+
const queryParams = {};
|
|
404
|
+
const bodyParams = {};
|
|
405
|
+
|
|
406
|
+
for (const [key, val] of Object.entries(args || {})) {
|
|
407
|
+
// Check if this is a path parameter (appears in URL template)
|
|
408
|
+
if (urlPath.includes(`{${key}}`)) {
|
|
409
|
+
urlPath = urlPath.replace(`{${key}}`, encodeURIComponent(String(val)));
|
|
410
|
+
} else if (toolDef.method === "GET") {
|
|
411
|
+
queryParams[key] = val;
|
|
412
|
+
} else if (key in toolDef.bodyProps) {
|
|
413
|
+
bodyParams[key] = val;
|
|
414
|
+
} else {
|
|
415
|
+
// Could be a query param on a non-GET (like limit on search)
|
|
416
|
+
// or a body param not in the spec — send as body
|
|
417
|
+
bodyParams[key] = val;
|
|
418
|
+
}
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
const result = await makeRequest(config, toolDef.method, urlPath, queryParams, bodyParams);
|
|
422
|
+
|
|
423
|
+
// Surface rate-limit errors with actionable guidance for the agent
|
|
424
|
+
if (result.status === 429) {
|
|
425
|
+
return {
|
|
426
|
+
content: [
|
|
427
|
+
{
|
|
428
|
+
type: "text",
|
|
429
|
+
text: `Rate limit exceeded (HTTP 429). The BD API default is 100 requests per 60 seconds per API key. For bulk operations: (1) pace requests at slower intervals, (2) wait at least 60 seconds before retrying, or (3) ask the customer to contact Brilliant Directories support to have their limit raised (available values: 100–1,000/min, not a self-service setting). Server response: ${JSON.stringify(result.body)}`,
|
|
430
|
+
},
|
|
431
|
+
],
|
|
432
|
+
isError: true,
|
|
433
|
+
};
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
// Surface auth errors with actionable guidance
|
|
437
|
+
if (result.status === 401 || result.status === 403) {
|
|
438
|
+
return {
|
|
439
|
+
content: [
|
|
440
|
+
{
|
|
441
|
+
type: "text",
|
|
442
|
+
text: `Authentication failed (HTTP ${result.status}). The API key is invalid, revoked, or lacks permission for this endpoint. Verify with: npx brilliant-directories-mcp --verify --api-key KEY --url URL. Server response: ${JSON.stringify(result.body)}`,
|
|
443
|
+
},
|
|
444
|
+
],
|
|
445
|
+
isError: true,
|
|
446
|
+
};
|
|
447
|
+
}
|
|
448
|
+
|
|
449
|
+
return {
|
|
450
|
+
content: [
|
|
451
|
+
{
|
|
452
|
+
type: "text",
|
|
453
|
+
text: JSON.stringify(result.body, null, 2),
|
|
454
|
+
},
|
|
455
|
+
],
|
|
456
|
+
};
|
|
457
|
+
} catch (err) {
|
|
458
|
+
return {
|
|
459
|
+
content: [
|
|
460
|
+
{
|
|
461
|
+
type: "text",
|
|
462
|
+
text: `Error calling ${name}: ${err.message}`,
|
|
463
|
+
},
|
|
464
|
+
],
|
|
465
|
+
isError: true,
|
|
466
|
+
};
|
|
467
|
+
}
|
|
468
|
+
});
|
|
469
|
+
|
|
470
|
+
// Start
|
|
471
|
+
const transport = new StdioServerTransport();
|
|
472
|
+
await server.connect(transport);
|
|
473
|
+
}
|
|
474
|
+
|
|
475
|
+
main().catch((err) => {
|
|
476
|
+
console.error("Fatal error:", err);
|
|
477
|
+
process.exit(1);
|
|
478
|
+
});
|
package/package.json
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "brilliant-directories-mcp",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "MCP integration for Brilliant Directories API — manage members, content, leads, and more from any AI agent",
|
|
5
|
+
"main": "index.js",
|
|
6
|
+
"bin": {
|
|
7
|
+
"brilliant-directories-mcp": "index.js"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"index.js",
|
|
11
|
+
"README.md",
|
|
12
|
+
"LICENSE"
|
|
13
|
+
],
|
|
14
|
+
"keywords": [
|
|
15
|
+
"mcp",
|
|
16
|
+
"model-context-protocol",
|
|
17
|
+
"brilliant-directories",
|
|
18
|
+
"api",
|
|
19
|
+
"ai-agent",
|
|
20
|
+
"directory",
|
|
21
|
+
"membership",
|
|
22
|
+
"claude",
|
|
23
|
+
"cursor",
|
|
24
|
+
"openapi"
|
|
25
|
+
],
|
|
26
|
+
"author": "Brilliant Directories <support@brilliantdirectories.com>",
|
|
27
|
+
"license": "MIT",
|
|
28
|
+
"homepage": "https://github.com/brilliantdirectories/brilliant-directories-mcp#readme",
|
|
29
|
+
"repository": {
|
|
30
|
+
"type": "git",
|
|
31
|
+
"url": "git+https://github.com/brilliantdirectories/brilliant-directories-mcp.git",
|
|
32
|
+
"directory": "mcp"
|
|
33
|
+
},
|
|
34
|
+
"bugs": {
|
|
35
|
+
"url": "https://github.com/brilliantdirectories/brilliant-directories-mcp/issues"
|
|
36
|
+
},
|
|
37
|
+
"scripts": {
|
|
38
|
+
"test": "node index.js --verify",
|
|
39
|
+
"start": "node index.js"
|
|
40
|
+
},
|
|
41
|
+
"dependencies": {
|
|
42
|
+
"@modelcontextprotocol/sdk": "^1.0.0"
|
|
43
|
+
},
|
|
44
|
+
"engines": {
|
|
45
|
+
"node": ">=18"
|
|
46
|
+
}
|
|
47
|
+
}
|