@bicharts/chart-mcp 0.1.1

package/LICENSE.txt

@@ -0,0 +1,134 @@
+BIC Chart MCP Server (@bicharts/chart-mcp)
+Copyright (c) 2026 CodeX Enterprises LLC. All rights reserved.
+
+This is proprietary software, distributed as a built bundle. It is NOT open source
+and is NOT covered by the Apache-2.0 licence that applies to @bicharts/chart-host
+and @bicharts/shape-core.
+
+Two documents govern, and they cover different things:
+
+  * THIS FILE governs the SOFTWARE — the bundle in this package. It is fixed to the
+    version you installed and does not change under you.
+  * The BIC Terms of Use at https://bizintelligencechampions.com/terms-llmchart, plus
+    your account agreement, govern the SERVICE this software calls and your account.
+    Those can change over time, as service terms do.
+
+Where the two conflict, this file controls the software and the online terms control
+the service and the account.
+
+
+1. GRANT
+--------
+You are granted a non-exclusive, non-transferable, revocable licence to install and
+run this software for the purpose of accessing the BIC chart generation service with
+a valid BIC trial or paid account.
+
+Installing it as a dependency of your own project, and redistributing it unmodified
+through a normal package manager as part of that project's dependency tree, is
+expressly permitted.
+
+
+2. GENERATED OUTPUT IS YOURS
+----------------------------
+The chart code, sample data, preview files and other output this software writes for
+you ("Output") are yours. CodeX Enterprises LLC claims no ownership of Output and
+asserts no licence over it. Use it, modify it, commit it, ship it, sell it — including
+commercially, including after you stop paying us, including forever. Nothing in this
+licence or the service terms requires a running account, a network connection, or any
+further payment in order to keep using Output you have already received.
+
+That is the product, not a concession: a generated chart is source you own, not a
+service you call.
+
+Two things to understand about what that ownership does and does not mean.
+
+  NOT EXCLUSIVE. Output is generated from your data by an automated system that
+  serves many customers. Another customer with similar data may receive similar or
+  substantially identical Output, and we may generate such Output for them. Your
+  ownership of your Output does not prevent that, and cannot.
+
+  YOUR RISK. Output is produced by an automated system, including large language
+  models. It is not reviewed by us before you receive it, and it can be wrong: it can
+  misrepresent your data, compute the wrong thing, fail to render, behave unexpectedly
+  in your application, or resemble other work. YOU ARE SOLELY RESPONSIBLE for
+  reviewing, testing, securing and validating any Output before relying on it, and you
+  accept all risk and all liability arising from your use of it. We provide no
+  warranty of any kind as to Output — including no warranty of correctness, accuracy,
+  fitness for any purpose, security, or non-infringement.
+
+  Output executes as code in your application. Treat it as you would any code you
+  accept into your codebase: read it, test it, and take responsibility for it.
+
+
+3. WHAT REMAINS OURS
+--------------------
+Your ownership of Output does not transfer any right in the MEANS of producing it.
+CodeX Enterprises LLC retains all right, title and interest in this software, the BIC
+backend service, and everything behind it — the chart-type selection engine, prompts,
+rules, guardrails, correctness gates, quality-control passes, models, weights,
+telemetry, and all related intellectual property. No licence to any of it is granted
+by implication, estoppel or otherwise.
+
+In short: the chart is yours; the machine that made it is ours.
+
+
+4. RESTRICTIONS
+---------------
+You may not:
+
+  * reverse engineer, decompile, or disassemble this software, except to the extent
+    that applicable law expressly permits despite this limitation;
+  * remove or alter this notice or any proprietary marking;
+  * redistribute this software, or a modified form of it, as your own product or as
+    part of a competing product or service;
+  * use this software or the service to build, train, or improve a competing chart
+    generation product or model, including by systematically collecting Output for
+    that purpose;
+  * access the BIC backend other than through a valid account, or circumvent account
+    limits, metering, rate limiting, or credit accounting.
+
+
+5. THIRD-PARTY COMPONENTS
+-------------------------
+This package depends on separately licensed open-source software, each under its own
+terms, including @bicharts/chart-host and @bicharts/shape-core (Apache-2.0, which
+embed geographic reference data from GeoNames under CC BY 4.0 — see the NOTICE file in
+those packages), @modelcontextprotocol/sdk, papaparse, and zod. Nothing in this licence
+limits your rights under theirs.
+
+
+6. NO WARRANTY
+--------------
+THE SOFTWARE AND ALL OUTPUT ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, ACCURACY, AND NONINFRINGEMENT. WE DO NOT WARRANT
+THAT THE SOFTWARE OR THE SERVICE WILL BE UNINTERRUPTED, ERROR-FREE, OR THAT ANY
+OUTPUT WILL BE CORRECT OR SUITABLE FOR ANY PURPOSE.
+
+
+7. LIMITATION OF LIABILITY
+--------------------------
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL CODEX ENTERPRISES LLC BE
+LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY OR PUNITIVE
+DAMAGES, OR FOR ANY LOSS OF PROFITS, REVENUE, DATA, OR BUSINESS, ARISING OUT OF OR IN
+CONNECTION WITH THIS SOFTWARE, THE SERVICE, OR ANY OUTPUT, WHETHER IN CONTRACT, TORT
+OR OTHERWISE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. OUR TOTAL AGGREGATE
+LIABILITY SHALL NOT EXCEED THE AMOUNT YOU PAID US FOR THE SERVICE IN THE TWELVE MONTHS
+PRECEDING THE CLAIM.
+
+Some jurisdictions do not allow certain exclusions or limitations, in which case the
+above apply to the greatest extent permitted, and nothing here limits liability that
+cannot lawfully be limited.
+
+
+8. SERVICE, CREDITS AND TERMINATION
+-----------------------------------
+Use of the BIC backend through this software consumes credits and is governed by the
+Terms of Use and your account agreement. This licence terminates automatically if you
+materially breach it. On termination you must stop using this software — but your
+rights in Output you already received survive, permanently and unconditionally.
+
+Sections 2, 3, 5, 6, 7 and this sentence survive termination.
+
+
+Questions: info@bizintelligencechampions.com

