Catalysis Hub MCP 服务器

一个模型上下文协议 (MCP) 服务器接口，用于连接 Catalysis Hub 的 GraphQL API，从而可以通过灵活的 GraphQL 查询以编程方式访问催化研究数据。

主要特性

• 直接 GraphQL 访问: 执行任何有效的 GraphQL 查询，访问 Catalysis Hub 的 API
• 全面的数据访问:
  • 催化反应 (方程式、条件、催化剂)
  • 材料体系 (结构、性质、描述符)
  • 研究出版物 (标题、DOI、作者)
  • 表面反应数据 (吸附能、结合位点)
• MCP 标准合规: 实现了用于 AI 代理互操作的模型上下文协议
• 灵活的查询支持: 使用变量参数化执行复杂查询
• 错误处理: 针对 API 连接和查询执行的强大错误报告

实现细节

• 服务器配置 (与 claude_desktop_config.json 匹配):

  {
    "command": "/Users/quentincody/.env/bin/python3",
    "args": ["/Users/quentincody/catalysishub-mcp-server/catalysishub_mcp_server.py"],
    "options": {
      "cwd": "/Users/quentincody/catalysishub-mcp-server"
    }
  }
  

• 核心依赖: httpx 用于异步 HTTP 请求
• 传输: 遵循 MCP 规范的标准输入/输出通信

安装 & 设置

1. 克隆仓库:

   git clone <repository_url>
   cd catalysishub-mcp-server
   

2. 安装依赖:

   pip install -r requirements.txt
   

3. 验证安装:

   python3 catalysishub_mcp_server.py --version
   # 应该输出: catalysishub-mcp-server 0.1.0
   

使用示例

基本查询执行

from mcp.client import MCPClient

async with MCPClient("catalysishub") as hub:
    result = await hub.catalysishub_graphql(
        query="""{
            reactions(first: 5) {
                edges {
                    node {
                        id
                        Equation
                        Temperature
                    }
                }
            }
        }"""
    )
    print(json.loads(result))

带变量的参数化查询

variables = {
    "materialId": "mp-1234",
    "firstResults": 5
}

response = await hub.catalysishub_graphql(
    query="""query GetMaterial($materialId: String!, $firstResults: Int!) {
        systems(uniqueId: $materialId) {
            edges {
                node {
                    energy
                    Cifdata
                    relatedReactions(first: $firstResults) {
                        edges {
                            node {
                                id
                                Equation
                            }
                        }
                    }
                }
            }
        }
    }""",
    variables=variables
)

查询优化技巧

1. 使用 GraphQL 片段:

   fragment ReactionDetails on Reaction {
       id
       Equation
       ActivationEnergy
       Catalyst {
           formula
           surface
       }
   }
   
   query {
       reactions(first: 10) {
           edges {
               node {
                   ...ReactionDetails
               }
           }
       }
   }
   

2. 批量处理相关查询:

   query BatchQuery {
       reactions: reactions(first: 5) { edges { node { id Equation } } }
       materials: systems(first: 5) { edges { node { formula energy } } }
   }
   

响应结构

成功的响应遵循以下结构:

{
    "data": { /* 查询结果 */ },
    "extensions": {
        "responseMetadata": {
            "requestDuration": 145,
            "apiVersion": "2024-06"
        }
    }
}

错误响应包括详细的诊断信息:

{
    "errors": [{
        "message": "Cannot query field 'invalidField' on type 'Reaction'",
        "locations": [{"line": 5, "column": 21}],
        "path": ["query", "reactions", "edges", "node", "invalidField"]
    }]
}

故障排除

常见问题:

• HTTP 请求错误: 验证与 api.catalysis-hub.org 的网络连接
• JSON 解码错误: 使用 Catalysis Hub 的 GraphQL Playground 检查查询语法
• 超时错误: 向复杂查询添加 timeout 参数

许可证

MIT 许可证 - 详情请参阅 LICENSE

致谢

本项目基于模型上下文协议 (MCP) 框架构建，旨在与 Catalysis Hub 数据库对接，该数据库是催化研究数据的综合资源。