brilliant-directories-mcp 1.0.2 → 1.2.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 (3) hide show
  1. package/README.md +10 -8
  2. package/index.js +233 -3
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -6,21 +6,22 @@
6
6
 
7
7
  Give any AI agent full access to your BD site with one API key.
8
8
 
9
- **154 endpoints** across 28 resources: members, leads, posts, reviews, categories, email templates, smart lists, widgets, menus, forms, membership plans, and more.
9
+ **159 endpoints** across 29 resources: members, leads, posts, reviews, categories, email templates, **pages (static site pages, homepage, landing pages)**, smart lists, widgets, menus, forms, membership plans, and more.
10
10
 
11
11
  ## 30-Second Quickstart
12
12
 
13
+ **One command. Answer two questions. Done.**
14
+
13
15
  ```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
+ npx brilliant-directories-mcp --setup
17
+ ```
16
18
 
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
+ 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.
19
20
 
20
- # 3. Ask Claude: "List all members on my BD site"
21
- ```
21
+ Restart your app, then ask your AI:
22
+ > "List members on my BD site"
22
23
 
23
- That's it. Get your API key from **BD Admin > Settings > API Keys > Create New Key**.
24
+ Get your API key from **BD Admin > Settings > API Keys > Create New Key**.
24
25
 
25
26
  ---
26
27
 
@@ -234,6 +235,7 @@ GET /api/v2/user/get?order_column=last_name&order_type=ASC
234
235
  | Menu Items | `/api/v2/menu_items/` | list, get, create, update, delete |
235
236
  | Unsubscribe | `/api/v2/unsubscribe_list/` | list, get, create, update, delete |
236
237
  | Smart Lists | `/api/v2/smart_lists/` | list, get, create, update, delete |
238
+ | Pages (SEO/static) | `/api/v2/list_seo/` | list, get, create, update, delete |
237
239
 
238
240
  ## Field Discovery
239
241
 
package/index.js CHANGED
@@ -20,9 +20,11 @@ const {
20
20
  ListToolsRequestSchema,
21
21
  } = require("@modelcontextprotocol/sdk/types.js");
22
22
  const fs = require("fs");
23
+ const os = require("os");
23
24
  const path = require("path");
24
25
  const https = require("https");
25
26
  const http = require("http");
27
+ const readline = require("readline");
26
28
  const { URL } = require("url");
27
29
 
28
30
  // Read package version once at startup (keeps User-Agent + server init in sync with package.json)
@@ -44,6 +46,7 @@ function parseArgs() {
44
46
  apiKey: process.env.BD_API_KEY || "",
45
47
  apiUrl: process.env.BD_API_URL || "",
46
48
  verify: false,
49
+ setup: false,
47
50
  help: false,
48
51
  debug: process.env.BD_DEBUG === "1" || process.env.BD_DEBUG === "true",
49
52
  };
@@ -55,6 +58,8 @@ function parseArgs() {
55
58
  config.apiUrl = args[++i];
56
59
  } else if (args[i] === "--verify") {
57
60
  config.verify = true;
61
+ } else if (args[i] === "--setup") {
62
+ config.setup = true;
58
63
  } else if (args[i] === "--debug") {
59
64
  config.debug = true;
60
65
  } else if (args[i] === "--help" || args[i] === "-h") {
@@ -67,6 +72,11 @@ function parseArgs() {
67
72
  process.exit(0);
68
73
  }
69
74
 
75
+ // Setup mode skips the API-key-required check — wizard will prompt for them
76
+ if (config.setup) {
77
+ return config;
78
+ }
79
+
70
80
  // Normalize URL: strip trailing slash, ensure protocol
71
81
  config.apiUrl = config.apiUrl.replace(/\/+$/, "");
72
82
  if (config.apiUrl && !/^https?:\/\//i.test(config.apiUrl)) {
@@ -90,12 +100,17 @@ function parseArgs() {
90
100
  function printHelp() {
91
101
  console.log(`brilliant-directories-mcp — MCP server for the Brilliant Directories API
92
102
 
103
+ FIRST TIME? Just run this and answer 2 questions:
104
+ npx brilliant-directories-mcp --setup
105
+
93
106
  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
107
+ brilliant-directories-mcp --setup Interactive setup wizard (recommended)
108
+ brilliant-directories-mcp --api-key KEY --url URL Run the MCP server
109
+ brilliant-directories-mcp --verify --api-key KEY --url URL Test credentials and exit
110
+ BD_API_KEY=KEY BD_API_URL=URL brilliant-directories-mcp Run via env vars
97
111
 
98
112
  Options:
113
+ --setup Interactive wizard: prompts for URL + key, writes client config
99
114
  --api-key KEY Your BD API key (or set BD_API_KEY env var)
100
115
  --url URL Your BD site URL, e.g. https://mysite.com (or BD_API_URL env var)
