mcp-meilisearch

MCP Meilisearch API 서버

AI 모델과 Meilisearch 검색 엔진 간의 브리지 역할을 하는 MCP(Model Context Protocol) 서버 구현입니다.

개요

• MCP 서버 : 모델 컨텍스트 프로토콜을 사용하여 Meilisearch API를 도구로 노출합니다.
• 웹 클라이언트 데모 : 검색 기능을 보여주는 데모 인터페이스입니다.
• AI 추론 : 사용자 질의에 따른 지능형 도구 선택.

주요 특징

• 다양한 전송 옵션 : STDIO 및 StreamableHTTP 전송을 모두 지원합니다.
• Meilisearch API 지원 : Meilisearch 기능에 대한 전체 액세스.
• 웹 클라이언트 데모 : 검색 기능과 특징을 보여주는 업데이트된 인터페이스입니다.
• AI 추론 : OpenAI, HuggingFace와 같은 공급업체의 LLM을 활용하여 사용자 질의에 가장 적합한 도구를 지능적으로 판단하고 활용합니다.

시작하기

필수 조건

• Node.js v20 이상.
• 실행 중인 Meilisearch 인스턴스(로컬 또는 원격).
• Meilisearch의 API 키(필요한 경우).
• AI 공급자 API 키(AI 추론을 사용하는 경우)

설치

패키지를 설치하세요:

지엑스피1

옵션

Meilisearch 연결 옵션

• meilisearchHost : Meilisearch 인스턴스의 URL(기본값: " http://localhost:7700 ")
• meilisearchApiKey : Meilisearch 인증을 위한 API 키(기본값: "")

MCP 서버 옵션

• transport : MCP 서버의 전송 유형("http" | "stdio")(기본값: "http")
• httpPort : MCP 서버의 HTTP 포트(기본값: 4995)
• mcpEndpoint : MCP 엔드포인트 경로(기본값: "/mcp")

세션 옵션

• sessionTimeout : 세션 시간 초과(밀리초) (기본값: 3600000)
• sessionCleanupInterval : 세션 정리 간격(밀리초) (기본값: 60000)

AI 추론 옵션

• aiProviderName : AI 제공자 이름("openai" | "huggingface" | "openrouter" | "ollama") (기본값: "openai")
• aiProviderApiKey : AI 추론을 위한 AI 공급자 API 키
• llmModel : 사용할 AI 모델(기본값: "gpt-3.5-turbo")

이 패키지에서 적절한 AI 추론에 필요한 함수 호출을 모든 모델이 지원하는 것은 아니라는 점에 유의하세요. tools 매개변수를 지원하는 모델을 선택해야 합니다.

예제 서버 설정

MCPClient 사용

패키지는 클라이언트 측 통합을 위해 MCPClient 클래스를 내보냅니다.

AI 추론 클라이언트 방법

callToolWithAI(query, options)

AI를 통해 사용자 쿼리를 처리하여 가장 적합한 도구를 결정하고 실행합니다.

매개변수:

• query : 문자열 - 처리할 사용자의 쿼리 또는 요청
• options : 개체(선택 사항) - 구성 옵션
  • specificTools : String[] (선택 사항) - 도구 선택을 이 도구 이름 목록으로 제한합니다.
  • justReasoning : Boolean(선택 사항) - true 로 설정하면 선택한 도구를 실행하지 않고 AI의 추론만 반환합니다.

서버 시작

다음과 같이 프로그래밍 방식으로 서버를 시작할 수 있습니다.

도구

MCP 서버는 Meilisearch 기능과 상호 작용할 수 있는 다양한 도구를 제공합니다. 각 도구는 특정 Meilisearch API 엔드포인트에 대응하여 문서 검색, 인덱싱, 관리 등의 작업을 수행할 수 있도록 합니다.

도구 카테고리

1. 시스템 도구 : 상태 점검, 버전 정보, 서버 통계.
2. 인덱스 도구 : 인덱스를 관리합니다(생성, 업데이트, 삭제, 나열).
3. 문서 도구 : 문서를 추가, 업데이트, 삭제 및 검색합니다.
4. 검색 도구 : 벡터 검색을 포함한 고급 검색.
5. 설정 도구 : 인덱스 설정을 구성합니다.
6. 작업 도구 : 비동기 작업을 관리합니다.
7. 벡터 도구 : 실험적 벡터 검색 기능.

