mcp-meilisearch 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+# MCP Meilisearch API Server
+
+A Model Context Protocol (MCP) server implementation that provides a bridge between AI models and the Meilisearch search engine using the StreamableHTTP transport. This project enables seamless integration of Meilisearch's powerful search capabilities within AI workflows.
+
+## Updated Overview
+
+This project provides a MCP server that enables AI models to interact directly with Meilisearch functionalities. The architecture includes:
+
+- **MCP Server**: Exposes Meilisearch APIs as tools using the Model Context Protocol.
+- **Web Client**: A demo interface showcasing search functionalities.
+
+## Architecture
+
+```
+┌───────────────┐      ┌───────────────┐      ┌───────────────┐
+│  Meilisearch  │      │   MCP Server  │      │   Web Client  │
+│   Instance    │ <--> │   (Node.js)   │ <--> │   (Browser)   │
+└───────────────┘      └───────────────┘      └───────────────┘
+        ^
+        │
+┌───────────────┐
+│ Document Data │
+│    Sources    │
+└───────────────┘
+```
+
+## Key Features
+
+- **StreamableHTTP Transport**: Real-time communication between clients and the server.
+- **Meilisearch API Support**: Full access to Meilisearch functionalities.
+- **Enhanced Error Handling**: Improved error management for API requests.
+- **Web Client Demo**: Updated interface for demonstrating search capabilities.
+
+## Tool Categories
+
+The MCP server organizes Meilisearch APIs into these categories:
+
+1. **System Tools**: Health checks, version info, server stats.
+2. **Index Tools**: Manage indexes (create, update, delete, list).
+3. **Document Tools**: Add, update, delete, and retrieve documents.
+4. **Search Tools**: Advanced search, including vector search.
+5. **Settings Tools**: Configure index settings.
+6. **Task Tools**: Manage asynchronous tasks.
+7. **Vector Tools**: Experimental vector search capabilities.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js v20 or higher.
+- A running Meilisearch instance (local or remote).
+- API key for Meilisearch (if required).
+
+### Setup Instructions
+
+1. Clone the repository:
+
+```bash
+git clone <repository-url>
+```
+
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Configure the environment:
+
+Create a `.env` file with the following content:
+
+```
+MEILISEARCH_HOST=http://localhost:7700
+MEILISEARCH_API_KEY=your_master_key_here
+```
+
+### Running the Server
+
+To start the server:
+
+```bash
+npm run start:server  # Start the MCP server
+npm run start:client  # Start the web client
+```
+
+### Accessing the Web Interface
+
+Visit the following URL in your browser:
+
+```
+http://localhost:8000
+```
+
+## Development
+
+This project uses:
+
+- **TypeScript**: Ensures type safety.
+- **Express**: Powers the web server.
+- **Model Context Protocol SDK**: Facilitates AI integration.
+
+## Project Structure
+
+- `src/`: Core MCP server implementation.
+  - `tools/`: Meilisearch API tools.
+  - `utils/`: Utility functions for API communication and error handling.
+  - `server.ts`: Main MCP server implementation.
+- `client/`: Web client for testing and demonstration.

package/dist/client.js

