Catalysis Hub MCP Server

Catalysis Hub MCP サーバー

Catalysis Hub の GraphQL API 用 Model Context Protocol（MCP）サーバーインターフェースです。柔軟な GraphQL クエリを通じて、触媒研究データにプログラムからアクセスできます。

主な機能

• GraphQL への直接アクセス：Catalysis Hub の API に対して、有効な GraphQL クエリを実行できます
• 包括的なデータアクセス：
  • 触媒反応（反応式、条件、触媒）
  • 材料系（構造、特性、記述子）
  • 研究論文（タイトル、DOI、著者）
  • 表面反応データ（吸着エネルギー、結合部位）
• MCP 標準への準拠：AI エージェント間の相互運用性を実現するため、Model Context Protocol を実装しています
• 柔軟なクエリのサポート：変数をパラメーター化した複雑なクエリを実行できます
• エラー処理：API 接続およびクエリ実行に関する堅牢なエラー報告機能を備えています

ライセンスと引用

このプロジェクトは、学術引用要件付きの MIT License の下で提供されています。コードは自由に使用、変更、配布できますが、このソフトウェアを使用した学術論文または科学論文では、適切な帰属表示が必要です。

学術・研究での利用：

このソフトウェアを、出版物、発表、または報告書につながる研究プロジェクトで使用する場合は、CITATION.md に記載されている形式に従って、必ずこの成果を引用してください。

商用・非学術での利用：

商用および非学術での利用には、引用要件のない標準的な MIT License の条項が適用されます。

このソフトウェアを使用することで、これらの条項に同意したものとみなされます。ライセンスの全文については、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 パラメーターを追加してください

謝辞

このプロジェクトは Model Context Protocol（MCP）フレームワークを基盤とし、触媒研究データの包括的なリソースである Catalysis Hub データベースとのインターフェースとして設計されています。