内容
# 查询工具
> 自然语言转换为OData v4查询 — 由大型语言模型支持并基于实际服务元数据。
<div align="center">
<img src="Recording.gif" alt="查询工具在运行 — 架构探索、查询生成和在Claude Desktop中执行" />
<p><em>在Claude Desktop中进行架构探索、查询生成和实时执行</em></p>
</div>
---
## 概述
OData v4表达能力强但要求严格。属性名称区分大小写，导航路径必须与元数据图匹配，筛选、展开和应用子句的语法规则各不相同。查询工具通过作为架构感知的中间件，位于大型语言模型和OData服务之间，解决了这个问题：
1. **元数据摄取** — 使用`Microsoft.OData.Edm`获取和解析`$metadata` XML，构建实体集、属性、键、导航链接、复杂类型和枚举的内存索引。
2. **基于架构的生成** — 为大型语言模型提供解析的架构作为结构化上下文，消除虚构的实体或属性名称。
3. **预执行验证** — 在查询执行之前，根据架构验证每个生成的查询，尽早捕获类型不匹配、缺少属性和损坏的导航路径。
4. **客户端聚合** — 当目标服务缺少`$apply`支持时，在本地执行分组、计数和统计操作。
---
## 功能
- **架构感知的查询生成** — 大型语言模型响应根据实时OData元数据验证，而不是最佳猜测
- **查询验证** — 通过`ODataUriParser`进行语法和语义检查，在执行前捕获错误
- **导航路径发现** — 基于广度优先搜索的遍历找到任意两个相关实体之间的最短`$expand`链
- **客户端聚合** — 当服务端`$apply`不可用时，提供GROUP BY、SUM、AVG、COUNT、MIN、MAX和COUNT DISTINCT
- **交互式UI** — 单文件Vite构建的前端实时可视化架构上下文、查询和结果表
---
## 技术栈
| 层 | 技术 |
|---|---|
| **后端** | .NET 9 · C# · ASP.NET Core |
| **OData解析** | Microsoft.OData.Edm · Microsoft.OData.Core |
| **MCP集成** | ModelContextProtocol SDK（预览版） |
| **前端** | TypeScript · Vite · 单文件HTML构建 |
---
## MCP工具
查询工具通过模型上下文协议公开八种工具：
| 工具 | 目的 |
|---|---|
| `list-configured-services` | 从配置中枚举可用的OData端点 |
| `connect-odata-service` | 加载和缓存服务元数据 |
| `list-entities` | 返回具有键属性的实体集 |
| `list-entity-properties` | 返回给定实体的属性和导航链接 |
| `validate-query` | 根据架构检查OData查询语法和语义 |
| `find-navigation-path` | 发现两个实体之间的最短`$expand`路径 |
| `execute-odata-query` | 运行验证的查询并返回JSON结果 |
| `aggregate-data` | 对结果集执行客户端分组和聚合 |
---
## 入门指南
### 先决条件
- .NET 9 SDK
- Node.js 18+
- MCP兼容的主机（例如Claude Desktop）
### 构建
```bash
# 前端
npm install && npm run build
# 后端
cd QueryCraft && dotnet build
```
### 配置
将OData服务添加到`QueryCraft/appsettings.json`：
```json
{
"QueryCraft": {
"MetadataCacheTtlMinutes": 60,
"MaxResponseBytes": 5000000,
"Services": [
{
"Key": "northwind",
"DisplayName": "Northwind 示例",
"ServiceRoot": "https://services.odata.org/V4/Northwind/Northwind.svc/",
"MetadataUrl": "https://services.odata.org/V4/Northwind/Northwind.svc/$metadata",
"Enabled": true
}
]
}
}
```
### 运行
在MCP主机配置文件中注册服务器：
```json
{
"mcpServers": {
"querycraft": {
"command": "dotnet",
"args": ["run", "--project", "/path/to/query-craft-mcp/QueryCraft"]
}
}
}
```
---
## 用例
```text
用户 → "连接到Northwind服务"
用户 → "有哪些可用的实体？"
用户 → "查找价格高于20的产品，按名称排序"
大型语言模型 → 验证查询 → 执行 → 在交互式表格中返回结果
```
---
## 项目结构
```
QueryCraft/ .NET 9 MCP服务器
├── ODataTools.cs MCP工具定义（8种工具）
├── ODataSchemaService.cs 元数据加载和架构解析
├── QueryValidator.cs OData v4语法和语义验证
├── ClientAggregator.cs 客户端聚合引擎
├── SchemaIndex.cs 内存架构查找和BFS遍历
├── SchemaState.cs 架构注册和状态管理
└── Models/ 导航和验证DTO
src/ TypeScript UI源代码
mcp-app.html UI入口点（单文件Vite构建）
```
---
## 限制
- 无身份验证或授权 — 仅适用于本地开发和演示
- OData功能支持因提供者而异；某些服务可能不公开完整的v4功能
- 大型结果集应使用`$top`限制，以避免性能问题
---
## 参考资料
- [模型上下文协议](https://modelcontextprotocol.io/)
- [MCP应用API](https://modelcontextprotocol.github.io/ext-apps/api/)
- [OData v4规范](https://www.odata.org/documentation/)
- [Microsoft.OData.Edm](https://www.nuget.org/packages/Microsoft.OData.Edm)
---
## 许可证
MIT
