vector-search
Search Meilisearch indexes using vector embeddings to find semantically similar content, supporting hybrid text-vector searches and customizable filtering.
Instructions
Perform a vector search in a Meilisearch index
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| indexUid | Yes | Unique identifier of the index | |
| vector | Yes | JSON array representing the vector to search for | |
| limit | No | Maximum number of results to return (default: 20) | |
| offset | No | Number of results to skip (default: 0) | |
| filter | No | Filter to apply (e.g., 'genre = horror AND year > 2020') | |
| embedder | No | Name of the embedder to use (if omitted, a 'vector' must be provided) | |
| attributes | No | Attributes to include in the vector search | |
| query | No | Text query to search for (if using 'embedder' instead of 'vector') | |
| hybrid | No | Whether to perform a hybrid search (combining vector and text search) | |
| hybridRatio | No | Ratio of vector vs text search in hybrid search (0-1, default: 0.5) |
Implementation Reference
- src/tools/vector-tools.ts:141-189 (handler)The async handler function that performs the vector search by parsing inputs, validating requirements (vector or embedder+query), building search parameters, and POSTing to Meilisearch's /indexes/{indexUid}/search endpoint.
async ({ indexUid, vector, limit, offset, filter, embedder, attributes, query, hybrid, hybridRatio }) => { try { const searchParams: Record<string, any> = {}; // Add required vector parameter if (vector) { try { searchParams.vector = JSON.parse(vector); } catch (parseError) { return { isError: true, content: [{ type: "text", text: "Vector must be a valid JSON array" }], }; } } // Add embedder parameters if (embedder) { searchParams.embedder = embedder; if (query !== undefined) { searchParams.q = query; } } // Ensure we have either vector or (embedder + query) if (!vector && (!embedder || query === undefined)) { return { isError: true, content: [{ type: "text", text: "Either 'vector' or both 'embedder' and 'query' must be provided" }], }; } // Add optional parameters if (limit !== undefined) searchParams.limit = limit; if (offset !== undefined) searchParams.offset = offset; if (filter) searchParams.filter = filter; if (attributes?.length) searchParams.attributes = attributes; if (hybrid !== undefined) searchParams.hybrid = hybrid; if (hybridRatio !== undefined) searchParams.hybridRatio = hybridRatio; const response = await apiClient.post(`/indexes/${indexUid}/search`, searchParams); return { content: [{ type: "text", text: JSON.stringify(response.data, null, 2) }], }; } catch (error) { return createErrorResponse(error); } } - src/tools/vector-tools.ts:129-140 (schema)Zod schema defining the input parameters for the vector-search tool.
{ indexUid: z.string().describe("Unique identifier of the index"), vector: z.string().describe("JSON array representing the vector to search for"), limit: z.number().min(1).max(1000).optional().describe("Maximum number of results to return (default: 20)"), offset: z.number().min(0).optional().describe("Number of results to skip (default: 0)"), filter: z.string().optional().describe("Filter to apply (e.g., 'genre = horror AND year > 2020')"), embedder: z.string().optional().describe("Name of the embedder to use (if omitted, a 'vector' must be provided)"), attributes: z.array(z.string()).optional().describe("Attributes to include in the vector search"), query: z.string().optional().describe("Text query to search for (if using 'embedder' instead of 'vector')"), hybrid: z.boolean().optional().describe("Whether to perform a hybrid search (combining vector and text search)"), hybridRatio: z.number().min(0).max(1).optional().describe("Ratio of vector vs text search in hybrid search (0-1, default: 0.5)"), }, - src/tools/vector-tools.ts:126-190 (registration)Direct registration of the 'vector-search' tool on the MCP server using server.tool(), including description, input schema, and handler.
server.tool( "vector-search", "Perform a vector search in a Meilisearch index", { indexUid: z.string().describe("Unique identifier of the index"), vector: z.string().describe("JSON array representing the vector to search for"), limit: z.number().min(1).max(1000).optional().describe("Maximum number of results to return (default: 20)"), offset: z.number().min(0).optional().describe("Number of results to skip (default: 0)"), filter: z.string().optional().describe("Filter to apply (e.g., 'genre = horror AND year > 2020')"), embedder: z.string().optional().describe("Name of the embedder to use (if omitted, a 'vector' must be provided)"), attributes: z.array(z.string()).optional().describe("Attributes to include in the vector search"), query: z.string().optional().describe("Text query to search for (if using 'embedder' instead of 'vector')"), hybrid: z.boolean().optional().describe("Whether to perform a hybrid search (combining vector and text search)"), hybridRatio: z.number().min(0).max(1).optional().describe("Ratio of vector vs text search in hybrid search (0-1, default: 0.5)"), }, async ({ indexUid, vector, limit, offset, filter, embedder, attributes, query, hybrid, hybridRatio }) => { try { const searchParams: Record<string, any> = {}; // Add required vector parameter if (vector) { try { searchParams.vector = JSON.parse(vector); } catch (parseError) { return { isError: true, content: [{ type: "text", text: "Vector must be a valid JSON array" }], }; } } // Add embedder parameters if (embedder) { searchParams.embedder = embedder; if (query !== undefined) { searchParams.q = query; } } // Ensure we have either vector or (embedder + query) if (!vector && (!embedder || query === undefined)) { return { isError: true, content: [{ type: "text", text: "Either 'vector' or both 'embedder' and 'query' must be provided" }], }; } // Add optional parameters if (limit !== undefined) searchParams.limit = limit; if (offset !== undefined) searchParams.offset = offset; if (filter) searchParams.filter = filter; if (attributes?.length) searchParams.attributes = attributes; if (hybrid !== undefined) searchParams.hybrid = hybrid; if (hybridRatio !== undefined) searchParams.hybridRatio = hybridRatio; const response = await apiClient.post(`/indexes/${indexUid}/search`, searchParams); return { content: [{ type: "text", text: JSON.stringify(response.data, null, 2) }], }; } catch (error) { return createErrorResponse(error); } } ); - src/index.ts:68-68 (registration)Registers the vector tools module (including vector-search) on the main MCP server instance.
registerVectorTools(server);