1. 项目概述为你的Brilliant Directories站点注入AI智能如果你正在运营一个基于Brilliant Directories以下简称BD构建的目录网站无论是商业名录、服务商黄页还是社区资源库日常的内容更新、会员管理和页面维护工作都可能相当繁琐。想象一下你不再需要手动登录后台点击几十个页面来添加新会员、更新分类或设计一个落地页。现在你可以直接告诉你的AI助手“帮我列出上周注册的所有会员并给他们发送一封欢迎邮件”或者“在‘洛杉矶’分类下创建一个新的牙医列表标题是‘阳光牙科诊所’”。这一切通过将你的BD站点与AI代理如Claude、Cursor等连接就能实现。这个项目的核心就是brilliant-directories-mcp——一个遵循Model Context ProtocolMCP标准的服务器。它本质上是一座桥梁将BD平台丰富的REST API能力管理会员、文章、页面、表单、标签等数十种资源安全、标准化地暴露给你日常使用的AI工具。这意味着你的AI助手不再只是一个聊天机器人它变成了一个能直接操作你网站后台的“数字员工”。我花了相当一段时间来配置和测试这套流程发现它确实能极大提升内容运营和站点管理的效率尤其是当你需要处理批量操作或复杂的数据关联时。2. 核心原理与架构拆解MCP如何让AI“动手”在深入实操之前理解背后的“为什么”至关重要。这能帮你避开很多配置陷阱并在出现问题时快速定位。2.1 Model Context Protocol (MCP)AI的“手和眼睛”你可以把MCP想象成一套标准的“插件”协议。在没有MCP之前每个AI应用如Claude Desktop、Cursor如果想接入外部服务如你的BD网站都需要单独开发适配器这既低效也不安全。MCP定义了一套统一的通信规范AI应用作为“客户端”外部服务如brilliant-directories-mcp作为“服务器”。服务器通过MCP向客户端宣告“我这里有哪些工具Tools可用”比如list_members、create_page。当你在AI聊天框里提出需求时AI会理解你的意图选择对应的工具并通过MCP协议调用它。关键优势标准化一次编写brilliant-directories-mcp服务器所有支持MCP的客户端Claude, Cursor, Windsurf等都能即插即用。安全性API密钥等敏感信息保存在你的本地配置或受信任的托管服务中AI应用本身不存储这些密钥。通信通常发生在你的机器内部或通过加密的HTTPS连接。能力扩展AI模型本身的知识截止于某个时间点且无法直接操作外部系统。MCP赋予了它实时获取和操作特定数据的能力使其变得“有用”。2.2 Brilliant Directories MCP 服务器的两种形态项目提供了两种部署方式对应不同的技术架构理解它们有助于你做出正确选择。 简易路径托管模式这种方式下你配置AI客户端直接连接到一个由官方托管的MCP服务器https://brilliantmcp.com。你的AI客户端将工具调用请求发送到这个远程服务器该服务器验证你的API密钥和站点URL后代表你向你的BD站点发起真正的API请求。优点无需安装Node.js或任何依赖配置最简单30秒内完成。服务器维护和升级由官方负责。缺点所有请求都需要经过第三方服务器尽管是官方的。对于网络环境有严格内网要求或对延迟极其敏感的场景可能不适用。工作原理图简化你的AI客户端 (Claude) - HTTPS - 托管MCP服务器 (brilliantmcp.com) - HTTPS - 你的BD站点️ 高级路径本地进程模式这种方式下你通过配置让AI客户端在本地启动一个brilliant-directories-mcp的Node.js进程。这个进程就运行在你的电脑上AI客户端通过本地进程间通信stdio与它交互。优点所有数据流转都在你的本地机器完成无需经过任何外部服务器理论上延迟更低隐私性更强。缺点需要预先安装Node.js环境配置稍复杂。你需要自行确保本地MCP进程的稳定运行。工作原理图简化你的AI客户端 (Claude) - 本地进程通信 - 本地MCP服务器进程 - HTTPS - 你的BD站点我的选择建议对于绝大多数用户尤其是初次尝试者强烈推荐使用简易路径。它避免了环境依赖问题且官方托管服务通常有更好的可用性和维护保障。只有在你的公司安全策略明确禁止数据经过外部服务或者你希望进行深度自定义开发时才需要考虑高级路径。2.3 权限模型安全的第一道闸门这是新手最容易“踩坑”的地方。BD的API密钥设计遵循“最小权限原则”。新生成的API密钥默认只拥有对“会员Members”资源的读写权限。这意味着什么如果你只配置了API密钥但没有调整权限那么AI可以顺利地帮你“列出会员”或“创建新会员”。但一旦你让它“创建一个新页面”或“修改网站菜单”它会立刻返回一个403 API Key does not have permission to access this endpoint错误。你会困惑于“明明连接成功了为什么这个功能不行”问题根源就在于权限未开启。必须完成的权限配置步骤登录你的BD网站后台。进入Developer Hub。找到你用于MCP的API密钥点击其Actions下拉菜单选择Permissions。切换到Advanced Endpoints标签页。将你需要用到的资源端点全部切换为“ON”。为了快速开始我建议先全部打开。之后你可以根据AI实际使用的工具再回来精细化关闭不必要的权限特别是delete删除类操作以降低误操作风险。点击Save Permissions。权限更改是即时生效的无需重新生成密钥或重启AI。重要心得在开始任何实质性操作前花5分钟检查并配置好API密钥的Advanced Endpoints权限。这能避免你后续花费大量时间在错误的调试方向上。我建议为生产环境创建一个专用的、权限精细控制的API密钥而为测试和开发环境使用一个拥有全部权限的密钥。3. 分平台详细配置指南与避坑实录不同AI客户端的配置界面和文件位置各不相同。下面我将以最常用的几个平台为例拆解每一步操作并附上我实际配置中遇到的典型问题和解决方法。3.1 Claude Desktop 配置详解Claude Desktop是Anthropic官方的桌面应用对MCP的支持最原生。配置的核心是修改一个JSON配置文件。操作步骤打开Claude Desktop应用。点击左上角菜单栏的Claude-SettingsWindows可能在File菜单。切换到Developer标签页。点击Edit Config。这会用文本编辑器打开一个名为claude_desktop_config.json的文件。配置文件处理两种场景场景A全新配置文件或文件中没有mcpServers字段。直接清空文件粘贴以下配置块推荐使用简易路径{ mcpServers: { brilliant-directories: { url: https://brilliantmcp.com, headers: { X-Api-Key: 你的32位BD_API_KEY, X-BD-Site-URL: https://你的站点域名.com } } } }将你的32位BD_API_KEY和https://你的站点域名.com替换成你的实际信息。务必注意URL不要以斜杠结尾。场景B配置文件中已有其他内容如其他MCP服务器或偏好设置。你需要合并配置而不是覆盖。关键是在正确的位置添加逗号和新的配置块。 例如原文件内容为{ preferences: { menuBarEnabled: false } }修改后应为{ preferences: { menuBarEnabled: false }, mcpServers: { brilliant-directories: { url: https://brilliantmcp.com, headers: { X-Api-Key: 你的32位BD_API_KEY, X-BD-Site-URL: https://你的站点域名.com } } } }注意在preferences的结束大括号后添加了逗号并将新的mcpServers块放在最后的大括号之前。保存并重启保存配置文件。完全退出Claude Desktop应用。在Mac上使用CmdQ或从菜单栏退出在Windows上右键点击系统托盘右下角的Claude图标并选择“退出”。重新启动Claude Desktop。验证与排查成功标志启动后在聊天输入框的右下角你会看到一个锤子图标旁边可能显示一个数字代表加载的工具数量。点击它可以查看所有可用的BD工具列表。无图标/报错前往Settings - Developer - MCP servers查看状态。如果brilliant-directories显示错误请按以下顺序检查JSON格式将你的整个配置文件内容粘贴到 jsonlint.com 验证。缺少逗号或括号不匹配是常见错误。API密钥与URL确认密钥正确且已开启Advanced Endpoints权限URL格式正确有https无末尾斜杠。网络问题仅简易路径检查防火墙是否阻止了对brilliantmcp.com的访问。3.2 Cursor 配置详解Cursor是深度集成AI的代码编辑器其MCP配置非常直观。它有两种配置方式通过官方目录一键安装或手动编辑配置文件。方法一通过 Cursor Directory 一键安装推荐这是最傻瓜式的方法适合不想手动编辑JSON文件的用户。在浏览器中打开https://cursor.directory/plugins/brilliant-directories。点击页面上的Install或Add to Cursor按钮。浏览器会请求打开Cursor应用并弹出一个“Install MCP Server?”的预填充配置窗口。你需要修改两个地方Name不要保留默认的server。建议改为有意义的名称如brilliant-directories-主站或bd-mcp-你的站点名。这样当你管理多个BD站点时可以轻松区分。Environment Variables在右侧填入你的值。BD_API_KEY: 你的BD API密钥。BD_API_URL:https://你的站点域名.com注意格式。点击Install。完全退出并重新启动Cursor。验证进入Cursor的Settings - Tools MCP你应该能看到新添加的服务器并且状态是启用的。方法二手动编辑配置文件如果目录安装失败或者你偏好手动控制可以编辑配置文件。找到Cursor的MCP配置文件路径通常为Mac/Linux:~/.cursor/mcp.jsonWindows:%USERPROFILE%\.cursor\mcp.json如果文件或目录不存在需要手动创建。用文本编辑器打开mcp.json文件。粘贴以下配置以简易路径为例{ mcpServers: { brilliant-directories: { url: https://brilliantmcp.com, headers: { X-Api-Key: 你的32位BD_API_KEY, X-BD-Site-URL: https://你的站点域名.com } } } }保存文件并完全退出再重启Cursor。一个强大的技巧多站点管理。你可以重复上述安装或配置步骤为每一个你管理的BD站点创建一个独立的MCP服务器配置只需使用不同的Name、BD_API_KEY和BD_API_URL。这样在同一个Cursor会话中你可以指挥AI操作不同的站点例如“在‘主站’上列出所有会员然后在‘测试站’上创建同样的分类结构”。AI能根据工具调用的上下文区分目标站点。3.3 在VS Code中使用Cline扩展Cline是VS Code的一个AI助手扩展。它的配置独立于Cursor也独立于VS Code本身的其他AI扩展。关键概念区分Cline扩展的MCP配置文件位于~/.claude.json(Mac/Linux) 或C:\Users\用户名\.claude.json(Windows)。配置在这里工具会在你与Cline聊天时出现。Cursor的MCP配置文件位于~/.cursor/mcp.json。两者互不影响。配置步骤在VS Code中确保已安装Cline扩展并激活。点击侧边栏的Cline图标打开面板。在Cline面板的顶部导航栏找到并点击MCP Servers图标通常是一个插头或服务器形状的图标。点击Configure MCP Servers这会在VS Code中打开配置文件。粘贴配置简易路径示例{ mcpServers: { brilliant-directories: { url: https://brilliantmcp.com, headers: { X-Api-Key: 你的32位BD_API_KEY, X-BD-Site-URL: https://你的站点域名.com } } } }保存文件返回Cline的MCP Servers面板确保brilliant-directories被启用Toggle为On。你可能需要重新加载Cline面板或重启VS Code以使工具生效。3.4 通过CLI连接Claude Code / OpenAI Codex对于喜欢命令行或需要在无GUI环境下集成的用户可以通过CLI进行配置。Claude Code CLI:首先你需要全局安装anthropic-ai/claude-code。npm install -g anthropic-ai/claude-code然后使用以下命令添加MCP服务器简易路径claude mcp add brilliant-directories --transport http https://brilliantmcp.com \ --header X-Api-Key: 你的BD_API_KEY \ --header X-BD-Site-URL: https://你的站点域名.com添加后使用claude mcp list验证然后重启Claude Code会话。OpenAI Codex CLI:OpenAI的ChatGPT网页版等目前不支持MCP但其Codex CLI支持。首先安装CLInpm install -g openai/codex然后编辑其TOML格式的配置文件~/.codex/config.toml或 Windows的%USERPROFILE%\.codex\config.toml[mcp_servers.brilliant-directories] command npx args [-y, brilliant-directories-mcplatest, --api-key, 你的BD_API_KEY, --url, https://你的站点域名.com]保存后运行codex即可。4. 核心使用场景与AI指令范例连接成功后你的AI助手就获得了操作BD站点的能力。以下是一些真实可用的指令范例展示了AI如何从“聊天伙伴”转变为“运营助手”。4.1 会员与用户管理查询与分析“列出过去7天内注册的所有会员并显示他们的邮箱和公司名。”“找出所有订阅了‘高级会员’计划但尚未支付首笔费用的用户。”“统计来自‘纽约’市的会员数量并按注册日期排序。”创建与更新“创建一个新会员邮箱是johnexample.com密码设为TempPass123!分配‘基础会员’订阅计划名字John姓氏Doe。”“将会员ID为456的用户的公司名称更新为‘新科技有限公司’并为其添加‘VIP客户’标签。”“批量将‘试用期已过’标签下的所有会员转移到‘待跟进’标签。”4.2 内容与页面管理文章与博客“以会员ID 123的身份发布一篇新的博客文章标题是‘行业最新趋势’内容来自这个文档附上文档并选择‘行业新闻’作为主分类。”“查找所有包含‘促销’关键词的文章并将它们的发布日期更新为今天。”页面与导航“在网站顶部主导航栏的‘服务’菜单下添加一个名为‘咨询’的新链接指向/consulting页面。”“创建一个新的落地页URL路径设为/summer-promo标题为‘夏季限时优惠’并插入一个联系表单小部件。”“设置一个301重定向将旧的/about-us.html永久重定向到新的/about页面。”4.3 营销与自动化潜在客户与评论“显示最近一个月内通过‘联系我们’表单提交的所有潜在客户信息。”“审核并发布所有状态为‘待审核’的客户评论。”邮件与列表“使用‘欢迎新会员’邮件模板给今天注册的所有会员发送一封欢迎邮件。”“创建一个智能列表包含所有在过去90天内登录过、且标签包含‘活跃用户’的会员。”“在侧边栏小部件区域添加一个显示‘本周热门商家’的小部件。”给AI的指令技巧从查询开始在进行任何写操作创建、更新、删除前先让AI“列出”或“显示”相关数据确认你的目标对象是正确的。明确指定尽量提供具体参数如会员ID、文章标题、分类名称等。AI虽然能推理但明确的信息能减少错误。分步进行对于复杂操作可以分解成多个指令。例如“1. 先创建一个新页面。2. 然后获取这个新页面的ID。3. 最后将这个页面链接添加到主菜单。”5. 高级技巧、问题排查与安全实践5.1 验证与调试命令在遇到连接问题时不要盲目猜测。使用项目提供的命令行工具进行快速诊断。基础连通性验证在终端Mac的TerminalWindows的PowerShell中运行以下命令替换为你自己的密钥和URLnpx brilliant-directories-mcplatest --verify --api-key 你的BD_API_KEY --url https://你的站点域名.com这个命令会直接测试你的API密钥和站点URL是否能成功访问BD API。如果一切正常它会输出OK。如果失败它会显示具体的HTTP状态码和错误信息这是排查的第一步。启用调试模式如果基础验证通过但AI客户端仍然无法工作可以使用调试模式查看详细的通信日志npx brilliant-directories-mcplatest --debug --verify --api-key 你的BD_API_KEY --url https://你的站点域名.com--debug参数会让工具输出每个API请求和响应的详细信息你的API密钥会被自动脱敏帮助你判断是权限问题、参数错误还是网络问题。5.2 常见错误代码与解决方案速查表错误现象/代码可能原因解决方案AI提示“没有可用工具”或“无法访问”1. AI客户端未重启。2. 配置文件JSON格式错误。3. MCP服务器配置未正确加载。1.完全退出并重启AI应用。2. 用 jsonlint.com 验证配置文件。3. 检查客户端MCP服务器列表状态。401 UnauthorizedAPI密钥错误、已撤销或完全无效。1. 登录BD后台在Developer Hub重新生成密钥。2. 在配置文件中更新为新密钥。3. 重启AI应用。403 Forbidden(API Key does not have permission)API密钥缺少访问特定端点如pages,forms的权限。1. 登录BD后台进入该API密钥的Permissions设置。2. 在Advanced Endpoints中启用对应资源的权限。3. 保存后立即重试。404 Not Found提供的BD站点URL不正确。确保URL格式为https://你的域名.com没有末尾的斜杠 (/)。429 Too Many Requests触发了API速率限制默认每分钟100次请求。1. 暂停操作等待一分钟。2. 如需更高限制联系BD支持申请提升配额。工具调用超时或无响应1. 网络问题简易路径。2. 本地Node.js进程卡住高级路径。3. BD站点服务器响应慢。1. 检查网络连接。2. 尝试使用--verify命令测试。3. 对于高级路径确保Node.js版本不是太旧。5.3 生产环境安全最佳实践将AI直接连接到生产网站意味着赋予它强大的操作能力。遵循以下原则可以最大程度降低风险使用专用API密钥不要复用其他集成中使用的API密钥。为MCP连接单独创建一个密钥便于权限管理和紧急吊销。遵循最小权限原则在测试初期可以开启所有权限。一旦稳定后回到BD后台的密钥权限设置仔细关闭AI不需要的、特别是所有delete删除操作的权限。这样即使AI被错误指令触发也无法删除关键数据。操作前预览养成让AI“先显示后操作”的习惯。例如在删除一批会员前先让AI“列出所有符合XX条件的会员”给你确认。善用测试环境如果条件允许在一个独立的BD测试站点上先行配置和测试所有AI操作流程。确认无误后再应用到生产环境。定期备份确保你的BD网站有定期的数据备份机制。这是应对任何意外操作的最后防线。密钥保管API密钥相当于密码。不要将其提交到公开的代码仓库或分享给不可信方。配置文件通常位于用户目录下相对安全。5.4 性能与扩展考量速率限制注意BD API的默认速率限制。复杂的、循环的AI指令可能会快速触发限制。如果AI报告“操作失败”或“超时”可能是遇到了限流。让AI将复杂任务分解或在指令间加入短暂延迟。数据量当要求AI处理大量数据如“列出所有会员”时响应可能会很慢或超时。建议在查询中总是使用分页参数例如“列出前50个会员”。多站点效率如前所述配置多个MCP服务器连接不同站点可以让AI成为你管理整个BD站点网络的统一控制台极大提升跨站操作的效率。通过以上步骤你应该能够顺利地将你的Brilliant Directories站点与AI助手连接起来。这个过程的核心价值在于它将结构化的数据操作能力赋予了自然语言界面让你能用说话的方式管理网站。从简单的数据查询到复杂的批量更新很多原本需要多次点击和跳转的任务现在一句话就能搞定。在实际使用中我建议从一个简单的查询任务开始逐步尝试更复杂的操作并随时利用验证和调试命令来解决问题。这套工具链的成熟度已经相当高一旦配置完成它将成为你内容运营和网站管理中一个不可或缺的效率倍增器。