Meilisearch

• Xem cài đặt kết nối hiện tại
• Chuyển đổi linh hoạt giữa các phiên bản Meilisearch
• 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 cùng số liệu thống kê
• Xóa chỉ mục và dữ liệu của chúng
• Xem 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 có 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à phân nhóm
• Tìm kiếm trên nhiều chỉ mục
• Tìm kiếm ngữ nghĩa bằng 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 phân nhóm và lọc
• Quản lý các 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
• Thiết lập quyền chi tiết
• Theo dõi mức sử dụng khóa

⚠️ Lưu ý: Bạn có thể thêm và cập nhật máy chủ cùng khóa API trực tiếp trong cuộc trò chuyện để thuận tiện, nhưng cách này chủ yếu dành cho mục đích phát triển (chẳng hạn như kết nối nhanh với nhiều phiên bản). 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 dùng trong môi trường sản xuất nếu chưa có biện pháp bảo vệ phù hợp.

• Kiểm tra tình trạng
• 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ụ hiện có

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 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ả chỉ mục hiện có
• delete-index: Xóa chỉ mục hiện có cùng toàn bộ tài liệu
• get-index-metrics: Xem số liệu chi tiết của một chỉ mục cụ thể

Thao tác với tài liệu

• get-documents: Truy xuất tài liệu từ chỉ mục có 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 của một chỉ mục
• update-settings: Cập nhật cài đặt chỉ mục (xếp hạng, phân nhóm, 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ê tác vụ với các 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 tình trạng cơ bản
• get-health-status: Xem trạng thái tình trạng 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 môi trường 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 bài 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: Các bài kiểm thử yêu cầu một phiên bản Meilisearch đang chạy tại 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. Tạo fork và sao chép kho lưu trữ
2. Thiết lập môi trường phát triển theo phần Thiết lập môi trường 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ả đều đạt trước khi commit
6. Định dạng mã bằng Black và đảm bảo chất lượng mã
7. Commit các thay đổi với thông điệp mô tả rõ ràng
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ử

• Mọi tính năng mới cần có kiểm thử
• Kiểm thử phải đạt trước khi gửi PR
• Dùng tên kiểm thử mô tả rõ ràng và các xác nhận dễ hiểu
• Kiểm thử cả trường hợp thành công lẫn lỗi
• Đảm bảo Meilisearch đang chạy trước khi thực hiện kiểm thử

Quy trình phát hành

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

Cách thức phát hành

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

   • Xây dựng gói Python
   • Phát hành lên PyPI bằng cơ chế phát hành đá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 commit trước đó để phát hiện thay đổi

3. Phát hành lên PyPI: Sử dụng publish action chính thức của PyPA với cơ chế phát hành đá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 Quy ước đánh số 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 gây lỗi tương thích, 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. Gộp vào nhánh chính

Sau khi PR được phê duyệt và gộp vào main, GitHub Action sẽ tự động:

1. Phát hiện thay đổi phiên bản
2. Tạo gói
3. Phát hành 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, hãy 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

Quy trình phát hành tự động được xử lý bởi .github/workflows/publish.yml, trong đó:

• Kích hoạt khi có thay đổi được đẩy lên nhánh main
• Kiểm tra xem phiên bản pyproject.toml có thay đổi hay không
• Sử dụng Python 3.10 và các công cụ tạo bản dựng chính thức
• Phát hành bằng phương thức 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

Khắc phục sự cố phát hành

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

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

Phát hành lên PyPI thất bại: Xác minh tên gói và cấu hình xuất bản đáng tin cậy

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ên PyPI

Phiên bản phát triển và 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