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 而不是静态密钥，并且可用性因桌面版本而异。

部署服务器

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 重新绑定保护。两者都不设置，启动日志会明确说明。

可选

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

多工作进程说明

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

Plesk 设置

添加到域的 附加 nginx 指令：

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 中单独记录。

工具

设计说明

上下文纪律。 整个工具面大约占用 3.6 KB——13 个描述加上服务器指令——因此保持加载成本很低。响应是紧凑的文本而非原始 JSON，并且每个列表都以一条明确说明省略内容的注释收尾。get_dashboard 有意省略 widget 配置；当你需要某个 widget 的配置时，按 id 请求该 widget 即可。

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

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

在 API 之前失败，而不是之后。 应用将 widget 配置存储为不透明 JSON，因此拼错的键会产生一个空白 widget 而不是报错。add_widget 首先根据该种类的契约验证配置——必填键、合法的聚合名称、当聚合需要时 field 必须存在——并返回一份具体的缺失项列表。

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

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

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

已知限制

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

• 目录覆盖率很高但并非完全覆盖。 已记录与实际配置字段对比：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，并保持账户的授权为只读。