@bicharts/chart-mcp 0.6.68 → 0.6.69

package/README.md

@@ -26,7 +26,7 @@ engine knows what ~90 chart types can honestly say, it will sometimes propose a
 
 **What it costs: authoring, and nothing else.** The calls that write a chart (and the
 eligibility lists beyond a free hourly allowance) are metered on your account. What they
-write is yours: the chart code needs no licence, no account, no credits and no connection to
+write is yours: the chart code needs no license, no account, no credits and no connection to
 us to run, view, deploy, ship or keep, for any number of viewers, forever. The host that draws
 it, `@bicharts/chart-host`, is open source (Apache-2.0), and the generated code makes no calls
 home. See section 1(d) of the [RegiaBI terms](https://bizintelligencechampions.com/terms-regiabi)
@@ -39,7 +39,7 @@ The main tools:
   credentials, no data leaves the machine. The free-teaser tool.
 - **`list_eligible_charts`** — the **authoritative** list of chart types that can
   render this data (server-side policy, not a local guess; **no LLM**, but a network
-  call to the engine and therefore **metered** — see Credentials).
+  call to the engine and therefore **metered** — see Signing in).
   By default it **auto-detects the project's language** (JS/TS vs Python from the
   working dir) and returns the charts for THAT language — **scoped to its renderers
   and ranked by the picker's chart-type×renderer weights** (best first), each tagged
@@ -48,10 +48,10 @@ The main tools:
   `renderer: "D3"/"PLOTLY"/…` to rank one specific renderer, or `renderer: ""` for the
   full **renderer-agnostic** eligibility across all renderers (unranked — the wide "what
   *can* render" net). `top: N` trims to the best N. If the language can't be auto-detected
-  and none is given, the tool asks you to specify one. **Credentials required** — no LLM
-  is not the same as no cost, because eligibility *is* the engine's own answer. Free within
-  a generous hourly allowance; beyond it a call may draw usage credits. A live licence
-  additionally unlocks *draft* types.
+  and none is given, the tool asks you to specify one. **An account is required** (the first
+  call signs you in) — no LLM is not the same as no cost, because eligibility *is* the
+  engine's own answer. Free within a generous hourly allowance; beyond it a call may draw
+  usage credits. A live license additionally unlocks *draft* types.
 - **`suggest_charts`** — "which charts suit this model?" in one call, for a semantic model in a
   Microsoft Fabric App on Rayfin's data app template: reads the model's tables, measures and
   relationships through the project's own `fabric-app-data` CLI, finds its natural views (by place,
@@ -132,31 +132,45 @@ Example (a semantic-model query result):
 }
 ```
 
-## Credentials (`generate_chart` and `list_eligible_charts`)
+## Signing in (`generate_chart` and `list_eligible_charts`)
 
-**A trial or paid BIC account is required — no freemium.** Use the same
-**License Key**, **Licensee**, and **Secret Key** from your BIC account (the ones
-the Power BI visual's license settings use).
+**Nothing to configure.** The first call that needs an account opens your browser on the
+BIC sign-in page, waits for you, and then finishes the call it was making — no second
+command, no retry. No account yet? The page leads with **Create a free account**, and a
+new account starts a free trial. **A trial or paid BIC account is required — no freemium.**
 
-`assess_data_shape` needs no credentials at all — it runs entirely locally in
+- The sign-in link is printed to the server's log before the browser opens (and sent as a
+  log message to clients that show them), so on a machine where no browser opens you can
+  open it yourself.
+- Your sign-in is kept in `~/.bic/oauth.json` (readable only by you; override with
+  `BIC_OAUTH_FILE`), separately for each service address, and renewed quietly while you
+  keep using it.
+- Each signed-in machine shows up on your account page, and you can sign any of them out
+  there. Its next call asks you to sign in again.
+
+Why a sign-in rather than a key: a key pasted into a config file tends to end up in a
+committed `.mcp.json`, and one key can't be switched off for a single machine. A sign-in
+keeps the secret out of your files and can be revoked per machine.
+
+`assess_data_shape` needs no account at all — it runs entirely locally in
 `@bicharts/shape-core` and never calls the backend. `list_eligible_charts` **does**
-need them: it is the server's own eligibility verdict, not a local guess, which is
+need one: it is the server's own eligibility verdict, not a local guess, which is
 the whole reason it is worth calling. It is free within a generous hourly allowance;
 beyond that, a call may draw usage credits from the account (both knobs are
 server-configured), so don't put it inside a tight loop. Use of the API and this MCP
 server is covered by the
 [RegiaBI Programmatic Access Terms](https://bizintelligencechampions.com/terms-regiabi).
 
-Two ways to supply them — env wins over the file:
+### Settings
 
-**1. Env vars** (via the MCP server's `env` block — see registration below):
+All optional, in the MCP server's `env` block (see registration below):
 
 | Var | Meaning |
 | --- | --- |
-| `BIC_LICENSE_KEY` | required |
-| `BIC_LICENSEE` | required (account name) |
-| `BIC_SECRET_KEY` | optional |
 | `BIC_URL` | override backend (default `https://bizintelligencechampions.com`) |
