AI-Powered Index Mediator (AIM-Bridge)

Introduction

This implementation establishes a Model Context Protocol (MCP) server infrastructure. Its primary role is to bridge large language models (LLMs) with the capabilities of the Meilisearch search engine. In essence, it translates complex analytical needs into structured database interactions, mirroring how public search engines process user queries to deliver relevant hyperlinks and summaries from massive datasets.

Key Features

Retained original functionalities are presented here with updated emphasis:

• Multiple Transport Options: It accommodates both synchronous standard input/output (STDIO) and Streamable HTTP communication channels.
• Meilisearch API Support: Comprehensive accessibility to all underlying Meilisearch functions is maintained.
• AI Inference: It utilizes various LLM providers, including OpenAI, HuggingFace, OpenRouter, and Ollama, to intelligently select the appropriate tool for any given request.
• Web Client Demo: A demonstration interface is supplied to visually confirm the system's active search capabilities.

Setup

Before proceeding, ensure the following prerequisites are satisfied for correct operation.

Prerequisites

• Runtime environment requires Node.js version 20 or a subsequent release.
• A functional Meilisearch instance must be operational, either locally hosted or externally accessible.
• If authentication is enforced, an active API key for the Meilisearch service is necessary.
• For any AI inference involving external services, the corresponding provider's API key is required.

Installation

Install the necessary package using your preferred package manager:

# Using npm
npm install mcp-meilisearch

# Using yarn
yarn add mcp-meilisearch

# Using pnpm
pnpm add mcp-meilisearch

Configuration

Several parameters govern how the mediator connects to Meilisearch and how the AI reasoning component operates.

Meilisearch Connection Options

• meilisearchHost: Specifies the URL for the Meilisearch instance (Default value is "http://localhost:7700").
• meilisearchApiKey: The required access credential for Meilisearch authorization (Default is an empty string).

MCP Server Options

• transport: Defines the communication protocol to be used ("http" or "stdio") (Default is "http").
• httpPort: Designates the network port for the HTTP interface (Default is 4995).
• mcpEndpoint: The designated path segment for the MCP interface (Default is "/mcp").

Session Options

• sessionTimeout: Duration, in milliseconds, before an inactive session is terminated (Default is 3600000).
• sessionCleanupInterval: How often the system checks for and removes expired sessions, measured in milliseconds (Default is 60000).

AI Inference Options

• aiProviderName: Identifies the external AI service being utilized ("openai", "huggingface", "openrouter", or "ollama") (Default is "openai").
• aiProviderApiKey: The security token necessary to authenticate with the chosen AI service provider.
• llmModel: The specific artificial intelligence model designated for reasoning tasks (Default is "gpt-3.5-turbo").

It is important to confirm that the selected AI model supports the required function-calling mechanism for effective tool utilization. Please verify that your chosen model accepts the 'tools' parameter during the inference request.

Provider	Supported Models
OpenAI	List of supported models
OpenRouter	List of supported models
HuggingFace	List of supported models
Ollama	List of supported models

Example server setup

To initiate the server with specific settings, use the following structure, ensuring the LLM supports tool invocation:

await mcpMeilisearchServer({
  meilisearchHost: "http://localhost:7700",
  aiProviderName: "openrouter",
  aiProviderApiKey: "your_openrouter_api_key",
  llmModel: "anthropic/claude-3-opus", // Verify support for function calling
});

Integration

The package exposes the MCPClient class, which facilitates integration from the consumer's perspective.

import { MCPClient } from "mcp-meilisearch/client";

const client = new MCPClient("mcp-meilisearch-client");

await client.connectToServer("http://localhost:4995/mcp");

const result = await client.callTool("global-search", {
  q: "search kiosco antonio",
});

Client Methods

callTool(name, args)

This method invokes a specific defined tool on the server, optionally supplying parameters.

Parameters:

• name: Textual identifier for the desired server tool.
• args: A data object containing any necessary arguments for the tool execution.

processSummary(query)

This function submits data to the AI component for the generation of a concise, human-readable summary.

Parameters:

• query: The input data set requiring summarization.

callToolWithAI(query, options)

This executes the full intelligent workflow: the AI interprets the string query, decides which tool to use, and executes it.

Parameters:

• query: The user's natural language request for processing.
• options: Supplementary configuration settings.
• specificTools: An array limiting the AI's tool selection capability to these names.
• justReasoning: If set to true, only the AI's decision process is returned, execution is skipped.
• provideSummary: If true, a summary of the retrieved search findings is generated alongside the main output.

Starting the Server

Programmatic server initiation uses the following structure:

import mcpMeilisearchServer from "mcp-meilisearch";

await mcpMeilisearchServer({
  meilisearchHost: "http://localhost:7700",
  meilisearchApiKey: "your_meilisearch_api_key",
  aiProviderName: "openai",
  aiProviderApiKey: "your_ai_provider_api_key",
  llmModel: "gpt-4",
});

Tools

The server exposes numerous functions, each corresponding to a Meilisearch endpoint. These tools facilitate searching, indexing configuration, and document management.

Tool Categories

1. System Tools: For health status, version checks, and statistical reports.
2. Index Tools: Operations related to index lifecycle management (creation, deletion, listing).
3. Document Tools: Functions for adding, modifying, deleting, and retrieving individual data entries.
4. Search Tools: Advanced querying capabilities, including those utilizing vector embedding searches.
5. Settings Tools: Configuration management for index parameters.
6. Task Tools: Oversight and control over asynchronous server operations.
7. Vector Tools: Features focused on experimental similarity search using vector representations.

System Tools

health

• Description: Verifies the operational status of the connected Meilisearch instance.

version

• Description: Retrieves the current software version details of the Meilisearch engine.

info

• Description: Fetches generalized system information pertaining to the Meilisearch deployment.

stats

• Description: Obtains performance metrics either for all indexes or a specified one.
• Parameters:
• indexUid (string, optional): The unique identifier of the index whose statistics are requested.

get-tasks

• Description: Retrieves a record of recent processing tasks, allowing for filtering.
• Parameters:
• limit (number, optional): Maximum number of recorded tasks to fetch.
• from (number, optional): The starting point UID for the task list retrieval.
• status (string, optional): Filter results based on task completion status.
• type (string, optional): Filter results based on the operation type performed.
• indexUids (string[], optional): Limit results to tasks affecting these specific indexes.

delete-tasks

• Description: Permanently removes specific tasks from the log based on defined criteria.
• Parameters:
• statuses (string[], optional): Specifies which task statuses are targeted for deletion.
• types (string[], optional): Specifies which operation types are targeted for deletion.
• indexUids (string[], optional): Targets tasks associated with these indexes for removal.
• uids (number[], optional): An explicit list of task UIDs to be deleted.
• canceledBy (number[], optional): UIDs of the processes that initiated the cancellation of tasks.
• beforeUid (number, optional): Deletes all tasks whose UID precedes this number.
• beforeStartedAt (string, optional): Deletes tasks that began processing before the provided ISO 8601 timestamp.
• beforeFinishedAt (string, optional): Deletes tasks that completed execution before the provided ISO 8601 timestamp.

Index Tools

list-indexes

• Description: Generates a list of all existing indexes within the current Meilisearch database.
• Parameters:
• limit (number, optional): Sets the maximum count of indexes returned in the result set.
• offset (number, optional): Skips a specified initial number of indexes during retrieval.

get-index

• Description: Retrieves the detailed metadata for a single, identified index.
• Parameters:
• indexUid (string, required): The unique name identifying the index.

create-index

• Description: Provisions a brand new index within the search system.
• Parameters:
• indexUid (string, required): The unique identifier assigned to the new index.
• primaryKey (string, optional): Designates the field that will serve as the primary key for document identification.

update-index

• Description: Modifies properties of an existing index; currently supports primary key adjustments.
• Parameters:
• indexUid (string, required): The identifier of the index requiring modification.
• primaryKey (string, required): The new designation for the index's primary key.

delete-index

• Description: Permanently removes an index and all its contained documents.
• Parameters:
• indexUid (string, required): The name of the index slated for deletion.

swap-indexes

• Description: Atomically exchanges the data between two or more specified indexes.
• Parameters:
• indexes (string, required): A JSON array detailing the pairs to swap, structured like [["old_name", "new_name"]].

Document Tools

get-documents

