dashboardbase

dashboardbase MCP

别再猜测仪表板 JSON 是否正确，直接询问。

这是 dashboardbase 的官方 MCP 服务。将它添加到你的 AI 工具中，它就能根据 dashboardbase 实际执行的契约，检查组件端点的响应，或整个仪表板配置文件，无需先打开应用。

dashboardbase 技能会教你的 Agent 掌握 JSON 契约。这个 MCP 则让它检查自己的成果。两者一起使用：技能确保结构正确，MCP 则验证结果。

---

这个 MCP 能做什么

它为你的 Agent 提供三个工具：

工具	检查内容
validate_setup_file	dashboardbase 配置文件，即用于配置整个仪表板的组件和数据源的 JSON。报告错误和警告，并指出字段、行和列。
validate_widget_response	组件端点返回的 JSON 正文是否符合组件契约。针对每个问题报告路径和消息。
create_setup_link	上传已完成的配置文件，并返回一个可直接打开其导入预览的链接——仅在你提出请求时才会生成。若文件包含凭据，则拒绝处理并列出有问题的字段。

这三个工具都会调用公开的 dashboardbase 工具 API。无需账户、无需 API 密钥，也无需配置任何内容。

使用前 / 使用后

不使用时——你的 Agent 编写端点，你部署它，将它接入 dashboardbase，组件显示错误，你去读文档，修复问题，再次部署。

使用后——你的 Agent 编写端点、验证响应、修复两个错误，然后交给你一个首次渲染就正常的结果。

Invalid setup file — 2 errors, 1 warning

  mappings[0].type  14:9  Unknown widget type "guage"
  mappings[1].path  22:5  Path must start with "/"

  warning  mappings[2]  No refreshInterval set

---

安装

Claude Code

claude mcp add dashboardbase -- npx -y @dashboardbase/mcp

一键安装

Claude Desktop

从最新版本下载 dashboardbase-mcp.mcpb，然后将它拖入 Claude Desktop 的扩展设置中。该安装包包含所有必需内容——甚至无需 Node。

Cursor、Windsurf 和大多数其他客户端

这些客户端使用 mcpServers 格式。将其添加到 ~/.cursor/mcp.json（Cursor）、~/.codeium/windsurf/mcp_config.json（Windsurf）或客户端对应的配置文件中：

{
  "mcpServers": {
    "dashboardbase": {
      "command": "npx",
      "args": ["-y", "@dashboardbase/mcp"]
    }
  }
}

VS Code

VS Code 是个例外——它使用 servers 而非 mcpServers，并且需要显式设置 type。配置位置可以是 .vscode/mcp.json（工作区）或你的用户配置文件：

{
  "servers": {
    "dashboardbase": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@dashboardbase/mcp"]
    }
  }
}

Codex CLI

Codex 使用 TOML。最简单的方式是通过 CLI：

codex mcp add dashboardbase -- npx -y @dashboardbase/mcp

也可以手动编辑 ~/.codex/config.toml：

[mcp_servers.dashboardbase]
command = "npx"
args = ["-y", "@dashboardbase/mcp"]

需要 Node.js 20 或更高版本——这是唯一的前置条件，而且仅适用于 npx 方式。无需进行其他配置：验证 API 是公开的，因此无需设置账户、密钥或环境变量。

保持最新

有两种不同的内容通过两种不同的途径更新，值得了解：

错误消息会自动改进。 服务端不保存任何架构——它会调用实时 API——因此验证消息一旦改进，你就能立即看到。无需更新。

新工具需要更新软件包。 如果某个版本新增了工具，需要等软件包更新，并且客户端重启服务端后才能使用。运行中的服务端在整个会话期间，工具列表都是固定的。

安装方式	更新方式
npx（Claude Code、Cursor、VS Code、Windsurf、Codex）	自动更新——重启客户端后，下次启动服务端时会使用最新版本。
Claude Desktop .mcpb	安装时固定版本。请从 releases 下载新版程序包并再次拖入。
Docker	执行 docker pull／重新构建镜像。

检查当前运行的版本：

npx -y @dashboardbase/mcp --version

如果显示的版本早于最新版本，说明 npm 提供的是缓存的注册表元数据——刚发布的版本可能需要几分钟才会显示。强制更新：

npx -y @dashboardbase/mcp@latest --version

版本发布遵循 semver：新增工具只会提升次版本号，绝不会破坏现有调用，因此默认可以安全更新。

---

使用方法

首先，检查是否已连接

claude mcp list

你应该能看到 dashboardbase 显示为已连接。在 Claude Code 会话中，/mcp 会显示该服务端及其三个工具。在其他客户端中，请在 MCP 面板或工具面板中查找 dashboardbase。

如果没有显示，说明服务端未能启动——请检查 node --version 是否为 20 或更高版本，并确认配置文件包含有效的 JSON。

然后直接提出请求

你无需亲自调用这些工具。 描述你的需求，Agent 会自行决定调用它们，就像决定读取文件一样。无需特殊语法，也无需记住任何内容。

验证已有内容：

• “验证我的 dashboardbase 配置文件”
• “.dashboardbase/revenue.json 是否有效？”
• “检查它是否符合 dashboardbase 契约”——然后粘贴 JSON

在构建过程中验证：

• “为 MRR 构建一个 KPI 端点，然后验证它返回的响应”
• “在我的配置文件中添加一个仪表盘组件，并确保验证仍能通过”