@@ -0,0 +1,146 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { TextContentSchema, LoggingMessageNotificationSchema, ToolListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
+export class MCPClient {
+    tools = [];
+    client;
+    tries = 0;
+    transport = null;
+    onToolsUpdatedCallback = null;
+    constructor(serverName) {
+        this.client = new Client({
+            name: serverName,
+            version: "1.0.0",
+        });
+    }
+    setOnToolsUpdatedCallback(callback) {
+        this.onToolsUpdatedCallback = callback;
+    }
+    async connectToServer(serverUrl) {
+        const url = new URL(serverUrl);
+        try {
+            console.log(`Connecting to MCP server at ${serverUrl}...`);
+            this.transport = new StreamableHTTPClientTransport(url);
+            await this.client.connect(this.transport);
+            console.log("✅ Successfully connected to server");
+            this.setUpTransport();
+            this.setUpNotifications();
+            await this.listTools();
+        }
+        catch (e) {
+            this.tries++;
+            if (this.tries > 5) {
+                console.error("❌ Failed to connect to MCP server: ", e);
+                throw e;
+            }
+            console.info(`⚠️ Retry attempt ${this.tries} to connect to server`);
+            await new Promise((resolve) => setTimeout(resolve, this.tries * 1000));
+            await this.connectToServer(serverUrl);
+        }
+    }
+    async listTools() {
+        try {
+            console.log("📋 Fetching available tools...");
+            const toolsResult = await this.client.listTools();
+            if (!toolsResult) {
+                console.error("❌ Received null or undefined tools result");
+                this.tools = [];
+            }
+            else if (toolsResult.tools && Array.isArray(toolsResult.tools)) {
+                this.tools = toolsResult.tools.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description ?? "",
+                }));
+            }
+            else {
+                console.error("❌ Invalid tools response format:", toolsResult);
+                this.tools = [];
+            }
+            if (this.onToolsUpdatedCallback) {
+                this.onToolsUpdatedCallback([...this.tools]);
+            }
+            if (this.tools.length) {
+                console.log(`✅ Successfully loaded ${this.tools.length} tools`);
+            }
+            else {
+                console.warn("⚠️ No tools were returned from the server or an error occurred.");
+            }
+        }
+        catch (error) {
+            console.error(`❌ Error fetching tools: ${error}`);
+            this.tools = [];
+            if (this.onToolsUpdatedCallback) {
+                this.onToolsUpdatedCallback([...this.tools]);
+            }
+        }
+    }
+    setUpNotifications() {
+        console.log("Setting up notification handlers...");
+        this.client.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => {
+            console.log("📢 LoggingMessage received:", notification);
+        });
+        this.client.setNotificationHandler(ToolListChangedNotificationSchema, async (notification) => {
+            console.log("🔄 ToolListChanged notification received:", notification);
+            await this.listTools();
+        });
+        console.log("✅ Notification handlers set up");
+    }
+    async callTool(name, args) {
+        try {
+            console.log(`\n🔧 Calling tool: ${name}`);
+            console.log("With arguments:", JSON.stringify(args, null, 2));
+            const result = await this.client.callTool({ name, arguments: args });
+            if (!result) {
+                return {
+                    success: false,
+                    error: "Received null or undefined result from tool",
+                };
+            }
+            const content = result.content;
+            if (!content?.length) {
+                return { success: true, data: [] };
+            }
+            const processedContent = content.reduce((acc, item) => {
+                const parse = TextContentSchema.safeParse(item);
+                if (parse.success) {
+                    try {
+                        return JSON.parse(parse.data.text);
+                    }
+                    catch (e) {
+                        return parse.data.text;
+                    }
+                }
+                return item;
+            }, {});
+            return { success: true, data: processedContent };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return { success: false, error: errorMessage };
+        }
+    }
+    setUpTransport() {
+        if (this.transport === null)
+            return;
+        this.transport.onclose = () => {
+            console.log("🔌 Transport closed");
+        };
+        this.transport.onerror = async (error) => {
+            console.log("❌ Transport error:", error);
+            await this.cleanup();
+        };
+    }
+    async cleanup() {
+        console.log("Cleaning up resources...");
+        try {
+            await this.client.close();
+            console.log("✅ Client closed successfully");
+        }
+        catch (error) {
+            console.error("❌ Error during cleanup:", error);
+        }
+    }
+    async close() {
+        await this.cleanup();
+    }
+}

package/dist/config.js

@@ -0,0 +1,20 @@
+/**
+ * Meilisearch MCP Server Configuration
+ *
+ * This file contains the configuration settings for connecting to the Meilisearch server.
+ * Configuration is loaded from environment variables with sensible defaults.
+ */
+/**
+ * Load and initialize configuration from environment variables
+ */
+export const loadConfig = () => {
+    return {
+        host: process.env.MEILISEARCH_HOST || "http://localhost:7700",
+        apiKey: process.env.MEILISEARCH_API_KEY || "",
+        timeout: parseInt(process.env.MEILISEARCH_TIMEOUT || "5000", 10),
+    };
+};
+// Export the config instance
+export const config = loadConfig();
+// Re-export for direct use
+export default config;

package/dist/http.js

@@ -0,0 +1,2 @@
+import { initServer } from "./server.js";
+initServer("http");

