Brilliant Directories API — 通用 AI 集成

只需一个 API 密钥，即可让任何 AI 代理完全访问您的 BD 网站。

涵盖 32 个资源（会员、潜在客户、文章、评论、分类、电子邮件模板、页面（主页、落地页）、301 重定向、智能列表、小工具、菜单、表单、会员计划等）的 170 个端点。

30 秒快速入门

一条命令。回答两个问题。搞定。

npx brilliant-directories-mcp --setup

该向导会询问您的 BD 网站 URL 和 API 密钥，测试连接，询问您使用的应用程序（Cursor / Claude Desktop / Windsurf / Claude Code），并为您编写配置。无需手动编辑 JSON。

重启您的应用程序，然后询问您的 AI：

"List members on my BD site"

从 BD Admin > Developer Hub > Generate API Key 获取您的 API 密钥。

针对 AI 代理 / 脚本（非交互式）

如果 AI 代理正在引导您，它可以让您粘贴一条预填好所有信息的命令：

npx brilliant-directories-mcp --setup --url https://your-site.com --api-key YOUR_KEY --client cursor

这将直接运行完整的设置，无需任何提示。将 cursor 替换为 claude-desktop、windsurf、claude-code 或 print（打印 JSON 配置而不是写入文件）。

按平台设置

Claude Code / Cursor / Windsurf / Cline (MCP)

选项 A — npx（推荐，无需安装）：

claude mcp add bd-api -- npx brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com

选项 B — 全局安装：

npm install -g brilliant-directories-mcp
claude mcp add bd-api -- brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com

Cursor / Windsurf / Cline — 添加到您的 MCP 配置文件（~/.cursor/mcp.json 等）：

{
  "mcpServers": {
    "bd-api": {
      "command": "npx",
      "args": ["-y", "brilliant-directories-mcp", "--api-key", "YOUR_KEY", "--url", "https://your-site.com"]
    }
  }
}

然后询问您的 AI："List all members on my BD site" 或 "Create a new member with email john@example.com"

ChatGPT (GPT Actions)

1. 在您的 GPT 中：Configure > Actions > Create new action

2. 在 Schema 下，选择 Import from URL 并粘贴：

   https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/openapi/bd-api.json

3. 当提示输入 bd_site_url 时，输入您的 BD 网站（例如 https://mysite.com）

4. 设置身份验证：API Key，Auth Type：Custom，Header Name：X-Api-Key，粘贴您的密钥

n8n

选项 A — 导入 OpenAPI 规范（推荐）：

将规范 URL 作为自定义 API 定义导入：

https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/openapi/bd-api.json

n8n 在导入时会提示您输入 BD 网站 URL 和 API 密钥。无需编辑文件。

选项 B — 普通 HTTP Request 节点：

1. 创建一个新工作流，添加一个 HTTP Request 节点

2. 设置：

   • Method: GET

   • URL: https://your-site.com/api/v2/user/get

   • Header: X-Api-Key: YOUR_KEY

Make / Zapier

Make： 使用 OpenAPI 规范创建一个自定义应用，或使用带有 X-Api-Key 头的 HTTP 模块。

Zapier： 如果您已经拥有 BD Zapier 应用，它使用相同的底层 API。对于新的端点，请使用带有 X-Api-Key 头的 Webhooks by Zapier。

curl / 任何 HTTP 客户端

# Verify your API key
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/token/verify

# List members
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/user/get?limit=10

# Create a member
curl -X POST -H "X-Api-Key: YOUR_KEY" \
  -d "email=new@example.com&password=secret123&subscription_id=1&first_name=Jane&last_name=Doe" \
  https://your-site.com/api/v2/user/create

# Search members
curl -X POST -H "X-Api-Key: YOUR_KEY" \
  -d "q=dentist&address=Los Angeles&limit=10" \
  https://your-site.com/api/v2/user/search

