Content
# QueryCraft
> Natural language to OData v4 queries — powered by LLMs and grounded in real service metadata.
<div align="center">
<img src="Recording.gif" alt="QueryCraft in action — schema exploration, query generation, and execution in Claude Desktop" />
<p><em>Schema exploration, query generation, and live execution inside Claude Desktop</em></p>
</div>
---
## Overview
OData v4 is expressive but unforgiving. Property names are case-sensitive, navigation paths must match the metadata graph, and syntax rules vary across filter, expand, and apply clauses. QueryCraft addresses this by sitting between the LLM and the OData service as a schema-aware middleware:
1. **Metadata ingestion** — fetches and parses `$metadata` XML using `Microsoft.OData.Edm`, building an in-memory index of entity sets, properties, keys, navigation links, complex types, and enums.
2. **Schema-grounded generation** — provides the parsed schema as structured context to the LLM, eliminating hallucinated entity or property names.
3. **Pre-execution validation** — validates every generated query against the schema before it touches the wire, catching type mismatches, missing properties, and broken navigation paths early.
4. **Client-side aggregation** — performs grouping, counting, and statistical operations locally when the target service lacks `$apply` support.
---
## Features
- **Schema-aware query generation** — LLM responses are validated against live OData metadata, not best guesses
- **Query validation** — syntax and semantic checks via `ODataUriParser` catch errors before execution
- **Navigation path discovery** — BFS-based traversal finds the shortest `$expand` chain between any two related entities
- **Client-side aggregation** — GROUP BY, SUM, AVG, COUNT, MIN, MAX, and COUNT DISTINCT when server-side `$apply` is unavailable
- **Interactive UI** — a single-file Vite-built frontend visualises schema context, queries, and result tables in real time
---
## Tech Stack
| Layer | Technology |
|---|---|
| **Backend** | .NET 9 · C# · ASP.NET Core |
| **OData parsing** | Microsoft.OData.Edm · Microsoft.OData.Core |
| **MCP integration** | ModelContextProtocol SDK (preview) |
| **Frontend** | TypeScript · Vite · single-file HTML build |
---
## MCP Tools
QueryCraft exposes eight tools through the Model Context Protocol:
| Tool | Purpose |
|---|---|
| `list-configured-services` | Enumerate available OData endpoints from configuration |
| `connect-odata-service` | Load and cache service metadata |
| `list-entities` | Return entity sets with key properties |
| `list-entity-properties` | Return properties and navigation links for a given entity |
| `validate-query` | Check OData query syntax and semantics against the schema |
| `find-navigation-path` | Discover the shortest `$expand` path between two entities |
| `execute-odata-query` | Run a validated query and return JSON results |
| `aggregate-data` | Perform client-side grouping and aggregation on result sets |
---
## Getting Started
### Prerequisites
- .NET 9 SDK
- Node.js 18+
- An MCP-compatible host (e.g. Claude Desktop)
### Build
```bash
# Frontend
npm install && npm run build
# Backend
cd QueryCraft && dotnet build
```
### Configure
Add OData services to `QueryCraft/appsettings.json`:
```json
{
"QueryCraft": {
"MetadataCacheTtlMinutes": 60,
"MaxResponseBytes": 5000000,
"Services": [
{
"Key": "northwind",
"DisplayName": "Northwind Sample",
"ServiceRoot": "https://services.odata.org/V4/Northwind/Northwind.svc/",
"MetadataUrl": "https://services.odata.org/V4/Northwind/Northwind.svc/$metadata",
"Enabled": true
}
]
}
}
```
### Run
Register the server in your MCP host configuration:
```json
{
"mcpServers": {
"querycraft": {
"command": "dotnet",
"args": ["run", "--project", "/path/to/query-craft-mcp/QueryCraft"]
}
}
}
```
---
## Usage
```text
User → "Connect to the Northwind service"
User → "What entities are available?"
User → "Find all products priced above 20, sorted by name"
LLM → validates query → executes → returns results in an interactive table
```
---
## Project Structure
```
QueryCraft/ .NET 9 MCP server
├── ODataTools.cs MCP tool definitions (8 tools)
├── ODataSchemaService.cs Metadata loading & schema parsing
├── QueryValidator.cs OData v4 syntax & semantic validation
├── ClientAggregator.cs Client-side aggregation engine
├── SchemaIndex.cs In-memory schema lookups & BFS traversal
├── SchemaState.cs Schema registry & state management
└── Models/ Navigation & validation DTOs
src/ TypeScript UI source
mcp-app.html UI entry point (single-file Vite build)
```
---
## Limitations
- No authentication or authorization — intended for local development and demonstration only
- OData feature support varies by provider; some services may not expose full v4 capabilities
- Large result sets should be bounded with `$top` to avoid performance issues
---
## References
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP Apps API](https://modelcontextprotocol.github.io/ext-apps/api/)
- [OData v4 Specification](https://www.odata.org/documentation/)
- [Microsoft.OData.Edm](https://www.nuget.org/packages/Microsoft.OData.Edm)
---
## License
MIT
