概述

MCP（Model Context Protocol）是一个开放协议，旨在通过标准化API连接大型语言模型（LLM）与外部数据源及工具，让AI应用能够高效处理复杂任务。本项目构建了基于阿里云表格存储（Tablestore）的MCP服务实现，通过其向量、标量、全文检索的混合检索能力，为MCP工具提供高效的数据存储与检索解决方案。本文将系统讲解技术实现、部署流程及应用场景。

1. 使用示例

这里展示 2 个 tool 的能力，一个是存储工具，一个是搜索工具。 我们使用的软件是热门的开源软件 Cherry-Studio，使用的大模型是通义千问的 qwen-max 模型。

1.1 文档存储工具

功能：将文本数据连同语义向量嵌入表格存储。

• 实现细节通过我们实现的 MCP 的 Store 接口，用户可通过可视化界面直接上传文档：



• 后端行为完整日志显示了数据写入过程：



• 存储结果：表格存储控制台展示结构化数据与向量的存储形态：





1.2 混合检索工具

支持向量相似度+关键词/结构化条件的复合查询。Tablestore(表格存储) 的多元索引支持向量、标量、全文检索等各种类型的组合查询，该示例代码中使用了混合检索，如需更复杂的查询，可以参考文章最后的“贡献代码和二次开发”章节了解如何自定义开发。

• 查询实例通过 Cherry Studio 界面进行多条件搜索，底层调用 MCP 的 Search 接口：



• 检索逻辑：服务端日志展示了向量转换与查询过程：



• 系统验证：表格存储控制台执行等效查询验证结果一致性：
  

2. 技术流程

MCP server 提供的 2 个工具十分简单：

1. 写入: 文档经过 MCP server 内置的 Embedding ( 默认为 BAAI/bge-base-zh-v1.5 ) 模型，写入到Tablestore(表格存储)即可。
2. 查询: 用户的查询文本经过 MCP server 内置的 Embedding 模型转成向量，然后调用表格存储的 多元索引 即可，其内部使用了 向量检索 和 全文检索 进行混合查询，最终召回用户期望的结果。





3. 为什么选择Tablestore？

与传统数据库和专用向量数据库相比，Tablestore(表格存储)在MCP场景中展现出显著优势：

• 混合查询：原生支持向量检索+全文检索+标量检索的联合查询。其多元索引可以完成任意列的查询（包括主键列和非主键列）、多字段自由组合查询、地理位置查询、全文检索、模糊查询、前缀查询、嵌套查询、去重、排序、查询数据总行数和统计聚合等丰富的查询能力。
• Serverless+低成本：Tablestore 提供 Serverless 的结构化数据存储，彻底免除硬件、软件运维与扩容压力。用户按需付费，存储计算分离，无需为闲置资源付费。让用户可以聚焦业务创新，将运维成本降至最低，适合业务快速迭代。
• 弹性扩展：PB级数据处理能力，支持自动水平分片与弹性资源调度。
• 快速落地与全周期支持：开发效率极高，帮助业务实现价值最大化。Tablestore(表格存储)提供标准化API接口/SQL接口，集成LangChain、LlamaIndex、PAI-RAG、LangEngine、LangChain4J、Dify、MCP等各种三方开源框架。
• 数据集成：支持与阿里云大数据生态无缝对接，如RDS、Flink、ODPS等，避免数据孤岛。

4. 本地运行

我们支持 Java 和 Python 2种语言运行 MCP 服务。

4.1 Python 版本

4.1.1 下载源码

1. 使用 git clone 将代码 https://github.com/aliyun/alibabacloud-tablestore-mcp-server 下载到本地。
2. 进入 python 源码的根目录：cd tablestore-mcp-server/tablestore-python-mcp-server

4.1.2 准备环境

代码需要 python3.10  版本以上进行构建，使用了 uv 进行包和环境管理。

• 安装 uv：

# 方式1：使用现有 python3 安装 uv
pip3 install uv

# 方式2：源码安装 uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

• 准备 Python 环境：

如果本地有 python3.10 版本以上环境，无需执行这一小步。

我们项目至少需要 python3.10 版本，这里使用 python3.12 进行示例。

# 查看当前有哪些 python 环境
uv python list

# 如果没有python 3.12.x 相关版本，请安装 python3.12 版本. 内部会从 github 下载 uv 官方维护的 python 包。 
uv python install 3.12

• 创建虚拟环境:

# 使用 python 3.12 版本当做虚拟环境
uv venv --python 3.12

4.1.3 配置环境变量

代码里所有的配置是通过环境变量来实现的，出完整的变量见下方表格。 主要依赖的数据库 表格存储 支持按量付费，使用该工具，表和索引都会自动创建，仅需要在控制台上申请一个实例即可。

4.1.4 Embedding

为了方便，这里不使用云服务的Embedding能力，而使用了内置的本地Embedding模型，示例代码仅支持了 HuggingFace 的本地Embedding模型，使用十分简单，如果网络不好，可以配置 HuggingFace 的镜像。

export HF_ENDPOINT=http://hf-mirror.com

4.1.5 运行 MCP 服务

# 加速下载 Hugging 的 Embedding Model，仅首次需要下载，后续使用本地缓存
export HF_ENDPOINT=http://hf-mirror.com