# Update a member
curl -X PUT -H "X-Api-Key: YOUR_KEY" \
  -d "user_id=42&company=New Company Name" \
  https://your-site.com/api/v2/user/update

故障排除

用一条命令验证您的设置：

npx brilliant-directories-mcp --verify --api-key YOUR_KEY --url https://your-site.com

如果凭据有效，则打印 OK，否则打印 FAIL 并显示错误。这是解决任何连接问题的首要步骤。

调试模式 — 查看具体发生了什么：

npx brilliant-directories-mcp --debug --verify --api-key YOUR_KEY --url https://your-site.com

将每个 API 请求和响应记录到 stderr（您的 API 密钥会自动脱敏），然后退出。当某些功能无法正常工作且您想与 BD 支持人员共享输出时非常有用。

去掉 --verify 以启动带有调试日志的完整 MCP stdio 服务器 — 它在普通终端中看起来会挂起，因为 MCP 服务器通过 stdio 永久运行，等待 AI 客户端连接。使用 --debug --verify 进行 shell 中的一次性调试。

常见问题：

• 401 Unauthorized — API 密钥错误、已撤销或缺乏该端点的权限

• 404 Not Found — 网站 URL 错误（检查是否有拼写错误；如果缺少 https:// 会自动添加）

• 429 Too Many Requests — 达到速率限制（默认 100 次请求/60秒）；请稍后再试或在 BD 管理后台增加限制

• Unknown tool (来自 Claude) — MCP 服务器未加载 OpenAPI 规范；请使用 npm install -g brilliant-directories-mcp 重新安装

身份验证

所有请求都需要 X-Api-Key 头：

X-Api-Key: your-api-key-here

API 密钥受权限范围限制 — 您可以控制每个密钥可以访问哪些端点。

速率限制

默认： 每个 API 密钥每 60 秒 100 次请求。 按需： 每分钟最多 1,000 次请求 — 请联系 Brilliant Directories 支持团队以提高您网站的限制（100 到 1,000/分钟之间的任何值）。

该限制由 BD 在服务器端设置，而非您在管理后台的自助设置。如果您预计会有大量的 API 使用，请在进行批量操作前通过电子邮件联系 BD 支持，并申请临时或永久增加限制。

当超过限制时，API 会返回 HTTP 429 Too Many Requests。MCP 服务器会将其作为可操作的错误呈现给您的 AI 代理 — 它将知道稍后再试或建议申请更高的限制。

规划批量操作： 如果您要求代理导入/更新数百条记录，请（a）先向 BD 支持申请更高的限制，或（b）告诉代理放慢速度（例如，“导入这 500 个会员，并暂停以遵守 100 次/分钟的速率限制”）。

分页

所有列表端点都支持分页：

响应包括：total、current_page、total_pages、next_page、prev_page

过滤

所有列表端点都支持过滤：

GET /api/v2/user/get?property=city&property_value=Los Angeles&property_operator==

多重过滤：

GET /api/v2/user/get?property[]=city&property_value[]=Los Angeles&property[]=state_code&property_value[]=CA

运算符：=, LIKE, >, <, >=, <={

排序

GET /api/v2/user/get?order_column=last_name&order_type=ASC

可用资源

字段发现

部分端点支持动态字段发现：

# Get all available user fields
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/user/fields

# Get custom fields for a specific post type
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/data_posts/fields?form_name=my-form

文件

稳定的资产 URL

对于通过 URL 导入规范的工具（ChatGPT Actions, n8n, Postman）：

https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/openapi/bd-api.json

安全性

• API 密钥绝不会嵌入到包中

• 所有请求直接从用户的机器发送到他们的 BD 网站

• 没有数据通过第三方服务器

• API 密钥权限控制可访问哪些端点

• 请像对待密码一样对待您的 API 密钥

支持

• BD 支持：https://support.brilliantdirectories.com

• API 文档：https://support.brilliantdirectories.com/support/solutions/articles/12000108045