Gen3 MCP Server

第三代MCP服务器

用于与Gen3元数据服务交互的模型上下文协议（MCP）服务器。此服务器提供用于管理Gen3公共资源中的元数据、对象及其关系的工具。

特性

• 元数据管理

- 搜索和检索元数据 - 创建、更新和删除元数据记录 - 聚合元数据操作

• 对象管理

- 使用元数据创建对象 - 获取已签名的下载URL

• 使用Pydantic模型进行输入验证
• 错误处理和详细响应
• 通过访问令牌提供身份验证支持

配置

服务器需要以下环境变量：

GEN3_URL=https://your-gen3-commons.org
GEN3_ACCESS_TOKEN=your-access-token  # Required for authenticated operations

创建一个 .env 包含这些变量的项目根目录中的文件。

安装

1. 确保已安装Python 3.12+
2. 安装依赖项：

uv pip install -r requirements.txt

在本地运行

uv run gen3.py

Docker实现

构建Docker镜像

docker build -t gen3-mcp-server .

使用Docker运行

1. 创建一个 .env 包含Gen3配置的文件：

GEN3_URL=https://your-gen3-commons.org
GEN3_ACCESS_TOKEN=your-access-token

1. 运行容器：

docker run --env-file .env gen3-mcp-server

在基于Docker的MCP客户端中使用

当将此服务器与基于Docker的MCP客户端一起使用时，请更新您的客户端配置：

{
    "mcpServers": {
        "gen3": {
            "image": "gen3-mcp-server",
            "env": {
                "GEN3_URL": "https://your-gen3-commons.org",
                "GEN3_ACCESS_TOKEN": "your-access-token"
            }
        }
    }
}

可用工具

元数据操作

1. get_aggregate_metadata

- 通过过滤和分页获取聚合元数据 - 参数： - 限制：要返回的最大记录数（最大值：2000） - 偏移：分页偏移 - counts：返回数组字段的计数 - flat：删除公共分组 - 分页：包括分页信息

1. search_metadata

- 使用查询参数搜索元数据 - 参数： - query：搜索参数字典 - params：可选的MetadataSearchParams用于分页

1. get_metadata_by_guid

- 获取特定GUID的元数据 - 参数： - guid:用于获取元数据的guid

1. create_metadata

- 为GUID创建或更新元数据 - 参数： - guid:目标guid - 元数据：元数据字典 - overwrite：是否覆盖现有数据

1. update_metadata

- 更新GUID的元数据 - 参数： - guid:目标guid - 元数据：新元数据 - merge：是否与现有数据合并

1. delete_metadata

- 删除GUID的元数据 - 参数： - guid:用于删除元数据的guid

对象操作

1. create_object

- 使用元数据创建新对象 - 参数： - input_data:CreateObjectInput模型，具有： - file_name：文件的名称 - authz：授权要求 - 别名：可选的唯一名称 - 元数据：可选的附加元数据

1. get_object_download_url

- 获取对象的签名下载URL - 参数： - guid：对象guid

添加到MCP客户端

将以下配置添加到MCP客户端设置中：

{
    "mcpServers": {
        "gen3": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/gen3-mcp-server",
                "run",
                "gen3.py"
            ],
            "env": {
                "GEN3_URL": "https://your-gen3-commons.org",
                "GEN3_ACCESS_TOKEN": "your-access-token"
            }
        }
    }
}

示例用法

# Search metadata
result = await search_metadata(
    query={"data_type": "clinical"},
    params={"limit": 10, "offset": 0}
)

# Create metadata
metadata = {
    "data_type": "clinical",
    "file_format": "csv",
    "file_size": 1024
}
result = await create_metadata("guid-123", metadata)

# Get download URL
url = await get_object_download_url("guid-123")

错误处理

当操作失败时，所有工具都会返回一个带有“error”键的字典：

{
    "error": "Unable to fetch metadata for GUID: guid-123"
}

发展

要添加新工具或修改现有工具，请执行以下操作：

1. 定义输入验证所需的任何新Pydantic模型
2. 使用添加工具 @mcp.tool() 装饰器
3. 使用新工具的文档更新README
4. 使用各种输入和错误条件测试工具