Dashboard Builder MCP 服务器

让 AI 客户端能够发现您的数据集并在 Dashboard Builder 中创建仪表板。

它作为普通 API 客户端通过 HTTP 与 Next.js 应用通信，因此应用中的每个权限守卫、依赖策略和验证规则仍然生效。主应用无需任何更改。

两种运行方式：

托管是常规部署方式，也是本文档所涵盖的内容。本地模式用于开发服务器本身，或用于按用户身份运行，详见 DEVELOPMENT.md。

面向用户：连接托管服务器

您需要从部署者那里获得两样东西：URL 和 您的网关密钥。无需克隆任何内容，无需指向任何文件，无需 .env。

将其添加到 claude_desktop_config.json（Claude Desktop）或 .mcp.json（Claude Code）：

{
  "mcpServers": {
    "dashboard-builder": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.yourcompany.com/mcp",
        "--header", "Authorization: Bearer YOUR_KEY_HERE",
        "--header", "X-Dashboard-Username: you",
        "--header", "X-Dashboard-Password: your-dashboard-password"
      ]
    }
  }
}

mcpServers 是一个顶级键，是 preferences 的兄弟键——而不是嵌套在它内部。从系统托盘中退出 Claude Desktop 并重新打开；仅关闭窗口是不够的。

带上两个 X-Dashboard-* 请求头后，服务器会在首次使用时自动以您的身份登录，并在会话过期时再次自动登录——无需其他操作，每次调用都以您的身份执行：您的权限、您的审计轨迹。代价是您的仪表板密码会存放在此配置文件中，并随每个请求（通过 HTTPS）传输。如果密码包含 ASCII 以外的字符，请改用下面的 curl 绑定方式——HTTP 请求头无法可靠地携带这些字符。

替代方案：用 curl 一次性绑定，密码不写入配置文件

省略两个 X-Dashboard-* 请求头，改为一次性绑定您的密钥——密码仅用于那一次登录，不会存储在任何地方；服务器只保留生成的会话令牌，就像浏览器保留 cookie 一样：

curl -X POST https://mcp.yourcompany.com/auth/bind \
  -H "Authorization: Bearer YOUR_KEY_HERE" \
  -H "content-type: application/json" \
  -d '{"username":"you","password":"your-dashboard-password"}'

与请求头方式的区别：当会话链最终过期时，您需要重新运行此命令，而请求头方式会自动重新绑定。无论哪种方式，使用相同的 Authorization 请求头调用 DELETE /auth/bind 都会注销该密钥。

Alice's Claude ──[gate key]──> MCP server ──[Alice's session cookies]──> Dashboard API
                     ^                                ^
              client config              bound via credential headers or
                                         POST /auth/bind; refreshed
                                         automatically after that

如果某个密钥从未绑定，工具调用将失败并显示解释绑定步骤的错误——或者，当服务器配置了旧版服务账户时，则回退到该共享身份。

mcp-remote 是一个小型桥接程序，在本地运行并转发到服务器，因此用户机器上必须安装 Node。要连这个都省掉，Claude Desktop 的 设置 → 连接器 → 添加自定义连接器 可以直接接受 URL，无需任何本地组件——但该路径期望 OAuth 而非静态密钥，且可用性因 Desktop 版本而异。

Related MCP server: MCP SQL Server Data Warehouse Connector

部署服务器

server.js 是启动文件。它像 Next.js 的 server.js 一样监听 PORT，并在每个 MCP 请求前设置 API 密钥网关，因此未认证的调用方在到达仪表板系统之前就会被拒绝。

端点：POST /mcp（受网关保护）、POST /auth/bind 和 DELETE /auth/bind（受网关保护——绑定或解绑调用方密钥的仪表板身份），以及 GET /health（开放，供平台健康检查使用）。其他一切返回 404。

环境变量

必需——缺少这些服务器将无法启动

使用 openssl rand -hex 24 生成密钥。冒号前的标签会出现在日志和限流桶中；密钥本身永远不会被记录。要撤销某个人的权限，删除其条目并重启——同时删除 ~/.dashboard-mcp/sessions/ 下对应的会话文件，以同时丢弃绑定的身份。