시스템 도구

건강

• 설명 : Meilisearch 서버가 정상인지 확인합니다.

버전

• 설명 : Meilisearch 서버의 버전 정보를 가져옵니다.

정보

• 설명 : Meilisearch 서버의 시스템 정보를 가져옵니다.

통계

• 설명 : 모든 인덱스 또는 특정 인덱스에 대한 통계를 가져옵니다.
• 매개변수 :
  • indexUid (문자열, 선택 사항): 인덱스의 고유 식별자입니다.

get-tasks

• 설명 : 선택적 필터링을 통해 작업에 대한 정보를 얻습니다.
• 매개변수 :
  • limit (숫자, 선택 사항): 반환할 작업의 최대 수.
  • from (숫자, 선택 사항): 가져오기를 시작할 작업 uid입니다.
  • status (문자열, 선택 사항): 반환할 작업의 상태입니다.
  • type (문자열, 선택 사항): 반환할 작업 유형입니다.
  • indexUids (문자열[], 선택 사항): 작업이 수행된 인덱스의 UID입니다.

삭제 작업

• 설명 : 제공된 필터를 기준으로 작업을 삭제합니다.
• 매개변수 :
  • statuses (문자열[], 선택 사항): 삭제할 작업의 상태입니다.
  • types (문자열[], 선택 사항): 삭제할 작업 유형입니다.
  • indexUids (문자열[], 선택 사항): 삭제할 작업이 수행된 인덱스의 UID입니다.
  • uids (숫자[], 선택 사항): 삭제할 작업의 UID입니다.
  • canceledBy (number[], 선택 사항): 삭제할 작업을 취소한 작업의 UID입니다.
  • beforeUid (숫자, 선택 사항): 이 값보다 uid가 앞선 작업을 삭제합니다.
  • beforeStartedAt (문자열, 선택 사항): 이 날짜 이전에 처리를 시작한 작업을 삭제합니다(ISO 8601 형식).
  • beforeFinishedAt (문자열, 선택 사항): 이 날짜 이전에 처리가 완료된 작업을 삭제합니다(ISO 8601 형식).

인덱스 도구

목록-인덱스

• 설명 : Meilisearch 인스턴스의 모든 인덱스를 나열합니다.
• 매개변수 :
  • limit (숫자, 선택 사항): 반환할 인덱스의 최대 개수.
  • offset (숫자, 선택 사항): 건너뛸 인덱스의 개수입니다.

get-index

• 설명 : 특정 Meilisearch 인덱스에 대한 정보를 가져옵니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.

인덱스 생성

• 설명 : 새로운 Meilisearch 인덱스를 만듭니다.
• 매개변수 :
  • indexUid (문자열, 필수): 새 인덱스의 고유 식별자입니다.
  • primaryKey (문자열, 선택 사항): 인덱스의 기본 키입니다.

업데이트-인덱스

• 설명 : Meilisearch 인덱스를 업데이트합니다(현재는 기본 키 업데이트만 지원).
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • primaryKey (문자열, 필수): 인덱스의 새로운 기본 키입니다.

삭제-인덱스

• 설명 : Meilisearch 인덱스를 삭제합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 삭제할 인덱스의 고유 식별자입니다.

스왑 인덱스

• 설명 : Meilisearch에서 두 개 이상의 인덱스를 교환합니다.
• 매개변수 :
  • indexes (문자열, 필수): 교환할 인덱스 쌍의 JSON 배열, 예: [["movies", "movies_new"]].

문서 도구

문서 가져오기

• 설명 : Meilisearch 인덱스에서 문서를 가져옵니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • limit (숫자, 선택 사항): 반환할 문서의 최대 개수(기본값: 20).
  • offset (숫자, 선택 사항): 건너뛸 문서 수(기본값: 0).
  • fields (문자열[], 선택 사항): 문서에서 반환할 필드입니다.
  • filter (문자열, 선택 사항): 적용할 필터 쿼리입니다.

