Meilisearch

• 현재 연결 설정 확인
• Meilisearch 인스턴스 간 동적 전환
• API 키를 즉시 업데이트

• 사용자 지정 기본 키로 새 인덱스 생성
• 통계와 함께 모든 인덱스 목록 확인
• 인덱스와 해당 데이터 삭제
• 상세한 인덱스 지표 확인

• 문서 추가 또는 업데이트
• 페이지네이션을 사용해 문서 가져오기
• 데이터 일괄 가져오기

• 필터, 정렬 및 패싯을 사용한 검색
• 여러 인덱스 검색
• 벡터를 사용한 시맨틱 검색
• 하이브리드 검색(키워드 + 시맨틱)

• 순위 규칙 구성
• 패싯 및 필터링 설정
• 검색 가능한 속성 관리
• 오타 허용 범위 사용자 지정

• API 키 생성 및 관리
• 세분화된 권한 설정
• 키 사용량 모니터링

⚠️ 참고: 편의를 위해 채팅에서 호스트와 API 키를 직접 추가하거나 업데이트할 수 있지만, 이 방식은 주로 개발 환경(예: 여러 인스턴스에 즉시 연결)에 맞춰 설계되었습니다. 이는 MCP 보안 모범 사례를 따르지 않으므로 적절한 보호 조치 없이 프로덕션 환경에서 사용해서는 안 됩니다.

• 상태 확인
• 시스템 통계
• 작업 모니터링
• 버전 정보

사용 가능한 도구

연결 관리

• get-connection-settings: 현재 Meilisearch 연결 URL 및 API 키 상태 확인
• update-connection-settings: 다른 인스턴스에 연결하도록 URL 및/또는 API 키 업데이트

인덱스 관리

• create-index: 선택적으로 기본 키를 지정해 새 인덱스 생성
• list-indexes: 사용 가능한 모든 인덱스 목록 확인
• delete-index: 기존 인덱스와 모든 문서 삭제
• get-index-metrics: 특정 인덱스의 상세 지표 확인

문서 작업

• get-documents: 페이지네이션을 사용해 인덱스에서 문서 가져오기
• add-documents: 인덱스에 문서 추가 또는 업데이트

검색

• search: 필터링 및 정렬 옵션을 사용해 하나 또는 여러 인덱스에서 유연하게 검색

설정 관리

• get-settings: 인덱스의 현재 설정 확인
• update-settings: 인덱스 설정 업데이트(순위 지정, 패싯 등)

API 키 관리

• get-keys: 모든 API 키 목록 확인
• create-key: 특정 권한을 가진 새 API 키 생성
• delete-key: 기존 API 키 삭제

작업 관리

• get-task: 특정 작업에 대한 정보 가져오기
• get-tasks: 선택적 필터를 사용해 작업 목록 확인
• cancel-tasks: 대기 중이거나 큐에 등록된 작업 취소

시스템 모니터링

• health-check: 기본 상태 확인
• get-health-status: 종합 상태 확인
• get-version: Meilisearch 버전 정보 가져오기
• get-stats: 데이터베이스 통계 가져오기
• get-system-info: 시스템 수준 정보 가져오기

개발 환경 설정

사전 요구 사항

1. Meilisearch 서버 시작:

   # Using Docker (recommended for development)
   docker run -d -p 7700:7700 getmeili/meilisearch:v1.28
   
   # Or using brew (macOS)
   brew install meilisearch
   meilisearch
   
   # Or download from https://github.com/meilisearch/meilisearch/releases
   

2. 개발 도구 설치:

   # Install uv for Python package management
   pip install uv
   
   # Install Node.js for MCP Inspector testing
   # Visit https://nodejs.org/ or use your package manager
   

테스트 실행

이 프로젝트에는 MCP 도구 기능을 검증하는 포괄적인 통합 테스트가 포함되어 있습니다.

# Run all tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_mcp_client.py -v

# Run tests with coverage report
python -m pytest --cov=src tests/

# Run tests in watch mode (requires pytest-watch)
pytest-watch tests/

중요: 테스트를 실행하려면 http://localhost:7700에서 Meilisearch 인스턴스가 실행 중이어야 합니다.

코드 품질

# Format code with Black
black src/ tests/

# Run type checking (if mypy is configured)
mypy src/

# Lint code (if flake8 is configured)
flake8 src/ tests/

기여 가이드라인

1. 저장소를 포크하고 클론합니다
2. 위의 개발 환경 설정 섹션에 따라 개발 환경을 설정합니다
3. main에서 기능 브랜치를 생성합니다
4. 새 기능을 추가하는 경우 먼저 테스트를 작성합니다(테스트 주도 개발)
5. 커밋하기 전에 모든 테스트가 통과하는지 확인하도록 로컬에서 테스트를 실행합니다
6. Black으로 코드 서식을 지정하고 코드 품질을 확인합니다
7. 설명이 명확한 커밋 메시지로 변경 사항을 커밋합니다
8. 포크에 푸시하고 Pull Request를 생성합니다

