Brilliant Directories API — 범용 AI 통합

단 하나의 API 키로 모든 AI 에이전트가 귀하의 BD 사이트에 완전히 액세스할 수 있도록 하세요.

회원, 리드, 게시물, 리뷰, 카테고리, 이메일 템플릿, 페이지(홈페이지, 랜딩 페이지), 301 리다이렉트, 스마트 리스트, 위젯, 메뉴, 양식, 멤버십 플랜 등 32개 리소스에 걸친 170개의 엔드포인트를 제공합니다.

30초 퀵스타트

명령어 하나. 두 가지 질문에 답변. 완료.

npx brilliant-directories-mcp --setup

마법사가 귀하의 BD 사이트 URL과 API 키를 묻고, 연결을 테스트하며, 사용하는 앱(Cursor / Claude Desktop / Windsurf / Claude Code)을 확인한 후 설정을 자동으로 작성합니다. JSON을 직접 수정할 필요가 없습니다.

앱을 재시작한 후 AI에게 다음과 같이 물어보세요:

"List members on my BD site"

API 키는 BD 관리자 페이지 > Developer Hub > Generate API Key에서 얻을 수 있습니다.

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 서버는 AI 클라이언트가 연결되기를 기다리며 stdio를 통해 영원히 실행되므로 일반 터미널에서는 멈춘 것처럼 보일 수 있습니다. 셸에서 일회성 디버깅을 하려면 --debug --verify를 사용하세요.

일반적인 문제:

• 401 Unauthorized — API 키가 잘못되었거나, 취소되었거나, 해당 엔드포인트에 대한 권한이 없음

• 404 Not Found — 사이트 URL이 잘못됨 (오타 확인; 누락된 경우 https://가 자동으로 추가됨)

• 429 Too Many Requests — 속도 제한 도달 (기본값 100 req/60s); 잠시 대기하거나 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 사이트로 전송됩니다.

• 제3자 서버를 통해 데이터가 전달되지 않습니다.

• API 키 권한으로 액세스 가능한 엔드포인트를 제어합니다.

• API 키를 비밀번호처럼 취급하세요.

지원

• BD 지원: https://support.brilliantdirectories.com

• API 문서: https://support.brilliantdirectories.com/support/solutions/articles/12000108045