package/dist/index.js

@@ -0,0 +1,2 @@
+export { MCPClient } from "./client.js";
+export { initServer } from "./server.js";

package/dist/server.js

@@ -0,0 +1,383 @@
+import { randomUUID } from "node:crypto";
+import { InitializeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import registerTaskTools from "./tools/task-tools.js";
+import registerIndexTools from "./tools/index-tools.js";
+import registerSearchTools from "./tools/search-tools.js";
+import registerSystemTools from "./tools/system-tools.js";
+import registerVectorTools from "./tools/vector-tools.js";
+import registerDocumentTools from "./tools/document-tools.js";
+import registerSettingsTools from "./tools/settings-tools.js";
+import { createErrorResponse } from "./utils/error-handler.js";
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+const DEFAULT_CONFIG = {
+    httpPort: 8080,
+    mcpEndpoint: "/mcp",
+    serverName: "meilisearch",
+    serverVersion: "1.0.0",
+    sessionCleanupInterval: 60000, // 1 minute
+    sessionTimeout: 3600000, // 1 hour
+};
+/**
+ * Implementation of an MCP server for Meilisearch
+ */
+class MCPServer {
+    JSON_RPC = "2.0";
+    SESSION_ID_HEADER_NAME = "mcp-session-id";
+    server;
+    sessions = new Map();
+    toolsRegistered = false;
+    cleanupInterval = null;
+    config;
+    /**
+     * Creates a new MCP server instance
+     * @param server The underlying MCP server implementation
+     * @param config Configuration options
+     */
+    constructor(server, config = {}) {
+        this.server = server;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.toolsRegistered = this.registerTools();
+        // Start session cleanup if using HTTP transport
+        this.startSessionCleanup();
+    }
+    /**
+     * Handles an HTTP GET request
+     * @param req The HTTP request
+     * @param res The HTTP response
+     */
+    async handleGetRequest(req, res) {
+        console.log("GET request received");
+        const sessionId = this.extractSessionId(req);
+        if (!sessionId || !this.sessions.has(sessionId)) {
+            console.error(`Invalid session ID: ${sessionId}`);
+            this.sendErrorResponse(res, 400, "Bad Request: invalid session ID");
+            return;
+        }
+        console.log(`Establishing HTTP stream for session ${sessionId}`);
+        const sessionInfo = this.sessions.get(sessionId);
+        const transport = sessionInfo.transport;
+        try {
+            await transport.handleRequest(req, res);
+            this.updateSessionActivity(sessionId);
+            this.sendNotification(transport, {
+                method: "notifications/message",
+                params: { level: "info", data: "HTTP Connection established" },
+            });
+        }
+        catch (error) {
+            console.error(`Error handling GET request for session ${sessionId}:`, error);
+            this.sendErrorResponse(res, 500, `Internal server error: ${error}`);
+        }
+    }
+    /**
+     * Handles an HTTP POST request (executes MCP commands)
+     * @param req The HTTP request
+     * @param res The HTTP response
+     */
+    async handlePostRequest(req, res) {
+        const sessionId = this.extractSessionId(req);
+        try {
+            // Case 1: Existing session
+            if (sessionId && this.sessions.has(sessionId)) {
+                console.log(`POST request for existing session ${sessionId}`);
+                const sessionInfo = this.sessions.get(sessionId);
+                await sessionInfo.transport.handleRequest(req, res, req.body);
+                this.updateSessionActivity(sessionId);
+                return;
+            }
+            // Case 2: Initialize request
+            if (!sessionId && this.isInitializeRequest(req.body)) {
+                await this.handleInitializeRequest(req, res);
+                return;
+            }
+            // Case 3: Invalid request
+            console.error("Invalid request: missing session ID or not an initialize request");
+            this.sendErrorResponse(res, 400, "Bad Request: invalid session ID or not an initialize request");
+        }
+        catch (error) {
+            console.error("Error handling MCP request:", error);
+            this.sendErrorResponse(res, 500, `Internal server error: ${error}`);
+        }
+    }
+    /**
+     * Clean up and release server resources
+     */
+    shutdown() {
+        console.log("Shutting down MCP server...");
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        // Close all active sessions
+        for (const [sessionId, sessionInfo] of this.sessions.entries()) {
+            try {
+                console.log(`Closing session ${sessionId}`);
+                sessionInfo.transport.close();
+            }
+            catch (error) {
+                console.error(`Error closing session ${sessionId}:`, error);
+            }
+        }
+        this.sessions.clear();
+        console.log("MCP server shutdown complete");
+    }
+    /**
+     * Handles the initial connection request
+     * @param req The HTTP request
+     * @param res The HTTP response
+     */
+    async handleInitializeRequest(req, res) {
+        console.log("Handling initialize request");
+        const newSessionId = randomUUID();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => newSessionId,
+        });
+        transport.sessionId = newSessionId;
+        try {
+            // Connect the transport to the MCP server
+            await this.server.connect(transport);
+            // Set response headers
+            res.setHeader(this.SESSION_ID_HEADER_NAME, newSessionId);
+            res.setHeader("Access-Control-Expose-Headers", this.SESSION_ID_HEADER_NAME);
+            // Handle the initialize request
+            await transport.handleRequest(req, res, req.body);
+            // Register the session
+            this.sessions.set(newSessionId, {
+                transport,
+                lastActivity: Date.now(),
+            });
+            // Notify client about available tools
+            this.sendToolListChangedNotification(transport);
+            console.log(`New session established: ${newSessionId}`);
+        }
+        catch (error) {
+            console.error("Error handling initialize request:", error);
+            transport.close();
+            this.sendErrorResponse(res, 500, `Failed to initialize: ${error}`);
+        }
+    }
+    /**
+     * Registers all available tools with the MCP server
+     */
+    registerTools() {
+        try {
+            console.log("Registering MCP tools...");
+            const tools = [
+                registerSystemTools,
+                registerIndexTools,
+                registerSearchTools,
+                registerSettingsTools,
+                registerDocumentTools,
+                registerTaskTools,
+                registerVectorTools,
+            ];
+            tools.forEach((registerFn) => registerFn(this.server));
+            console.log("Successfully registered all tools");
+            return true;
+        }
+        catch (error) {
+            console.error("Failed to register tools:", error);
+            return false;
+        }
+    }
+    /**
+     * Sends a notification about tool list changes
+     */
+    sendToolListChangedNotification(transport) {
+        const notification = {
+            method: "notifications/tools/list_changed",
+            params: {},
+        };
+        this.sendNotification(transport, notification);
+    }
+    /**
+     * Sends a notification through the transport
+     */
+    async sendNotification(transport, notification) {
+        try {
+            const rpcNotification = {
+                ...notification,
+                jsonrpc: this.JSON_RPC,
+            };
+            await transport.send(rpcNotification);
+            console.log(`Sent notification: ${notification.method}`);
+        }
+        catch (error) {
+            console.error(`Failed to send notification ${notification.method}:`, error);
+        }
+    }
+    /**
+     * Checks if the request body represents an initialize request
+     */
+    isInitializeRequest(body) {
+        const isInitial = (data) => {
+            const result = InitializeRequestSchema.safeParse(data);
+            return result.success;
+        };
+        if (Array.isArray(body)) {
+            return body.some(isInitial);
+        }
+        return isInitial(body);
+    }
+    /**
+     * Extracts session ID from request headers
+     */
+    extractSessionId(req) {
+        return req.headers[this.SESSION_ID_HEADER_NAME.toLowerCase()];
+    }
+    /**
+     * Updates the activity timestamp for a session
+     */
+    updateSessionActivity(sessionId) {
+        const sessionInfo = this.sessions.get(sessionId);
+        if (sessionInfo) {
+            sessionInfo.lastActivity = Date.now();
+        }
+    }
+    /**
+     * Sends an error response with the specified status code and message
+     */
+    sendErrorResponse(res, status, message) {
+        res.status(status).json(createErrorResponse(message));
+    }
+    /**
+     * Starts the session cleanup process
+     */
+    startSessionCleanup() {
+        this.cleanupInterval = setInterval(() => {
+            this.cleanupExpiredSessions();
+        }, this.config.sessionCleanupInterval);
+    }
+    /**
+     * Removes expired sessions
+     */
+    cleanupExpiredSessions() {
+        const now = Date.now();
+        const expiredIds = [];
+        // Find expired sessions
+        for (const [sessionId, info] of this.sessions.entries()) {
+            if (now - info.lastActivity > this.config.sessionTimeout) {
+                expiredIds.push(sessionId);
+            }
+        }
+        // Remove expired sessions
+        if (expiredIds.length > 0) {
+            console.log(`Cleaning up ${expiredIds.length} expired sessions`);
+            for (const sessionId of expiredIds) {
+                try {
+                    const info = this.sessions.get(sessionId);
+                    if (info) {
+                        info.transport.close();
+                    }
+                    this.sessions.delete(sessionId);
+                }
+                catch (error) {
+                    console.error(`Error closing expired session ${sessionId}:`, error);
+                }
+            }
+        }
+    }
+}
+/**
+ * Initialize the MCP server with HTTP transport
+ */
+const initServerHTTPTransport = () => {
+    const config = DEFAULT_CONFIG;
+    const serverInstance = new McpServer({
+        name: config.serverName,
+        version: config.serverVersion,
+    });
+    const server = new MCPServer(serverInstance, config);
+    const app = express();
+    app.use(express.json());
+    // Configure CORS and preflight handling
+    app.use((req, res, next) => {
+        res.header("Access-Control-Allow-Origin", "*");
+        res.header("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+        res.header("Access-Control-Allow-Headers", `Origin, X-Requested-With, Content-Type, Accept, ${server["SESSION_ID_HEADER_NAME"]}`);
+        if (req.method === "OPTIONS") {
+            res.sendStatus(200);
+            return;
+        }
+        next();
+    });
+    // Set up routes
+    const router = express.Router();
+    router.post(config.mcpEndpoint, async (req, res) => {
+        console.log(`Received POST request to ${config.mcpEndpoint}`);
+        await server.handlePostRequest(req, res);
+    });
+    router.get(config.mcpEndpoint, async (req, res) => {
+        console.log(`Received GET request to ${config.mcpEndpoint}`);
+        await server.handleGetRequest(req, res);
+    });
+    app.use("/", router);
+    // Start the server
+    const httpServer = app.listen(config.httpPort, () => {
+        console.log("Meilisearch MCP Server is running on http transport:", `http://localhost:${config.httpPort}${config.mcpEndpoint}`);
+    });
+    // Handle server shutdown
+    process.on("SIGINT", async () => {
+        console.log("Received SIGINT signal");
+        server.shutdown();
+        httpServer.close(() => {
+            console.log("HTTP server closed");
+            process.exit(0);
+        });
+        // Force exit after timeout
+        setTimeout(() => {
+            console.log("Forcing process exit");
+            process.exit(1);
+        }, 5000);
+    });
+};
+/**
+ * Initialize the MCP server with stdio transport
+ */
+const initServerStdioTransport = async () => {
+    const config = DEFAULT_CONFIG;
+    const server = new McpServer({
+        name: config.serverName,
+        version: config.serverVersion,
+    });
+    // Register all tools
+    registerIndexTools(server);
+    registerDocumentTools(server);
+    registerSearchTools(server);
+    registerSettingsTools(server);
+    registerVectorTools(server);
+    registerSystemTools(server);
+    registerTaskTools(server);
+    // Connect stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.log("Meilisearch MCP Server is running on stdio transport");
+    // Handle process termination
+    process.on("SIGINT", () => {
+        console.log("Shutting down stdio server...");
+        process.exit(0);
+    });
+};
+/**
+ * Initialize the MCP server with the specified transport
+ * @param transport The transport type to use ("stdio" or "http")
+ * @throws Error if the transport type is unsupported
+ */
+export const initServer = (transport) => {
+    switch (transport) {
+        case "stdio":
+            initServerStdioTransport().catch((error) => {
+                console.error("Fatal error initializing stdio transport:", error);
+                process.exit(1);
+            });
+            break;
+        case "http":
+            initServerHTTPTransport();
+            break;
+        default:
+            throw new Error(`Unsupported transport type: ${transport}`);
+    }
+};

package/dist/stdio.js

@@ -0,0 +1,2 @@
+import { initServer } from "./server.js";
+initServer("stdio");