然后，每个密钥由其持有者通过 POST /auth/bind 绑定到仪表板账户——参见上面的用户部分。服务器的环境中不存放任何仪表板凭据。

可选的旧版回退——共享服务账户

设置后，尚未绑定的密钥将以此共享账户的身份执行操作，而不是失败——绑定已过期的密钥也是如此，直到重新绑定。迁移期间有用；新部署请跳过此项，以便每个调用方都有自己的身份。

强烈推荐

将 DASHBOARD_MCP_PERSIST_SESSION 保持默认值（true）：绑定按每个密钥一个文件存储，并在重启后保留。设为 false 则绑定仅保存在内存中，因此每次重启——以及多工作进程主机中的每个工作进程——都需要重新绑定。

MCP_ALLOWED_HOSTS 和 MCP_ALLOWED_ORIGINS 是可选的——服务器在没有它们的情况下也能运行，API 密钥网关仍然生效。设置其中任何一个都会开启传输层的 DNS 重绑定保护。两者都不设置时，启动日志会明确说明。

可选

更多调优变量——会话文件路径、请求超时、响应上限和仪表板 kind 覆盖——在 .env.example 中有内联文档，该文件按模式组织并列出服务器读取的所有变量。

多工作进程说明

绑定是每个密钥一个文件，某个工作进程的内存令牌被另一个工作进程轮换掉后，会通过重新读取该文件来恢复——该文件已被胜出的工作进程更新。失败窗口是两个工作进程在同一瞬间刷新同一令牌；失败方会在下一次尝试时恢复，最坏情况下该密钥需要重新绑定。MCP 传输层本身是无状态的，因此请求可以落在任何工作进程上。

Plesk 设置

在域名的 Additional nginx directives 中添加：

proxy_buffering off;
proxy_read_timeout 300s;

MCP 以 Server-Sent Events 方式回复，而 nginx 默认会缓冲代理响应。没有 proxy_buffering off，请求会表现为挂起而不是失败，这是一种让人浪费一下午的令人困惑的方式。

保持 Node 端口不暴露在公共防火墙之外。Plesk 的 nginx 代理到该端口并设置 X-Forwarded-For，这正是日志中客户端 IP 可信的原因。

访问与身份

网关密钥控制访问；身份来自绑定。密钥让调用方通过网关，而绑定到该密钥的会话决定仪表板看到的是谁——他们的权限、他们的审计轨迹。两者有意分离：轮换密钥的密钥值会丢弃其绑定（会话按密钥摘要归档），而撤销密钥会移除访问权限而不影响账户。

绑定的工作方式与浏览器登录相同。POST /auth/bind 运行应用真实的 /api/auth/login 一次，密码在交换后被丢弃，只保留轮换的刷新令牌会话——每个密钥一个文件，权限为 0600。由于应用在每次使用时都会轮换刷新令牌，泄露的会话文件很快就会失效；由于密码从不存储，没有长期存在的东西可泄露。代价是：当刷新链过期或中断时，该密钥用一条 curl 命令即可重新绑定。

稳定的每请求凭据（主系统中的 ApiKey，或 OAuth）可以连重新绑定都省掉，但需要在主应用中做更改。本设计刻意不需要任何更改。

本地开发或运行

在您自己的机器上运行服务器——用于开发，或用于无需托管的按用户身份——在 DEVELOPMENT.md 中单独说明。

工具

链路为：数据源（HTTP API 或 Excel 上传）→ 数据集（带转换工作流的塑形视图）→ 仪表板组件。工具覆盖全部三个阶段。

test_datasource 属于写入集合，因为应用将其置于数据源创建/编辑权限之后，并且它会调用上游端点——但它不持久化任何内容。

设计说明

上下文纪律。 整个工具面约占 7 KB——24 个描述加上服务器指令——因此保持加载成本低廉。响应是紧凑文本而非原始 JSON，每个列表都附有关于省略内容的明确说明。get_dashboard 有意省略组件配置；需要配置时按 ID 请求单个组件。

渐进式披露。 图表配置约有 59 个字段。将其放入工具描述会在每次请求时占据客户端上下文的主导地位，因此 describe_widget_kind 改为按需提供契约：字段名、类型、说明、最小可用示例，以及——最有用的部分——从工作区中该类型的现有组件中提取的真实配置。复制一个已经能渲染的形状，胜过根据字段名凭空发明一个。