export TABLESTORE_ACCESS_KEY_ID=xx
export TABLESTORE_ACCESS_KEY_SECRET=xx
export TABLESTORE_ENDPOINT=xxx
export TABLESTORE_INSTANCE_NAME=xxx

# 默认以 sse 模式运行，如果希望以 stdio 模式运行可以添加: `--transport stdio`
uv run tablestore-mcp-server

4.2 Java 版本

4.2.1 编译代码

1. 使用 git clone 将代码 https://github.com/aliyun/alibabacloud-tablestore-mcp-server 下载到本地。
2. 进入 java 源码的根目录：cd tablestore-mcp-server/tablestore-java-mcp-server代码需要 jdk17 版本以上进行构建，使用了 mvn 进行包和环境管理。

# 确保 jdk17 环境
./mvnw package -DskipTests -s settings.xml

4.2.2 配置环境变量

代码里所有的配置是通过环境变量来实现的，出完整的变量见下方表格。 主要依赖的数据库 Tablestore(表格存储) 支持按量付费，使用该工具，表和索引都会自动创建，仅需要在控制台上申请一个实例即可。

4.2.3  Embedding

为了方便，这里不使用云服务的Embedding能力，而使用了内置的本地Embedding模型，这些模型都是可以应用生产的模型，示例代码仅支持了 DeepJavaLibrary 上自带的Embedding模型，基本上都来自 Hugging Face，使用十分简单。

想用其它Embedding模型可以运行 com.alicloud.openservices.tablestore.sample.service.EmbeddingService.listModels() 方法查看支持的模型。

4.2.4 运行 MCP 服务

export TABLESTORE_ACCESS_KEY_ID=xx
export TABLESTORE_ACCESS_KEY_SECRET=xx
export TABLESTORE_ENDPOINT=xxx
export TABLESTORE_INSTANCE_NAME=xxx

java -jar target/tablestore-java-mcp-server-1.0-SNAPSHOT.jar

5. 集成三方工具

5.1 Cherry Studio

Cherry-Studio，是一个热门的开源的 AI Client 软件, 免费使用，其支持 MCP 服务。

• 安装 ：

Github链接 下载最新版本的适合自己机器运行环境的安装包. 比如我的电脑是m1芯片的mac，因此下载 Cherry-Studio-1.1.4-arm64.dmg 进行安装。安装好后，需要配置大模型的 api-key 相关信息，这里不再一一描述。

• 按照如下所示创建MCP服务:



• 在聊天里使用MCP服务

可以把一些模版填充到 Cherry Studio 的模版里，生成一个自己的特殊助手，后续可以直接使用。





6. 拓展应用场景

MCP 的 Tool 的能力和场景是 Tool 的描述来提供的，因此我们可以定义一些特殊的能力，可以发挥你的想象力。另外，当前我们没有接入一些复杂的多字段自由 Filter 能力、稀疏向量(Sparse Vector)能力，后续有时间会继续进行集成。

以Python为例，MCP Server 仅需要修改如下配置即可, 如何写可以参考源码的 settings.py。

  export TOOL_STORE_DESCRIPTION="你的自定义的描述"
  export TOOL_SEARCH_DESCRIPTION="你的自定义的描述"

修改后从 MCP Client 中可以看到工具 (Tool) 的描述已经变成了自定义的描述，那么大模型（LLM）就会根据你的描述去使用工具(Tool)。



7. 贡献代码和二次开发

7.1 Python 版本

如果你需要基于此代码进行二次开发，可以参考如下。

7.1.1 依赖

1. uv tool
   

1. Make sure you are working with PyCharm version 2024.3.2 or later.
2. Configure a uv environment in PyCharm
   

2. python 3.10

7.1.2 本地调试: sse 模式

首先在 PyCharm 里启动 src/tablestore_mcp_server/server.py即可，然后运行可视化调试界面 MCP Inspector, 根据 Terminal的日志提示打开"http://localhost:5173"进行调试。

# 启动 MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

即可连接并展示MCP的一些能力，我们这里仅仅使用了Tools，可以直接在界面上进行调试和运行。



7.1.3 本地调试: stdio 模式

下面命令会自动运行 MCP Inspector，打开UI界面使用 stdio 进行链接即可，但是体验没有 sse 模式友好。因此建议 AI client 使用 sse 传输连接到 MCP 服务器，sse 模式可以轻松地与你的团队共享服务器或在云环境中使用。

mcp dev src/tablestore_mcp_server/server.py

7.1.4 代码格式化和测试

运行测试前，需要配置Tablestore相关的4个环境变量。

pytest --log-cli-level=INFO

提交代码前，自己运行代码检查和格式化。

ruff check
ruff format

7.2 Java 版本

7.2.1 本地调试: sse 模式

首先在 IDEA 里启动 Spring 的 App.java 文件即可。然后运行可视化调试界面 MCP Inspector, 根据 Terminal的日志提示打开"http://localhost:5173"进行调试。

# 启动 MCP Inspector
 npx @modelcontextprotocol/inspector node build/index.js

即可连接并展示MCP的一些能力，我们这里仅仅使用了Tools，可以直接在界面上进行调试和运行。