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.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +280 -0
  3. package/index.js +478 -0
  4. 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
+ [![npm version](https://img.shields.io/npm/v/brilliant-directories-mcp.svg)](https://www.npmjs.com/package/brilliant-directories-mcp)
4
+ [![license](https://img.shields.io/npm/l/brilliant-directories-mcp.svg)](LICENSE)
5
+ [![MCP](https://img.shields.io/badge/MCP-compatible-blue.svg)](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
+ }