关键词

Gen3数据共享平台Schema元数据GraphQL查询数据访问工具调用

项目简介

该项目是一个基于Model Context Protocol (MCP) 实现的应用后端，旨在将大模型客户端（如AI助手）与Gen3数据共享平台集成。它通过标准化的JSON-RPC接口，提供访问Gen3 Schema（数据模型）、构建和验证GraphQL查询以及执行数据查询的能力，帮助LLM理解Gen3数据结构并安全地进行数据交互。

主要功能点

  • Schema元数据访问: 提供丰富的Schema信息，包括实体（Entity）、字段、关系（Relationship）等，帮助LLM理解数据模型的结构。
  • Schema结构注释: 对Schema信息进行处理和注释，提供实体的层级位置（Root/Intermediate/Leaf）、字段列表、关系描述以及针对每个实体的GraphQL查询示例，便于LLM快速发现和利用Schema信息。
  • 查询模板生成: 根据指定的实体名称，生成包含常用字段和基本关系的GraphQL查询模板，作为LLM构建查询的起点。
  • GraphQL查询验证: 在执行查询前，根据Gen3 Schema对GraphQL查询的语法和字段进行验证，有效减少因幻觉或Schema不匹配导致的查询错误，并提供修改建议。
  • GraphQL查询执行: 执行经过验证的GraphQL查询，并将结果返回给LLM客户端，实现对Gen3数据共享平台的数据访问。
  • 工作流程指导: 提供关于如何发现Schema、构建查询和执行查询的推荐工作流程资源，帮助LLM或其他客户端更好地使用提供的工具。

安装步骤

该项目是一个Python应用，需要Python环境。

  1. 克隆该项目的代码仓库到本地。
  2. 进入项目目录，安装所需的Python依赖库（通常通过'pip install -r requirements.txt'或'pip install .'）。

服务器配置

MCP客户端需要配置如何启动该MCP服务器进程并与之通信。以下是一个示例JSON配置，用于指示客户端通过标准输入/输出（stdio）与服务器建立连接。客户端无需关心Gen3平台的具体配置（如证书路径、Gen3基础URL等），这些配置由MCP服务器自身在启动时读取（通常通过环境变量或配置文件）。

{
  "name": "gen3",
  "command": "python",
  "args": ["-m", "gen3_mcp.main"],
  "transport": "stdio"
}

配置项说明：

  • 'name': MCP服务器的唯一名称，本实现中固定为 "gen3"。
  • 'command': 启动服务器进程的命令，这里指定为执行Python解释器。
  • 'args': 传递给'command'的参数列表，'-m gen3_mcp.main'指示Python运行'gen3_mcp.main'模块作为主程序，即启动MCP服务器。
  • 'transport': 通信协议，这里指定使用标准输入/输出（stdio）。

注意: 实际的Gen3凭证文件路径或API地址等服务器端配置，需要在使用该MCP服务器的环境中通过设置相应的环境变量（如'GEN3_CREDENTIALS_FILE', 'GEN3_BASE_URL'）或修改服务器代码中的默认值来完成，而不是通过MCP客户端配置传递。

基本使用方法

通过兼容MCP协议的客户端（如LLM应用），连接到该MCP服务器后，可以调用其暴露的Resources和Tools。

  1. 发现Schema和工具: 客户端可以读取以下Resources获取信息：
    • 'gen3://tools-by-category': 获取按类别组织的可用工具列表及其用途。
    • 'gen3://workflow': 获取推荐的数据探索和查询工作流程。
    • 'gen3://endpoints': 获取Gen3 API端点信息。
    • 'gen3://info': 获取MCP服务器及所连接Gen3实例的基本信息。
  2. 探索Schema详情: 调用 'annotated_schema_structure()' 工具，获取完整的Gen3数据模型结构，包括所有实体、字段、关系、Schema摘要和查询示例。
  3. 构建GraphQL查询:
    • 调用 'query_template(entity_name="...")' 工具，为指定实体生成一个安全、有效的查询模板作为起点。
    • 根据需求修改查询模板。
  4. 验证查询: 调用 'validate_query(query="...")' 工具，在执行前检查修改后的GraphQL查询是否存在语法错误或无效的实体/字段名。根据返回结果中的建议进行修正。
  5. 执行查询: 调用 'execute_graphql(query="...")' 工具，执行通过验证的GraphQL查询，获取Gen3平台上的实际数据。

推荐遵循 'gen3://workflow' 中描述的流程，尤其是在修改查询后总是先进行验证 ('validate_query')，以最大限度地提高数据访问的成功率。

信息

分类

数据库与文件

访问项目