Merge branch 'main' into mintlify-iso

Author: guimachiavelli

.code-samples.meilisearch.yaml

@@ -1423,6 +1423,39 @@ search_parameter_reference_retrieve_vectors_1: |-
         "embedder": "EMBEDDER_NAME"
       }
     }'
+related_results_embedder_1: |-
+  curl -X PATCH 'MEILISEARCH_URL/indexes/movies/settings' 
+    -H 'Content-Type: application/json' 
+    -H 'Authorization: Bearer MEILISEARCH_API_KEY' 
+    --data-binary '{
+      "embedders": {
+        "movies-text": {
+          "source": "openAi",
+          "apiKey": "OPENAI_API_KEY",
+          "model": "text-embedding-3-small",
+          "documentTemplate": "A movie titled '{{doc.title}}' released in {{ doc.release_date }}. The movie genres are: {{doc.genres}}. The story is about: {{doc.overview|truncatewords: 20}}"
+        }
+      }
+    }'
+related_results_search_1: |-
+  curl -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/search' \
+    -H 'content-type: application/json' \
+    -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
+    --data-binary '{
+      "q": "batman",
+      "hybrid": {
+        "embedder": "EMBEDDER_NAME"
+      }
+    }'
+related_results_similar_1: |-
+  curl \
+    -X POST 'MEILISEARCH_URL/indexes/movies/similar' \
+    -H 'Content-Type: application/json' \
+    -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
+    --data-binary '{
+      "id": 192,
+      "embedder": "EMBEDDER_NAME"
+    }'
 
 ### Code samples for experimental features
 experimental_get_metrics_1: |-

.github/workflows/code-sample-automation.yml

@@ -0,0 +1,16 @@
+name: Add PR to Code Samples Changes project
+
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize]
+    paths:
+      - '.code-samples.meilisearch.yaml'
+
+jobs:
+  add-pr-to-project:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/add-to-project@280af8ae1f83a494cfad2cb10f02f6d13529caa9
+        with:
+          project-url: https://github.com/orgs/meilisearch/projects/44
+          github-token: ${{ secrets.GH_TOKEN }}

assets/images/similar-guide/01-add-embedder-ui.gif

