# MOF Tools MCP Server
A **production-ready**, professional MCP server for Metal-Organic Framework (MOF) research. This server uses the **Streamable HTTP** transport to provide scientific tools over HTTP with comprehensive **Pydantic validation** and a **formal tool registry system**.
## ✨ Key Features
- **🔒 Input/Output Validation**: All tool inputs and outputs are validated using Pydantic models
- **📋 Formal Tool Registry**: Centralized tool management with metadata, categories, and tags
- **🛡️ Production-Ready**: Industry-standard code with comprehensive error handling
- **📊 Type Safety**: Full type hints throughout the codebase
- **✅ Tested**: Comprehensive test suite with over 35 tests
## 📁 Repository Structure
- `main.py`: Server entrypoint with tool registration and initialization
- `tools.py`: Core scientific tools with Pydantic validation models
- `tool_registry.py`: Formal tool registration system with metadata management
- `tool_definitions.yaml`: YAML configuration file defining all available tools and their metadata
- `tests/test_tools.py`: Comprehensive test suite for tools and validation
- `tests/test_tools_load.py`: Load and consistency tests for tool definitions
- `pyproject.toml`: Dependency and package management
## 🚀 Installation
```bash
# Install dependencies
pip install mcp[server] ase pydantic pyyaml bohr-agent-sdk
```
## 🏃 Running the Server
To run as the modern HTTP server (Streamable HTTP):
```bash
python main.py
```
The server will start on `http://0.0.0.0:50001` and display registered tools information:
```
=== MOF Tools Server ===
Registered 3 tools:
- search_mofs (search)
- calculate_energy (calculation)
- optimize_structure (optimization)
Tools by category:
search: 1 tool(s)
calculation: 1 tool(s)
optimization: 1 tool(s)
analysis: 0 tool(s)
```
## 🧪 Testing
Run the comprehensive test suite:
```bash
# Run all tests
PYTHONPATH=. pytest tests/ -v
# Run specific test file
PYTHONPATH=. pytest tests/test_tools.py -v
PYTHONPATH=. pytest tests/test_tools_load.py -v
```
## 🧪 Testing the Server
### Method 1: MCP Inspector
```bash
# Connect inspector to your running HTTP server
npx @modelcontextprotocol/inspector http://localhost:50001/mcp
```
### Method 2: Manual HTTP Check
Since the server runs on HTTP, you can verify it's up with a simple `curl`:
```bash
curl http://localhost:50001/mcp
```
## 🛠️ Available Tools
All tools return validated JSON responses with comprehensive error handling.
Bohr Agent SDK integration also provides asynchronous job management tools:
- `submit_`: Submit a calculation job
- `query_job_status`: Check job progress
- `get_job_results`: Retrieve completed job data
### search_mofs
**Category**: Search
**Description**: Search for Metal-Organic Frameworks by name or formula in the database
**Input**:
```json
{
"query": "MOF-5"
}
```
**Output**:
```json
{
"success": true,
"results": [
{
"name": "MOF-5",
"formula": "Zn4O(BDC)3",
"surface_area": 3800.0
}
],
"count": 1,
"message": "Found 1 MOF(s)"
}
```
### calculate_energy
**Category**: Calculation
**Description**: Calculate the potential energy of a structure from CIF file content or path using ASE
**Input**:
```json
{
"data": "<CIF file content or path>"
}
```
**Output**:
```json
{
"success": true,
"energy": -123.4567,
"error": null,
"message": "Energy: -123.4567 eV"
}
```
### optimize_structure
**Category**: Optimization
**Description**: Perform structure optimization for a named MOF structure (placeholder implementation)
**Input**:
```json
{
"name": "HKUST-1"
}
```
**Output**:
```json
{
"success": true,
"structure_name": "HKUST-1",
"message": "Successfully initiated optimization for HKUST-1"
}
```
## 🔌 Integration
To connect your agent to this server, use the Streamable HTTP endpoint:
**URL**: `http://localhost:50001/mcp`
## 🏗️ Architecture
### Pydantic Validation
All tools use Pydantic models for comprehensive input/output validation:
- **Input Models**: Validate and sanitize user inputs
- **Output Models**: Ensure consistent response structure
- **Field Validators**: Custom validation logic (e.g., trimming whitespace, checking ranges)
- **Error Handling**: Graceful error messages returned as validated JSON
### Tool Registry System
The formal tool registry provides:
- **Metadata Management**: Description, category, version, tags for each tool
- **Categorization**: Tools organized by category (search, calculation, optimization, analysis)
- **Tag-based Discovery**: Find tools by tags (e.g., "mof", "energy", "database")
### Production-Ready Features
- ✅ Full type hints throughout
- ✅ Comprehensive error handling
- ✅ Input sanitization and validation
- ✅ Consistent JSON output format
- ✅ Detailed documentation
- ✅ Test coverage (38 tests)
- ✅ Modular, maintainable code structure
## 📚 Development
### Tool Configuration
Tool definitions are stored in `tool_definitions.yaml` for easy configuration and management. This separates tool metadata from code logic.
**Example tool definition:**
```yaml
tools:
- name: my_tool
description: Tool description
category: CALCULATION
function_name: my_tool # Function name in tools.py
tags:
- tag1
- tag2
version: "1.0.0"
```
### Adding a New Tool
1. **Define Pydantic models** in `tools.py`:
```python
class MyToolInput(BaseModel):
param: str = Field(..., description="Parameter description")
class MyToolOutput(BaseModel):
success: bool
result: str
```
2. **Implement the tool function** in `tools.py`:
```python
def my_tool(param: str) -> str:
try:
validated_input = MyToolInput(param=param)
# ... tool logic ...
output = MyToolOutput(success=True, result="...")
return output.model_dump_json(indent=2)
except ValidationError as e:
# ... error handling ...
```
3. **Add the tool definition** to `tool_definitions.yaml`:
```yaml
- name: my_tool
description: Tool description
category: CALCULATION
function_name: my_tool
tags:
- tag1
- tag2
version: "1.0.0"
```
The tool will be automatically registered when the server starts.
4. **Add tests** in `test_tools.py`:
```python
def test_my_tool():
result = tools.my_tool("test")
parsed = json.loads(result)
assert parsed["success"] is True
```
## 📝 License
See LICENSE file for details.
