Milvus MCP 서버

본 프로그램은 대규모 언어 모델을 위해 설계된, Model Context Protocol (MCP) 프로토콜을 준수하는 Milvus 벡터 데이터베이스 액세스 서비스입니다. 대규모 언어 모델(예: Antigravity)의 외부 벡터 데이터베이스 상호 작용 도구로 사용할 수 있습니다.

Milvus 2.6 벡터 데이터베이스를 지원하며, OpenAI 호환 임베딩 서비스(예: 통이첸원 text-embedding-v4)가 내장되어 있어 대규모 모델이 자연어를 사용하여 직접 의미론적 검색을 수행할 수 있습니다.

💡 주요 기능

1. 벡터 검색: 텍스트 입력 기반의 의미론적 검색(자동 임베딩) 및 원시 벡터 검색을 지원합니다.

2. 내장 임베딩: OpenAI 호환 엔드포인트가 통합되어 있어, 대규모 모델이 텍스트를 전달하면 자동으로 벡터로 변환되므로 외부 임베딩 서비스가 필요하지 않습니다.

3. 컬렉션 전체 수명 주기 관리: 컬렉션 생성, 조회, 삭제가 가능하며 생성 시 자동으로 인덱스를 구축하고 로드합니다.

4. 데이터 읽기/쓰기: 벡터 데이터 삽입 및 조건부 삭제를 지원합니다.

5. 다중 연결 관리: JSON 구성 파일을 통해 여러 명명된 연결을 정의할 수 있으며, 하나의 MCP 서버 인스턴스로 여러 Milvus 인스턴스를 서비스할 수 있습니다.

6. 보안 설계: drop_collection 및 delete_entities는 독립적인 도구로서 MCP 클라이언트에서 개별적으로 켜거나 끌 수 있으며, drop_collection은 이중 안전장치로 confirmDrop=true 매개변수가 추가로 필요합니다.

7. 하이브리드 검색: 벡터 유사도 검색과 스칼라 필터링을 결합한 쿼리를 지원합니다.

Related MCP server: MCP Server MySQL

⚙️ 실행 환경 요구 사항

1. Node.js 환경: Node.js 버전 v18 이상이 필요합니다.

2. Milvus 인스턴스: 액세스 가능한 Milvus 2.6 서비스 인스턴스가 필요합니다.

3. Embedding API: OpenAI 호환 임베딩 서비스 엔드포인트(예: 통이첸원 바이리엔 플랫폼)가 필요합니다.

4. 의존성 패키지: 실행 머신에서 npm install --omit=dev를 실행하여 의존성을 설치해야 합니다.

🛠 설치 및 빌드

1. 소스 코드 빌드

npm install
npm run build

컴파일 결과물은 ./dist 디렉토리에 저장됩니다.

2. 전역 로컬 설치

npm link

실행이 완료되면 시스템 어디에서나 전역 명령 milvus-mcp-server를 사용하여 해당 서비스를 빠르게 호출할 수 있습니다.

📝 구성 파일

JSON 파일을 사용하여 Milvus 연결 및 임베딩 서비스를 구성합니다.

구성 파일 예시

{
  "connections": [
    {
      "name": "my-milvus",
      "address": "localhost:19530",
      "username": "root",
      "password": "Milvus",
      "database": "default",
      "description": "本地开发 Milvus 实例，存储文档和图片的向量索引"
    }
  ],
  "embedding": {
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "apiKey": "sk-your-api-key",
    "model": "text-embedding-v4",
    "dimensions": 1024
  }
}

연결 필드 설명

임베딩 필드 설명

🚀 시작 및 사용

milvus-mcp-server --config <path-to-config.json>

매개변수 목록:

• -c, --config <path>: 구성 파일 경로(필수).

🧠 MCP 클라이언트 구성 예시

일반적인 MCP 클라이언트(예: Antigravity)의 구성을 예로 들면 다음과 같습니다:

{
  "mcpServers": {
    "MilvusMCP": {
      "command": "node",
      "args": [
        "绝对路径/milvus_mcp_server/dist/index.js",
        "--config", "绝对路径/milvus-config.json"
      ]
    }
  }
}

🧰 모델이 호출할 수 있는 도구 (Tools)

1. list_milvus_connections

• 설명: 구성된 모든 Milvus 연결 정보를 나열합니다(비밀번호 제외, 마스킹 처리).

