# Query Engine MCP

一个声明驱动、可机械证明的企业取数 MCP Server。它将 Agent 提出的业务语义意图解析为 canonical refs，由 Runtime 验证统计范围、筛选、粒度、关系、fanout、权限和物理 binding 后才执行受控查询。

该仓库只包含 MCP Server、运行所需的语义 Runtime、Zeekr instance pack 和 `ask-data` skill；不包含 pa-chatbi 应用、Agent SDK、`.env`、凭据、真实查询结果、trace/replay artifact 或预构建 Python 环境。

## 公开 MCP 工具

- `semantic_query`
- `list_query_capabilities`
- `get_system_date`
- `get_data_horizon`

Agent 只能提出指标、维度、统计范围、时间、筛选与分析操作；不能提交 SQL/VQL、表、字段、join 或物理 binding。无法由已发布原子与证明推导的组合必须 fail-closed。

## 本机启动

需要 Python 3.13 和 [uv](https://docs.astral.sh/uv/)。先准备本机运行时：

```sh
./tools/bootstrap-runtime.sh
```

操作方将已有的 Denodo 配置放在仓库外部的 dotenv 文件中，再注册给 Codex：

```sh
export QUERY_ENGINE_LOCAL_DOTENV_PATH=/absolute/path/to/operator.env
./tools/install-codex-mcp.sh
```

新开一个 Codex task 后即可发现 MCP。业务问答使用 [`skills/ask-data/SKILL.md`](skills/ask-data/SKILL.md)，它只调用 `semantic_query`，不会绕过 Runtime 写 SQL。

## 目录

```text
docs/architecture/uose/uose-caliber-harness/  Runtime 与 MCP Server
docs/architecture/uose/instance-packs/        客户语义包与物理 binding
docs/architecture/uose/semantic-domain-modules/ 通用业务域角色
skills/ask-data/                              Agent 问数指引
tools/                                        启动与 Codex 安装脚本
docs/migration-inputs/semantic-kernel-v2/     已导入的 v2 迁移输入与采用决策
```

Zeekr 特有口径、视图映射和值域留在其 instance pack；Core Runtime 不写客户字段，也不会为每个指标 × 维度组合预枚举 Shape。

## 验证

完成安装后，在新开的 Codex task 中确认能发现四个公开工具；再通过 `get_data_horizon` 完成不读业务行的启动检查。业务查询必须走 `semantic_query`，并由当前 instance pack 的声明和 physical binding 决定是否准入。

本仓库是本机 read-only MCP 的源码项目，不是远程托管的生产 MCP 服务。生产认证、多租户隔离、部署与发布验收需在独立生产环境完成。

外部 v2 阶段包的完整源文件保留在
[`docs/migration-inputs/semantic-kernel-v2/`](docs/migration-inputs/semantic-kernel-v2/)。
它们是可审计的迁移输入，不会被运行时导入或额外暴露为 MCP/HTTP 服务；采用规则见其中的
[`INTEGRATION_DECISIONS.md`](docs/migration-inputs/semantic-kernel-v2/INTEGRATION_DECISIONS.md)。