# brandcheck

Does your brand actually show up when a buyer asks an AI
assistant for a recommendation? brandcheck is a small
keyless bridge to the hosted AskedThrice measurement
service, which asks real buyer questions to OpenAI,
Anthropic and Gemini and reports what they answered —
not what they claim they would answer.

There is no score from 0 to 100. A finished measurement
reports a verdict in three bands, how many of the buyer
questions the brand won, which competitors were named
instead, and which providers actually answered. The
service is free, needs no signup and no API key, and
allows one measurement per domain every 30 days; that
quota lives upstream, and a `quota_reached` answer
passes through this client untouched.

## Tools

- `start_visibility_check` — start a measurement for a
  brand. Required: `brand` (the brand name as customers
  write it), `website` (the domain, like
  `yourbrand.com`) and `category` (what the business
  sells, in plain words). Optional: `competitors` (up
  to 5 real competitors, comma separated), `location`
  (where the business competes) and `language` (`en` or
  `es`, the language the buyer questions are asked in).
  Returns a `runId`.
- `get_visibility_check` — collect a measurement by
  its `runId`. Returns status `running` while the
  providers are still answering, so poll every 20 to 30
  seconds (a measurement takes about a minute); when
  ready it reports the verdict and the counts.

Nothing is validated or counted locally: arguments are
forwarded exactly as given, and the upstream result
content comes back verbatim, including any `isError`
flag.

## Configuration

- `ASKEDTHRICE_MCP_URL` (optional) — override the
  hosted endpoint. Defaults to
  `https://mcp.askedthrice.com/mcp`.
- `ASKEDTHRICE_TIMEOUT_MS` (optional) — per-request
  timeout in milliseconds. Defaults to `60000`.

Failures use three renderings (this rebuild's own,
labelled): a JSON-RPC error from the upstream becomes
`askedthrice error: <message>`, an unparseable upstream
response becomes `askedthrice error: malformed
response`, and a request that cannot be completed —
including a timeout — becomes `askedthrice
unreachable`.

### Forwarding mechanics

The bridge internals are a labelled reconstruction (the
Streamable HTTP session pattern): on the first call the
client POSTs an `initialize` request (protocolVersion
`2025-03-26`, empty capabilities, clientInfo name
`brandcheck`), captures the `mcp-session-id` response
header when one is returned, POSTs
`notifications/initialized`, then POSTs the `tools/call`
request with the session header attached when captured.
The session is reused for the life of the process.
Every POST carries `Content-Type: application/json` and
`Accept: application/json, text/event-stream`, and
responses may be plain JSON or SSE.

## CLI

Each tool is a subcommand taking one JSON argument
string:

```bash
npx @reneturcios/brandcheck start_visibility_check '{"brand":"Acme","website":"acme.com","category":"project management tool","competitors":"Asana, Monday"}'
npx @reneturcios/brandcheck get_visibility_check '{"runId":"run-123"}'
npx @reneturcios/brandcheck --version
```

Output is the forwarded result content as JSON. Exit
codes: `0` on success, `1` on an `isError` result, `2`
on a usage error.

## MCP server

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

MCP client config:

```json
{
  "mcpServers": {
    "brandcheck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/brandcheck", "mcp"]
    }
  }
}
```

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/brandcheck
docker run --rm ghcr.io/cloudcorprecords/brandcheck get_visibility_check '{"runId":"run-123"}'
```

## Development

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

## License

MIT — Copyright (c) 2026 Rene Turcios