io.github.CloudCorpRecords/dashcheck

dashcheck

Check a dashboard before you ship it. dashcheck is a small client for the dashboardbase validation service: hand it a setup file and it reports any schema, layout, binding or contents errors; hand it the JSON a widget endpoint actually returned and it checks that body against the widget contract for its type; and when a setup is ready to share, it can mint a read-only link to it that expires after 48 hours.

Setup content can be passed inline as a string or pointed at with a local file path — in the path case the file is read on your machine and its text is what gets sent. Whatever the service returns comes back exactly as it sent it: nothing is trimmed, renamed or summarised on the way through. That includes refusals: if a setup file carries credentials, the service itself refuses to create a link and lists the offending fields, and that refusal body passes through like any other response.

Configuration

Three environment variables control the client:

• DASHBOARDBASE_API_URL (optional) — API base URL. Defaults to https://api.dashboardbase.com.
• DASHBOARDBASE_API_KEY (optional) — when set, it is sent on every request as the x-api-key header. Leaving it unset is not an error: the validation endpoints are usable without a key.
• DASHBOARDBASE_TIMEOUT_MS (optional) — request timeout in milliseconds, enforced with an abort controller. Defaults to 15000; a timeout counts as a fetch failure.

Tools

• validate_setup_file — validate a dashboardbase setup file (JSON) and return any schema, layout, binding, or contents errors. Takes content (the setup file contents) or path (a local path to a setup file); one of them is required.
• validate_widget_response — validate a widget endpoint's JSON response against the dashboardbase widget contract for its type (kpi, timeseries, bar, table or text). Takes response (the JSON body the endpoint returned) or path (a local path to a JSON file holding the response); one of them is required. widgetType is optional and overrides the type field in the response envelope. A response value that parses as JSON is sent as the parsed value; otherwise it is sent as the raw string.
• create_setup_link — create a shareable, read-only setup link for a setup file; the link expires after 48 hours. Takes content or path, as above.

The one-of rule is enforced locally before any request: one of content or path is required (for the widget-response tool, one of response or path is required). A local file that cannot be read fails with cannot read file: <path>. An upstream non-2xx reply fails with dashboardbase error: HTTP <status> and an unreachable API (including a timeout) with dashboardbase unreachable.

Endpoint provenance

The original record pins the three tools, their argument tables, the three environment variables, the 48-hour link behaviour and the credential-refusal behaviour, but it does not publish the upstream HTTP paths. The three paths below are reconstructions, labelled as such:

• POST <base>/validate/setup-file with JSON body {"content": "..."} — reconstruction (used by validate_setup_file).
• POST <base>/validate/widget-response with JSON body {"response": ..., "widgetType": "..."} (the widgetType key is omitted when not given) — reconstruction (used by validate_widget_response).
• POST <base>/setup-links with JSON body {"content": "..."} — reconstruction (used by create_setup_link).

CLI

Each tool is a subcommand taking one JSON argument string:

npx @reneturcios/dashcheck validate_setup_file '{"path":"./setup.json"}'
npx @reneturcios/dashcheck validate_widget_response '{"response":"{\"type\":\"kpi\",\"value\":42}","widgetType":"kpi"}'
npx @reneturcios/dashcheck create_setup_link '{"content":"{\"widgets\":[]}"}'
npx @reneturcios/dashcheck --version

Output is the tool's result text (the upstream body on success). Exit codes: 0 on success, 1 on a runtime error (including a validation, file-read or upstream failure), 2 on a usage error.

MCP server

npx -y @reneturcios/dashcheck mcp

MCP client config (the key is optional; provide it through the client's environment when you have one):

{
  "mcpServers": {
    "dashcheck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/dashcheck", "mcp"],
      "env": {
        "DASHBOARDBASE_API_KEY": "<your key>"
      }
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/dashcheck
docker run --rm ghcr.io/cloudcorprecords/dashcheck validate_setup_file '{"path":"./setup.json"}'

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch and injected file reader only, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios