Meilisearch

• Xem cài đặt kết nối hiện tại
• Chuyển đổi giữa các phiên bản Meilisearch một cách linh hoạt
• Cập nhật khóa API ngay lập tức

• Tạo chỉ mục mới với khóa chính tùy chỉnh
• Liệt kê tất cả chỉ mục với số liệu thống kê
• Xóa chỉ mục và dữ liệu của chúng
• Lấy số liệu chi tiết của chỉ mục

• Thêm hoặc cập nhật tài liệu
• Truy xuất tài liệu với phân trang
• Nhập dữ liệu hàng loạt

• Tìm kiếm với bộ lọc, sắp xếp và khía cạnh
• Tìm kiếm đa chỉ mục
• Tìm kiếm ngữ nghĩa với vector
• Tìm kiếm kết hợp (từ khóa + ngữ nghĩa)

• Cấu hình quy tắc xếp hạng
• Thiết lập khía cạnh và lọc
• Quản lý thuộc tính có thể tìm kiếm
• Tùy chỉnh khả năng chịu lỗi chính tả

• Tạo và quản lý khóa API
• Đặt quyền chi tiết
• Giám sát việc sử dụng khóa

⚠️ Lưu ý: Mặc dù bạn có thể thêm và cập nhật máy chủ cũng như khóa API trực tiếp trong cuộc trò chuyện để thuận tiện, cách tiếp cận này chủ yếu được thiết kế cho các trường hợp sử dụng phát triển (như kết nối với nhiều phiên bản một cách linh hoạt). Cách này không tuân theo các phương pháp bảo mật MCP tốt nhất và không nên được sử dụng trong môi trường sản xuất nếu không có biện pháp bảo vệ phù hợp.

• Kiểm tra sức khỏe
• Thống kê hệ thống
• Giám sát tác vụ
• Thông tin phiên bản

Các công cụ có sẵn

Quản lý kết nối

• get-connection-settings: Xem URL kết nối Meilisearch hiện tại và trạng thái khóa API
• update-connection-settings: Cập nhật URL và/hoặc khóa API để kết nối với một phiên bản khác

Quản lý chỉ mục

• create-index: Tạo chỉ mục mới với khóa chính tùy chọn
• list-indexes: Liệt kê tất cả các chỉ mục có sẵn
• delete-index: Xóa chỉ mục hiện có và tất cả tài liệu của nó
• get-index-metrics: Lấy số liệu chi tiết cho một chỉ mục cụ thể

Thao tác tài liệu

• get-documents: Truy xuất tài liệu từ chỉ mục với phân trang
• add-documents: Thêm hoặc cập nhật tài liệu trong chỉ mục

Tìm kiếm

• search: Tìm kiếm linh hoạt trên một hoặc nhiều chỉ mục với các tùy chọn lọc và sắp xếp

Quản lý cài đặt

• get-settings: Xem cài đặt hiện tại cho một chỉ mục
• update-settings: Cập nhật cài đặt chỉ mục (xếp hạng, khía cạnh, v.v.)

Quản lý khóa API

• get-keys: Liệt kê tất cả khóa API
• create-key: Tạo khóa API mới với quyền cụ thể
• delete-key: Xóa khóa API hiện có

Quản lý tác vụ

• get-task: Lấy thông tin về một tác vụ cụ thể
• get-tasks: Liệt kê các tác vụ với bộ lọc tùy chọn
• cancel-tasks: Hủy các tác vụ đang chờ hoặc đã xếp hàng

Giám sát hệ thống

• health-check: Kiểm tra sức khỏe cơ bản
• get-health-status: Trạng thái sức khỏe toàn diện
• get-version: Lấy thông tin phiên bản Meilisearch
• get-stats: Lấy thống kê cơ sở dữ liệu
• get-system-info: Lấy thông tin cấp hệ thống

Thiết lập phát triển

Điều kiện tiên quyết

1. Khởi động máy chủ 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. Cài đặt công cụ phát triển:

   # 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
   

Chạy kiểm thử

Dự án này bao gồm các kiểm thử tích hợp toàn diện xác minh chức năng của công cụ 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/

Quan trọng: Kiểm thử yêu cầu phiên bản Meilisearch đang chạy trên http://localhost:7700.

Chất lượng mã

# 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/

Hướng dẫn đóng góp

