mcp-meilisearch 1.0.0

package/dist/tools/task-tools.js

@@ -0,0 +1,190 @@
+import { z } from "zod";
+import apiClient from "../utils/api-handler.js";
+import { createErrorResponse } from "../utils/error-handler.js";
+/**
+ * Register task management tools with the MCP server
+ *
+ * @param server - The MCP server instance
+ */
+export const registerTaskTools = (server) => {
+    // Get all tasks
+    server.tool("list-tasks", "List tasks with optional filtering", {
+        limit: z
+            .number()
+            .min(0)
+            .optional()
+            .describe("Maximum number of tasks to return"),
+        from: z
+            .number()
+            .min(0)
+            .optional()
+            .describe("Task uid from which to start fetching"),
+        statuses: z
+            .array(z.enum(["enqueued", "processing", "succeeded", "failed", "canceled"]))
+            .optional()
+            .describe("Statuses of tasks to return"),
+        types: z
+            .array(z.enum([
+            "indexCreation",
+            "indexUpdate",
+            "indexDeletion",
+            "documentAddition",
+            "documentUpdate",
+            "documentDeletion",
+            "settingsUpdate",
+            "dumpCreation",
+            "taskCancelation",
+        ]))
+            .optional()
+            .describe("Types of tasks to return"),
+        indexUids: z
+            .array(z.string())
+            .optional()
+            .describe("UIDs of the indexes on which tasks were performed"),
+        uids: z
+            .array(z.number())
+            .optional()
+            .describe("UIDs of specific tasks to return"),
+    }, async ({ limit, from, statuses, types, indexUids, uids, }) => {
+        try {
+            const params = {};
+            if (limit !== undefined)
+                params.limit = limit;
+            if (from !== undefined)
+                params.from = from;
+            if (statuses && statuses.length > 0)
+                params.statuses = statuses.join(",");
+            if (types && types.length > 0)
+                params.types = types.join(",");
+            if (indexUids && indexUids.length > 0)
+                params.indexUids = indexUids.join(",");
+            if (uids && uids.length > 0)
+                params.uids = uids.join(",");
+            const response = await apiClient.get("/tasks", { params });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Get a specific task
+    server.tool("get-task", "Get information about a specific task", {
+        taskUid: z.number().describe("Unique identifier of the task"),
+    }, async ({ taskUid }) => {
+        try {
+            const response = await apiClient.get(`/tasks/${taskUid}`);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Cancel tasks
+    server.tool("cancel-tasks", "Cancel tasks based on provided filters", {
+        statuses: z
+            .array(z.enum(["enqueued", "processing"]))
+            .optional()
+            .describe("Statuses of tasks to cancel"),
+        types: z
+            .array(z.enum([
+            "indexCreation",
+            "indexUpdate",
+            "indexDeletion",
+            "documentAddition",
+            "documentUpdate",
+            "documentDeletion",
+            "settingsUpdate",
+            "dumpCreation",
+            "taskCancelation",
+        ]))
+            .optional()
+            .describe("Types of tasks to cancel"),
+        indexUids: z
+            .array(z.string())
+            .optional()
+            .describe("UIDs of the indexes on which tasks to cancel were performed"),
+        uids: z
+            .array(z.number())
+            .optional()
+            .describe("UIDs of the tasks to cancel"),
+    }, async ({ statuses, types, indexUids, uids }) => {
+        try {
+            const body = {};
+            if (statuses && statuses.length > 0)
+                body.statuses = statuses;
+            if (types && types.length > 0)
+                body.types = types;
+            if (indexUids && indexUids.length > 0)
+                body.indexUids = indexUids;
+            if (uids && uids.length > 0)
+                body.uids = uids;
+            const response = await apiClient.post("/tasks/cancel", body);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Wait for a task to complete
+    server.tool("wait-for-task", "Wait for a specific task to complete", {
+        taskUid: z.number().describe("Unique identifier of the task to wait for"),
+        timeoutMs: z
+            .number()
+            .min(0)
+            .optional()
+            .describe("Maximum time to wait in milliseconds (default: 5000)"),
+        intervalMs: z
+            .number()
+            .min(100)
+            .optional()
+            .describe("Polling interval in milliseconds (default: 500)"),
+    }, async ({ taskUid, timeoutMs = 5000, intervalMs = 500, }) => {
+        try {
+            const startTime = Date.now();
+            let taskCompleted = false;
+            let taskData = null;
+            while (!taskCompleted && Date.now() - startTime < timeoutMs) {
+                // Fetch the current task status
+                const response = await apiClient.get(`/tasks/${taskUid}`);
+                taskData = response.data;
+                // Check if the task has completed
+                if (["succeeded", "failed", "canceled"].includes(taskData.status)) {
+                    taskCompleted = true;
+                }
+                else {
+                    // Wait for the polling interval
+                    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+                }
+            }
+            if (!taskCompleted) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Task ${taskUid} did not complete within the timeout period of ${timeoutMs}ms`,
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(taskData, null, 2) }],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+};
+export default registerTaskTools;

package/dist/tools/vector-tools.js

@@ -0,0 +1,214 @@
+import { z } from "zod";
+import apiClient from "../utils/api-handler.js";
+import { createErrorResponse } from "../utils/error-handler.js";
+/**
+ * Meilisearch Vector Search Tools
+ *
+ * This module implements MCP tools for vector search capabilities in Meilisearch.
+ * Note: Vector search is an experimental feature in Meilisearch.
+ */
+/**
+ * Register vector search tools with the MCP server
+ *
+ * @param server - The MCP server instance
+ */
+export const registerVectorTools = (server) => {
+    // Enable vector search experimental feature
+    server.tool("enable-vector-search", "Enable the vector search experimental feature in Meilisearch", {}, async () => {
+        try {
+            const response = await apiClient.post("/experimental-features", {
+                vectorStore: true,
+            });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Get experimental features status
+    server.tool("get-experimental-features", "Get the status of experimental features in Meilisearch", {}, async () => {
+        try {
+            const response = await apiClient.get("/experimental-features");
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Update embedders configuration
+    server.tool("update-embedders", "Configure embedders for vector search", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+        embedders: z
+            .string()
+            .describe("JSON object containing embedder configurations"),
+    }, async ({ indexUid, embedders }) => {
+        try {
+            // Parse the embedders string to ensure it's valid JSON
+            const parsedEmbedders = JSON.parse(embedders);
+            // Ensure embedders is an object
+            if (typeof parsedEmbedders !== "object" ||
+                parsedEmbedders === null ||
+                Array.isArray(parsedEmbedders)) {
+                return {
+                    isError: true,
+                    content: [
+                        { type: "text", text: "Embedders must be a JSON object" },
+                    ],
+                };
+            }
+            const response = await apiClient.patch(`/indexes/${indexUid}/settings/embedders`, parsedEmbedders);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Get embedders configuration
+    server.tool("get-embedders", "Get the embedders configuration for an index", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+    }, async ({ indexUid }) => {
+        try {
+            const response = await apiClient.get(`/indexes/${indexUid}/settings/embedders`);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Reset embedders configuration
+    server.tool("reset-embedders", "Reset the embedders configuration for an index", {
+        indexUid: z.string().describe("Unique identifier of the index"),
+    }, async ({ indexUid }) => {
+        try {
+            const response = await apiClient.delete(`/indexes/${indexUid}/settings/embedders`);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(response.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Perform vector search
+    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 = {};
+            // 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);
+        }
+    });
+};
+export default registerVectorTools;

package/dist/utils/api-handler.js

@@ -0,0 +1,33 @@
+import axios from 'axios';
+import config from '../config.js';
+/**
+ * Meilisearch API client
+ *
+ * This module provides a configured Axios instance for making requests to the Meilisearch API.
+ */
+/**
+ * Creates a configured Axios instance for Meilisearch API requests
+ *
+ * @returns An Axios instance with base configuration
+ */
+export const createApiClient = () => {
+    const instance = axios.create({
+        baseURL: config.host,
+        headers: {
+            Authorization: `Bearer ${config.apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        timeout: config.timeout,
+    });
+    return {
+        get: (url, config) => instance.get(url, config),
+        post: (url, data, config) => instance.post(url, data, config),
+        put: (url, data, config) => instance.put(url, data, config),
+        patch: (url, data, config) => instance.patch(url, data, config),
+        delete: (url, config) => instance.delete(url, config),
+    };
+};
+// Create and export a singleton instance of the API client
+export const apiClient = createApiClient();
+// Re-export for direct use
+export default apiClient;

package/dist/utils/error-handler.js

@@ -0,0 +1,35 @@
+/**
+ * Error handling utilities for Meilisearch API responses
+ */
+/**
+ * Formats Meilisearch API errors for consistent error messaging
+ *
+ * @param error - The error from the API request
+ * @returns A formatted error message
+ */
+export const handleApiError = (error) => {
+    // If it's an Axios error with a response
+    if (error.isAxiosError && error.response) {
+        const { status, data } = error.response;
+        // Return formatted error with status code and response data
+        return `Meilisearch API error (${status}): ${JSON.stringify(data)}`;
+    }
+    // If it's a network error or other error
+    return `Error connecting to Meilisearch: ${error.message}`;
+};
+/**
+ * Creates a standardized error response object for MCP tools
+ *
+ * @param error - The error from the API request
+ * @returns An MCP tool response object with error flag
+ */
+export const createErrorResponse = (error) => {
+    return {
+        isError: true,
+        content: [{ type: "text", text: handleApiError(error) }],
+    };
+};
+export default {
+    handleApiError,
+    createErrorResponse,
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "mcp-meilisearch",
+  "version": "1.0.0",
+  "description": "Model Context Protocol (MCP) implementation for Meilisearch",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "workspaces": [
+    "client"
+  ],
+  "scripts": {
+    "build:http": "tsc && chmod 755 dist/http.js",
+    "build:stdio": "tsc && chmod 755 dist/stdio.js",
+    "server": "npm run build:stdio && node --env-file=.env dist/stdio.js",
+    "client": "npm run build:http && node --env-file=.env dist/http.js & npm run preview --workspace=client",
+    "prepare": "tsc",
+    "prepublishOnly": "npm run build:http && npm run build:stdio"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.1",
+    "axios": "^1.9.0",
+    "express": "^5.1.0",
+    "vue": "^3.5.13",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.1",
+    "@types/node": "^22.14.0",
+    "@vitejs/plugin-vue": "^5.2.3",
+    "@vue/tsconfig": "^0.7.0",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5"
+  },
+  "engines": {
+    "node": ">=20.12.2",
+    "npm": ">=10.5.0"
+  }
+}