• Description: Fetches records from a specified index, supporting retrieval constraints.
• Parameters:
• indexUid (string, required): The target index identifier.
• limit (number, optional): Maximum count of documents to return (defaults to 20).
• offset (number, optional): Number of initial documents to skip (defaults to 0).
• fields (string[], optional): A list specifying which fields must be included in the response documents.
• filter (string, optional): A query string applied to restrict which documents are returned.

get-document

• Description: Retrieves a single document using its unique ID within an index.
• Parameters:
• indexUid (string, required): The index housing the document.
• documentId (string, required): The specific identifier for the document record.
• fields (string[], optional): Which fields should be extracted and shown for that document.

add-documents

• Description: Inserts new data entries into the designated index.
• Parameters:
• indexUid (string, required): The index where documents will be added.
• documents (string, required): A serialized JSON array containing the new documents.
• primaryKey (string, optional): Overrides or sets the primary key specifically for this batch.

update-documents

• Description: Merges changes into existing documents within an index; new fields are added, existing ones are modified.
• Parameters:
• indexUid (string, required): The target index identifier.
• documents (string, required): A JSON array of documents containing updated information.
• primaryKey (string, optional): The key used to match documents for updating.

delete-document

• Description: Removes one specific document from an index based on its ID.
• Parameters:
• indexUid (string, required): The index containing the document.
• documentId (string, required): The ID of the document slated for removal.

delete-documents

• Description: Executes batch removal of multiple documents identified by their IDs.
• Parameters:
• indexUid (string, required): The index from which documents are being deleted.
• documentIds (string, required): A JSON array listing the IDs of all documents to remove.

delete-all-documents

• Description: Clears every single document from the specified index.
• Parameters:
• indexUid (string, required): The index that will be completely emptied.

Search Tools

search

• Description: Executes a standard text query against an index, returning ranked results.
• Parameters:
• indexUid (string, required): The index being searched.
• q (string, required): The specific search term entered by the user.
• limit (number, optional): Maximum number of results to be returned (defaults to 20).
• offset (number, optional): How many initial results to skip (defaults to 0).
• filter (string, optional): Criteria used to narrow down the document pool before ranking.
• sort (string[], optional): Specifies the order of results using attribute names, e.g., ["price:asc"].
• facets (string[], optional): Lists attributes for which facet counts should be calculated.
• attributesToRetrieve (string[], optional): Limits the fields returned in the matching documents.
• attributesToCrop (string[], optional): Attributes whose content will be truncated for brevity.
• cropLength (number, optional): The maximum length permitted for cropped attribute content.
• attributesToHighlight (string[], optional): Attributes where matching text sections will be specially marked.
• highlightPreTag (string, optional): The marker placed immediately before highlighted text snippets.
• highlightPostTag (string, optional): The marker placed immediately following highlighted text snippets.
• showMatchesPosition (boolean, optional): Instructs the engine to include positional data regarding text matches.
• matchingStrategy (string, optional): Determines if all terms must match ('all') or just the last one ('last').

multi-search

• Description: Allows the concurrent execution of several distinct search operations within a single network request.
• Parameters:
• queries (string, required): A JSON array where each element duplicates the parameter structure of the search tool.

global-search

• Description: Executes a term search across every accessible index, combining the outputs into a unified result set.
• Parameters:
• q (string, required): The term being sought across all indexes.
• limit (number, optional): The maximum number of matches to return from each individual index (default is 20).
• attributesToRetrieve (string[], optional): Which fields should be included from the results originating from any index.

facet-search

• Description: Retrieves potential values for a specified facet field, optionally filtering the base search.
• Parameters:
• indexUid (string, required): The index scope for the facet value lookup.
• facetName (string, required): The field name whose distinct values are being investigated.
• facetQuery (string, optional): A substring used to match against the known facet values.
• filter (string, optional): A filter applied before calculating the facet values.

Settings Tools

get-settings

• Description: Retrieves the complete configuration schema currently applied to a specific index.
• Parameters:
• indexUid (string, required): The identifier for the index whose settings are requested.

update-settings

• Description: Applies a new configuration object to update various index parameters simultaneously.
• Parameters:
• indexUid (string, required): The index being reconfigured.
• settings (string, required): A JSON representation of the settings structure to be applied.

reset-settings

• Description: Reverts all configuration parameters for an index back to their factory default states.
• Parameters:
• indexUid (string, required): The index whose settings are to be reset.

