Feature Request: New Tool for Hybrid Vector + Metadata Search

[retail-amelis]

Summary

Currently, the vector_search_hash tool in mcp-redis supports pure vector similarity search (KNN) over Redis indexes created via create_vector_index_hash, but does not allow hybrid search — i.e., combining vector similarity with structured metadata filters (tags, text, numeric ranges).

Redis natively supports hybrid queries through RediSearch syntax (e.g., (@category:{tech} @year:[2020 9999])=>[KNN 10 @embedding $vec_param AS score]), but this capability is not yet exposed in the MCP layer.

Motivation

Many real-world applications (semantic search, recommendation, retrieval-augmented generation) require combining semantic similarity with structured constraints.
For example:

filter_query = "@category:{tech} @language:{en}"
vector_query = [KNN 10 @embedding $vec_param AS score]

Without this feature, users must either:

• Build multiple vector indexes per filter subset, or
• Chain two tools manually (filter first, then vector search), which is inefficient and error-prone.

Proposed Solution

Introduce a new tool called hybrid_vector_search_hash, extending the functionality of vector_search_hash by adding a filter_query argument.

Example Signature

@tool
def hybrid_vector_search_hash(
    index_name: str,
    vector_field: str,
    query_vector: list[float],
    k: int,
    filter_query: Optional[str] = None,
    return_fields: Optional[list[str]] = None,
) -> list[dict]:
    """
    Perform a hybrid vector + metadata search using Redis RediSearch.
    """

Expected Behavior

• If filter_query is provided, it is prepended to the KNN clause:

  ({filter_query})=>[KNN {k} @{vector_field} $vec_param AS score]
  

• Otherwise, defaults to *=>[KNN ...] (current behavior).

• Returns the same payload as vector_search_hash.

Implementation Notes

• filter_query should support standard RediSearch syntax (TEXT, TAG, NUMERIC fields).
• Reuse the Query construction pattern from redis_query_engine.py.
• Compatible with existing indexes created via create_vector_index_hash.
• Consider supporting hybrid ranking (e.g., combined score weighting).

Example Use Case

result = hybrid_vector_search_hash(
    index_name="idx:products",
    vector_field="embedding",
    query_vector=query_vec,
    k=5,
    filter_query="@brand:{Nike} @price:[50 200]",
    return_fields=["id", "name", "brand", "price"]
)

Benefits

• Enables true hybrid search directly in MCP.
• Eliminates need for index duplication.
• Aligns with Redis Vector Database best practices.
• Provides an intuitive interface for LLMs and agents to perform filtered retrieval.

[vchomakov]

Thank you very much for this feature request, @retail-amelis! We’ll review it with the team and prioritize accordingly.