• 매개변수: 없음.

2. list_collections

• 설명: 지정된 연결 하의 모든 컬렉션을 나열합니다.

• 매개변수:

  • connectionName (String): 대상 연결 이름.

3. describe_collection

• 설명: 필드 정의, 인덱스, 행 수 통계를 포함한 컬렉션의 상세 스키마 정보를 가져옵니다.

• 매개변수:

  • connectionName (String): 대상 연결 이름.

  • collectionName (String): 컬렉션 이름.

4. create_collection

• 설명: 새 컬렉션을 생성합니다. 벡터 필드에 대해 자동으로 AUTOINDEX 인덱스를 생성하고 컬렉션을 로드하여 즉시 검색 가능하게 합니다.

• 매개변수:

  • connectionName (String): 대상 연결 이름.

  • collectionName (String): 새 컬렉션 이름.

  • description (String, 선택): 컬렉션 설명.

  • fields (Array): 필드 정의 배열, 각 항목은 name, dataType, isPrimaryKey?, autoId?, dimension?, maxLength?, description?을 포함합니다.

5. drop_collection

• 설명: 컬렉션과 그 안의 모든 데이터를 영구적으로 삭제합니다. 되돌릴 수 없는 작업입니다.

• 매개변수:

  • connectionName (String): 대상 연결 이름.

  • collectionName (String): 삭제할 컬렉션 이름.

  • confirmDrop (Boolean): true로 설정해야만 삭제가 실행됩니다. 안전 이중 확인 메커니즘.

• 스위치 제어: 이 도구는 MCP 클라이언트에서 개별적으로 활성화하거나 비활성화할 수 있습니다.

6. insert_vectors

• 설명: 컬렉션에 데이터를 삽입합니다. 각 데이터는 각 필드 값(벡터 필드 포함)을 포함하는 JSON 객체입니다.

• 매개변수:

  • connectionName (String): 대상 연결 이름.

  • collectionName (String): 대상 컬렉션 이름.

  • data (Array): 데이터 배열.

7. delete_entities

• 설명: 필터 표현식에 따라 엔티티를 삭제합니다.

• 매개변수:

  • connectionName (String): 대상 연결 이름.

  • collectionName (String): 대상 컬렉션 이름.

  • filter (String): Milvus 필터 표현식, 예: 'id in [1, 2, 3]'.

• 스위치 제어: 이 도구는 MCP 클라이언트에서 개별적으로 활성화하거나 비활성화할 수 있습니다.

8. vector_search

• 설명: 벡터 유사도 검색. 텍스트 입력(자동으로 임베딩 서비스를 호출하여 벡터로 변환) 또는 원시 벡터 입력을 지원합니다.

• 매개변수:

  • connectionName (String): 대상 연결 이름.

  • collectionName (String): 대상 컬렉션 이름.

  • text (String, 선택): 검색 텍스트, vector와 둘 중 하나 선택.

  • vector (Number[], 선택): 원시 검색 벡터, text와 둘 중 하나 선택.

  • topK (Number, 선택): 반환할 개수, 기본값 10.

  • filter (String, 선택): 스칼라 필터 표현식.

  • outputFields (String[], 선택): 반환할 필드 목록.

9. query_entities

• 설명: 벡터 검색을 포함하지 않고 스칼라 조건에 따라 엔티티를 쿼리합니다.

• 매개변수:

  • connectionName (String): 대상 연결 이름.

  • collectionName (String): 대상 컬렉션 이름.

  • filter (String): Milvus 필터 표현식.

  • outputFields (String[], 선택): 반환할 필드 목록.

  • limit (Number, 선택): 최대 반환 개수, 기본값 100.

10. hybrid_search

• 설명: 벡터 검색 + 스칼라 필터링 결합 쿼리. vector_search와의 차이점은 filter가 필수 매개변수라는 점입니다.

• 매개변수:

  • connectionName (String): 대상 연결 이름.

  • collectionName (String): 대상 컬렉션 이름.

  • text (String, 선택): 검색 텍스트, vector와 둘 중 하나 선택.

  • vector (Number[], 선택): 원시 검색 벡터, text와 둘 중 하나 선택.

  • filter (String): 필수, 스칼라 필터 표현식.

  • topK (Number, 선택): 반환할 개수, 기본값 10.

  • outputFields (String[], 선택): 반환할 필드 목록.