Get Settings Tools

The following tools allow granular reading of individual index configurations. They are essential for understanding the current state of fine-tuning.

• get-displayed-attributes
• get-searchable-attributes
• get-filterable-attributes
• get-sortable-attributes
• get-ranking-rules
• get-stop-words
• get-synonyms
• get-typo-tolerance
• get-pagination
• get-faceting
• get-dictionary
• get-proximity-precision
• get-separator-tokens
• get-non-separator-tokens
• get-word-dictionary

All these retrieval operations share a single mandatory parameter:

• indexUid (string, required): The unique identifier of the index in question.

Update Settings Tools

These functions enable precise modification of single configuration elements within an index. This fine-grained control is crucial for optimizing search quality.

• update-displayed-attributes

• indexUid (string, required): Target index identifier.

• displayedAttributes (string, required): JSON array listing fields that should appear in results, e.g., ["title", "description"].

• update-searchable-attributes

• indexUid (string, required): Target index identifier.

• searchableAttributes (string, required): JSON array specifying fields eligible for textual searching, e.g., ["title", "description"].

• update-filterable-attributes

• indexUid (string, required): Target index identifier.

• filterableAttributes (string, required): JSON array detailing fields usable within filter expressions, e.g., ["genre", "director"].

• update-sortable-attributes

• indexUid (string, required): Target index identifier.

• sortableAttributes (string, required): JSON array listing attributes allowed for result ordering, e.g., ["price", "date"].

• update-ranking-rules

• indexUid (string, required): Target index identifier.

• rankingRules (string, required): JSON array defining the sequence of ranking criteria, e.g., ["typo", "words", "proximity", "attribute", "sort", "exactness"].

• update-stop-words

• indexUid (string, required): Target index identifier.

• stopWords (string, required): JSON array of common, insignificant words to ignore during queries, e.g., ["the", "a", "an"].

• update-synonyms

• indexUid (string, required): Target index identifier.

• synonyms (string, required): A JSON map linking terms to their alternative synonyms, e.g., {"movie": ["film"]}.

• update-typo-tolerance

• indexUid (string, required): Target index identifier.

• typoTolerance (string, required): JSON object specifying tolerance settings, e.g., {"enabled": true, "minWordSizeForTypos": {"oneTypo": 5, "twoTypos": 9}}.

• update-pagination

• indexUid (string, required): Target index identifier.

• pagination (string, required): JSON object controlling result limits, e.g., {"maxTotalHits": 1000}.

• update-faceting

• indexUid (string, required): Target index identifier.

• faceting (string, required): JSON object setting limits for facet calculations, e.g., {"maxValuesPerFacet": 100}.

• update-dictionary

• indexUid (string, required): Target index identifier.

• dictionary (string, required): JSON array of phrases treated as single search units, e.g., ["San Francisco", "New York"].

• update-proximity-precision

• indexUid (string, required): Target index identifier.

• proximityPrecision (string, required): A setting string to define proximity calculation granularity, either 'byWord' or 'byAttribute'.

• update-separator-tokens

• indexUid (string, required): Target index identifier.

• separatorTokens (string, required): JSON array of characters considered word separators, e.g., ["-", "_"].

• update-non-separator-tokens

• indexUid (string, required): Target index identifier.

• nonSeparatorTokens (string, required): JSON array of characters explicitly treated as non-separators, e.g., ["@", "."].

• update-word-dictionary

• indexUid (string, required): Target index identifier.
• wordDictionary (string, required): JSON array of custom terms to integrate into the engine's base vocabulary, e.g., ["cbuilder", "meilisearch"].

Reset Settings Tools

These functions revert specific configuration values for an index back to their system defaults. Each tool requires only the index UID.

• reset-displayed-attributes
• reset-searchable-attributes
• reset-filterable-attributes
• reset-sortable-attributes
• reset-ranking-rules
• reset-stop-words
• reset-synonyms
• reset-typo-tolerance
• reset-pagination
• reset-faceting
• reset-dictionary
• reset-proximity-precision
• reset-separator-tokens
• reset-non-separator-tokens
• reset-word-dictionary

All these reset operations share the same required parameter:

• indexUid (string, required): The unique identifier of the index undergoing the reset.

Task Tools

list-tasks