문서 가져오기

• 설명 : Meilisearch 인덱스에서 ID로 문서를 가져옵니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • documentId (문자열, 필수): 검색할 문서의 ID입니다.
  • fields (문자열[], 선택 사항): 문서에서 반환할 필드입니다.

문서 추가

• 설명 : Meilisearch 인덱스에 문서를 추가합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • documents (문자열, 필수): 추가할 문서의 JSON 배열입니다.
  • primaryKey (문자열, 선택 사항): 문서의 기본 키입니다.

업데이트 문서

• 설명 : Meilisearch 인덱스의 문서를 업데이트합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • documents (문자열, 필수): 업데이트할 문서의 JSON 배열입니다.
  • primaryKey (문자열, 선택 사항): 문서의 기본 키입니다.

문서 삭제

• 설명 : Meilisearch 인덱스에서 ID로 문서를 삭제합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • documentId (문자열, 필수): 삭제할 문서의 ID입니다.

문서 삭제

• 설명 : Meilisearch 인덱스에서 ID별로 여러 문서를 삭제합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • documentIds (문자열, 필수): 삭제할 문서 ID의 JSON 배열입니다.

모든 문서 삭제

• 설명 : Meilisearch 인덱스의 모든 문서를 삭제합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.

검색 도구

찾다

• 설명 : Meilisearch 인덱스에서 문서를 검색합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • q (문자열, 필수): 검색어.
  • limit (숫자, 선택 사항): 반환할 결과의 최대 개수(기본값: 20).
  • offset (숫자, 선택 사항): 건너뛸 결과 수(기본값: 0).
  • filter (문자열, 선택 사항): 적용할 필터 쿼리입니다.
  • sort (문자열[], 선택 사항): 정렬 기준이 되는 속성, 예: ["price"].
  • facets (string[], 선택 사항): 반환할 facet입니다.
  • attributesToRetrieve (string[], 선택 사항): 결과에 포함할 속성입니다.
  • attributesToCrop (string[], 선택 사항): 자를 속성입니다.
  • cropLength (숫자, 선택 사항): 잘린 속성을 자를 길이입니다.
  • attributesToHighlight (string[], 선택 사항): 강조 표시할 속성입니다.
  • highlightPreTag (문자열, 선택 사항): 강조된 텍스트 앞에 삽입할 태그입니다.
  • highlightPostTag (문자열, 선택 사항): 강조된 텍스트 뒤에 삽입할 태그입니다.
  • showMatchesPosition (부울, 선택 사항): 결과에 경기 위치를 포함할지 여부입니다.
  • matchingStrategy (문자열, 선택 사항): 매칭 전략: 'all' 또는 'last'.

다중 검색

• 설명 : 한 번의 요청으로 여러 검색을 수행합니다.
• 매개변수 :
  • queries (문자열, 필수): search 도구와 동일한 매개변수를 포함하는 검색 쿼리의 JSON 배열입니다.

글로벌 검색

• 설명 : 사용 가능한 모든 Meilisearch 인덱스에서 용어를 검색하여 결합된 결과를 반환합니다.
• 매개변수 :
  • q (문자열, 필수): 검색어.
  • limit (숫자, 선택 사항): 인덱스당 반환할 결과의 최대 개수(기본값: 20).
  • attributesToRetrieve (string[], 선택 사항): 결과에 포함할 속성입니다.

패싯 검색

• 설명 : 특정 기준과 일치하는 패싯 값을 검색합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • facetName (문자열, 필수): 검색할 패싯의 이름입니다.
  • facetQuery (문자열, 선택 사항): 패싯 값과 일치시킬 쿼리입니다.
  • filter (문자열, 선택 사항): 기본 검색에 적용할 필터입니다.

설정 도구

get-settings

• 설명 : Meilisearch 인덱스에 대한 모든 설정을 가져옵니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.

업데이트 설정

• 설명 : Meilisearch 인덱스에 대한 설정을 업데이트합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • settings (문자열, 필수): 업데이트할 설정이 포함된 JSON 객체입니다.

