# BigQuery-MCP GitHub Distribution V1

Company distribution for a read-only Google BigQuery MCP server, built on the official Google MCP Toolbox for Databases **v1.8.0**. V1 production support is macOS on Apple Silicon. The installer is deliberately fail-closed on other platforms, even where the release manifest records an official checksum.

The installed server exposes exactly these stable tool names: `find_*`, `color_*`, `paintbynumber_*`, and `pixelspark_*` (list tables, table metadata, and SQL for each group). Every generated source is dataset-scoped with `writeMode: blocked`, a 200-row result cap, and 10 GiB maximum billed bytes. SQL use is read-only: use `SELECT` only.

## Install

Prerequisites: Node.js 20+ and Google Cloud CLI. Authentication uses your existing Google Application Default Credentials (ADC); no credential, token, project ID, or dataset ID is committed by this package.

1. Copy and fill the local configuration. Do not commit it.

   ```sh
   cp config.example.json config.local.json
   ```

2. If ADC is not already set up, authenticate interactively (the installer never runs this):

   ```sh
   gcloud auth application-default login
   ```

3. Install the pinned binary and generated local configuration:

   ```sh
   node install.js --config config.local.json
   ```

The default install root is `~/Library/Application Support/BigQuery-MCP`. The command prints a structured receipt and copyable Codex/Cursor stdio snippets; it never edits either client configuration. For a no-network, locally verified install (useful for tests), add `--toolbox-source /path/to/toolbox`.

## Client configuration

The installer prints two separate, copyable client snippets:

- `clientConfig.codexToml`: TOML for Codex `~/.codex/config.toml`.
- `clientConfig.cursorJson`: JSON object for Cursor MCP configuration.

Both point at the installed binary with:

```text
--stdio --config <installed config path> --disable-reload
```

The installer only prints these snippets; it never edits an existing Codex or Cursor configuration.

## Verify

```sh
node status.js
node smoke-test.js
```

The default smoke test starts the local MCP stdio server and requires exactly the expected 12 tools; it makes no MCP `tools/call` request. Toolbox v1.8.0 itself validates configured `allowedDatasets` during source initialization, so a successful stdio start may require ADC and network access even in this default mode. A deliberately opt-in read-only live check requires a real table identifier:

```sh
node smoke-test.js --live --group find --table events_YYYYMMDD
```

The live check performs only `list_table_ids`, `SELECT 1 AS smoke_test`, and `get_table_info`. It does not write data, authenticate, or inspect credential files.

## Versioning and upgrades

V1 is pinned to Toolbox `1.8.0`; the downloader never uses `latest`. The known release URLs and SHA-256 values are in `release-manifest.json`. Upgrade work is intentionally separate: update the manifest, validate the release independently, then publish a new distribution revision. Do not replace the pin casually.

## Repository boundaries

This working directory also contains machine-local production assets that predate the distribution package. They are deliberately kept on disk but ignored by Git:

- `toolbox` — the existing ~154 MB production binary.
- `toolbox.yaml` and `tools_bootstrap.yaml` — current machine production configuration containing real project/dataset identifiers.
- `BigQuery_MCP_正式配置与恢复说明_20260816.md` — local historical recovery notes.
- `config.local.json`, runtime/state/log/cache material, and credential-like files.

The tracked distribution source should therefore contain the installer, generator, manifest, example config, tests, smoke/status tools, README, and `.gitignore` only. Do not force-add ignored production assets.