feat(api): VSS and Semantic Search MCPs for Valkey #1862
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
6 tasks
Jonathan-Improving
changed the title
src/valkey-mcp-server/awslabs/valkey_mcp_server/embeddings/__init__.py
Outdated
Show resolved
Hide resolved
src/valkey-mcp-server/awslabs/valkey_mcp_server/embeddings/__init__.py
Outdated
Show resolved
Hide resolved
src/valkey-mcp-server/awslabs/valkey_mcp_server/tools/semantic_search.py
Show resolved
Hide resolved
vasigorc
reviewed
Dec 2, 2025
| Example: | ||
| provider = BedrockEmbeddings( | ||
| region_name="us-east-1", | ||
| model_id="amazon.titan-embed-text-v1" |
There was a problem hiding this comment.
FWIW, there is a newer V2 version now: https://docs.aws.amazon.com/bedrock/latest/userguide/titan-embedding-models.html
src/valkey-mcp-server/awslabs/valkey_mcp_server/tools/semantic_search.py
Outdated
Show resolved
Hide resolved
src/valkey-mcp-server/awslabs/valkey_mcp_server/tools/semantic_search.py
Outdated
Show resolved
Hide resolved
Jonathan-Improving
force-pushed
the
feature/semantic-search
branch
from
54b7023 to
a6d1023
Compare
jbrinkman
reviewed
Dec 4, 2025
src/valkey-mcp-server/awslabs/valkey_mcp_server/embeddings/__init__.py
Outdated
Show resolved
Hide resolved
Jonathan-Improving
changed the title
Jonathan-Improving
changed the title
Jonathan-Improving
force-pushed
the
feature/semantic-search
branch
3 times, most recently
from
3042a57 to
26ecda1
Compare
Author
|
Latest enhancements include full |
Jonathan-Improving
force-pushed
the
feature/semantic-search
branch
from
661d50a to
29bc757
Compare
Jonathan-Improving
force-pushed
the
feature/semantic-search
branch
from
dd87995 to
c8be313
Compare
Author
|
Removing draft status to push this forward, one thing remains: to thoroughly test the Bedrock integration. |
Author
|
Ready for review |
seaofawareness
requested changes
Dec 8, 2025
Contributor
seaofawareness
left a comment
seaofawareness
left a comment
There was a problem hiding this comment.
Great to see this addition, please address comments
src/valkey-mcp-server/awslabs/valkey_mcp_server/embeddings/__init__.py
Outdated
Show resolved
Hide resolved
src/valkey-mcp-server/awslabs/valkey_mcp_server/embeddings/__init__.py
Outdated
Show resolved
Hide resolved
src/valkey-mcp-server/awslabs/valkey_mcp_server/embeddings/__init__.py
Outdated
Show resolved
Hide resolved
src/valkey-mcp-server/awslabs/valkey_mcp_server/embeddings/providers.py
Outdated
Show resolved
Hide resolved
| 'embedding', 'VECTOR', 'FLAT', '6', | ||
| 'TYPE', 'FLOAT32', | ||
| 'DIM', str(actual_dimensions), | ||
| 'DISTANCE_METRIC', 'L2' |
Contributor
There was a problem hiding this comment.
- Why not expose settings to user from env variables? Use of FLAT is limiting, HNSW with default settings should be supported for this PR.
| async def vector_search(index: str, | ||
| field: str, | ||
| vector: List[float], | ||
| filter_expression: Optional[str] = None, |
Contributor
There was a problem hiding this comment.
Do you need to sanitize this string to ensure only safe/approved content is allowed to prevent unexpected executions? Any length limit checks etc?
|
|
||
| # Initialize embeddings provider | ||
| try: | ||
| embeddings_provider = create_embeddings_provider() |
Contributor
There was a problem hiding this comment.
Do you want to support mock enbedding provider to enable validation without setup of actual provider?
| @pytest.fixture(autouse=True) | ||
| def setup_valkey_config(self): | ||
| """Configure Valkey connection to use environment variables.""" | ||
| original_config = VALKEY_CFG.copy() |
Contributor
There was a problem hiding this comment.
Error out if Valkey is not available or doesn't have search module
| print("="*70) | ||
|
|
||
| @pytest.mark.asyncio | ||
| async def test_semantic_search_with_filter_expression(self): |
Contributor
There was a problem hiding this comment.
Add tests for invalid input
| assert isinstance(result, str) | ||
|
|
||
| @pytest.mark.asyncio | ||
| async def test_vector_search_connection_error(self, mock_connection): |
Contributor
There was a problem hiding this comment.
Add test for missing search module
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Changes
Introduces a simple MCP wrapper around the Valkey vector search capability, and provides a full semantic search MCP for Valkey, leveraging its VSS capabilities, and encapsulating vector embeddings so that agents can interop using pure natural language and/or keywords.
User experience
Vector Similarity Search
Prior to the introduction of this tool users could not interact with Valkey's vector search capabilities via an MCP client, but now one can and retrieve documents stored in a Valkey instance, sought according to a vector embedding.
Caveat: The user must provide the vector embedding itself, and the vector embedding must have been generated by the same model that the documents stored within the Valkey instance contain (if applicable), presuming that the end-user has already seeded a Valkey instance with documents each having a vector embedding field used to VSS.
Results
A basic test revealed that the agent struggled to generate vector embeddings from an MCP that provides embeddings, and then pass them on intact to this VSS MCP, which requires a list of floats (vector embedding) for input. In one test the agent passed a completely fake vector embedding to the VSS MCP, and in another test the agent hung for more than 10 minutes before it was terminated. This implies that a specifically configured agentic context is key for the VSS MCP to be useful.
Semantic Search
The role of a data scientist would first add documents to the Valkey database using the
add_documentsMCP, under a specifically named collection, that can be sought using semantic search. The role of researcher would leverage thesemantic_searchMCP to seek for documents added under a specifically named collection, or query thelist_collectionsMCP to find out what named collections are available for searching.Checklist
If your change doesn't seem to apply, please leave them unchecked.
Not a breaking change.
RFC issue number:
Checklist:
Acknowledgment
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.