Catalysis Hub MCP Server

Catalysis Hub MCP 服务

一个面向 Catalysis Hub GraphQL API 的模型上下文协议（MCP）服务接口，可通过灵活的 GraphQL 查询，以编程方式访问催化研究数据。

主要功能

• 直接访问 GraphQL：针对 Catalysis Hub API 执行任意有效的 GraphQL 查询
• 全面的数据访问：
  • 催化反应（方程式、条件、催化剂）
  • 材料体系（结构、属性、描述符）
  • 研究出版物（标题、DOI、作者）
  • 表面反应数据（吸附能、结合位点）
• 符合 MCP 标准：实现模型上下文协议，支持 AI Agent 互操作
• 灵活的查询支持：通过变量参数化执行复杂查询
• 错误处理：针对 API 连接和查询执行提供可靠的错误报告

许可与引用

本项目采用 MIT 许可证，并要求学术引用。这意味着你可以自由使用、修改和分发代码，但任何使用本软件的学术或科学出版物都必须提供适当的出处说明。

学术／研究用途：

如果你在某个最终形成出版物、演示或报告的研究项目中使用本软件，必须按照 CITATION.md 中提供的格式引用本项目。

商业／非学术用途：

商业和非学术用途遵循标准 MIT 许可证条款，无需引用。

使用本软件即表示你同意这些条款。完整的许可证文本请参阅 LICENSE.md。

实现详情

• 服务配置（与 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"
    }
  }
  

• 核心依赖项：用于异步 HTTP 请求的 httpx
• 传输方式：遵循 MCP 规范的标准输入／输出通信

设置与安装

1. 克隆代码库：

   git clone <repository_url>
   cd catalysishub-mcp-server
   

2. 安装依赖项：

   pip install -r requirements.txt
   

3. 验证安装：

   python3 catalysishub_mcp_server.py --version
   # Should output: 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": { /* Query results */ },
    "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 Request Error：检查到 api.catalysis-hub.org 的网络连接
• JSON Decode Error：使用 Catalysis Hub 的 GraphQL Playground 检查查询语法
• Timeout Errors：为复杂查询添加 timeout 参数

致谢

本项目基于模型上下文协议（MCP）框架构建，旨在与 Catalysis Hub 数据库交互。该数据库是全面的催化研究数据资源。