Jmmt-mingrui opened a new pull request, #182:
URL: https://github.com/apache/doris-mcp-server/pull/182
## 概述
本 PR 为 Doris MCP Server 引入 **Semantic Provider 插件框架**——一个 `Semantic Model →
Doris SQL` 的编译器运行时（定位类似 dbt compile + query engine + MCP
interface），将语义模型支持从单一内置 MetricFlow 扩展为可插拔的多格式体系。
## 架构
```
Build Time（上传模型） Runtime（Agent 查询）
ModelSource(filename, content) CompiledArtifact + QueryRequest
│ │
SemanticProvider SemanticRuntime
validate() → parse() → compile() get_metrics() / get_dimensions()
│ generate_sql() → Doris SQL
▼ │
CompiledArtifact ──► ArtifactStore ▼
(provider 私有 payload) validate_readonly → 连接池执行
```
**关键设计决策**
- **编译产物不跨 Provider
标准化**：envelope（provider/name/version/source_digest）统一，`payload` 各家私有（类比 Java
`.class` / dbt `manifest.json`）——这是编译器框架，不是语义交换标准。
- **Provider = Parser + Compiler + Runtime SQL Generator + Metadata
Provider**（类似数据库驱动），而非简单 Parser。
- **结构化 Filter**：Agent 传 `{dimension, operator, value}` 而非 SQL 片段；名称对
artifact 校验、字面量转义，生成 SQL 构造上免疫注入。
## 内置 Provider（尽量借用现有开源项目）
| Provider | 格式 | 借用 |
|---|---|---|
| `cube` | cube-js YAML（cubes/measures/dimensions/many_to_one joins）| 遵循
[cube-js/cube](https://github.com/cube-js/cube) 数据模型规范；MCP 交互参考
[isaacwasserman/mcp_cube_server](https://github.com/isaacwasserman/mcp_cube_server)
|
| `lookml` | Looker `.view.lkml` | 解析基于
[joshtemple/lkml](https://github.com/joshtemple/lkml)（MIT，新增依赖）；编译时翻译成 Cube
artifact 形状，**复用 Cube 运行时** |
| `metricflow` | dbt `semantic_models` YAML | 适配器桥接本仓库已 vendor 的 MetricFlow
引擎（`bind()` 挂接 workspace compiler）|
格式自动嗅探（`detect()` 置信度 ≥0.5 路由）或显式指定 provider。
## 新增 MCP Tools（7 个，总计 17 个）
`list_semantic_providers` / `compile_semantic_model` /
`list_semantic_artifacts` / `delete_semantic_artifact` /
`get_semantic_metadata` / `generate_semantic_sql`（干跑）/
`query_semantic_model`（生成+只读校验+执行）
## 测试与文档
- **88 个新增离线单元测试**（Cube 28 / LookML 10 / MetricFlow 12 / 注册表+存储 14 / 工具层 12
/ 冒烟散见各文件），全部接入 `test/run_all_tests.sh --offline`；本地 20 项离线套件全绿。
- `DESIGN.md` 新增 §6A 完整设计文档；双语 README 更新；`examples/semantic-models/` 提供
Cube/LookML 示例（均通过 provider 校验）。
## Review 过程发现并已修复
- `bind()` 原设计会修改注册表单例 → 跨工作区并发竞态，改为返回新绑定副本（`3c52dd8`）
- `requirements.txt` 漏加 `lkml`（CI/build.sh 不走 pyproject）→ 补齐（`28a155d`）
- MetricFlow 适配器零覆盖 → 补 12 个测试（`3beaef9`）
## 已知边界（后续 PR）
- Cube 跨 cube 指标查询（fact-to-fact join）暂未支持，报错信息明确
- LookML explores/joins、derived_table 暂不支持（v1 仅 `sql_table_name` 视图）
- MetricFlow provider 的 `generate_sql` 需要绑定 workspace 引擎，未绑定时明确报错引导至
`query_metric`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
