内容
<div align="center">
# 大查询 MCP 服务器，带有强制性成本控制和可衡量的准确性指标
[](https://pypi.org/project/mcp-bigquery-evals/)
[](#eval-harness)
[](https://github.com/Umarfarook1/mcp-bigquery-evals/actions/workflows/ci.yml)
[](https://pypi.org/project/mcp-bigquery-evals/)
[](LICENSE)
`uvx mcp-bigquery-evals` · 适用于任何 MCP 兼容客户端 · v0.1.0
</div>
---
## 为什么选择这个 BigQuery MCP 而不是其他 MCP
| | 大多数 BQ MCPs | `mcp-bigquery-evals` |
|---|---|---|
| 成本控制 | 无 | **强制** 在每次查询前进行 dry-run，如果超过上限则拒绝 |
| 质量信号 | "相信我" | **实时准确性指标**，每次发布都会重新计算 |
| 写操作 | 通常启用 | **默认禁用**（只读） |
| 出现错误时的处理 | 原始 API 异常 | **7 个稳定的错误代码**，代理可以切换 |
| 无 GCP 的本地开发 | 不可能 | **内存 SQLite 支持的模拟**，随产品提供 |
## 产品内容
- **7 种只读 MCP 工具**，用于仓库发现和查询
- **强制性 dry-run 成本上限**，适用于每次 `run_query`（默认 100 MB 扫描，约 0.0005 美元每查询）
- **结果集等价性评估框架**（Spider/BIRD 方法），带有本 README 中的实时准确性指标
- **结构化的 BigQuery 错误**，包含 7 个稳定代码（`invalid_sql`、`table_not_found`、`permission_denied`、`unauthenticated`、`rate_limited`、`query_timeout`、`unknown`）
- **两个 BigQueryClient 实现**：`RealBigQueryClient`（生产环境，封装 `google-cloud-bigquery`）和 `FakeBigQueryClient`（内存 SQLite 支持，适用于开发和 CI，无需 GCP 凭证）
## 快速入门（5 分钟）
### 1. 安装
```bash
uvx mcp-bigquery-evals --help
```
首次运行大约需要 30 秒，而 `uv` 获取依赖项；后续运行则立即完成，无需等待。您也可以使用 `pip install mcp-bigquery-evals` 进行安装。
### 2. GCP 身份验证
```bash
gcloud auth application-default login
```
### 3. 配置到您的 MCP 客户端
打开您的 MCP 客户端服务器配置（开发者设置）并添加：
```json
{
"mcpServers": {
"bigquery": {
"command": "uvx",
"args": ["mcp-bigquery-evals", "serve"],
"env": {
"BIGQUERY_PROJECT": "您的 GCP 项目 ID"
}
}
}
}
```
重启您的客户端。MCP 指示器应显示 "bigquery"，并带有 7 个工具。
### 4. 测试
> 使用 bigquery 工具，找到标记为 'python' 的 Stack Overflow 浏览量最高的 5 个问题。
代理会链接 `list_datasets`、`list_tables`、`describe_table`、`run_query` 来回答问题。每次 `run_query` 在执行前都会进行 dry-run 成本检查。
详细设置、故障排除和替代 `pip` 安装路径请参见 [`docs/mcp_client_setup.md`](docs/mcp_client_setup.md)。
## 7 种工具
| 工具 | 用途 |
|---|---|
| `list_datasets()` | 列出 GCP 项目中的所有数据集 |
| `list_tables(dataset_id)` | 列出数据集中的表 |
| `describe_table(table_id)` | 表格架构、行数、大小 |
| `sample_table(table_id, n=5)` | 最多 n 行样本 |
| `search_schema(term)` | 模糊匹配术语与所有列名 |
| `estimate_cost(sql)` | 免费 dry-run；返回 bytes_scanned 和估计的 USD |
| `run_query(sql, max_bytes_scanned=100MB)` | Dry-run，超过上限则拒绝，然后执行 |
所有工具均为只读。v1 版本中没有写操作。有关设计原理，请参见 [`docs/architecture.md`](docs/architecture.md)。
## 成本控制
每次 `run_query` 调用都会进行 dry-run（免费），然后再执行。如果 dry-run 估计值超过 `max_bytes_scanned`，则调用会返回结构化错误，而不是消耗字节：
```json
{
"error": "cost_cap_exceeded",
"would_scan": "1.4 GB",
"cap": "100.0 MB",
"estimated_usd": 0.007,
"hint": "narrow your WHERE clause or pass max_bytes_scanned=1500000000 to override"
}
```
代理读取结构化错误并自我纠正（缩小 WHERE 子句、显式提高上限、选择不同的表格）。
## 评估框架
每次发布都会运行一个结果集等价性评估套件，针对 `bigquery-public-data` 进行评估，并更新上方的准确性指标。方法论与 Spider 和 BIRD 学术基准相符：执行黄金和预测 SQL，比较结果集作为行的多重集（与顺序无关，带有浮点容差、Decimal 处理、NULL 相等性、NaN 相等性、ARRAY/STRUCT 递归、bool/int 区分）。
本地运行：
```bash
mcp-bigquery-evals evals run --model <您的模型 ID>
```
完整的方法论、黄金对 YAML 格式以及如何添加您自己的对：[`docs/how_evals_work.md`](docs/how_evals_work.md)。
## 开发
```bash
git clone https://github.com/Umarfarook1/mcp-bigquery-evals
cd mcp-bigquery-evals
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest # 单元测试（无需 GCP；约 160 个测试）
pytest -m bq # 真实 BQ 集成测试（需要 GCP 凭证）
pytest -m live # 端到端测试，带有真实模型和真实 BQ
```
## 贡献
欢迎提出问题和 PR。影响力最大的贡献：
1. **更多验证的黄金 NL-to-SQL 对**，针对 `bigquery-public-data`
2. **提示改进**，带有前后评估数字，显示准确性指标的变化
3. **错误报告**，带有最小的重现
## 许可证
MIT，请参见 [`LICENSE`](LICENSE)。