服务器负责几何布局。 模型在二维排布上不可靠。add_widget 接受 size 提示（small、medium、large、full），并自行在 12 列网格上找到第一个空闲且不重叠的单元格。arrange_dashboard 在 auto 模式下会重新整理整个仪表板。

在 API 之前失败，而不是之后。 组件配置由应用以不透明 JSON 存储，因此拼写错误的键会产生空白组件而非错误。add_widget 首先根据类型契约验证配置——必需键、有效的聚合名称、聚合需要时 field 是否存在——并返回缺失项的具体列表。

组件与 UI 会创建的内容一致。 应用的面板会用注册表中的 defaultConfig 为每个新组件播种（config === undefined ? def.defaultConfig : config）。add_widget 与此对应：类型默认值叠加在调用者提供的任何内容之下，因此 MCP 创建的图表与手工构建的图表具有相同的 paginationMode 和 maxPoints 基线，而不是渲染器不得不回退的稀疏配置。合并后的对象才是被验证的对象。

合并而非重发。 PATCH /widgets/:id 会整体替换配置对象。update_widget 默认将你的键合并到现有配置中，因此更改一个设置并不意味着重发全部内容。

启动时默认拒绝。 没有至少一个 MCP_API_KEYS 条目时，HTTP 服务器拒绝启动，并拒绝少于 24 个字符的密钥。未认证的 MCP 端点绝不应意外存在。密钥以 SHA-256 摘要形式通过 timingSafeEqual 比较，且仅记录标签。

机密保留在服务器端。 describe_datasource 读取应用的 /schema 端点，该端点从不包含凭据。update_datasource 需要完整的存储配置来进行合并——它在工具运行内部获取该配置并发送合并结果，而绝不会将 authConfig、存储的标头或正文渲染到模型的上下文中。

保存前验证。 工作流信封很容易在细微处出错，因此流程是：使用 get_dataset includeWorkflow 复制一个可用的信封，编辑它，运行 validate_dataset_workflow（在服务器端执行并报告每步的行数、输出字段和空值计数，不持久化任何内容），然后使用 update_dataset 保存。

已知限制

• 组件类型目录是副本。 src/catalog/widget-kinds.ts 镜像了 src/features/dashboard/widgets/registry.ts——包括每种类型的 defaultConfig——以及各类型的配置接口。应用的注册表是客户端组件并导入 React，因此无法在此导入。如果组件类型新增字段，或 defaultConfig 值发生变化，也需要更新目录，否则 MCP 创建的组件将与 UI 创建的组件产生偏差。

• 目录覆盖率高但并非完全。 已记录与实际配置字段：table 18/21、stat 22/25、chart 39/59、select 9/12、text 16/17。遗漏的主要是外观变体（饼图/折线图/柱状图样式选项、右侧轴覆盖）以及被 highlightBindings 取代的旧版交互键。describe_widget_kind 返回的实时示例是这些内容的参考。字段按核心/显示/交互分组，以便数据契约优先阅读。

• 绑定随刷新链过期。 密钥的会话持续到应用保持其轮换刷新令牌有效为止。当它失效时，调用会失败并显示指明修复方法的错误，密钥持有者用一条 curl 重新绑定。永不过期的身份需要将 ApiKey 接入主系统中的 src/lib/api-guard.ts，这尚未完成。

• 写入是直接的。 应用具有变更草稿和审批工作流（ChangeDraft、ApprovalRequest）。这些工具以登录账户的权限直接写入。如果 AI 创建的仪表板在上线前需要审核，请将写入工具路由到 /api/change-drafts，并保持账户的授权为只读。

• Excel 数据源在此为只读。 创建或刷新 Excel 数据源需要 multipart 文件上传，这不适合 MCP 文本流程。它们仍会出现在 list_datasources、describe_datasource 和 preview_datasource 中；请在 UI 中创建和刷新它们。

• 没有删除工具。 删除数据源会将软删除级联到基于它构建的每个数据集，因此删除操作保留为 UI 中的人工操作。delete_widget 是唯一暴露的破坏性工具。