@@ -55,6 +55,11 @@
     "title": "Artificial Intelligence",
     "slug": "ai",
     "routes": [
+      {
+        "source": "guides/ai/mcp.mdx",
+        "label": "Model Context Protocol - Talk to Meilisearch with Claude desktop",
+        "slug": "mcp"
+      },
       {
         "source": "guides/embedders/openai.mdx",
         "label": "Semantic search with OpenAI embeddings",

config/sidebar-guides.json

@@ -44,11 +44,6 @@
         "label": "Getting started with AI-powered search",
         "slug": "getting_started_with_ai_search"
       },
-      {
-        "source": "learn/ai_powered_search/search_with_user_provided_embeddings.mdx",
-        "label": "Use AI-powered search with user-provided embeddings",
-        "slug": "search_with_user_provided_embeddings"
-      },
       {
         "source": "learn/ai_powered_search/configure_rest_embedder.mdx",
         "label": "Configure a REST embedder",
@@ -59,16 +54,26 @@
         "label": "Document template best practices",
         "slug": "document_template_best_practices"
       },
-      {
-        "source": "learn/ai_powered_search/choose_an_embedder.mdx",
-        "label": "Which embedder should I choose?",
-        "slug": "choose_an_embedder"
-      },
       {
         "source": "learn/ai_powered_search/image_search_with_user_provided_embeddings.mdx",
         "label": "Image search with user-provided embeddings",
         "slug": "image_search_with_user_provided_embeddings"
       },
+      {
+        "source": "learn/ai_powered_search/search_with_user_provided_embeddings.mdx",
+        "label": "Use AI-powered search with user-provided embeddings",
+        "slug": "search_with_user_provided_embeddings"
+      },
+      {
+        "source": "learn/ai_powered_search/retrieve_related_search_results.mdx",
+        "label": "Retrieve related search results",
+        "slug": "retrieve_related_search_results"
+      },
+      {
+        "source": "learn/ai_powered_search/choose_an_embedder.mdx",
+        "label": "Which embedder should I choose?",
+        "slug": "choose_an_embedder"
+      },
       {
         "source": "learn/ai_powered_search/difference_full_text_ai_search.mdx",
         "label": "Differences between full-text and AI-powered search",

config/sidebar-learn.json

@@ -0,0 +1,197 @@
+---
+title: Meilisearch & Model Context Protocol - Talk to Meilisearch with Claude desktop
+description: This guide walks Meilisearch users through setting up the MCP server with Claude desktop to talk to the Meilisearch API
+---
+
+# Model Context Protocol - Talk to Meilisearch with Claude desktop
+
+## Introduction
+
+This guide will walk you through setting up and using Meilisearch through natural language interactions with Claude AI via Model Context Protocol (MCP).
+
+## Requirements
+
+To follow this guide, you'll need:
+
+- [Claude Desktop](https://claude.ai/download) (free)
+- [A Meilisearch Cloud project](https://www.meilisearch.com/cloud) (14 days free-trial)
+- Python ≥ 3.9
+- From the Meilisearch Cloud dashboard, your Meilisearch host & api key
+
+## Setting up Claude Desktop with the Meilisearch MCP Server
+
+### 1. Install Claude Desktop
+
+Download and install [Claude Desktop](https://claude.ai/download).
+
+### 2. Install the Meilisearch MCP Server
+
+You can install the Meilisearch MCP server using `uv` or `pip`:
+
+```bash
+# Using uv (recommended)
+uv pip install meilisearch-mcp
+
+# Using pip
+pip install meilisearch-mcp
+```
+
+### 3. Configure Claude Desktop
+
+Open Claude Desktop, click on the Claude menu in the top bar, and select "Settings". In the Settings window, click on "Developer" in the left sidebar, then click "Edit Config". This will open your `claude_desktop_config.json` file.
+
+Add the Meilisearch MCP server to your configuration:
+
+```json
+{
+  "mcpServers": {
+    "meilisearch": {
+      "command": "uvx",
+      "args": ["-n", "meilisearch-mcp"]
+    }
+  }
+```
+
+Save the file and restart Claude.
+
+## Connecting to Your Meilisearch Instance
+
+Once Claude Desktop is set up with the Meilisearch MCP server, you can connect to your Meilisearch instance by asking Claude to update the connection settings.
+
+Open Claude Desktop and start a new conversation.
+
+Next, connect to your Meilisearch instance by asking Claude to update the connection settings, replacing `MEILISEARCH_URL` with your project URL and `API_KEY` with your project's API key:
+
+```
+Please connect to my Meilisearch instance at MEILISEARCH_URL using the API key API_KEY
+```
+
+Claude will use the MCP server's `update-connection-settings` tool to establish a connection to your Meilisearch instance.
+
+Finally, verify the connection by asking:
+
+```
+Can you check the connection to my Meilisearch instance and tell me what version it's running?
+```
+
+Claude will use the `get-version` and `health-check` tools to verify the connection and provide information about your instance.
+
+
+## Create an e-commerce index
+
+Now you have configured the MCP to work with Meilisearch, you can use it to manage your indexes.
+
+First, verify what indexes you have in your project:
+
+```
+What indexes do I have in my Meilisearch instance?
+```
+
+Next, ask Claude to create an index optimized for e-commerce:
+
+```
+Create a new index called "products" for our e-commerce site with the primary key "product_id"
+```
+
+Finally, check the index has been created successfully and is completely empty:
+
+```
+How many documents are in my "products" index and what's its size?
+```
+
+## Add documents to your new index
+
+Ask Calude to add a couple of test documents to your "products" index:
+
+```
+Add these products to my "products" index:
+[
+  {"product_id": 1, "name": "Ergonomic Chair", "description": "Comfortable office chair", "price": 299.99, "category": "Furniture"},
+  {"product_id": 2, "name": "Standing Desk", "description": "Adjustable height desk", "price": 499.99, "category": "Furniture"}
+]
+```
+
+Since you are only using "products" for testing, you can also ask Claude to automatically populate it with placeholder data:
+
+```
+Add 10 documents in the index "products" with a name, category, price, and description of your choice
+```
+
+To verify data insertion worked as expected, retrieve the first few documents in your index:
+
+```
+Show me the first 5 products in my "products" index
+```
+
+## Configure your index
+
+Before performing your first search, set a few index settings to ensure relevant results.
+
+Ask Claude to prioritize exact word matches over multiple partial matches:
+
+```
+Update the ranking rules for the "products" index to prioritize word matches and handle typos, but make exact matches more important than proximity
+```
+
+It's also a good practice to limit searchable attributes only to highly-relevant fields, and only return attributes you are going to display in your search interface:
+
+```
+Configure my "products" index to make the "name" and "description" fields searchable, but only "name", "price", and "category" should be displayed in results
+```
+
+## Perform searches with MCP
+
+Perform your first search with the following prompt:
+
+```
+Search the "products" index for "desk" and return the top 3 results
+```
+
+You can also request your search uses other Meilisearch features such as filters and sorting:
+
+```
+Search the "products" index for "chair" where the price is less than 200 and the category is "Furniture". Sort results by price in ascending order.
+```
+
+<Capsule intent="warning" title="Important note about LLM limitation">
+Large Language Models like Claude tend to say "yes" to most requests, even if they can't actually perform them. 
+
+Claude can only perform actions that are exposed through the Meilisearch API and implemented in the MCP server. If you're unsure whether a particular operation is possible, refer to the [Meilisearch documentation](https://docs.meilisearch.com) and the [MCP server README](https://github.com/meilisearch/meilisearch-mcp).
+</Capsule>
+
+## Troubleshooting
+
+If you encounter issues with the Meilisearch MCP integration, try these steps
+
+### 1. Ask Claude to verify your connection settings
+
+```
+What are the current Meilisearch connection settings?
+```
+
+### 2. Ask Claude to check your Meilisearch instance health
+
+```
+Run a health check on my Meilisearch instance
+```
+
+### 3. Review Claude's logs
+
+Open the logs file in your text editor or log viewer:
+
+- On macOS: `~/Library/Logs/Claude/mcp*.log`
+- On Windows: `%APPDATA%\Claude\logs\mcp*.log`
+
+### 4. Test the MCP server independently
+
+Open your terminal and query the MCP Inspector with `npx`:
+
+```bash
+npx @modelcontextprotocol/inspector uvx -n meilisearch-mcp
+```
+
+## Conclusion
+
+The Meilisearch MCP integration with Claude can transform multiple API calls and configuration tasks into conversational requests. This can help you focus more on building your application and less on implementation details.
+
+For more information about advanced configurations and capabilities, refer to the [Meilisearch documentation](https://docs.meilisearch.com) and the [Meilisearch MCP server repository](https://github.com/meilisearch/meilisearch-mcp).

guides/ai/mcp.mdx

@@ -0,0 +1,68 @@
+---
+title: Retrieve related search results
+description: This guide shows you how to use the similar documents endpoint to create an AI-powered movie recommendation workflow.
+---
+
+# Retrieve related search results
+
+This guide shows you how to use the [similar documents endpoint](/reference/api/similar) to create an AI-powered movie recommendation workflow.
+
+First, you will create an embedder and add documents to your index. You will then perform a search, and use the top result's primary key to retrieve similar movies in your database.
+
+## Prerequisites
+
+- A running Meilisearch project
+- A [tier >=2](https://platform.openai.com/docs/guides/rate-limits#usage-tiers) OpenAI API key  
+
+## Create a new index
+
+Create an index called `movies` and add this <ButtonLink as="a" id="downloadMovie" href="/movies.json" download="movies.json">`movies.json`</ButtonLink> dataset to it. If necessary, consult the [getting started](/learn/getting_started/cloud_quick_start) for more instructions on index creation.
+
+Each document in the dataset represents a single movie and has the following structure:
+
+- `id`: a unique identifier for each document in the database
+- `title`: the title of the movie
+- `overview`: a brief summary of the movie's plot
+- `genres`: an array of genres associated with the movie
+- `poster`: a URL to the movie's poster image
+- `release_date`: the release date of the movie, represented as a Unix timestamp
+
+## Configure an embedder
+
+Next, use the Cloud UI to configure an OpenAI embedder:
+
+![Animated image of the Meilisearch Cloud UI showing a user clicking on "add embedder". This opens up a modal window, where the user fills in the name of the embedder, chooses OpenAI as its source. They then select a model, input their API key, and type out a document template.](/assets/images/similar-guide/01-add-embedder-ui.gif)
+
+You may also use the `/settings/embedders` API subroute to configure your embedder:
+
+<CodeSamples id="related_results_embedder_1" />
+
+Replace `MEILISEARCH_URL`, `MEILISEARCH_API_KEY`, and `OPENAI_API_KEY` with the corresponding values in your application.
+
+Meilisearch will start generating the embeddings for all movies in your dataset. Use the returned `taskUid` to [track the progress of this task](/learn/async/asynchronous_operations). Once it is finished, you are ready to start searching.
+
+## Perform a hybrid search
+
+With your documents added and all embeddings generated, you can perform a search:
+
+<CodeSamples id="related_results_search_1" />
+
+This request returns a list of movies. Pick the top result and take note of its primary key in the `id` field. In this case, it's the movie "Batman" with `id` 192.
+
+## Return similar documents
+
+Pass "Batman"'s `id` to your index's [`/similar` route](/reference/api/similar), specifying `movies-text` as your embedder:
+
+<CodeSamples id="related_results_similar_1" />
+
+Meilisearch will return a list of the 20 documents most similar to the movie you chose. You may then choose to display some of these similar results to your users, pointing them to other movies that may also interest them.
+
+## Conclusion
+
+Congratulations! You have successfully built an AI-powered movie search and recommendation system using Meilisearch by:
+
+- Setting up a Meilisearch project and configured it for AI-powered search
+- Implementing hybrid search combining keyword and semantic search capabilities
+- Integrating Meilisearch's similarity search for movie recommendations
+
+In a real-life application, you would now start integrating this workflow into a front end, like the one in this [official Meilisearch blog post](https://www.meilisearch.com/blog/add-ai-powered-search-to-react).

learn/ai_powered_search/retrieve_related_search_results.mdx

@@ -8,7 +8,7 @@ In most datasets, some fields are more relevant to search than others. A `title`
 
 When `searchableAttributes` is using its default value, `[*]`, all fields carry the same weight.
 
-If you manually configure [the searchable attributes list](/learn/relevancy/displayed_searchable_attributes#the-searchableattributes-list), attributes that appear early in the array are more important when claculating search result relevancy.
+If you manually configure [the searchable attributes list](/learn/relevancy/displayed_searchable_attributes#the-searchableattributes-list), attributes that appear early in the array are more important when calculating search result relevancy.
 
 ## Example
 

learn/relevancy/attribute_ranking_order.mdx

@@ -325,7 +325,7 @@ Meilisearch currently supports five log levels, listed in order of increasing ve
 
 <Note>Experimental feature</Note>
 
-**Environment variable**: `MEILI_LOGS_MODE`<br />
+**Environment variable**: `MEILI_EXPERIMENTAL_LOGS_MODE`<br />
 **CLI option**: `--experimental-logs-mode`<br />
 **Default value**: `'human'`<br />
 **Expected value**: one of `human` or `json`