Meilisearch MCP Server

• 查看当前连接设置
• 动态切换 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. 推送到你的复刻仓库并创建拉取请求

开发工作流

# 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 官方发布 Action 进行可信发布（无需手动 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 安装