1. Fork và clone kho lưu trữ
2. Thiết lập môi trường phát triển theo phần Thiết lập phát triển ở trên
3. Tạo nhánh tính năng từ main
4. Viết kiểm thử trước nếu thêm chức năng mới (Phát triển hướng kiểm thử)
5. Chạy kiểm thử cục bộ để đảm bảo tất cả kiểm thử đều vượt qua trước khi cam kết
6. Định dạng mã bằng Black và đảm bảo chất lượng mã
7. Cam kết thay đổi với thông điệp cam kết mô tả
8. Đẩy lên fork của bạn và tạo pull request

Quy trình phát triển

# 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

Hướng dẫn kiểm thử

• Tất cả tính năng mới nên bao gồm kiểm thử
• Kiểm thử nên vượt qua trước khi gửi PR
• Sử dụng tên kiểm thử mô tả và xác nhận rõ ràng
• Kiểm thử cả trường hợp thành công và lỗi
• Đảm bảo Meilisearch đang chạy trước khi chạy kiểm thử

Quy trình phát hành

Dự án này sử dụng phiên bản và xuất bản tự động lên PyPI. Quy trình phát hành được thiết kế đơn giản và tự động.

Cách phát hành hoạt động

1. Xuất bản tự động: Khi số phiên bản trong pyproject.toml thay đổi trên nhánh main, một GitHub Action tự động:

   • Xây dựng gói Python
   • Xuất bản lên PyPI bằng xuất bản đáng tin cậy
   • Tạo bản phát hành mới trên GitHub

2. Phát hiện phiên bản: Quy trình so sánh phiên bản hiện tại trong pyproject.toml với cam kết trước đó để phát hiện thay đổi

3. Xuất bản PyPI: Sử dụng hành động xuất bản chính thức của PyPA với xuất bản đáng tin cậy (không cần khóa API thủ công)

Tạo bản phát hành mới

Để tạo bản phát hành mới, hãy làm theo các bước sau:

1. Xác định số phiên bản

Tuân theo Phiên bản ngữ nghĩa (MAJOR.MINOR.PATCH):

• PATCH (ví dụ: 0.4.0 → 0.4.1): Sửa lỗi, cập nhật tài liệu, cải tiến nhỏ
• MINOR (ví dụ: 0.4.0 → 0.5.0): Tính năng mới, công cụ MCP mới, cải tiến đáng kể
• MAJOR (ví dụ: 0.5.0 → 1.0.0): Thay đổi phá vỡ, thay đổi API lớn

2. Cập nhật phiên bản và tạo 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. Hợp nhất vào nhánh chính

Khi PR được phê duyệt và hợp nhất vào main, GitHub Action sẽ tự động:

1. Phát hiện thay đổi phiên bản
2. Xây dựng gói
3. Xuất bản lên PyPI tại https://pypi.org/p/meilisearch-mcp
4. Cung cấp phiên bản mới qua pip install meilisearch-mcp

4. Xác minh bản phát hành

Sau khi hợp nhất, xác minh bản phát hành:

# 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

Tệp quy trình phát hành

Việc phát hành tự động được xử lý bởi .github/workflows/publish.yml, tệp này:

• Kích hoạt khi đẩy lên nhánh main
• Kiểm tra xem phiên bản pyproject.toml có thay đổi không
• Sử dụng Python 3.10 và các công cụ xây dựng chính thức
• Xuất bản bằng xuất bản đáng tin cậy (không cần khóa API)
• Cung cấp đầu ra chi tiết để gỡ lỗi

Xử lý sự cố phát hành

Bản phát hành không được kích hoạt: Kiểm tra rằng phiên bản trong pyproject.toml thực sự đã thay đổi giữa các commit

Bản dựng thất bại: Kiểm tra nhật ký GitHub Actions để tìm lỗi xây dựng gói Python

Xuất bản PyPI thất bại: Xác minh tên gói và đảm bảo tính năng xuất bản tin cậy được cấu hình đúng cách

Xung đột phiên bản: Đảm bảo số phiên bản mới chưa từng được sử dụng trước đó trên PyPI

Phiên bản Phát triển so với Phiên bản Sản xuất

• Phát triển: Cài đặt từ mã nguồn bằng pip install -e .
• Sản xuất: Cài đặt từ PyPI bằng pip install meilisearch-mcp
• Phiên bản cụ thể: Cài đặt bằng pip install meilisearch-mcp==0.5.0