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 

# 设置 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. 检查实体存在：在构建查询前