재설정 설정

• 설명 : Meilisearch 인덱스의 모든 설정을 기본값으로 재설정합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.

설정 도구 가져오기

다음 도구는 Meilisearch 인덱스에 대한 특정 설정을 검색합니다.

• get-displayed-attributes
• 검색 가능한 속성 가져오기
• 필터링 가능한 속성 가져오기
• 정렬 가능한 속성 가져오기
• 랭킹 규칙 가져오기
• 중지 단어 가져오기
• 동의어 얻기
• 타이포 허용 범위 설정
• 페이지 매김 가져오기
• get-faceting
• get-dictionary
• 근접도-정밀도 가져오기
• get-separator-tokens
• 구분 기호가 없는 토큰 가져오기
• get-word-dictionary

이러한 모든 도구는 동일한 매개변수를 갖습니다.

• indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.

업데이트 설정 도구

다음 도구는 Meilisearch 인덱스의 특정 설정을 업데이트합니다.

• 업데이트-표시-속성
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • displayedAttributes (문자열, 필수): 표시할 속성의 JSON 배열, 예: ["title", "description"].
• 업데이트-검색-속성
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • searchableAttributes (문자열, 필수): 검색할 수 있는 속성의 JSON 배열, 예: ["title", "description"].
• 업데이트-필터링-속성
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • filterableAttributes (문자열, 필수): 필터로 사용할 수 있는 속성의 JSON 배열, 예: ["genre", "director"].
• 업데이트-정렬-속성
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • sortableAttributes (문자열, 필수): 정렬에 사용할 수 있는 속성의 JSON 배열, 예: ["price", "date"].
• 업데이트-순위-규칙
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • rankingRules (문자열, 필수): 순위 규칙의 JSON 배열, 예: ["typo", "words", "proximity", "attribute", "sort", "exactness"].
• 업데이트-중단어
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • stopWords (문자열, 필수): 검색 쿼리에서 무시할 단어의 JSON 배열, 예: ["the", "a", "an"].
• 업데이트-동의어
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • synonyms (문자열, 필수): 단어를 동의어에 매핑하는 JSON 객체, 예: {"movie": ["film"]}.
• 업데이트-오타-허용 범위
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • typoTolerance (문자열, 필수): 타이포 허용 구성이 포함된 JSON 객체, 예: {"enabled": true, "minWordSizeForTypos": {"oneTypo": 5, "twoTypos": 9}}.
• 업데이트-페이지 매김
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • pagination (문자열, 필수): 페이지 번호 매기기 구성이 포함된 JSON 객체, 예: {"maxTotalHits": 1000}.
• 업데이트 패싯
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • faceting (문자열, 필수): 패싯 구성이 포함된 JSON 객체, 예: {"maxValuesPerFacet": 100}.
• 업데이트 사전
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • dictionary (문자열, 필수): 단일 단어로 간주할 단어의 JSON 배열, 예: ["샌프란시스코", "뉴욕"].
• 업데이트-근접-정밀도
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • proximityPrecision (문자열, 필수): 근접 정밀도 값이 포함된 문자열입니다. 'byWord' 또는 'byAttribute'가 될 수 있습니다.
• 업데이트 구분자 토큰
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • separatorTokens (문자열, 필수): 단어 구분 기호로 간주해야 하는 토큰의 JSON 배열, 예: ["-", "_"].
• 업데이트-비-구분-토큰
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • nonSeparatorTokens (문자열, 필수): 단어 구분 기호로 간주되어서는 안 되는 토큰의 JSON 배열, 예: ["@", "."].
• 업데이트-단어-사전
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • wordDictionary (문자열, 필수): 사전에 추가할 사용자 정의 단어의 JSON 배열, 예: ["cbuilder", "meilisearch"].

설정 재설정 도구

다음 도구는 Meilisearch 인덱스의 특정 설정을 기본값으로 재설정합니다.