101
116
  --verify Test credentials against /api/v2/token/verify and exit
@@ -324,6 +339,216 @@ function makeRequest(config, method, urlPath, queryParams, bodyParams) {
324
339
  // Main
325
340
  // ---------------------------------------------------------------------------
326
341
 
342
+ // ---------------------------------------------------------------------------
343
+ // Setup wizard
344
+ // ---------------------------------------------------------------------------
345
+
346
+ function prompt(question, { hidden = false } = {}) {
347
+ return new Promise((resolve) => {
348
+ const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
349
+ if (hidden && process.stdin.isTTY) {
350
+ // Mask input for API key
351
+ process.stdout.write(question);
352
+ const onData = (char) => {
353
+ const c = char.toString("utf8");
354
+ if (c === "\n" || c === "\r" || c === "\r\n" || c === "\u0004") {
355
+ process.stdin.removeListener("data", onData);
356
+ process.stdout.write("\n");
357
+ } else if (c === "\u0003") {
358
+ // Ctrl+C
359
+ process.exit(130);
360
+ } else {
361
+ process.stdout.write("*");
362
+ }
363
+ };
364
+ process.stdin.on("data", onData);
365
+ rl.question("", (answer) => {
366
+ rl.close();
367
+ resolve(answer.trim());
368
+ });
369
+ } else {
370
+ rl.question(question, (answer) => {
371
+ rl.close();
372
+ resolve(answer.trim());
373
+ });
374
+ }
375
+ });
376
+ }
377
+
378
+ function normalizeUrl(input) {
379
+ let u = (input || "").trim().replace(/\/+$/, "");
380
+ if (u && !/^https?:\/\//i.test(u)) u = "https://" + u;
381
+ return u;
382
+ }
383
+
384
+ function getClientConfigPath(client) {
385
+ const home = os.homedir();
386
+ switch (client) {
387
+ case "cursor":
388
+ return path.join(home, ".cursor", "mcp.json");
389
+ case "claude-desktop":
390
+ if (process.platform === "darwin") {
391
+ return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
392
+ } else if (process.platform === "win32") {
393
+ return path.join(process.env.APPDATA || path.join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
394
+ } else {
395
+ return path.join(home, ".config", "Claude", "claude_desktop_config.json");
396
+ }
397
+ case "windsurf":
398
+ return path.join(home, ".codeium", "windsurf", "mcp_config.json");
399
+ case "claude-code":
400
+ return null; // Claude Code uses `claude mcp add` CLI — we print instructions instead
401
+ default:
402
+ return null;
403
+ }
404
+ }
405
+
406
+ function buildMcpServerEntry(apiKey, apiUrl) {
407
+ return {
408
+ command: "npx",
409
+ args: ["-y", "brilliant-directories-mcp", "--api-key", apiKey, "--url", apiUrl],
410
+ };
411
+ }
412
+
413
+ function writeClientConfig(configPath, serverName, entry) {
414
+ const dir = path.dirname(configPath);
415
+ if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
416
+
417
+ let existing = { mcpServers: {} };
418
+ if (fs.existsSync(configPath)) {
419
+ try {
420
+ const raw = fs.readFileSync(configPath, "utf8").trim();
421
+ if (raw) existing = JSON.parse(raw);
422
+ if (!existing.mcpServers || typeof existing.mcpServers !== "object") {
423
+ existing.mcpServers = {};
424
+ }
425
+ } catch (err) {
426
+ console.error(`\nCould not parse existing config at ${configPath}`);
427
+ console.error(`Error: ${err.message}`);
428
+ console.error("Skipping write to avoid overwriting. Fix the file manually and rerun --setup.");
429
+ return false;
430
+ }
431
+ }
432
+
433
+ existing.mcpServers[serverName] = entry;
434
+ fs.writeFileSync(configPath, JSON.stringify(existing, null, 2) + "\n");
435
+ return true;
436
+ }
437
+
438
+ async function runSetup() {
439
+ console.log("");
440
+ console.log("Brilliant Directories MCP — Setup Wizard");
441
+ console.log("=========================================");
442
+ console.log("");
443
+
444
+ // URL
445
+ let apiUrl = process.env.BD_API_URL || "";
446
+ if (!apiUrl) {
447
+ while (!apiUrl) {
448
+ const raw = await prompt("Your BD site URL (e.g. https://mysite.com): ");
449
+ if (!raw) {
450
+ console.log(" Please enter your site URL.");
451
+ continue;
452
+ }
453
+ apiUrl = normalizeUrl(raw);
454
+ }
455
+ }
456
+
457
+ // API Key
458
+ let apiKey = process.env.BD_API_KEY || "";
459
+ if (!apiKey) {
460
+ console.log("");
461
+ console.log("Get an API key from: BD Admin > Settings > API Keys > Create New Key");
462
+ while (!apiKey) {
463
+ const raw = await prompt("Your BD API key: ", { hidden: true });
464
+ if (!raw) {
465
+ console.log(" Please paste your API key.");
466
+ continue;
467
+ }
468
+ apiKey = raw;
469
+ }
470
+ }
471
+
472
+ // Verify
473
+ console.log("");
474
+ process.stdout.write("Testing connection... ");
475
+ try {
476
+ const result = await makeRequest({ apiKey, apiUrl, debug: false }, "GET", "/api/v2/token/verify", null, null);
477
+ if (result.status >= 200 && result.status < 300 && result.body?.status === "success") {
478
+ console.log("OK");
479
+ } else {
480
+ console.log("FAILED");
481
+ console.log(` HTTP ${result.status}: ${JSON.stringify(result.body)}`);
482
+ console.log("");
483
+ console.log("Setup will still write the config, but your AI agent won't be able to call the API until this is fixed.");
484
+ const proceed = await prompt("Continue anyway? (y/N): ");
485
+ if (!/^y/i.test(proceed)) {
486
+ console.log("Setup cancelled.");
487
+ process.exit(1);
488
+ }
489
+ }
490
+ } catch (err) {
491
+ console.log("FAILED");
492
+ console.log(` ${err.message}`);
493
+ const proceed = await prompt("Continue anyway? (y/N): ");
494
+ if (!/^y/i.test(proceed)) {
495
+ console.log("Setup cancelled.");
496
+ process.exit(1);
497
+ }
498
+ }
499
+
500
+ // Client
501
+ console.log("");
502
+ console.log("Where are you using this?");
503
+ console.log(" 1) Cursor");
504
+ console.log(" 2) Claude Desktop");
505
+ console.log(" 3) Windsurf");
506
+ console.log(" 4) Claude Code (CLI)");
507
+ console.log(" 5) Other / just show me the config");
508
+ const choice = await prompt("Choice [1-5]: ");
509
+
510
+ const entry = buildMcpServerEntry(apiKey, apiUrl);
511
+ const serverName = "brilliant-directories";
512
+
513
+ let clientKey, clientLabel;
514
+ switch ((choice || "").trim()) {
515
+ case "1": clientKey = "cursor"; clientLabel = "Cursor"; break;
516
+ case "2": clientKey = "claude-desktop"; clientLabel = "Claude Desktop"; break;
517
+ case "3": clientKey = "windsurf"; clientLabel = "Windsurf"; break;
518
+ case "4": clientKey = "claude-code"; clientLabel = "Claude Code"; break;
519
+ default: clientKey = "other"; clientLabel = "Other";
520
+ }
521
+
522
+ console.log("");
523
+
524
+ if (clientKey === "claude-code") {
525
+ console.log("For Claude Code, run this command in your terminal:");
526
+ console.log("");
527
+ console.log(` claude mcp add ${serverName} -- npx -y brilliant-directories-mcp --api-key ${apiKey} --url ${apiUrl}`);
528
+ console.log("");
529
+ console.log("Then restart Claude Code and ask: \"List members on my BD site\"");
530
+ } else if (clientKey === "other") {
531
+ console.log("Add this to your MCP client's config file:");
532
+ console.log("");
533
+ console.log(JSON.stringify({ mcpServers: { [serverName]: entry } }, null, 2));
534
+ console.log("");
535
+ console.log("Then restart your client and ask: \"List members on my BD site\"");
536
+ } else {
537
+ const configPath = getClientConfigPath(clientKey);
538
+ const wrote = writeClientConfig(configPath, serverName, entry);
539
+ if (wrote) {
540
+ console.log(`Config written to:`);
541
+ console.log(` ${configPath}`);
542
+ console.log("");
543
+ console.log(`Done! Restart ${clientLabel} and ask Claude:`);
544
+ console.log(` "List members on my BD site"`);
545
+ }
546
+ }
547
+
548
+ console.log("");
549
+ process.exit(0);
550
+ }
551
+
327
552
  async function runVerify(config) {
328
553
  try {
329
554
  const result = await makeRequest(config, "GET", "/api/v2/token/verify", null, null);
@@ -347,6 +572,11 @@ async function runVerify(config) {
347
572
  async function main() {
348
573
  const config = parseArgs();
349
574
 
575
+ if (config.setup) {
576
+ await runSetup();
577
+ return;
578
+ }
579
+
350
580
  if (config.verify) {
351
581
  await runVerify(config);
352
582
  return;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "brilliant-directories-mcp",
3
- "version": "1.0.2",
3
+ "version": "1.2.0",
4
4
  "description": "MCP integration for Brilliant Directories API — manage members, content, leads, and more from any AI agent",
5
5
  "main": "index.js",
6
6
  "bin": {