使用说明

项目简介

本项目是一个演示性质的MCP服务器实现，展示了如何通过“数据句柄”（Data Handles）来管理和操作 pandas DataFrame。与直接将大量数据返回给LLM不同，该服务器返回和接收数据句柄（UUID字符串），句柄指向存储在服务器内存中的数据。这种方式可以有效减少数据传输量，并允许LLM通过句柄调用不同的工具来操作数据。

项目提供了两种工具API的实现方式：

简化的 DataFrame 抽象 API: 提供预定义的一组常用 DataFrame 操作，接口安全可控，适用于基础数据操作。
通用的 Pandas 操作 API: 允许执行任意 pandas 代码，功能更灵活，但需注意安全风险。

主要功能点

资源管理 (Resources): 使用数据句柄在服务器端内存中托管和管理 pandas DataFrame。
工具注册和执行 (Tools):
- DataFrame 抽象 API: 提供 'query_database', 'combine_columns', 'join_dataframes', 'get_shape', 'get_head', 'get_top_n_rows' 等工具，用于常见的 DataFrame 操作。
- 通用 Pandas API: 提供 'query_database', 'execute_pandas_code', 'materialize_dataframe', 'get_shape' 等工具，允许执行任意 Pandas 代码，并能将 DataFrame 数据以多种格式（字符串、JSON、CSV）返回给客户端。
会话管理: 通过句柄在服务器端维护会话状态，LLM客户端可以通过句柄引用之前操作的数据。
能力声明: 通过 MCP 协议声明服务器提供的工具和功能。
多种传输协议支持: 默认使用 Stdio (标准输入输出) 作为传输协议。

安装步骤

克隆仓库: 将 GitHub 仓库 'https://github.com/EvanOman/mcp-data-handles' 克隆到本地。

git clone https://github.com/EvanOman/mcp-data-handles
cd mcp-data-handles

安装依赖: 建议使用 'uv' 或 'pip' 等工具创建虚拟环境并安装项目依赖。

# 使用 uv (如果已安装 uv):
uv venv
uv pip install -r requirements.txt

# 或者使用 pip:
python -m venv venv
source venv/bin/activate  # 或 venv\Scripts\activate (Windows)
pip install -r requirements.txt

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令和参数才能连接。以下是针对本项目提供的两种服务器实现的配置示例 (JSON 格式)：

1. DataFrame 抽象 API 服务器配置 (df-abstractions-handler-demo):

{
  "serverName": "df-abstractions-handler-demo",
  "command": "uv",
  "args": [
    "run",
    "-m",
    "mcp_handles_server.df_abstractions"
  ]
}

serverName: 服务器名称，客户端用于标识和引用该服务器。
command: 启动服务器的命令，这里使用 'uv run' (或 'python -m' 如果使用 pip)。
args: 传递给命令的参数列表：
- '"run"': 'uv' 的运行命令。
- '"-m"': Python 模块参数，表示运行一个模块。
- '"mcp_handles_server.df_abstractions"': 要运行的 Python 模块，指向 'mcp_handles_server' 目录下的 'df_abstractions.py' 文件，该文件实现了 DataFrame 抽象 API 服务器。

2. 通用 Pandas API 服务器配置 (generic-pandas-handler-demo):

{
  "serverName": "generic-pandas-handler-demo",
  "command": "uv",
  "args": [
    "run",
    "-m",
    "mcp_handles_server.pandas_generic"
  ]
}

配置与 DataFrame 抽象 API 服务器类似，主要区别在于 'args' 中指定的模块为 '"mcp_handles_server.pandas_generic"'，指向 'pandas_generic.py' 文件，该文件实现了通用 Pandas API 服务器。

注意:

'command' 和 'args' 需要根据你的实际环境进行调整。例如，如果未使用 'uv'，可以将 'command' 更改为 'python' 或 'python3'，并相应调整 'args'。
确保 MCP 客户端能够找到并执行配置的 'command'。如果 'uv' 或 'python' 不在系统 PATH 环境变量中，需要提供完整的路径。
配置中的 'serverName' 字段可以自定义，但在客户端引用时需要保持一致。

基本使用方法

启动服务器: 根据你选择的 API 类型，运行相应的命令来启动 MCP 服务器。

DataFrame 抽象 API 服务器:

uv run -m mcp_handles_server.df_abstractions

通用 Pandas API 服务器:

uv run -m mcp_handles_server.pandas_generic

服务器成功启动后，会监听来自 MCP 客户端的请求。

配置 MCP 客户端: 在你的 MCP 客户端（例如 MCP Inspector, Claude Desktop, 或 OpenAI Agents SDK）中，根据上述 "服务器配置" 部分的说明，添加或配置 MCP 服务器连接信息，选择相应的 'serverName' 和配置。
使用客户端与服务器交互: 通过 MCP 客户端向服务器发送请求，例如：
- 使用 'query_database' 工具加载数据表并获取数据句柄。
- 使用其他工具（如 'combine_columns', 'join_dataframes', 'execute_pandas_code' 等）和数据句柄来操作数据。
- 使用 'materialize_dataframe' 工具将数据句柄指向的 DataFrame 数据以指定格式返回给客户端。
具体操作方式取决于你使用的 MCP 客户端的功能和界面。可以参考仓库 README 中提供的 MCP Inspector, Claude Desktop 和 OpenAI Agents SDK 的使用示例。

安全提示: 通用 Pandas API ('pandas_generic.py') 提供了 'execute_pandas_code' 工具，允许执行任意 Python 代码，在生产环境中使用时存在严重的安全风险，请务必谨慎评估和采取必要的安全措施 (例如沙箱隔离)。 DataFrame 抽象 API ('df_abstractions.py') 提供了更安全、可控的接口，推荐在对安全性有较高要求的场景中使用。

关键词