mcp-meilisearch 1.0.0

package/dist/tools/document-tools.js

@@ -0,0 +1,208 @@
+import { z } from "zod";
+import apiClient from "../utils/api-handler.js";
+import { createErrorResponse } from "../utils/error-handler.js";
+/**
+ * Register document management tools with the MCP server
+ *
+ * @param server - The MCP server instance
+ */
+export const registerDocumentTools = (server) => {
+    // Get documents from an index
+    server.tool("get-documents", "Get documents from a Meilisearch index", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+        limit: z
+            .number()
+            .min(1)
+            .max(1000)
+            .optional()
+            .describe("Maximum number of documents to return (default: 20)"),
+        offset: z
+            .number()
+            .min(0)
+            .optional()
+            .describe("Number of documents to skip (default: 0)"),
+        fields: z
+            .array(z.string())
+            .optional()
+            .describe("Fields to return in the documents"),
+        filter: z.string().optional().describe("Filter query to apply"),
+    }, async ({ indexUid, limit, offset, fields, filter }) => {
+        try {
+            const response = await apiClient.get(`/indexes/${indexUid}/documents`, {
+                params: {
+                    limit,
+                    offset,
+                    fields: fields?.join(","),
+                    filter,
+                },
+            });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Get a single document by ID
+    server.tool("get-document", "Get a document by its ID from a Meilisearch index", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+        documentId: z.string().describe("ID of the document to retrieve"),
+        fields: z
+            .array(z.string())
+            .optional()
+            .describe("Fields to return in the document"),
+    }, async ({ indexUid, documentId, fields }) => {
+        try {
+            const response = await apiClient.get(`/indexes/${indexUid}/documents/${documentId}`, {
+                params: {
+                    fields: fields?.join(","),
+                },
+            });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Add documents to an index
+    server.tool("add-documents", "Add documents to a Meilisearch index", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+        documents: z.string().describe("JSON array of documents to add"),
+        primaryKey: z
+            .string()
+            .optional()
+            .describe("Primary key for the documents"),
+    }, async ({ indexUid, documents, primaryKey }) => {
+        try {
+            // Parse the documents string to ensure it's valid JSON
+            const parsedDocuments = JSON.parse(documents);
+            // Ensure documents is an array
+            if (!Array.isArray(parsedDocuments)) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: "Documents must be a JSON array" }],
+                };
+            }
+            const params = {};
+            if (primaryKey) {
+                params.primaryKey = primaryKey;
+            }
+            const response = await apiClient.post(`/indexes/${indexUid}/documents`, parsedDocuments, {
+                params,
+            });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Update documents in an index
+    server.tool("update-documents", "Update documents in a Meilisearch index", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+        documents: z.string().describe("JSON array of documents to update"),
+        primaryKey: z
+            .string()
+            .optional()
+            .describe("Primary key for the documents"),
+    }, async ({ indexUid, documents, primaryKey }) => {
+        try {
+            // Parse the documents string to ensure it's valid JSON
+            const parsedDocuments = JSON.parse(documents);
+            // Ensure documents is an array
+            if (!Array.isArray(parsedDocuments)) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: "Documents must be a JSON array" }],
+                };
+            }
+            const params = {};
+            if (primaryKey) {
+                params.primaryKey = primaryKey;
+            }
+            const response = await apiClient.put(`/indexes/${indexUid}/documents`, parsedDocuments, {
+                params,
+            });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Delete a document by ID
+    server.tool("delete-document", "Delete a document by its ID from a Meilisearch index", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+        documentId: z.string().describe("ID of the document to delete"),
+    }, async ({ indexUid, documentId }) => {
+        try {
+            const response = await apiClient.delete(`/indexes/${indexUid}/documents/${documentId}`);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Delete multiple documents by ID
+    server.tool("delete-documents", "Delete multiple documents by their IDs from a Meilisearch index", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+        documentIds: z.string().describe("JSON array of document IDs to delete"),
+    }, async ({ indexUid, documentIds }) => {
+        try {
+            // Parse the document IDs string to ensure it's valid JSON
+            const parsedDocumentIds = JSON.parse(documentIds);
+            // Ensure document IDs is an array
+            if (!Array.isArray(parsedDocumentIds)) {
+                return {
+                    isError: true,
+                    content: [
+                        { type: "text", text: "Document IDs must be a JSON array" },
+                    ],
+                };
+            }
+            const response = await apiClient.post(`/indexes/${indexUid}/documents/delete-batch`, parsedDocumentIds);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Delete all documents in an index
+    server.tool("delete-all-documents", "Delete all documents in a Meilisearch index", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+    }, async ({ indexUid }) => {
+        try {
+            const response = await apiClient.delete(`/indexes/${indexUid}/documents`);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+};
+export default registerDocumentTools;

package/dist/tools/index-tools.js

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import apiClient from "../utils/api-handler.js";
+import { createErrorResponse } from "../utils/error-handler.js";
+/**
+ * Register index management tools with the MCP server
+ *
+ * @param server - The MCP server instance
+ */
+export const registerIndexTools = (server) => {
+    // List all indexes
+    server.tool("list-indexes", "List all indexes in the Meilisearch instance", {
+        limit: z
+            .number()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe("Maximum number of indexes to return"),
+        offset: z
+            .number()
+            .min(0)
+            .optional()
+            .describe("Number of indexes to skip"),
+    }, async ({ limit, offset }) => {
+        try {
+            const response = await apiClient.get("/indexes", {
+                params: {
+                    limit,
+                    offset,
+                },
+            });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Get index information
+    server.tool("get-index", "Get information about a specific Meilisearch index", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+    }, async ({ indexUid }) => {
+        try {
+            const response = await apiClient.get(`/indexes/${indexUid}`);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Create a new index
+    server.tool("create-index", "Create a new Meilisearch index", {
+        indexUid: z.string().describe("Unique identifier for the new index"),
+        primaryKey: z.string().optional().describe("Primary key for the index"),
+    }, async ({ indexUid, primaryKey }) => {
+        try {
+            const response = await apiClient.post("/indexes", {
+                uid: indexUid,
+                primaryKey,
+            });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Update an index
+    server.tool("update-index", "Update a Meilisearch index (currently only supports updating the primary key)", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+        primaryKey: z.string().describe("New primary key for the index"),
+    }, async ({ indexUid, primaryKey }) => {
+        try {
+            const response = await apiClient.patch(`/indexes/${indexUid}`, {
+                primaryKey,
+            });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Delete an index
+    server.tool("delete-index", "Delete a Meilisearch index", {
+        indexUid: z.string().describe("Unique identifier of the index to delete"),
+    }, async ({ indexUid }) => {
+        try {
+            const response = await apiClient.delete(`/indexes/${indexUid}`);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Swap indexes
+    server.tool("swap-indexes", "Swap two or more indexes in Meilisearch", {
+        indexes: z
+            .string()
+            .describe('JSON array of index pairs to swap, e.g. [["movies", "movies_new"]]'),
+    }, async ({ indexes }) => {
+        try {
+            // Parse the indexes string to ensure it's valid JSON
+            const parsedIndexes = JSON.parse(indexes);
+            // Ensure indexes is an array of arrays
+            if (!Array.isArray(parsedIndexes) ||
+                !parsedIndexes.every((pair) => Array.isArray(pair) && pair.length === 2)) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: 'Indexes must be a JSON array of pairs, e.g. [["movies", "movies_new"]]',
+                        },
+                    ],
+                };
+            }
+            const response = await apiClient.post("/swap-indexes", parsedIndexes);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+};
+export default registerIndexTools;

package/dist/tools/search-tools.js

@@ -0,0 +1,221 @@
+import { z } from "zod";
+import apiClient from "../utils/api-handler.js";
+import { createErrorResponse } from "../utils/error-handler.js";
+/**
+ * Register search tools with the MCP server
+ *
+ * @param server - The MCP server instance
+ */
+export const registerSearchTools = (server) => {
+    // Search in an index
+    server.tool("search", "Search for documents in a Meilisearch index", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+        q: z.string().describe("Search query"),
+        limit: z
+            .number()
+            .min(1)
+            .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 query to apply"),
+        sort: z
+            .array(z.string())
+            .optional()
+            .describe('Attributes to sort by, e.g. ["price:asc"]'),
+        facets: z.array(z.string()).optional().describe("Facets to return"),
+        attributesToRetrieve: z
+            .array(z.string())
+            .optional()
+            .describe("Attributes to include in results"),
+        attributesToCrop: z
+            .array(z.string())
+            .optional()
+            .describe("Attributes to crop"),
+        cropLength: z
+            .number()
+            .optional()
+            .describe("Length at which to crop cropped attributes"),
+        attributesToHighlight: z
+            .array(z.string())
+            .optional()
+            .describe("Attributes to highlight"),
+        highlightPreTag: z
+            .string()
+            .optional()
+            .describe("Tag to insert before highlighted text"),
+        highlightPostTag: z
+            .string()
+            .optional()
+            .describe("Tag to insert after highlighted text"),
+        showMatchesPosition: z
+            .boolean()
+            .optional()
+            .describe("Whether to include match positions in results"),
+        matchingStrategy: z
+            .string()
+            .optional()
+            .describe("Matching strategy: 'all' or 'last'"),
+    }, async ({ indexUid, q, limit, offset, filter, sort, facets, attributesToRetrieve, attributesToCrop, cropLength, attributesToHighlight, highlightPreTag, highlightPostTag, showMatchesPosition, matchingStrategy, }) => {
+        try {
+            const response = await apiClient.post(`/indexes/${indexUid}/search`, {
+                q,
+                limit,
+                offset,
+                filter,
+                sort,
+                facets,
+                attributesToRetrieve,
+                attributesToCrop,
+                cropLength,
+                attributesToHighlight,
+                highlightPreTag,
+                highlightPostTag,
+                showMatchesPosition,
+                matchingStrategy,
+            });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Multi-search across multiple indexes
+    server.tool("multi-search", "Perform multiple searches in one request", {
+        searches: z
+            .string()
+            .describe("JSON array of search queries, each with indexUid and q fields"),
+    }, async ({ searches }) => {
+        try {
+            // Parse the searches string to ensure it's valid JSON
+            const parsedSearches = JSON.parse(searches);
+            // Ensure searches is an array
+            if (!Array.isArray(parsedSearches)) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: "Searches must be a JSON array" }],
+                };
+            }
+            // Ensure each search has at least indexUid
+            for (const search of parsedSearches) {
+                if (!search.indexUid) {
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: "text",
+                                text: "Each search must have an indexUid field",
+                            },
+                        ],
+                    };
+                }
+            }
+            const response = await apiClient.post("/multi-search", {
+                queries: parsedSearches,
+            });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    server.tool("search-across-all-indexes", "Search for a term across all available Meilisearch indexes and return combined results.", {
+        q: z.string().describe("Search query"),
+        limit: z
+            .number()
+            .min(1)
+            .optional()
+            .describe("Maximum number of results to return per index (default: 20)"),
+        attributesToRetrieve: z
+            .array(z.string())
+            .optional()
+            .describe("Attributes to include in results"),
+    }, async ({ q, limit, attributesToRetrieve }) => {
+        try {
+            const indexesResponse = await apiClient.get("/indexes", {
+                params: { limit: 1000 },
+            });
+            const indexUids = indexesResponse.data.results.map((index) => index.uid);
+            if (!indexUids || indexUids.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ allHits: [], message: "No indexes found in Meilisearch." }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const searchPromises = indexUids.map(async (uid) => {
+                try {
+                    const searchResult = await apiClient.post(`/indexes/${uid}/search`, {
+                        q,
+                        limit,
+                        attributesToRetrieve,
+                    });
+                    return searchResult.data.hits.map((hit) => ({
+                        indexUid: uid,
+                        ...hit,
+                    }));
+                }
+                catch (searchError) {
+                    return [];
+                }
+            });
+            const resultsPerIndex = await Promise.all(searchPromises);
+            const allHits = resultsPerIndex.flat();
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ allHits }, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Facet search
+    server.tool("facet-search", "Search for facet values matching specific criteria", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+        facetName: z.string().describe("Name of the facet to search"),
+        facetQuery: z
+            .string()
+            .optional()
+            .describe("Query to match against facet values"),
+        filter: z
+            .string()
+            .optional()
+            .describe("Filter to apply to the base search"),
+    }, async ({ indexUid, facetName, facetQuery, filter }) => {
+        try {
+            const params = {
+                facetName,
+            };
+            if (facetQuery !== undefined)
+                params.facetQuery = facetQuery;
+            if (filter)
+                params.filter = filter;
+            const response = await apiClient.post(`/indexes/${indexUid}/facet-search`, params);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+};
+export default registerSearchTools;