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 initializationtools.py: Core scientific tools with Pydantic validation modelstool_registry.py: Formal tool registration system with metadata managementtool_definitions.yaml: YAML configuration file defining all available tools and their metadatatests/test_tools.py: Comprehensive test suite for tools and validationtests/test_tools_load.py: Load and consistency tests for tool definitionspyproject.toml: Dependency and package management
🚀 Installation
# Install dependencies
pip install mcp[server] ase pydantic pyyaml bohr-agent-sdk
🏃 Running the Server
To run as the modern HTTP server (Streamable HTTP):
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:
# 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
# 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:
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 jobquery_job_status: Check job progressget_job_results: Retrieve completed job data
search_mofs
Category: Search
Description: Search for Metal-Organic Frameworks by name or formula in the database
Input:
{
"query": "MOF-5"
}
Output:
{
"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:
{
"data": "<CIF file content or path>"
}
Output:
{
"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:
{
"name": "HKUST-1"
}
Output:
{
"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:
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
- Define Pydantic models in
tools.py:
class MyToolInput(BaseModel):
param: str = Field(..., description="Parameter description")
class MyToolOutput(BaseModel):
success: bool
result: str
- Implement the tool function in
tools.py:
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 ...
- Add the tool definition to
tool_definitions.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.
- Add tests in
test_tools.py:
def test_my_tool():
result = tools.my_tool("test")
parsed = json.loads(result)
assert parsed["success"] is True
📝 License
See LICENSE file for details.