+| `BIC_SIGNIN` | `off` turns the browser sign-in off (CI, containers); with no key set, a call then fails with a message naming the key settings |
+| `BIC_SIGNIN_WAIT_MS` | how long a call waits for you to finish signing in (default `180000`, 3 minutes); past it, the call returns the sign-in link |
+| `BIC_OAUTH_FILE` | where the sign-in is kept (default `~/.bic/oauth.json`) |
 | `BIC_MCP_REASONING` | OPTIONAL override of the default reasoning mode (else `""` = leave-to-visual, same as the PBI visual) |
 | `BIC_MCP_MODEL` | OPTIONAL override of the default model (else `""` = the account's IsDefault model, same as the visual) |
 | `BIC_MCP_TIMEOUT_MS` | OPTIONAL: how long one `generate_chart` call waits, recovery included (default `900000`, 15 minutes) |
@@ -193,6 +207,21 @@ needs**:
 `BIC_MCP_REASONING=CP`/`1P` *would* finish faster, but that trades away visual parity
 (no validator) — prefer raising the timeout.
 
+### Advanced: a license key (CI, containers, machines with no browser)
+
+A key is the way in where no person is at the machine to sign in. It's the same
+**License Key**, **Licensee** and **Secret Key** from your BIC account (the ones the
+Power BI visual's license settings use). **When a key is set, it wins:** the server
+sends it exactly as before and never opens a sign-in. Env wins over the file:
+
+**1. Env vars:**
+
+| Var | Meaning |
+| --- | --- |
+| `BIC_LICENSE_KEY` | the license key |
+| `BIC_LICENSEE` | the account name it was issued to |
+| `BIC_SECRET_KEY` | optional |
+
 **2. A credentials file** — so secrets never sit in a project-committed
 `.mcp.json`. Default `~/.bic/credentials.json` (override with
 `BIC_CREDENTIALS_FILE`):
@@ -204,7 +233,9 @@ needs**:
 (`secretKey` optional.)
 
 Prefer the file, or a **user-scoped** `claude mcp add` (stored in your user
-config), over putting secrets in a repo-committed `.mcp.json`.
+config), over putting secrets in a repo-committed `.mcp.json`. On a machine with no
+browser, set `BIC_SIGNIN=off` too, so a missing key fails at once instead of waiting
+for a sign-in nobody can finish.
 
 Note: this package deliberately does NOT contain the freemium key-mint secret —
 consistent with trial/paid-only access, and safe if the folder is ever published.
@@ -277,15 +308,15 @@ difference is not knowing the API, it is not knowing the shape of the answer.
 claude mcp add --scope user bic-chart -- npx -y @bicharts/chart-mcp
 ```
 
-`--scope user` stores it in your user config so it works in every project. With
-credentials in `~/.bic/credentials.json` you need no `-e` flags at all; add them only
-if you prefer env vars:
+`--scope user` stores it in your user config so it works in every project. That's the
+whole setup: the first chart call signs you in through your browser. Only a machine with
+no browser needs a key (see *Advanced: a license key*):
 
 ```powershell
-claude mcp add --scope user bic-chart -e BIC_LICENSE_KEY=... -e BIC_LICENSEE=... -- npx -y @bicharts/chart-mcp
+claude mcp add --scope user bic-chart -e BIC_LICENSE_KEY=... -e BIC_LICENSEE=... -e BIC_SIGNIN=off -- npx -y @bicharts/chart-mcp
 ```
 
-or in a project `.mcp.json`:
+or in a project `.mcp.json` (no secrets in it, so it's safe to commit):
 
 ```json
 {