• Description: Provides a comprehensive record of ongoing and historical processing actions, allowing for filtering.
• Parameters:
• limit (number, optional): The maximum number of tasks to display in the log.
• from (number, optional): The starting point UID when fetching the logs.
• statuses (string[], optional): Filters the list based on the current task status.
• types (string[], optional): Filters the list based on the type of operation performed.
• indexUids (string[], optional): Restricts the view to tasks affecting these specific indexes.
• uids (number[], optional): Retrieves only the tasks matching this exact list of UIDs.

get-task

• Description: Fetches the specific status and details for a single task identified by its UID.
• Parameters:
• taskUid (number, required): The unique numeric identifier for the task being queried.

cancel-tasks

• Description: Attempts to halt the execution of running or queued tasks based on specified criteria.
• Parameters:
• statuses (string[], optional): Targets tasks matching these statuses for cancellation.
• types (string[], optional): Targets tasks matching these operation types for cancellation.
• indexUids (string[], optional): Targets tasks associated with these indexes for cancellation.
• uids (number[], optional): An explicit list of task UIDs to be canceled.

wait-for-task

• Description: Pauses execution until a designated task reaches a terminal state or a timeout occurs.
• Parameters:
• taskUid (number, required): The identifier of the task to monitor.
• timeoutMs (number, optional): The maximum wait time allowed, in milliseconds (default is 5000).
• intervalMs (number, optional): The frequency, in milliseconds, at which the task status is checked (default is 500).

Vector Tools

These tools interface with Meilisearch's experimental capabilities for semantic similarity searching.

enable-vector-search

• Description: Activates the experimental vector search functionality within the Meilisearch environment.

get-experimental-features

• Description: Reports the current activation status of various experimental features.

update-embedders

• Description: Configures the specific embedding models the system should utilize for vector transformation.
• Parameters:
• indexUid (string, required): The index where the embedder configuration will be stored.
• embedders (string, required): A JSON object defining the configurations for the chosen embedders.

get-embedders

• Description: Retrieves the currently defined configuration for vector embedders on a given index.
• Parameters:
• indexUid (string, required): The index whose embedder settings are being inspected.

reset-embedders

• Description: Erases custom embedder configurations, reverting them to default or disabling them.
• Parameters:
• indexUid (string, required): The index from which to clear the embedder setup.

vector-search

• Description: Executes a similarity search, either pure vector matching or a combination of vector and keyword search.
• Parameters:
• indexUid (string, required): The index involved in the vector matching operation.
• vector (string, required): The numeric vector array used for similarity comparison.
• limit (number, optional): The maximum number of nearest neighbors to retrieve (defaults to 20).
• offset (number, optional): The number of initial vector results to skip (defaults to 0).
• filter (string, optional): Standard query filters applied to the vector search results, e.g., 'genre = horror AND year > 2020'.
• embedder (string, optional): The named embedder configuration to use; required if vector is omitted in favor of query.
• attributes (string[], optional): Specifies which document fields should be analyzed during the vector comparison.
• query (string, optional): A traditional text query used when an embedder is specified instead of providing a raw vector.
• hybrid (boolean, optional): If true, a mix of text relevance and vector similarity is used for ranking.
• hybridRatio (number, optional): Controls the weighting between text and vector relevance in a hybrid search (ranges from 0.0 to 1.0, default 0.5).

Related Topics

• Distributed Computing Systems
• Information Retrieval Algorithms
• Semantic Search
• Web Crawling and Indexing
• Natural Language Processing (NLP)

Extra Details

This tool's core value lies in abstracting the intricacies of real-time index management, offering LLMs a consistent interface. Unlike many public search engines where visibility heavily depends on optimizing for one dominant provider, this system provides direct, structured access to the underlying search capabilities. This allows applications to perform highly specific data lookups and configurations previously requiring dedicated administrative tooling. The ability to manage settings like typo tolerance and synonym lists directly impacts search accuracy, much like how a well-maintained index improves response relevance in global web searches.

Conclusion

By wrapping Meilisearch operations within the Model Context Protocol, this server allows intelligent agents to interact with structured data retrieval effectively. This capability enables automated systems to fulfill complex information needs by dynamically selecting the appropriate indexing or search tool, providing accurate, contextualized results similar to the targeted delivery of information expected from modern web search platforms.