Meilisearch MCP Server

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

• 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à phân nhóm
• Tìm kiếm đa chỉ mục
• Tìm kiếm ngữ nghĩa với vector
• Tìm kiếm lai (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ý thuộc tính có thể tìm kiếm
• Tùy chỉnh dung sai 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ủ và khóa API trực tiếp trong 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 nhanh chóng). Nó 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ó các biện pháp bảo vệ thích 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ô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ừ một chỉ mục với phân trang
• add-documents: Thêm hoặc cập nhật tài liệu trong một 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, 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 các 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
• delete-tasks: Xóa các tác vụ đã hoàn thành

Giám sát Hệ thống

• health-check: Kiểm tra tình trạng cơ bản
• get-health-status: 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 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ô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 kiểm thử yêu cầu một 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 commit
6. Định dạng mã bằng Black và đảm bảo chất lượng mã
7. Commit thay đổi với thông điệp commit 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ả các tính năng mới nên bao gồm kiểm thử
• Kiểm thử phải 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 quản lý 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 thức 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, GitHub Action sẽ tự động:

   • Xây dựng gói Python
   • Xuất bản lên PyPI bằng cách sử dụng xuất bản 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 làm việc 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. 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 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 Main

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, 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

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

• 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 cách sử dụng xuất bản tin cậy (không yêu cầu khóa API)
• Cung cấp đầu ra chi tiết để gỡ lỗi

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

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

Xây 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à rằ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 đây 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