调试故障：

• “我的仪表盘组件在 dashboardbase 中显示错误——检查我的端点返回的内容是否符合契约”
• “为什么 dashboardbase 拒绝我的配置文件？”

实际效果

你： 我的收入组件没有渲染。检查 .dashboardbase/revenue.json。

Agent： 调用 validate_setup_file

Invalid setup file — 2 errors

  mappings[0].type  14:9  Unknown widget type "guage"
  mappings[1].path  22:5  Path must start with "/"

Agent： 有两个问题——guage 是 gauge 的拼写错误，第二个映射的路径缺少开头的斜杠。现在修复这两个问题。

编辑文件，再次调用 validate_setup_file

Valid setup file — no errors.

这个循环——验证、修复、重新验证——正是它的全部价值。Agent 会自行完成整个流程，你无需打开 dashboardbase。

或直接调用

在 Claude Code 中，服务会添加一个斜杠命令——输入 /，就能在菜单中找到：

/mcp__dashboardbase__validate .dashboardbase/revenue.json

不填写路径，它就会验证你正在处理的内容，或接下来粘贴的内容。这是确定性调用方式：不依赖 Agent 判断工具是否适用。

中间部分取决于你安装时使用的名称。如果你运行的是 claude mcp add dashboardbase …，命令就是 /mcp__dashboardbase__validate；如果安装时使用了其他名称，中间部分也会相应变化。

在不支持 MCP 提示词的客户端中，只需用普通语言说出工具名称：

• “对 .dashboardbase/revenue.json 使用 validate_setup_file”
• “使用 validate_widget_response 检查这个内容”

Agent 有时第一次需要提示一下；之后通常就会自行调用。

三种工具

工具	参数	说明
validate_setup_file	content — 文件文本 path — 改为从磁盘读取	二选一即可。
validate_widget_response	response — 端点的 JSON 正文 path — 改为从磁盘读取 widgetType — 可选，例如 kpi	如果省略 widgetType，将根据响应推断。
create_setup_link	content — 文件文本 path — 改为从磁盘读取	链接会在 48 小时后过期，任何持有链接的人都可以读取文件，因此请直接分享给对方。

有两点需要注意：

• **path 仅在 stdio 模式下可用。**托管的 HTTP 部署无法访问你的磁盘，因此不会提供此参数——请改为传入 content / response。
• validate_widget_response 需要完整的响应正文——也就是端点实际返回的 title / actions / data / alert 封装结构，而不只是内部的 data 负载。

配置

所有配置项均为可选。

变量	默认值	用途
DASHBOARDBASE_API_URL	https://api.dashboardbase.com	指向其他环境。
DASHBOARDBASE_API_KEY	未设置	作为 x-api-key 发送。公共 API 无需设置。
DASHBOARDBASE_TIMEOUT_MS	15000	请求超时时间，单位为毫秒。

作为 HTTP 服务运行

用于容器或共享的内部部署：

npx @dashboardbase/mcp --http --port 3000
# or
docker build -t dashboardbase-mcp . && docker run -p 3000:3000 dashboardbase-mcp

在 /mcp 提供 Streamable HTTP 服务，并在 /health 提供健康检查。服务完全无状态，因此可以水平扩展，无需会话亲和性。除非使用 --allowed-origin https://example.com 将浏览器源加入允许列表，否则会拒绝浏览器源。此模式下不会公开读取文件的 path 参数。

---

仓库内容

mcp/
├── src/
│   ├── index.ts            # CLI entry — stdio by default, --http optional
│   ├── server.ts           # Registers the three tools
│   ├── api.ts              # Client for the dashboardbase Tools API
│   ├── format.ts           # Renders results as readable text
│   ├── http.ts             # Stateless Streamable HTTP handler
│   └── tools/              # One file per tool
├── test/                   # Unit tests, no network required
├── tools.json              # OpenAPI spec for the validation API
├── server.json             # MCP Registry manifest
├── manifest.json           # Claude Desktop bundle manifest
└── Dockerfile

验证机制

服务本身不包含一份模式副本，而是调用实时的 dashboardbase 验证 API。因此它不会与平台接受的内容产生偏差，并且随着 API 改进，错误消息也会变得更好，你无需在本地进行升级。

这适用于验证规则和消息，不包括服务本身——新增工具的版本仍需要更新软件包。请参阅保持最新。

相关资源

• dashboardbase — 产品主页。基于你的 API 构建、托管并分享仪表盘。
• dashboardbase skill — 免费安装；帮助 Agent 掌握 JSON 契约，从一开始就编写正确的端点。可与此 MCP 直接配合使用。
• 文档 — 组件参考、JSON 契约、Webhook 设置。

参与贡献

发现遗漏或难以理解的错误？请提交 issue。请注意，验证规则本身位于 dashboardbase 后端——如果是错误消息不清楚，也欢迎在此反馈，我们会在上游修复。

许可证

MIT — 详见 LICENSE。你可以 fork、修改并发布。

MIT 许可证适用于此仓库中的代码，不适用于 dashboardbase 这个名称或徽标，它们归 Kompile ApS 所有。你可以自由使用和修改此服务；请勿以暗示官方关联的方式使用该名称或品牌标识。

dashboardbase skill 的许可方式不同：可免费安装和使用，但不是开源软件。