Skip to main content
Glama
README.md
# 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:

```bash
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

```bash
npx -y @reneturcios/dashcheck mcp
```

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

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

## Docker

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

## Development

```bash
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