Catalysis Hub MCP Server

1# Catalysis Hub MCP Server
2 
3A Model Context Protocol (MCP) server interface to Catalysis Hub's GraphQL API, enabling programmatic access to catalysis research data through flexible GraphQL queries.
4 
5## Key Features
6 
7- **Direct GraphQL Access**: Execute any valid GraphQL query against Catalysis Hub's API
8- **Comprehensive Data Access**:
9  - Catalytic reactions (equations, conditions, catalysts)
10  - Material systems (structures, properties, descriptors)
11  - Research publications (titles, DOIs, authors)
12  - Surface reaction data (adsorption energies, binding sites)
13- **MCP Standard Compliance**: Implements the Model Context Protocol for AI-agent interoperability
14- **Flexible Query Support**: Execute complex queries with variables parameterization
15- **Error Handling**: Robust error reporting for API connectivity and query execution
16 
17## License and Citation
18 
19This project is available under the MIT License with an Academic Citation Requirement. This means you can freely use, modify, and distribute the code, but any academic or scientific publication that uses this software must provide appropriate attribution.
20 
21### For academic/research use:
22If you use this software in a research project that leads to a publication, presentation, or report, you **must** cite this work according to the format provided in [CITATION.md](CITATION.md).
23 
24### For commercial/non-academic use:
25Commercial and non-academic use follows the standard MIT License terms without the citation requirement.
26 
27By using this software, you agree to these terms. See [LICENSE.md](LICENSE.md) for the complete license text.
28 
29## Implementation Details
30 
31- **Server Configuration** (matches `claude_desktop_config.json`):
32  ```json
33  {
34    "command": "/Users/quentincody/.env/bin/python3",
35    "args": ["/Users/quentincody/catalysishub-mcp-server/catalysishub_mcp_server.py"],
36    "options": {
37      "cwd": "/Users/quentincody/catalysishub-mcp-server"
38    }
39  }
40  ```
41- **Core Dependency**: `httpx` for asynchronous HTTP requests
42- **Transport**: Standard input/output communication following MCP specifications
43 
44## Setup & Installation
45 
461. **Clone the repository**:
47   ```bash
48   git clone <repository_url>
49   cd catalysishub-mcp-server
50   ```
51 
522. **Install dependencies**:
53   ```bash
54   pip install -r requirements.txt
55   ```
56 
573. **Verify installation**:
58   ```bash
59   python3 catalysishub_mcp_server.py --version
60   # Should output: catalysishub-mcp-server 0.1.0
61   ```
62 
63## Usage Examples
64 
65### Basic Query Execution
66```python
67from mcp.client import MCPClient
68 
69async with MCPClient("catalysishub") as hub:
70    result = await hub.catalysishub_graphql(
71        query="""{
72            reactions(first: 5) {
73                edges {
74                    node {
75                        id
76                        Equation
77                        Temperature
78                    }
79                }
80            }
81        }"""
82    )
83    print(json.loads(result))
84```
85 
86### Parameterized Query with Variables
87```python
88variables = {
89    "materialId": "mp-1234",
90    "firstResults": 5
91}
92 
93response = await hub.catalysishub_graphql(
94    query="""query GetMaterial($materialId: String!, $firstResults: Int!) {
95        systems(uniqueId: $materialId) {
96            edges {
97                node {
98                    energy
99                    Cifdata
100                    relatedReactions(first: $firstResults) {
101                        edges {
102                            node {
103                                id
104                                Equation
105                            }
106                        }
107                    }
108                }
109            }
110        }
111    }""",
112    variables=variables
113)
114```
115 
116## Query Optimization Tips
117 
1181. **Use GraphQL Fragments**:
119   ```graphql
120   fragment ReactionDetails on Reaction {
121       id
122       Equation
123       ActivationEnergy
124       Catalyst {
125           formula
126           surface
127       }
128   }
129   
130   query {
131       reactions(first: 10) {
132           edges {
133               node {
134                   ...ReactionDetails
135               }
136           }
137       }
138   }
139   ```
140 
1412. **Batch Related Queries**:
142   ```graphql
143   query BatchQuery {
144       reactions: reactions(first: 5) { edges { node { id Equation } } }
145       materials: systems(first: 5) { edges { node { formula energy } } }
146   }
147   ```
148 
149## Response Structure
150 
151Successful responses follow this structure:
152```json
153{
154    "data": { /* Query results */ },
155    "extensions": {
156        "responseMetadata": {
157            "requestDuration": 145,
158            "apiVersion": "2024-06"
159        }
160    }
161}
162```
163 
164Error responses include detailed diagnostics:
165```json
166{
167    "errors": [{
168        "message": "Cannot query field 'invalidField' on type 'Reaction'",
169        "locations": [{"line": 5, "column": 21}],
170        "path": ["query", "reactions", "edges", "node", "invalidField"]
171    }]
172}
173```
174 
175## Troubleshooting
176 
177**Common Issues**:
178- `HTTP Request Error`: Verify network connectivity to `api.catalysis-hub.org`
179- `JSON Decode Error`: Check query syntax using Catalysis Hub's [GraphQL Playground](https://www.catalysis-hub.org/api/graphql)
180- `Timeout Errors`: Add `timeout` parameter to complex queries
181 
182## Acknowledgements
183 
184This project builds on the Model Context Protocol (MCP) framework and is designed to interface with the Catalysis Hub database, a comprehensive resource for catalysis research data.