• 표시된 속성 재설정
• 검색 가능 속성 재설정
• 필터링 가능 속성 재설정
• 정렬 가능 속성 재설정
• 순위 규칙 재설정
• 중지 단어 재설정
• 재설정-동의어
• 재설정-오타-허용 범위
• 리셋-페이지네이션
• 리셋 패싯팅
• 재설정-사전
• 근접도-정밀도 재설정
• 재설정-구분자-토큰
• 재설정-비-구분-토큰
• 단어 사전 재설정

이러한 모든 재설정 도구는 동일한 매개변수를 갖습니다.

• indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.

작업 도구

목록 작업

• 설명 : 선택적 필터링을 통해 작업을 나열합니다.
• 매개변수 :
  • limit (숫자, 선택 사항): 반환할 작업의 최대 수.
  • from (숫자, 선택 사항): 가져오기를 시작할 작업 uid입니다.
  • statuses (문자열[], 선택 사항): 반환할 작업의 상태입니다.
  • types (문자열[], 선택 사항): 반환할 작업 유형입니다.
  • indexUids (문자열[], 선택 사항): 작업이 수행된 인덱스의 UID입니다.
  • uids (숫자[], 선택 사항): 반환할 특정 작업의 UID입니다.

작업 받기

• 설명 : 특정 작업에 대한 정보를 얻습니다.
• 매개변수 :
  • taskUid (숫자, 필수): 작업의 고유 식별자입니다.

작업 취소

• 설명 : 제공된 필터를 기준으로 작업을 취소합니다.
• 매개변수 :
  • statuses (문자열[], 선택 사항): 취소할 작업의 상태입니다.
  • types (문자열[], 선택 사항): 취소할 작업 유형입니다.
  • indexUids (문자열[], 선택 사항): 취소할 작업이 수행된 인덱스의 UID입니다.
  • uids (숫자[], 선택 사항): 취소할 작업의 UID입니다.

작업 대기

• 설명 : 특정 작업이 완료될 때까지 기다립니다.
• 매개변수 :
  • taskUid (숫자, 필수): 기다릴 작업의 고유 식별자입니다.
  • timeoutMs (숫자, 선택 사항): 대기할 최대 시간(밀리초)(기본값: 5000).
  • intervalMs (숫자, 선택 사항): 밀리초 단위의 폴링 간격(기본값: 500).

벡터 도구

벡터 검색 활성화

• 설명 : Meilisearch에서 벡터 검색 실험적 기능을 활성화합니다.

실험적 기능 얻기

• 설명 : Meilisearch의 실험적 기능 상태를 가져옵니다.

업데이트 임베더

• 설명 : 벡터 검색을 위한 임베더를 구성합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • embedders (문자열, 필수): embedder 구성을 포함하는 JSON 객체입니다.

get-embedders

• 설명 : 인덱스에 대한 임베더 구성을 가져옵니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.

리셋-임베더

• 설명 : 인덱스에 대한 임베더 구성을 재설정합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.

벡터 검색

• 설명 : Meilisearch 인덱스에서 벡터 검색을 수행합니다.
• 매개변수 :
  • indexUid (문자열, 필수): 인덱스의 고유 식별자입니다.
  • vector (문자열, 필수): 검색할 벡터를 나타내는 JSON 배열입니다.
  • limit (숫자, 선택 사항): 반환할 결과의 최대 개수(기본값: 20).
  • offset (숫자, 선택 사항): 건너뛸 결과 수(기본값: 0).
  • filter (문자열, 선택 사항): 적용할 필터(예: '장르 = 공포 AND 연도 > 2020').
  • embedder (문자열, 선택 사항): 사용할 embedder의 이름(생략된 경우 'vector'를 제공해야 함).
  • attributes (문자열[], 선택 사항): 벡터 검색에 포함할 속성입니다.
  • query (문자열, 선택 사항): 검색할 텍스트 쿼리('vector' 대신 'embedder'를 사용하는 경우).
  • hybrid (부울, 선택 사항): 하이브리드 검색(벡터와 텍스트 검색을 결합)을 수행할지 여부입니다.
  • hybridRatio (숫자, 선택 사항): 하이브리드 검색에서 벡터 검색과 텍스트 검색의 비율(0-1, 기본값: 0.5).