Metadata-Version: 2.4
Name: mochow-mcp-server
Version: 2.4.1
Summary: MCP server for Mochow vector database
Author-email: caoshili <caoshili@baidu.com>
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.1.2
Requires-Dist: pymochow==2.4.1
Requires-Dist: dotenv>=0.9.9
Dynamic: license-file

# 百度向量数据库MCP Server

本代码仓库包含一个 MCP 服务器，它提供对[百度云向量数据库](https://cloud.baidu.com/doc/VDB/index.html)功能的访问。

## 前提条件

在使用百度云向量数据库MCP Server之前，请确保你具备以下条件：
1. Python 3.10 或更高版本
2. 已安装[uv](https://github.com/astral-sh/uv)用于运行MCP Server
3. 项目依赖由 `uv` 根据 `pyproject.toml` 自动安装，其中 `pymochow` 固定为 `2.4.1`

## 使用方式

使用百度云向量数据库MCP Server的推荐方式是通过`uv`运行，而无需进行安装。

克隆代码仓库，执行以下命令：
```
git clone https://github.com/baidu/mochow-mcp-server-python.git
cd mochow-mcp-server-python
```
随后，你可以直接通过`uv`运行，其中`endpoint`、`user`和`api-key`根据实际需要修改：
```
uv run src/mochow_mcp_server/server.py
uv run src/mochow_mcp_server/server.py --transport stdio --endpoint http://127.0.0.1:8287 --user root --api-key mochow
```

或者，将`src/mochow_mcp_server/example.env`复制为当前运行目录下的`.env`来设置环境变量。若从仓库根目录运行以下命令，`.env`应放在仓库根目录：
```
uv run src/mochow_mcp_server/server.py
```

非空环境变量会覆盖命令行参数；如果 `.env` 中已经设置了 `MOCHOW_ENDPOINT`、`MOCHOW_USER`、`MOCHOW_API_KEY` 或 `MOCHOW_MCP_*`，对应的命令行参数不会生效。

### MCP协议

当前支持两种 MCP transport：

- `stdio`：默认协议，适合 Claude Desktop、Cursor 和本地 MCP client 以子进程方式启动。
- `sse`：HTTP SSE 协议，适合需要独立 MCP Server 进程并通过 HTTP 连接的 MCP client。

stdio 启动示例：

```
uv run src/mochow_mcp_server/server.py \
  --transport stdio \
  --endpoint http://127.0.0.1:8287 \
  --user root \
  --api-key mochow
```

SSE 启动示例：

```
uv run src/mochow_mcp_server/server.py \
  --transport sse \
  --host 127.0.0.1 \
  --port 8000 \
  --endpoint http://127.0.0.1:8287 \
  --user root \
  --api-key mochow
```

SSE 默认监听与路径：

- host：`0.0.0.0`
- port：`8000`
- SSE endpoint：`/sse`
- message endpoint：`/messages/`

可选运行参数：

- `--transport`: `stdio` 或 `sse`，默认 `stdio`
- `--host`: SSE 服务监听地址
- `--port`: SSE 服务监听端口
- `--sse-path`: SSE endpoint 路径
- `--message-path`: SSE message endpoint 路径
- `--log-level`: SSE transport 使用的 Uvicorn 日志级别

对应环境变量：

- `MOCHOW_MCP_TRANSPORT`
- `MOCHOW_MCP_HOST`
- `MOCHOW_MCP_PORT`
- `MOCHOW_MCP_SSE_PATH`
- `MOCHOW_MCP_MESSAGE_PATH`
- `MOCHOW_MCP_LOG_LEVEL`

SSE 会暴露 HTTP 服务；本地使用建议显式设置 `--host 127.0.0.1`，不要把未加鉴权的 MCP Server 直接暴露到不可信网络。

## 支持的应用程序

百度云向量数据库MCP Server可以与各种支持模型上下文协议的大语言模型应用程序配合使用：

- **Claude Desktop**：Anthropic 公司为 Claude 开发的桌面应用程序

- **Cursor**：支持 MCP 的人工智能代码编辑器

- **自定义 MCP 客户端**：任何实现 MCP 客户端规范的应用程序

## 在Claude Desktop中的使用方式

从[https://claude.ai](https://claude.ai/download)下载 Claude Desktop。

打开 Claude Desktop 的配置文件，在 macOS 系统中，路径为`~/Library/Application Support/Claude/claude_desktop_config.json`。

添加以下配置：
```JSON
{
    "mcpServers": {
        "mochow": {
            "command": "/PATH/TO/uv",
            "args": [
                "--directory",
                "/path/to/mochow-mcp-server-python",
                "run",
                "src/mochow_mcp_server/server.py",
                "--endpoint",
                "http://127.0.0.1:8287",
                "--user",
                "root",
                "--api-key",
                "mochow"
            ]
        }
    }
}
```
重启 Claude Desktop。

## 在 Cursor 中的使用方法

[Cursor 也支持 MCP](https://docs.cursor.com/context/model-context-protocol)工具。你可以通过以下方式将百度MCP Server添加到Cursor中：

依次打开`Cursor设置`>`功能`>`MCP`，点击`+添加新的MCP服务器`按钮，在`mcp.json`中添加以下配置：
```JSON
{
    "mcpServers": {
        "mochow": {
            "command": "/PATH/TO/uv",
            "args": [
                "--directory",
                "/path/to/mochow-mcp-server-python",
                "run",
                "src/mochow_mcp_server/server.py",
                "--endpoint",
                "http://127.0.0.1:8287",
                "--user",
                "root",
                "--api-key",
                "mochow"
            ]
        }
    }
}
```
重启 Cursor 或重新加载窗口。

## 可用工具

百度云向量数据库MCP Server提供以下工具：

除 `list_databases`、`create_database` 和 `use_database` 外，Table、索引、数据和检索操作都需要先调用 `use_database` 选择目标 Database。

### Database操作

- `list_databases`: 列出数据库中所有的Database

- `create_database`: 创建一个新的Database

  - 参数：
    - `database_name`: 待创建的Database名称

- `use_database`: 切换到一个已存在的Database

  - 参数：
    - `database_name`: 待切换的Database名称

### Table操作

- `list_tables`: 列出数据库中所有的Table

- `create_table`: 创建一个新的Table

  - 参数：
    - `table_name`: Table名称
    - `fields`: 字段定义列表，支持 `field_name`、`field_type`、`primary_key`、`partition_key`、`not_null`、`dimension` 等结构化字段；主键和分区键字段省略 `not_null` 时会按非空处理，显式设置 `not_null: false` 会被拒绝
    - `indexes`: 可选索引定义列表，支持向量索引、倒排索引、二级索引和过滤索引；倒排索引使用 `index_type: INVERTED`，兼容 `BM25`/`FULLTEXT` 别名，字段类型必须是 `TEXT`、`TEXT_GBK` 或 `TEXT_GB18030`，未指定 analyzer 时默认使用 `ENGLISH_ANALYZER`
    - `replication`: 副本数
    - `partition_num`: 分区数量
    - `partition_type`: 分区类型
    - `enable_dynamic_field`: 是否启用动态字段
    - `description`: Table描述
    - `ttl`: 数据过期时间，0 表示不启用

- `describe_table`: 获取指定Table的详细信息

  - 参数：
    - `table_name`: Table名称

- `stats_table`: 获取指定Table的统计信息

  - 参数：
    - `table_name`: Table名称

### 数据操作

- `upsert_rows`: 向Table中写入或覆盖数据

  - 参数：
    - `table_name`: Table名称
    - `rows`: 待写入的数据行列表
    - `vector_fields`: 可选向量字段类型映射，例如 `{"vector": "FLOAT"}`

- `update_rows`: 使用主键局部更新已有数据

  - 参数：
    - `table_name`: Table名称
    - `updates`: 更新操作列表，每项包含 `primary_key`、可选 `partition_key` 和
      `update_fields`
    - `vector_fields`: 可选向量字段类型映射；当 `update_fields` 中包含向量字段时使用

- `query_rows`: 使用主键查询数据

  - 参数：
    - `table_name`: Table名称
    - `primary_key`: 主键字段和值
    - `partition_key`: 可选分区键字段和值
    - `output_fields`: 查询结果中要返回的字段名
    - `retrieve_vector`: 是否返回向量字段
    - `read_consistency`: 读一致性，支持 `EVENTUAL` 和 `STRONG`

- `batch_query_rows`: 使用多个主键批量查询数据

  - 参数：
    - `table_name`: Table名称
    - `keys`: 主键列表，每项必须包装为 `{"primary_key": {"id": "row_1"}}`，可包含 `partition_key`；不要直接传 `{"id": "row_1"}`
    - `output_fields`: 查询结果中要返回的字段名
    - `retrieve_vector`: 是否返回向量字段
    - `read_consistency`: 读一致性，支持 `EVENTUAL` 和 `STRONG`

- `delete_table_rows`: 使用过滤表达式删除数据

  - 参数：
    - `table_name`: Table名称
    - `filter_expr`: 过滤表达式，字符串值必须使用单引号，例如 `id = 'row_1'`

- `delete_rows_by_key`: 使用主键删除单行数据

  - 参数：
    - `table_name`: Table名称
    - `primary_key`: 主键字段和值
    - `partition_key`: 可选分区键字段和值

- `select_table_rows`: 使用过滤表达式查询数据

  - 参数：
    - `table_name`: Table名称
    - `filter_expr`: 过滤表达式，字符串值必须使用单引号，例如 `id = 'row_1'`
    - `limit`: 查询结果的最大条数
    - `output_fields`: 查询结果中要返回的字段名
    - `read_consistency`: 读一致性，支持 `EVENTUAL` 和 `STRONG`

### 索引操作

- `create_vector_index`: 在指定向量字段上创建向量索引
  同一向量字段不要重复创建多个向量索引；验证创建/删除生命周期时，使用未建索引字段或临时表。

  - 参数：
    - `table_name`: Table名称
    - `index_name`: 向量索引名称
    - `field_name`: 向量字段名称
    - `index_type`: 向量索引类型
    - `metric_type`: 向量索引的距离度量
    - `params`: 向量索引的创建参数
    - `auto_build`: 是否在创建索引后立即触发一次 `rebuild_vector_index`
    - `auto_build_policy`: 可选，Mochow 原生自动构建策略；设置后会发送 `autoBuildPolicy`，支持 `TIMING`、`PERIODICAL`、`ROW_COUNT_INCREMENT`

  - 支持的向量索引类型：
    - `FLAT`
    - `HNSW`
    - `HNSWPQ`
    - `HNSWSQ`
    - `PUCK`
    - `IVF`
    - `IVFSQ`
    - `DISKANN`
    - `SPARSE_OPTIMIZED_FLAT`

- `create_scalar_index`: 创建标量索引

  - 参数：
    - `table_name`: Table名称
    - `index_name`: 索引名称
    - `field_name`: 单字段索引的字段名；创建 `SECONDARY` 索引时目标字段必须在建表时设置 `not_null: true`
    - `fields`: 多字段过滤索引的字段名列表
    - `index_type`: 标量索引类型，支持 `SECONDARY` 和 `FILTERING`

- `rebuild_vector_index`: 重新构建指定向量索引

  - 参数：
    - `table_name`: Table名称
    - `index_name`: 向量索引名称

- `drop_vector_index`: 删除指定向量索引

  - 参数：
    - `table_name`: Table名称
    - `index_name`: 向量索引名称

- `describe_index`: 获取指定索引的详情信息

  - 参数：
    - `table_name`: Table名称
    - `index_name`: 索引名称

### 检索操作

- `vector_search`: 执行带标量过滤的向量相似性检索

  - 参数：
    - `table_name`: Table名称
    - `vector`: 向量
    - `vector_field`: 向量字段名称
    - `limit`: 相似性检索结果中返回最接近目标向量的记录数量
    - `filter_expr`: 过滤表达式
    - `output_fields`: 查询结果中要返回的字段名
    - `params`: 检索参数，支持 `ef`、`pruning`、`searchCoarseCount`、`nprobe`、`W`、`searchL`、`twoPhaseRetrieval` 等
    - `offset`: 结果偏移量
    - `vector_type`: 向量类型，支持 `FLOAT`、`BINARY` 和 `SPARSE_FLOAT`

- `vector_range_search`: 执行向量距离范围检索

  - 参数：
    - `table_name`: Table名称
    - `vector`: 向量
    - `distance_near`: 距离范围下界
    - `distance_far`: 距离范围上界
    - `vector_field`: 向量字段名称
    - `limit`: 返回结果数量
    - `filter_expr`: 过滤表达式
    - `output_fields`: 查询结果中要返回的字段名
    - `params`: 检索参数
    - `offset`: 结果偏移量
    - `vector_type`: 向量类型

- `fulltext_search`: 执行全文检索

  - 参数：
    - `table_name`: Table名称
    - `index_name`: 倒排索引名称
    - `search_text`: 全文检索的检索表达式
    - `limit`: 全文检索返回相关性最高的条目数
    - `filter_expr`: 过滤表达式
    - `output_fields`: 查询结果中要返回的字段名

- `hybrid_search`: 执行向量检索和BM25全文检索融合

  - 参数：
    - `table_name`: Table名称
    - `vector`: 向量
    - `index_name`: 倒排索引名称
    - `search_text`: 全文检索表达式
    - `vector_field`: 向量字段名称
    - `limit`: 返回结果数量
    - `filter_expr`: 过滤表达式
    - `output_fields`: 查询结果中要返回的字段名
    - `vector_weight`: 向量检索权重
    - `bm25_weight`: BM25检索权重
    - `params`: 向量检索参数
    - `vector_type`: 向量类型

## 环境变量

- `MOCHOW_ENDPOINT`: 百度云向量数据库连接实例URI
- `MOCHOW_USER`: 百度云向量数据库实例认证用户，默认值为 `root`
- `MOCHOW_API_KEY`: 百度云向量数据库实例API密钥

## 验证

### 基础语法检查

```
uv run python -m compileall src
```

## 使用样例

### 使用Claude Desktop

#### Example 1: 列出数据库中所有的Database

```
How many databases do i have in the mochow db?
```
Claude将使用百度云向量数据库MCP Server提供的list_databases来获取数据库列表.

```
Let me check how many databases you have in the Mochow instance.

You have 2 databases in your Mochow instance:

1. book
2. test
```

#### Example 2: 查看指定表的schema信息

```
I want to get the detail of table named book_segments in database book.
```

Claude将使用百度云向量数据库MCP Server提供的describe_table来获取表的详情信息.

```
I'll help you get the details of the "book_segments" table in the "book" database. Let me first switch to the "book" database and then describe the table.

Here's the information about the "book_segments" table in the "book" database:

Database: book
Table Name: book_segments
Creation Time: 2025-05-06 11:08:22
State: NORMAL

Schema:

id (STRING)
Primary Key: Yes
Partition Key: Yes
Not Null: Yes

bookName (STRING)
Not Null: Yes

author (STRING)
Not Null: No

page (UINT32)
Not Null: No

segment (TEXT)
Not Null: No

vector (FLOAT_VECTOR)
Not Null: Yes
Dimension: 1024

Indexes
book_name_filtering_idx (FILTERING_INDEX)
Field: bookName
Order: ASCEND
Structure Type: DEFAULT

vector_idx (HNSW)
Field: vector
Metric Type: L2
Auto Build: False
Parameters: (M: 16 efConstruction: 200)
```
