# MCP-Manticore：让您的AI助手为您编写Manticore查询

了解MCP-Manticore服务器如何帮助Cursor、Claude Code和其他AI助手生成正确的Manticore Search查询，创建适当的模式，并在没有语法错误的情况下探索您的数据。

## 介绍

您可能听说过Manticore Search速度很快。您可能听说过它在一个引擎中处理全文、向量和模糊搜索。但当您真正开始使用它时，您却盯着文档，猜测SQL语法，并希望您的`CREATE TABLE`不会抛出一个晦涩的错误。

**MCP-Manticore** 改变了游戏规则。它是一个模型上下文协议（MCP）服务器，可将Cursor、Claude Code、Codex CLI或任何MCP兼容的AI助手直接连接到您的Manticore实例。AI可以阅读文档、检查您的模式并执行查询——在为您编写第一个查询之前。

[MCP](https://modelcontextprotocol.io)（模型上下文协议）是一个开放标准，允许AI助手连接到外部工具和数据源。与AI基于未知时间的训练数据猜测Manticore语法不同，它现在可以实时访问您的数据库和官方文档。

## 这对您有帮助的两种方式

根据您正在做的事情，MCP-Manticore以两种不同的方式为您提供价值：

**1. 开发者辅助（主要）：** 您正在构建一个使用Manticore的应用程序。AI帮助您创建表、编写复杂查询并理解功能——无需您记忆SQL语法。

**2. 数据探索（次要）：** 您在Manticore中有数据，并想用普通英语提问。“显示最便宜的配件”或“找到与这个产品相似的产品。”对于向量搜索或模糊匹配等复杂操作，AI需要MCP来了解正确的Manticore特定语法。

让我们看看这两种方式。

## 问题：没有上下文的AI

当您要求AI助手在**没有**MCP集成的情况下帮助Manticore时，会发生以下情况：

### 示例：创建带有自动嵌入的表

**您：** “如何创建一个带有自动嵌入的Manticore表以进行语义搜索？”

**AI（猜测）：**
```sql
CREATE TABLE products (
    title text,
    description text,
    description_vector float_vector 
        embedding='sentence-transformers/all-MiniLM-L6-v2' 
        source='description'
);
```

看起来合理，对吧？**错误。** 实际语法使用`MODEL_NAME`和`FROM`，而不是`embedding`和`source`。您只有在查询失败后才会发现这一点，这会将您送回文档。

这是模式：
1. AI基于过时或猜测的语法生成查询
2. 您运行它，得到一个错误
3. 您手动检查文档
4. 您纠正AI（或自己修复）
5. 重复直到它工作

对于将Manticore集成到应用程序中的开发人员来说，这种摩擦会扼杀生产力。您不是在探索数据——您在与语法搏斗。

## 解决方案：MCP-Manticore

启用MCP-Manticore后，对话发生了变化：

**您：** “如何创建一个带有自动嵌入的Manticore表以进行语义搜索？”

**AI：** “让我通过MCP检查文档以获取正确的语法...”

*[AI通过MCP调用`list_documentation`，搜索“embedding|semantic|knn|vector”]*

**AI：** “这是正确的语法。Manticore使用`MODEL_NAME`和`FROM`进行自动嵌入：”

```sql
CREATE TABLE products (
    title TEXT,
    description TEXT,
    embedding_vector FLOAT_VECTOR KNN_TYPE='hnsw' HNSW_SIMILARITY='l2'
    MODEL_NAME='sentence-transformers/all-MiniLM-L6-v2' FROM='title,description'
);
```

AI现在拥有：
- **实时访问** Manticore文档
- 通过`list_tables()`和`describe_table()`进行**模式内省**
- **查询执行** 以测试和验证
- **安全控制**——默认只读，写操作需要主动启用

## 实际示例：有和没有MCP的情况

### 示例1：模式创建

**没有MCP：**
AI猜测了语法，使用了`embedding='...'`和`source='...'`——这在Manticore中不存在。您会遇到错误并浪费时间调试。

**有MCP：**
AI首先检索了官方文档，并提供了正确的`MODEL_NAME`和`FROM`语法。它还解释了支持的模型（本地HuggingFace模型、OpenAI、Voyage、Jina）和`HNSW_SIMILARITY`选项（`L2`、`IP`、`COSINE`）。

### 示例2：使用自动嵌入的语义搜索

**您：** “查找与'旅行用的降噪耳机'相似的产品”

**没有MCP：**
AI完全失去了方向。没有文档访问权限，它：
- 尝试SELECT所有数据并内部聚合，没有任何过滤器
- 幻想使用虚构语法的嵌入向量：`ANY_KNN(embedding, (-0.07089090,0.04201586,-0.03262700...))`
- 尝试编写Python脚本手动计算相似性
- 最终放弃，只在描述中进行字符串匹配

**结果：** 它只找到了“无线耳机”，因为描述中确实包含“降噪耳机”——纯粹是运气，而不是语义搜索。

**有MCP：**
AI检查文档，发现您的表使用了自动嵌入，并了解到当配置了`MODEL_NAME`时，`knn()`可以**直接接受文本**：

```sql
SELECT id, name, description, knn_dist() 
FROM products 
WHERE knn(embedding, 5, 'noise-canceling headphones for travel');
```

**结果：** 返回无线耳机作为#1（正确），但还显示了语义上相关的产品——实际的向量相似性，而不是关键词匹配。

### 示例3：模糊搜索（拼写容错）

**您：** “即使我拼错名称，比如用'headphons'而不是'headphones'，也要找到产品”

**没有MCP：**
AI尝试了它所训练的一切，希望其中一些能起作用：
- `MATCH('headphons~1')`和`MATCH('headphons~')`——错误的操作符
- `CALL SUGGEST('headphons', 'products')`——这个用例的错误方法
- `MATCH('FUZZY(headphons')`——虚构的语法不存在
- `ALTER TABLE products SET min_infix_len = 3`——不必要的且错误的
- `OPTION expand_keywords = 1`——无关的功能

它甚至尝试优化表并再次运行建议。完全的混乱。

**结果：** 没有可行的查询。只是基于过时或困惑的训练数据的一堆失败尝试。

**有MCP：**
AI检查文档，立即找到正确的语法：

```sql
SELECT * FROM products WHERE MATCH('headphons') OPTION fuzzy=1;
```

**结果：** 尽管存在拼写错误，仍返回 "Wireless Headphones"。AI 还解释了 `fuzzy=1` 允许 Levenshtein 距离为 1（一个字符差异），并且可以通过 `OPTION fuzzy=1, distance=2` 调整容差以获得更大的灵活性。

## 主要功能

### 智能文档查找

MCP-Manticore 包含一个文档获取器，可直接从 GitHub 上的 [Manticore Search 手册](https://manual.manticoresearch.com) 获取文档。当您询问 KNN 向量搜索、模糊匹配或全文本操作符等功能时，AI 会在回答前检索官方文档。

### 了解数据结构的查询构建

服务器提供工具，让 AI 在编写查询前了解您的数据结构：
- `list_tables()` — 查看存在的表
- `describe_table()` — 了解列名和类型
- `execute_query()` — 运行查询并查看结果

### 安全查询执行

默认情况下，MCP-Manticore 以 **只读模式** 运行。写操作（INSERT、UPDATE、DELETE、DROP）需要通过环境变量显式启用：

```bash
export MANTICORE_ALLOW_WRITE_ACCESS=true  # Enable INSERT/UPDATE/DELETE
export MANTICORE_ALLOW_DROP=true            # Enable DROP/TRUNCATE
```

### 多种传输选项

通过以下方式连接：
- **stdio**（适用于基于 CLI 的 AI 助手，如 Claude Code）
- **HTTP**（适用于基于 Web 的集成）
- **SSE**（用于实时更新的服务器发送事件）

可选 JWT 认证以实现安全部署。

## 教程：设置 MCP-Manticore

MCP-Manticore 与任何 MCP 兼容的 AI 助手一起工作，包括 [Cursor](https://cursor.sh)、[Claude Code](https://claude.ai/download)、[Codex CLI](https://github.com/openai/codex)、[Windsurf](https://codeium.com/windsurf) 以及任何支持 Model Context Protocol 的工具。

### 第 1 步：确保已安装 UV

MCP-Manticore 最佳搭配 [uv](https://docs.astral.sh/uv/) 使用，这是一个快速的 Python 包管理器：

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

使用 `uv`，您无需手动安装 MCP-Manticore——`uvx` 会自动下载并运行它。

### 第 2 步：配置环境变量（可选）

```bash
# Required: Manticore connection (defaults shown)
export MANTICORE_HOST=localhost
export MANTICORE_PORT=9308

# Optional: Enable write access (default: read-only)
export MANTICORE_ALLOW_WRITE_ACCESS=true

# Optional: Allow destructive operations (DROP, TRUNCATE)
export MANTICORE_ALLOW_DROP=false
```

### 第 3 步：添加到您的 MCP 客户端

**通用配置：**
- **命令**：`uvx mcp-manticore`
- **环境变量**（如需）：`MANTICORE_HOST`、`MANTICORE_PORT` 等

**示例配置**（`mcp.json`）：
```json
{
  "mcpServers": {
    "manticore": {
      "command": "uvx",
      "args": ["mcp-manticore"],
      "env": {
        "MANTICORE_HOST": "localhost",
        "MANTICORE_PORT": "9308"
      }
    }
  }
}
```

对于特定客户端的设置说明（Cursor、Claude Desktop、Windsurf 等），请参阅 [MCP-Manticore README](https://github.com/manticoresoftware/mcp-manticore#client-configuration)。

### 第 4 步：验证连接

通过询问您的 AI 助手进行测试：

> "显示 Manticore 中的所有表"

您应该看到 AI 调用 `list_tables()` 工具并显示您的表。

## 配置参考

| 环境变量 | 描述 | 默认值 |
|---|---|---|
| `MANTICORE_HOST` | Manticore 服务器主机名 | `localhost` |
| `MANTICORE_PORT` | Manticore HTTP 端口 | `9308` |
| `MANTICORE_ALLOW_WRITE_ACCESS` | 启用 INSERT/UPDATE/DELETE | `false` |
| `MANTICORE_ALLOW_DROP` | 启用 DROP/TRUNCATE | `false` |
| `MANTICORE_MCP_TRANSPORT` | 传输类型（stdio/http/sse） | `stdio` |
| `MANTICORE_MCP_AUTH_TOKEN` | HTTP/SSE 的 JWT 令牌 | - |

## 未来：能够自行安装的代理

还有一个第三种用例正在酝酿：**自主代理**，它们可以自行发现并安装 MCP 服务器。

想象一个 AI 代理，它：
1. 找到您提到 Manticore 的 GitHub 仓库
2. 搜索 "Manticore MCP 服务器"
3. 找到 MCP-Manticore，自动安装
4. 开始查询您的数据库以完成任务

这并非科幻小说——OpenAI 的 Codex 和类似的代理系统正在朝这个方向发展。当这个未来到来时，将 MCP-Manticore 放入 MCP 注册表意味着您的 AI 工具将无需手动设置即可与 Manticore 一起工作。

## 结论

MCP-Manticore 将 AI 助手从被动的文本生成器转变为积极、知识丰富的开发合作伙伴。无论您是：

- **使用 Manticore 进行开发** —— 让 AI 处理语法，您专注于应用程序
- **学习 Manticore** —— 用普通英语提问，获得有文档支持的准确答案
- **探索您的数据** —— 查询时无需记忆 SQL 语法或表结构

旧方法：猜测、错误、调试、重复。  
新方法：提问、验证、执行、完成。

准备好尝试了吗？在安装了 `uv` 后，只需将 MCP-Manticore 添加到您的 MCP 客户端设置中并开始提问。未来的您——摆脱语法陷阱——会感谢您的。

---

**资源：**
- [MCP-Manticore 在 GitHub](https://github.com/manticoresoftware/mcp-manticore)
- [MCP 文档](https://modelcontextprotocol.io)
- [Manticore Search 手册](https://manual.manticoresearch.com)
- [Cursor MCP 设置指南](https://docs.cursor.com/context/model-context-protocol)