package/README.md

@@ -0,0 +1,215 @@
+# @bicharts/chart-mcp (experimental)
+
+An MCP (Model Context Protocol) stdio server that lets any MCP-capable AI client
+(Claude Code, Claude Desktop, Copilot Studio, Cursor, …) use the BIC chart engine:
+
+- **`assess_data_shape`** — profiles a CSV **locally** with the same measurement
+  engine the Power BI visual uses (`@bicharts/shape-core`). No backend call, no
+  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; **zero-credit**, no LLM).
+  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
+  with its **source language** (JavaScript for D3/Vega, Python for Plotly/matplotlib),
+  its renderer, and a 0–100 score. Pass `language: "javascript"|"python"` to force it,
+  `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 optional (a license
+  only unlocks *draft* types).
+- **`generate_chart`** — profiles locally, then calls the BIC backend, which picks
+  an eligible chart type for the measured shape (or honors `chart_type`) and
+  returns code that has passed the backend's gates/QC. Renderer selection is the same
+  **language-aware** intersection: with no explicit `renderer`, the detected/`language`
+  narrows the backend's auto renderer pick to that language (JS → D3/Vega, Python →
+  Plotly/matplotlib); an explicit `renderer` always wins. For D3 output, passing
+  **`preview_html: true`** alongside `out_dir` also writes a standalone `preview.html`
+  you can open with no build step. It is **off by default** — the code is meant to be
+  merged into your app, not run as an index.html.
+
+## Language & renderer
+
+Both list/generate tools speak **language** (what your project is written in) as well as
+**renderer** (a specific chart library). The server maps `javascript`/`typescript` → D3 +
+Vega and `python` → Plotly + matplotlib, and the picker's weights rank across that
+language's renderers. Precedence is **explicit `renderer` > `language` > auto-detected
+language**. The MCP sniffs the working directory (or `project_dir`) for language markers
+(`package.json`/`tsconfig.json` → JS, `pyproject.toml`/`requirements.txt` → Python) plus a
+bounded source-file count; when the signal is genuinely mixed or absent it asks you to
+pick rather than silently assuming one.
+
+## Data inputs — CSV or a pre-typed table
+
+Both tools accept, as alternatives:
+
+- `csv_path` / `csv_text` — a CSV; column types and measure/dimension roles are
+  **inferred** (numeric-non-identifier = measure), and you can steer them with the
+  `measures`/`dimensions`/`formats`/`descriptions` levers.
+- `data: { columns, rows }` — a **pre-typed table**, the shape a **Fabric DAX
+  Execute-Queries result**, a dataframe, or an arrow table already has. `columns`
+  carry `name` and (optionally) `dataType`, `isMeasure`, `format`, `description`;
+  `rows` are positional arrays **or** objects keyed by column name. When a caller
+  supplies `isMeasure` + `format` + `description` from a semantic model, the shape
+  matches Power BI fidelity with **no heuristic guessing** — the profiler engine
+  is the same one the visual runs; CSV was only ever one adapter over it.
+
+Example (a semantic-model query result):
+
+```json
+{
+  "data": {
+    "columns": [
+      { "name": "Region",  "dataType": "String",  "isMeasure": false },
+      { "name": "Revenue", "dataType": "Decimal", "isMeasure": true,
+        "format": "$#,##0", "description": "Net booked revenue" }
+    ],
+    "rows": [ { "Region": "West", "Revenue": 12000.5 }, { "Region": "East", "Revenue": 9000 } ]
+  }
+}
+```
+
+## Build
+
+```powershell
+cd mcp
+npm install
+npm run build     # bundles to dist/index.mjs (single file)
+```
+
+## Credentials (generate_chart only)
+
+**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). `assess_data_shape` needs no
+credentials at all (it runs entirely locally).
+
+Two ways to supply them — env wins over the file:
+
+**1. Env vars** (via 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_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) |
+
+**Defaults match the Power BI visual.** Unset, the MCP sends `model=""` (server
+resolves the `IsDefault` model), `reasoning_mode=""` (leave-to-visual heuristic), and
+`privacy_level="20"` (detailed stats, **no sample rows** — see below). The two env
+vars above are escape hatches only; leave them unset for visual parity.
+
+### Response timeouts (HTTP 499 / dropped connection)
+
+The backend completes long multi-pass generations (the visual regularly runs several
+minutes on rich charts). A dropped connection is therefore a **delivery timeout in
+the calling path** — the MCP host's tool-call timeout or an intermediary proxy — not
+a server ceiling, and not a generation failure (the chart likely generated and may
+have been billed). The parity-preserving fix is to **let the call take as long as it
+needs**:
+
+- **Built in:** the server sends MCP progress notifications every 10s during a
+  generation; spec-compliant hosts (including Claude Code) reset their per-call
+  timeout on progress, so the call stays alive as long as the generation needs —
+  no user configuration required.
+- Fallback for hosts that don't reset on progress: raise the host's per-tool
+  timeout (Claude Code: `MCP_TOOL_TIMEOUT` in ms, set in the environment Claude
+  Code itself runs in — e.g. the `env` block of `settings.json`).
+- (Planned) retrieve an already-generated result by `correlationId` so a dropped
+  connection recovers the billed code instead of re-generating.
+
+`BIC_MCP_REASONING=CP`/`1P` *would* finish faster, but that trades away visual parity
+(no validator) — prefer raising the timeout.
+
+**2. A credentials file** — so secrets never sit in a project-committed
+`.mcp.json`. Default `~/.bic/credentials.json` (override with
+`BIC_CREDENTIALS_FILE`):
+
+```json
+{ "licenseKey": "…", "licensee": "…" }
+```
+
+(`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`.
+
+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.
+
+### Credit charges
+
+Each `generate_chart` call spends credits on your account, exactly like the Power BI
+visual (the MCP hits the same billed endpoint):
+
+- **Hosted** (our models) → **token-based** — you pay for the tokens the generation
+  actually used.
+- **BYO** (your own API key) → a **flat operating fee per request**. The MCP/SDK
+  surface has its own dial (`LLMSdkByoOperatingCost`, default **3 credits**),
+  separate from the visual's fee, so it can be priced independently.
+
+The response header line shows `credits: N` so you can see what each call cost.
+
+## Register with Claude Code
+
+```powershell
+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:
+
+```powershell
+claude mcp add --scope user bic-chart -e BIC_LICENSE_KEY=... -e BIC_LICENSEE=... -- npx -y @bicharts/chart-mcp
+```
+
+or in a project `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "bic-chart": {
+      "command": "npx",
+      "args": ["-y", "@bicharts/chart-mcp"]
+    }
+  }
+}
+```
+
+Claude Desktop uses the same `command`/`args`/`env` block in
+`claude_desktop_config.json` under `mcpServers`.
+
+**Developing on the server itself?** Point at your build instead, so you are not
+running whatever npx last cached:
+
+```powershell
+claude mcp add --scope user bic-chart-dev -- node c:/Source/PowerBI_Controls/llmchart/mcp/dist/index.mjs
+```
+
+The ready banner prints the build stamp, which is how you tell the two apart.
+
+Try: *"Assess the shape of testharness/datasets/divisional_revenue_by_year.csv,
+then generate a chart for it and write the preview to ./out."*
+
+## Wire notes
+
+Wire-compatible with the visual/harness envelope (see
+`testharness/harness/client.py`, the reference implementation): gzip→base64→`.`
+body, FNV X-Signature, `clientVersion >= 2.0.0.0`, plus `host: "SDK"` so prompts
+resolve to the generic host profile once server rev 144 + tokenized config are
+live (older servers ignore the field — deployment-order safe).
+
+## Publishing (when the experiment proves out — NOT yet)
+
+1. Keep `"private": true` until the conscious decision to release.
+2. Publish **built artifacts only** (`files: ["dist"]` already enforces this —
+   the tarball carries the bundled `dist/index.mjs`, no source, no history).
+3. `npm publish --access public` under the org scope; users then configure
+   `"command": "npx", "args": ["-y", "@bicharts/chart-mcp"]` — zero-install.
+4. List in MCP registries/directories for discoverability.
+5. shape-core rides inside the bundle minified (shared, not shown); the
+   open-source decision for readable source is separate and deferred.