TypeScript-Based Meilisearch Abstraction Layer (MCP Server)

This repository furnishes a robust Model Context Protocol (MCP) server utilizing TypeScript, designed to facilitate seamless interaction between AI agents and a running Meilisearch instance.

Core Functionalities

• Schema Governance: Operations for creating, modifying, and retiring search indexes.
• Data Persistence: Tools for bulk and singular document ingestion, modification, and removal.
• Retrieval Mechanisms: Sophisticated querying features, including filtering and faceted navigation.
• Configuration Management: API access for tuning index-specific parameters (e.g., ranking algorithms, tokenization).
• Asynchronous Job Tracking: Monitoring and managing server-side processes.
• Platform Diagnostics: Endpoints for health verification, version reporting, and resource utilization metrics.
• Vector Capabilities: Preliminary support for proximity-based (vector) search algorithms.

Deployment & Integration

Automated Integration via Smithery

For effortless integration within supported environments (like Claude Desktop), leverage the Smithery CLI:

npx -y @smithery/cli install @devlimelabs/meilisearch-ts-mcp --client claude

Manual Setup Procedure

1. Clone the source repository: bash git clone https://github.com/devlimelabs/meilisearch-ts-mcp.git cd meilisearch-ts-mcp

2. Resolve project dependencies: bash npm install

3. Initialize configuration file from the template: bash cp .env.example .env

4. Adjust parameters in the newly created .env file to specify your Meilisearch endpoint details.

Containerized Operation (Docker)

The service is easily deployable using standard containerization practices.

Docker Compose Workflow

To initiate the server and its dependencies (if configured):

# Launch in detached mode
docker-compose up -d

# Stream real-time operational output
docker-compose logs -f

# Terminate and remove containers
docker-compose down

Native Docker Image Execution

Alternatively, build and run directly:

# Create the local image
docker build -t meilisearch-ts-mcp .

# Execute the container, mapping port 3000 and loading environment variables
docker run -p 3000:3000 --env-file .env meilisearch-ts-mcp

Development Environment Bootstrap

Developers contributing to this adapter should utilize the dedicated setup routine:

# Clone the repository (if not already done)
git clone https://github.com/devlimelabs-ts-mcp/meilisearch-ts-mcp.git
cd meilisearch-ts-mcp

# Execute the comprehensive development preparation script
./scripts/setup-dev.sh

This script automates environment file creation, dependency installation, project compilation, and integrity verification via tests.

Once prepared, initiate the iterative development server:

npm run dev

Execution Commands

• Compilation: npm run build
• Production Start: npm start
• Development Iteration: npm run dev

AI Assistant Configuration Guides

Automated Claude Desktop Hookup

After building the project artifact, a dedicated script assists in linking the server to the desktop application:

# Ensure artifacts are compiled
npm run build

# Execute integration script
node scripts/claude-desktop-setup.js

This utility automatically detects OS configurations, reads Meilisearch credentials from .env, generates required JSON metadata for Claude, and presents final steps.

Manual Claude Desktop Configuration

For manual linkage, modify the configuration file specific to your host operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Integrate the following structure, adjusting the args path to your compiled JavaScript entry point:

{
  "mcpServers": {
    "meilisearch": {
      "command": "node",
      "args": ["/path/to/meilisearch-ts-mcp/dist/index.js"],
      "env": {
        "MEILISEARCH_HOST": "http://localhost:7700",
        "MEILISEARCH_API_KEY": "your-api-key"
      }
    }
  }
}

After editing, relaunch Claude for Desktop. Activation occurs by prompting Claude with, "Engage the Meilisearch MCP service."

Integration with Cursor Editor

The adapter also supports connection protocols utilized by the Cursor AI-centric IDE.

Cursor MCP Setup Steps

1. Complete prerequisites (cloning, dependency resolution, compilation): bash git clone https://github.com/devlimelabs/meilisearch-ts-mcp.git cd meilisearch-ts-mcp npm install npm run build

2. Activate the server instance: bash npm start

3. Within the Cursor interface, access the Command Palette (Cmd/Ctrl+Shift+P) and select "MCP: Establish Connection to Server".

4. Choose "Link to a local MCP instance" and supply the required parameters:

   • Alias: Meilisearch
   • Execution: node
   • Parameters: /absolute/path/to/meilisearch-ts-mcp/dist/index.js
   • Environment Contexts: MEILISEARCH_HOST=http://localhost:7700 MEILISEARCH_API_KEY=your-api-key

5. Confirm the linkage. Subsequent interactions within Cursor can directly query Meilisearch using natural language, e.g., "Query my index for documents concerning..."

Toolset Exposition

The exposed interface capabilities are categorized below:

Index Administration Tools