개발 워크플로

# Create feature branch
git checkout -b feature/your-feature-name

# Make your changes, write tests first
# Edit files...

# Run tests to ensure everything works
python -m pytest tests/ -v

# Format code
black src/ tests/

# Commit and push
git add .
git commit -m "Add feature description"
git push origin feature/your-feature-name

테스트 가이드라인

• 모든 새 기능에는 테스트를 포함해야 합니다
• PR을 제출하기 전에 테스트가 통과해야 합니다
• 설명이 명확한 테스트 이름과 분명한 단언을 사용합니다
• 성공 사례와 오류 사례를 모두 테스트합니다
• 테스트를 실행하기 전에 Meilisearch가 실행 중인지 확인합니다

릴리스 프로세스

이 프로젝트는 PyPI에 자동 버전 관리 및 게시를 사용합니다. 릴리스 프로세스는 간단하고 자동화되도록 설계되었습니다.

릴리스 작동 방식

1. 자동 게시: main 브랜치에서 pyproject.toml의 버전 번호가 변경되면 GitHub Action이 자동으로 다음 작업을 수행합니다.

   • Python 패키지 빌드
   • 신뢰할 수 있는 게시를 사용해 PyPI에 게시
   • GitHub에 새 릴리스 생성

2. 버전 감지: 워크플로는 pyproject.toml의 현재 버전을 이전 커밋과 비교해 변경 사항을 감지합니다

3. PyPI 게시: 신뢰할 수 있는 게시를 사용하는 PyPA 공식 게시 액션을 이용합니다(수동 API 키 불필요)

새 릴리스 만들기

새 릴리스를 만들려면 다음 단계를 따르세요.

1. 버전 번호 결정

시맨틱 버저닝을 따릅니다(MAJOR.MINOR.PATCH).

• PATCH(예: 0.4.0 → 0.4.1): 버그 수정, 문서 업데이트, 사소한 개선
• MINOR(예: 0.4.0 → 0.5.0): 새 기능, 새 MCP 도구, 주요 개선 사항
• MAJOR(예: 0.5.0 → 1.0.0): 호환성을 깨는 변경 사항, 주요 API 변경 사항

2. 버전 업데이트 및 PR 생성

# 1. Create a branch from latest main
git checkout main
git pull origin main
git checkout -b release/v0.5.0

# 2. Update version in pyproject.toml
# Edit the version = "0.4.0" line to your new version

# 3. Commit and push
git add pyproject.toml
git commit -m "Bump version to 0.5.0"
git push origin release/v0.5.0

# 4. Create PR and get it reviewed/merged
gh pr create --title "Release v0.5.0" --body "Bump version for release"

3. Main에 병합

PR이 승인되어 main에 병합되면 GitHub Action이 자동으로 다음 작업을 수행합니다.

1. 버전 변경 사항을 감지합니다
2. 패키지를 빌드합니다
3. PyPI에 게시합니다: https://pypi.org/p/meilisearch-mcp
4. 새 버전을 다음을 통해 사용할 수 있도록 합니다: pip install meilisearch-mcp

4. 릴리스 확인

병합한 후 릴리스를 확인합니다:

# Check GitHub Action status
gh run list --workflow=publish.yml

# Verify on PyPI (may take a few minutes)
pip index versions meilisearch-mcp

# Test installation of new version
pip install --upgrade meilisearch-mcp

릴리스 워크플로 파일

자동 릴리스는 .github/workflows/publish.yml에서 처리하며, 다음 작업을 수행합니다.

• main 브랜치에 푸시될 때 트리거됩니다
• pyproject.toml 버전이 변경되었는지 확인합니다
• Python 3.10 및 공식 빌드 도구를 사용합니다
• 신뢰할 수 있는 게시를 사용해 게시합니다(API 키 필요 없음)
• 디버깅을 위한 상세 출력을 제공합니다

릴리스 문제 해결

릴리스가 트리거되지 않음: 커밋 간에 pyproject.toml의 버전이 실제로 변경되었는지 확인합니다

빌드 실패: GitHub Actions 로그에서 Python 패키지 빌드 오류를 확인합니다

PyPI 게시 실패: 패키지 이름과 신뢰할 수 있는 게시가 올바르게 구성되었는지 확인합니다

버전 충돌: 새 버전 번호가 PyPI에서 이전에 사용된 적이 없는지 확인합니다

개발 버전과 프로덕션 버전

• 개발: pip install -e .을 사용해 소스에서 설치합니다
• 프로덕션: pip install meilisearch-mcp을 사용해 PyPI에서 설치합니다
• 특정 버전: pip install meilisearch-mcp==0.5.0을 사용해 설치합니다