# Orama Hybrid Search Query Builder MCP for AI Agents MCP

> Orama Hybrid Search Query Builder MCP. It transforms simple, flat filter dictionaries into the complex, nested JSON payloads required for Orama search queries. This ensures your AI agents can perform advanced filtering like range queries on prices or dates without ever generating invalid syntax.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_BQ7O5IoM6rjvkdusKaOa2Mt3EgaF6wXmj0IWNjuL/mcp
- **Tags:** orama, search-engine, query-builder, json, filtering, javascript

## Description

Writing Orama search queries is a headache because of the nested JSON structure required for filtering. If you are building an agent to interact with your search engine, one small mistake in a 'where' clause breaks everything. This MCP handles that heavy lifting by taking simple key-value pairs and turning them into precise comparison operators like equality or range checks. You can check your filters before they ever hit the engine to ensure they are valid. It is part of the massive Vinkius catalog, so you's can just connect it to your preferred client and start building complex search logic immediately without worrying about syntax errors.

When you use this, you stop manually managing deep JSON trees. Instead, you provide a flat list of what you want to find, like a price range or a specific category, and the MCP handles the hierarchical mapping. This means your agent can perform much more sophisticated searches, such as finding items within a certain date range or filtering by multiple attributes at once, without the risk of generating invalid syntax. It essentially gives your AI client the ability to speak the complex language of Orama's search engine fluently. You get reliable, deterministic results that match exactly what you intended, making your search-driven applications much more robust and easier to maintain.

## Tools

### get_operator_mapping_summary
Shows you exactly how your filters map to Orama operators. Use this to see which rules apply to your data.

### validate_filter_syntax
Checks your filter dictionary for errors before you run a query. It prevents broken requests from hitting your engine.

### build_orama_query
Converts simple input into a nested JSON object for Orama searches. It handles all the complex hierarchy for you.

## Prompt Examples

**Prompt:** 
```
Find all running shoes under $100 in the sports category.
```

**Response:** 
```
**Search Payload Generated:**

| Field | Operator | Value |
| :--- | :--- | :--- |
| `term` | match | `running shoes` |
| `price` | `lt` | `100` |
| `category` | `eq` | `sports` |

Your query is ready for execution.
```

**Prompt:** 
```
Check if this filter is okay: {'brand': 'Nike', 'rating': {'gt': 4}}
```

**Response:** 
```
The syntax is valid. Your brand will use an equality check and your rating will use a greater-than operator.
```

**Prompt:** 
```
What operators can I use for my search?
```

**Response:** 
```
You can use the following operators:
* `eq`: Exact equality
* `gt`: Greater than
* `lt`: Less than
```

## Capabilities

### Generate nested JSON payloads
Converts simple inputs into the complex hierarchical structure Orama requires.

### Validate filter syntax
Checks your filter dictionaries for errors before they reach your search engine.

### Map simple keys to operators
Automatically transforms flat key-value pairs into eq, gt, and lt comparison operators.

### Review operator rules
Provides a summary of all supported operator tiers for your queries.

### Automate range queries
Handles the construction of complex numeric and date-based comparison logic.

## Use Cases

### Price Filtering
An engineer needs to find products under $50; the agent uses this MCP to build a 'lt' operator query automatically.

### Date Range Queries
A developer wants to search for logs from the last 24 hours; the agent generates the correct timestamp comparison logic.

### Category Filtering
A user asks for all sports gear; the agent builds an exact match equality query for the category field.

### Multi-attribute Search
An agent needs to find blue shirts in size large; it constructs a complex, multi-layered JSON payload without errors.

## Benefits

- Stop breaking searches with invalid JSON by using deterministic mapping for every query.
- Speed up development by letting the MCP handle all nested JSON construction.
- Prevent broken requests from hitting your engine by validating syntax before execution.
- Simplify complex range queries for prices or dates without manual coding.
- Keep your agent's logic clean by using flat, easy-to-read filter dictionaries.

## How It Works

The bottom line is you stop debugging broken search syntax and start building functional queries.

1. Connect the MCP to your preferred AI client through Vinkius.
2. Provide a simple dictionary of filters or keys you want to query.
3. Receive a perfectly formatted, syntactically correct JSON payload ready for Orama.

## Frequently Asked Questions

**How do I stop getting syntax errors in Orama?**
Use the Oramah Hybrid Search Query Builder to generate payloads that are guaranteed to follow the correct JSON structure.

**Can this MCP help with price range searches?**
Yes, it transforms simple numeric filters into the proper 'lt' or 'gt' operators for your search engine.

**Does the Orama Hybrid Search Query Builder work with any AI client?**
It works with any compatible client like Claude, Cursor, or Windsurf connected via Vinkius.

**How do I know if my filter dictionary is valid?**
You can use the validation tool within this MCP to check your syntax before you ever send a query to Orama.

**What kind of filtering is possible with this MCP?**
It supports equality, greater than, and less than comparisons for any field in your index.

**What is the main purpose of this MCP server?**
It automates the creation of complex, nested JSON payloads for Orama search queries, ensuring syntactical correctness using `build_orama_query`.

**How can I ensure my filter dictionary is valid?**
You should use the `validate_filter_syntax` tool to check your dictionary for any unsupported types or invalid characters before attempting to build a query.

**What operators are supported for filtering?**
The server supports `eq` (equality), `gt` (greater than), and `lt` (less than) through its deterministic mapping logic.