QueryCraft

Natural language to OData v4 queries — powered by LLMs and grounded in real service metadata.

Schema exploration, query generation, and live execution inside Claude Desktop

---

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

# Frontend
npm install && npm run build

# Backend
cd QueryCraft && dotnet build

Configure

Add OData services to QueryCraft/appsettings.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:

{
  "mcpServers": {
    "querycraft": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/query-craft-mcp/QueryCraft"]
    }
  }
}

---

Usage

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
• MCP Apps API
• OData v4 Specification
• Microsoft.OData.Edm

---

License

MIT