AI导哈

Gen3 MCP Server with Schema Validation

Gen3 MCP Server 是一个用于与 Gen3 数据共享平台交互的模型上下文协议（MCP）服务器，提供全面的 GraphQL 查询验证功能，以防止字段名错误。该服务器集成了 Gen3 数据共享平台的核心功能，并提供了一系列工具来帮助用户探索数据模型、执行验证查询以及理解实体关系。

  • by delocalizer
  • 更新于
在 GitHub 查看 delocalizer/gen3-mcp

使用说明

基本能力

产品定位

Gen3 MCP Server 是一个用于与 Gen3 数据共享平台交互的模型上下文协议（MCP）服务器，提供全面的 GraphQL 查询验证功能，以防止字段名错误。

核心功能

Gen3 集成

  • 模式发现：获取完整的数据模型和实体模式
  • GraphQL 查询：针对 Gen3 数据执行验证查询
  • 数据探索：样本记录和字段值分析
  • 关系映射：理解实体连接

模式验证工具

  • 查询验证：在执行前检查 GraphQL 查询是否符合实际模式
  • 字段建议：为无效字段名提供智能建议
  • 安全模板：生成保证字段有效的查询模板
  • 错误预防：在导致失败前捕获字段名错误

适用场景

  • 需要与 Gen3 数据共享平台交互的开发者和数据分析师
  • 需要确保 GraphQL 查询正确性的项目
  • 需要探索和理解 Gen3 数据模型的用户

工具列表

模式发现

  • get_schema_summary() - 所有实体的概览
  • get_full_schema() - 完整的模式（大响应）
  • get_entity_schema(entity_name) - 特定实体的模式
  • list_available_entities() - 所有实体及其关系

数据查询

  • query_graphql(query) - 执行 GraphQL 查询
  • get_field_values(entity, field) - 实际使用的字段值
  • get_sample_records(entity) - 示例记录
  • explore_entity_data(entity) - 全面的实体概览

验证

  • validate_query_fields(query) - 验证查询中的所有字段
  • suggest_similar_fields(field, entity) - 获取字段建议
  • get_query_template(entity) - 生成安全查询模板

常见问题解答

错误预防优势

验证系统防止常见问题：

  1. 字段名错误：在执行查询前捕获不存在的字段
  2. 实体名错误：为拼写错误提供正确的实体名建议
  3. 关系错误：验证关系字段的使用
  4. 模式漂移：确保查询在模式演变时保持有效

使用教程

使用依赖

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

安装教程

# 克隆仓库
git clone <repository-url>

# 设置 Gen3 凭证（参见配置 - 凭证文件部分）

# 设置客户端（参见配置 - 客户端 MCP 部分）

配置

凭证文件

创建一个包含 Gen3 API 密钥的凭证文件 credentials.json

{
  "api_key": "xxxx",
  "key_id": "xxxx"
}

客户端 MCP

Claude 桌面的示例 ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gen3-mcp-server": {
      "command": "uv",
      "args": [
          "--directory",
          "/home/myuser/gen3-mcp",
          "run",
          "gen3.py"
      ],
      "env": {
        "BASE_URL": "https://gen3.datacommons.io/",
        "CREDENTIALS_FILE": "~/credentials.json",
        "LOG_LEVEL": "info"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

调试方式

# 测试验证功能
uv run test_validation.py


# 演示验证功能
uv run demo_validation.py

最佳实践

  1. 始终验证：在执行复杂查询前验证
  2. 从模板开始：为新实体使用模板
  3. 使用建议：学习正确的字段名
  4. 缓存验证结果：对频繁使用的查询
  5. 检查实体存在：在构建查询前

相关 MCP