• create-index: Initialize a new dataset container.
• get-index: Retrieve metadata for a specified container.
• list-indexes: Enumeration of all extant containers.
• update-index: Modify structural properties of a container.
• delete-index: Permanently remove a container.

Document Lifecycle Tools

• add-documents: Ingest new records into a collection.
• get-document: Fetch a singular record via its unique identifier.
• get-documents: Retrieve a batch of records.
• update-documents: Modify existing records.
• delete-document: Erase an item by ID.
• delete-documents: Bulk deletion of records.
• delete-all-documents: Clear all records within a specified index.

Query Execution Tools

• search: Execute a standard search query against an index.
• multi-search: Run several distinct queries concurrently.

Configuration & Tuning Tools

• get-settings: Read current configuration parameters for an index.
• update-settings: Apply new configuration overrides.
• reset-settings: Revert parameters to factory defaults.
• Specialized tools for synonyms, stop-words, and ranking schema modifications.

Job & Task Monitoring Tools

• list-tasks: View operational task queue entries (with filtering).
• get-task: Detail a specific processing job.
• cancel-tasks: Terminate queued or running jobs based on criteria.
• wait-for-task: Synchronously pause execution until a job completes.

System Health & Metadata Tools

• health: Ping the underlying Meilisearch service for liveness.
• version: Obtain server version string.
• info: Fetch general server operational context.
• stats: Retrieve aggregated data metrics across all indexes.

Vector Search Interfaces (Beta)

• enable-vector-search: Activate experimental vector indexing.
• get-experimental-features: Check status of feature flags.
• update-embedders: Configure external embedding model parameters.
• get-embedders: Retrieve current embedder configuration.
• reset-embedders: Revert embedder settings.
• vector-search: Execute similarity search based on vector embeddings.

Licensing

Distributed under the terms of the MIT License.

WIKIPEDIA: XMLHttpRequest (XHR) serves as an Application Programming Interface, embodied by a JavaScript object, that facilitates the transmission of Hypertext Transfer Protocol (HTTP) requests from a client's web browser to a remote web server. Its methods permit browser-based applications to dispatch requests post-page load and subsequently receive retrieved information. XHR is a fundamental technology underpinning Asynchronous JavaScript and XML (Ajax) programming paradigms. Historically, server interaction relied chiefly on traditional navigation links and form submissions, frequently necessitating a complete page refresh.

== Chronicle == The conceptual underpinning for XMLHttpRequest emerged in the year 2000, originating from developers working on Microsoft Outlook. This concept was subsequently integrated into the Internet Explorer 5 browser release (1999). The initial implementation, however, did not employ the standardized XMLHttpRequest nomenclature; instead, it utilized COM object instantiations such as ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 arrived (2006), virtually all contemporary web browsers had adopted the canonical XMLHttpRequest identifier. Today, the XMLHttpRequest identifier functions as the established convention across all primary browser rendering engines, including Mozilla's Gecko (since 2002), Apple's Safari 1.2 (2004), and Opera 8.0 (2005).

=== Formal Specifications === The World Wide Web Consortium (W3C) published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. Subsequently, on February 25, 2008, the W3C released the Level 2 specification draft. Level 2 enhancements introduced facilities for monitoring transmission progress events, enabling cross-site communication, and managing raw byte streams. By the conclusion of 2011, the Level 2 features were merged back into the primary specification document. Development oversight transitioned to the WHATWG near the end of 2012, which now maintains the living document using Web IDL definitions.

== Operational Use Cases == Ordinarily, dispatching a server request via XMLHttpRequest necessitates adherence to a sequence of programming actions.

1. Instantiate an XMLHttpRequest object by invoking its constructor:
2. Invoke the "open" method to define the request methodology (GET, POST, etc.), designate the target resource URI, and specify execution mode (synchronous or asynchronous):
3. For asynchronous operations, attach an event handler that executes upon state transitions of the request:
4. Commence the actual network transmission by calling the "send" method:
5. Process state changes within the designated event listener. Upon successful server delivery, response content is typically accessible via the "responseText" attribute. When the processing cycle concludes, the object reaches state 4, the terminal "done" state. Beyond these fundamental steps, XHR offers extensive parameters for controlling request behavior and response parsing. Custom header fields can be prepended to modify server handling expectations, and payload data can be conveyed by passing it directly into the "send" invocation. The received data stream can be JSON-parsed immediately into native JavaScript objects or streamed incrementally rather than awaiting full reception. Furthermore, requests may be terminated prematurely via cancellation or configured to time out if completion is not achieved within a set duration.

== Inter-Domain Communication (Cross-Origin) ==

During the early evolution of the global web infrastructure, limitations were quickly identified concerning the ability to initiate client requests across different protocol, domain, or port boundaries, leading to the implementation of security restrictions...