使用说明

项目简介

本项目是阿里云表格存储（Tablestore）的MCP服务器实现，旨在为大型语言模型（LLM）应用提供一个高效、可扩展的后端服务，用于文档数据的存储和基于向量相似度的快速检索。通过MCP协议，LLM客户端可以方便地调用服务器提供的工具，实现与表格存储的无缝集成，从而构建具备上下文感知能力的AI应用。

主要功能点

文档存储 (store): 允许LLM应用将自然语言文档及其元数据存储到阿里云表格存储中，为后续的检索和知识库构建打下基础。
文档检索 (search): 支持基于自然语言描述的相似文档检索。利用向量嵌入技术，能够根据用户输入的查询语句，在表格存储中快速找到语义相关的文档。

安装步骤

环境准备

Java版本: 确保已安装JDK 1.8或更高版本。
Python版本: 建议使用Python 3.8或更高版本，并安装必要的依赖包（见具体语言版本的README）。
阿里云表格存储服务: 需要开通阿里云表格存储服务，并准备好以下信息：
- 'instance_name': 表格存储实例名称
- 'end_point': 表格存储Endpoint
- 'access_key_id': 阿里云Access Key ID
- 'access_key_secret': 阿里云Access Key Secret

下载代码

git clone https://github.com/aliyun/alibabacloud-tablestore-mcp-server.git
cd alibabacloud-tablestore-mcp-server

选择并进入对应语言版本的目录

本项目提供了Java和Python两个版本的实现，您可以根据需要选择其一。

Java版本: 'cd tablestore-java-mcp-server'
Python版本: 'cd tablestore-python-mcp-server'

Java版本构建和运行

构建: 在'tablestore-java-mcp-server'目录下，使用Maven进行构建：
```
mvn clean install
```
运行: 构建成功后，在'tablestore-java-mcp-server'目录下，运行Spring Boot应用。您需要设置以下环境变量：
- 'TABLESTORE_INSTANCE_NAME': 您的表格存储实例名称
- 'TABLESTORE_ENDPOINT': 您的表格存储Endpoint
- 'TABLESTORE_ACCESS_KEY_ID': 您的阿里云Access Key ID
- 'TABLESTORE_ACCESS_KEY_SECRET': 您的阿里云Access Key Secret
```
mvn spring-boot:run
```

Python版本安装和运行

安装依赖: 在'tablestore-python-mcp-server'目录下，创建并激活虚拟环境（可选），然后安装依赖：

python3 -m venv venv  # 创建虚拟环境 (可选)
source venv/bin/activate # 激活虚拟环境 (可选)
pip install -r requirements.txt

运行: 在'tablestore-python-mcp-server'目录下，运行MCP服务器。您需要设置以下环境变量：
- 'TABLESTORE_INSTANCE_NAME': 您的表格存储实例名称
- 'TABLESTORE_ENDPOINT': 您的表格存储Endpoint
- 'TABLESTORE_ACCESS_KEY_ID': 您的阿里云Access Key ID
- 'TABLESTORE_ACCESS_KEY_SECRET': 您的阿里云Access Key Secret
```
python src/tablestore_mcp_server/main.py --transport sse
```
或使用stdio传输协议:
```
python src/tablestore_mcp_server/main.py --transport stdio
```

服务器配置 (MCP客户端配置)

MCP客户端需要配置连接到此MCP服务器的信息。以下是配置示例 (JSON格式)：

Java 版本 MCP 服务器配置

{
  "serverName": "tablestore-java-mcp-server",
  "command": "mvn",
  "args": [
    "spring-boot:run"
  ],
  "transport": "stdio"  // 或 "sse", 根据实际服务器运行方式配置
}

参数注释:

'serverName': 服务器名称，自定义即可。
'command': 启动服务器的命令，Java版本使用Maven Spring Boot插件运行。
'args': 命令参数，Java版本无需额外参数。
'transport': 传输协议，与服务器运行的传输协议保持一致 (例如 'stdio' 或 'sse')。

Python 版本 MCP 服务器配置 (SSE 传输)

{
  "serverName": "tablestore-python-mcp-server-sse",
  "command": "python",
  "args": [
    "src/tablestore_mcp_server/main.py",
    "--transport",
    "sse"
  ],
  "transport": "sse"
}

Python 版本 MCP 服务器配置 (Stdio 传输)

{
  "serverName": "tablestore-python-mcp-server-stdio",
  "command": "python",
  "args": [
    "src/tablestore_mcp_server/main.py",
    "--transport",
    "stdio"
  ],
  "transport": "stdio"
}

参数注释 (Python版本通用):

'serverName': 服务器名称，自定义即可。
'command': 启动服务器的命令，Python版本使用'python'命令运行主程序。
'args': 命令参数:
- '"src/tablestore_mcp_server/main.py"': 指定主程序文件路径。
- '"--transport"': 指定传输协议。
- '"sse"' 或 '"stdio"': 选择 SSE 或 Stdio 传输协议。
'transport': 传输协议，与服务器运行的传输协议保持一致 ('sse' 或 'stdio')。

环境变量配置 (Java 和 Python 版本通用)

在运行服务器之前，请确保已设置以下环境变量，这些环境变量是连接阿里云表格存储所必需的：

'TABLESTORE_INSTANCE_NAME': 您的表格存储实例名称
'TABLESTORE_ENDPOINT': 您的表格存储Endpoint
'TABLESTORE_ACCESS_KEY_ID': 您的阿里云Access Key ID
'TABLESTORE_ACCESS_KEY_SECRET': 您的阿里云Access Key Secret

基本使用方法

启动MCP服务器: 按照上述步骤启动Java或Python版本的MCP服务器。
配置MCP客户端: 在您的LLM应用或MCP客户端中，配置上述生成的JSON配置信息，指定连接到正在运行的MCP服务器。
调用工具: 通过MCP客户端，您可以调用服务器提供的 'tablestore-store' (存储文档) 和 'tablestore-search' (检索文档) 工具，与阿里云表格存储进行交互。

示例工具调用 (假设使用MCP客户端 SDK):

存储文档:

client.call_tool(
    "tablestore-store",
    {"information": "这是一篇示例文档的内容。", "metadata": {"source": "example", "tag": "test"}}
)

检索文档:

response = client.call_tool(
    "tablestore-search",
    {"query": "查找与示例文档内容相关的文档", "size": 10}
)
print(response)

请参考MCP客户端SDK的文档，了解如何更详细地配置和使用MCP服务器。

关键词