https://github.com/webworn/openfoam-mcp-server
LLM-powered OpenFOAM MCP server for intelligent CFD education with Socratic questioning and expert error resolution
https://github.com/webworn/openfoam-mcp-server
in llm llm-in-analysis mcp mcp-openfoam mcp-server openfoam openfoam-mcp opensource-projects
Last synced: 17 days ago
JSON representation
LLM-powered OpenFOAM MCP server for intelligent CFD education with Socratic questioning and expert error resolution
- Host: GitHub
- URL: https://github.com/webworn/openfoam-mcp-server
- Owner: webworn
- License: other
- Created: 2025-07-06T03:08:55.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-18T12:04:28.000Z (6 months ago)
- Last Synced: 2026-01-18T17:44:56.622Z (6 months ago)
- Topics: in, llm, llm-in-analysis, mcp, mcp-openfoam, mcp-server, openfoam, openfoam-mcp, opensource-projects
- Language: C++
- Homepage:
- Size: 24.5 MB
- Stars: 65
- Watchers: 1
- Forks: 10
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Roadmap: ROADMAP.md
Awesome Lists containing this project
- awesome-ai-cae - webworn/openfoam-mcp-server - OpenFOAM MCP server with Socratic questioning for CFD education and expert error resolution. (MCP Servers / Verified vs declared)
README
# OpenFOAM MCP Server
๐ **Intelligent CFD education and problem-solving system** - OpenFOAM Model Context Protocol server with AI-powered educational capabilities including Socratic questioning, context engineering, and systematic error resolution.
[](https://openfoam.org/)
[](https://isocpp.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
## ๐ **Current Status**
| Component | Status | Details |
|-----------|--------|---------|
| **MCP Server** | โ
**Working** | JSON-RPC 2.0, 12 registered tools, Claude Code integration |
| **OpenFOAM Integration** | โ ๏ธ **Partial** | Basic connectivity, solver migration needed for OF12 |
| **Educational AI** | โ
**Working** | Context engine, Socratic questioning, adaptive learning |
| **Mesh & Geometry Tools** | โ
**Complete** | Mesh quality assessment, STL analysis with snappyHexMesh guidance |
| **RDE Analysis Suite** | โ
**Complete** | 2D/3D wave analysis, geometry generation, performance calculation |
| **Pipe Flow Analysis** | โ
**Complete** | Full implementation with mesh generation and validation |
| **Advanced Physics** | โ ๏ธ **In Development** | Heat transfer, multiphase frameworks exist, need implementation |
**Overall System Status: 75% Functional** - Core educational, mesh quality, and RDE analysis capabilities working.
## ๐ฏ Why This MCP? The CFD-AI Educational Revolution
### The Problem: CFD Expertise Barrier
- **Complex Setup**: OpenFOAM requires deep expertise in mesh generation, boundary conditions, and solver selection
- **Physics Knowledge**: CFD analysis demands understanding of fluid dynamics, heat transfer, and numerical methods
- **Time-Intensive**: Manual setup and analysis can take hours to days for complex cases
- **Error-Prone**: Incorrect boundary conditions or solver settings lead to non-physical results
- **Learning Curve**: Traditional CFD tools lack educational guidance and progressive learning support
### The Solution: Intelligent CFD Education System
This revolutionary MCP transforms CFD learning and problem-solving through:
- **Context Engineering**: Advanced user modeling that tracks CFD concept understanding and adapts complexity
- **Socratic Questioning**: Strategic questioning engine with 4 proven patterns (Clarify, Explore, Confirm, Apply)
- **Intelligent Parameter Extraction**: Natural language to CFD parameter translation with confidence scoring
- **Advanced Error Resolution**: 5 Whys methodology with research-backed solutions and academic references
- **CFD Knowledge Graph**: Concept relationship mapping for guided learning paths
- **Dual-Terminal Architecture**: Seamless OpenFOAM execution with intelligent conversation flow
### Market Impact
- **Revolutionizes CFD Education**: First AI-driven system that teaches CFD through guided discovery
- **Democratizes CFD**: Makes professional fluid dynamics analysis accessible through natural language
- **Accelerates Learning**: Progressive complexity adaptation based on user understanding level
- **Enhances Problem-Solving**: 5 Whys error resolution with research-backed solutions
- **Professional Integration**: Maintains full OpenFOAM compatibility with intelligent guidance overlay
## ๐ ๏ธ Intelligent CFD Capabilities
### ๐ง Advanced AI Features
#### **Context Engineering System**
- **Enhanced User Modeling**: Tracks CFD concept understanding, experience level, and learning progress
- **Confidence Scoring**: Monitors user comprehension across fluid dynamics, heat transfer, and numerical methods
- **Adaptive Complexity**: Automatically adjusts explanations and guidance based on user expertise
- **Learning Path Optimization**: Suggests optimal concept progression for effective CFD mastery
#### **Socratic Questioning Engine**
- **Strategic Question Patterns**: 4 proven educational strategies for progressive learning
- ๐ **CLARIFY**: "What specifically do you mean by turbulent flow in this context?"
- ๐ **EXPLORE**: "What would happen if we increased the Reynolds number to 500,000?"
- โ
**CONFIRM**: "So you're saying that pressure drop increases quadratically with velocity?"
- ๐ฏ **APPLY**: "How would you use the Moody diagram for this pipe flow problem?"
- **Context-Aware Questions**: Generated based on user's current understanding and conversation history
- **Progressive Difficulty**: Questions adapt complexity to build understanding systematically
#### **Intelligent Parameter Extraction**
- **Natural Language Processing**: Converts conversational descriptions to precise CFD parameters
- **Physics Validation**: Ensures extracted parameters are physically reasonable and consistent
- **Confidence Scoring**: Provides certainty levels for parameter extraction accuracy
- **Interactive Clarification**: Asks intelligent follow-up questions when parameters are ambiguous
#### **Advanced Error Resolution**
- **5 Whys Methodology**: Systematic root cause analysis for CFD simulation failures
- **Research Integration**: Academic paper database with evidence-based solutions
- **Diagnostic Guidance**: Step-by-step troubleshooting with educational explanations
- **Prevention Strategies**: Teaches users to avoid similar issues through understanding
#### **CFD Knowledge Graph**
- **Concept Relationships**: Maps connections between fluid mechanics, heat transfer, and numerical methods
- **Learning Dependencies**: Identifies prerequisite concepts for advanced topics
- **Skill Assessment**: Evaluates user knowledge gaps and suggests focused learning areas
- **Academic References**: Links concepts to authoritative sources and research papers
### ๐ Available MCP Tools
The server provides **12 registered tools** across different CFD domains:
| Tool | Description | Status |
|------|-------------|--------|
| `start_cfd_assistance` | Start an intelligent CFD conversation with context engineering | โ
Working |
| `continue_cfd_conversation` | Continue CFD discussion with adaptive Socratic questioning | โ
Working |
| `execute_openfoam_operation` | Execute OpenFOAM operations (mesh, solve, post-process) | โ
Working |
| `analyze_cfd_results` | Analyze CFD results with educational explanations | โ
Working |
| `get_cfd_learning_guidance` | Get personalized CFD learning recommendations | โ
Working |
| `assess_mesh_quality` | Mesh quality analysis with solver compatibility assessment | โ
Working |
| `analyze_stl_geometry` | STL preprocessing and snappyHexMesh readiness analysis | โ
Working |
| `analyze_turbulent_flow` | Comprehensive turbulent flow analysis with model recommendations | โ
Working |
| `analyze_rde_waves_2d` | 2D RDE wave detection and performance metrics | โ
Working |
| `generate_rde_3d_geometry` | 3D RDE annular geometry generation with blockMesh | โ
Working |
| `analyze_rde_waves_3d` | 3D RDE wave propagation and interaction analysis | โ
Working |
| `calculate_rde_3d_performance` | 3D RDE thrust, Isp, and efficiency calculations | โ
Working |
### Core Analysis Tools
#### 1. ๐ฌ **Pipe Flow Analysis** (`run_pipe_flow`)
**Physics**: Internal flow in circular pipes with laminar flow analysis
- **Calculates**: Reynolds number, friction factor, pressure drop, wall shear stress
- **Applications**: Hydraulic systems, pipeline design, HVAC analysis
- **Solvers**: `icoFoam` (laminar), `foamRun -solver incompressibleFluid` (in development)
- **Status**: โ
**Working** - Complete implementation with mesh generation
- **Current Limitations**: For advanced turbulent analysis, use `analyze_turbulent_flow`
#### 1b. ๐ **Turbulent Flow Analysis** (`analyze_turbulent_flow`)
**Physics**: Comprehensive turbulent flow analysis for pipes, channels, and external flows
- **Turbulence Models**: Automatic selection between k-epsilon and k-omega SST with justification
- **Friction Factors**: Smooth pipes (Blasius) and rough pipes (Colebrook-White/Swamee-Jain)
- **Pipe Roughness**: Built-in database with 13 standard materials (steel, cast iron, PVC, etc.)
- **Calculates**:
- Reynolds number and flow regime classification
- Friction factor (smooth and rough pipes)
- Pressure drop and head loss (Darcy-Weisbach)
- Wall shear stress and friction velocity
- y+ estimation and first cell height recommendations
- Turbulent inlet conditions (k, ฮต, ฯ, ฮฝt)
- **Mesh Guidance**: y+ validation for wall functions, first cell height calculator
- **Educational Content**: Socratic questions, physics explanations, model comparisons
- **Status**: โ
**Working** - Complete implementation with validation
#### 2. โ๏ธ **External Flow Analysis** (`analyze_external_flow`)
**Physics**: Basic aerodynamics analysis (simplified implementation)
- **Calculates**: Basic flow patterns and pressure distributions
- **Applications**: Preliminary aerodynamic assessments
- **Solvers**: `foamRun -solver incompressibleFluid` (basic configuration)
- **Status**: โ ๏ธ **Partial** - Framework exists, needs solver integration fixes
- **Current Limitations**: Advanced turbulence models not fully integrated
#### 3. ๐ก๏ธ **Heat Transfer Analysis** (`analyze_heat_transfer`)
**Physics**: Basic heat transfer analysis (limited implementation)
- **Calculates**: Temperature distributions (simplified cases)
- **Applications**: Basic thermal analysis
- **Solvers**: Heat transfer solvers integration in progress
- **Status**: โ ๏ธ **In Development** - Basic framework, solver integration needed
- **Current Limitations**: Conjugate heat transfer not yet implemented
#### 4. ๐ **Multiphase Flow Analysis** (`analyze_multiphase_flow`)
**Physics**: Multiphase flow framework (early development)
- **Applications**: Basic free surface flow analysis
- **Solvers**: Multiphase solver integration planned
- **Status**: โ ๏ธ **Framework Only** - Tool structure exists, solver integration needed
- **Current Limitations**: VOF methods and advanced multiphase physics not implemented
### Mesh & Geometry Tools
#### 5. ๐ **Mesh Quality Assessment** (`assess_mesh_quality`)
**Purpose**: Comprehensive mesh quality analysis for OpenFOAM cases
- **Metrics**: Non-orthogonality, skewness, aspect ratio, cell volume distribution
- **Features**: Solver compatibility assessment, quality grading (A-F), improvement recommendations
- **Educational**: Explains mesh quality impact on solver convergence and accuracy
- **Status**: โ
**Working** - Complete implementation with educational content
#### 6. ๐บ **STL Geometry Analyzer** (`analyze_stl_geometry`)
**Purpose**: STL file quality analysis for snappyHexMesh preprocessing
- **Checks**: Watertightness, manifold edges, normal consistency, triangle quality
- **Features**: Feature edge extraction, refinement region suggestions, complexity assessment
- **Expert Insight**: "90% of snappyHexMesh failures start with bad geometry"
- **Status**: โ
**Working** - Complete implementation with repair guidance
### RDE (Rotating Detonation Engine) Analysis Suite
#### 7. ๐ฅ **2D RDE Wave Analysis** (`analyze_rde_waves_2d`)
**Physics**: 2D rotating detonation wave detection and performance analysis
- **Detects**: Wave fronts, multi-wave interactions, collision events
- **Calculates**: Thrust (validated: 11,519 N), Isp (1,629 s), combustion efficiency (85%)
- **Features**: Wave tracking, collision analysis, stability assessment
- **Status**: โ
**Working** - Validated against analytical solutions
#### 8. ๐๏ธ **3D RDE Geometry Generator** (`generate_rde_3d_geometry`)
**Purpose**: Generate complete 3D annular RDE geometry for OpenFOAM
- **Components**: Inlet section, annular combustor, nozzle with expansion
- **Outputs**: blockMeshDict, boundary patches, injection port locations
- **Features**: Mesh quality prediction, computational requirement estimation
- **Status**: โ
**Working** - Full geometry generation with validation
#### 9. ๐ **3D RDE Wave Analysis** (`analyze_rde_waves_3d`)
**Physics**: 3D detonation wave propagation and interaction analysis
- **Tracks**: 3D wave fronts, axial propagation, wave-wave interactions
- **Calculates**: 3D thrust components, radial losses, wave collision enhancement
- **Educational**: Explains 3D vs 2D wave physics differences
- **Status**: โ
**Working** - Enhanced from validated 2D baseline
#### 10. ๐ **3D RDE Performance Calculator** (`calculate_rde_3d_performance`)
**Purpose**: Comprehensive 3D RDE performance metrics calculation
- **Thrust Analysis**: Combustor + nozzle breakdown, axial/radial components
- **Efficiency**: Combustion efficiency, nozzle performance, mixing analysis
- **Validation**: Compares against 2D baseline (11,519 N, 1,629 s, 85%)
- **Status**: โ
**Working** - Complete with optimization guidance
### ๐ฏ Intelligent CFD Education Features
#### ๐งฎ **Physics-Based Calculations with AI Guidance**
- **Dimensionless Numbers**: Reynolds, Prandtl, Nusselt, Rayleigh, Grashof with educational context
- **Material Properties**: Thermal conductivity, density, specific heat, viscosity with database references
- **Validation**: Analytical comparisons against Hagen-Poiseuille, Blasius, and experimental correlations
- **Error Detection**: Non-physical results detection with 5 Whys analysis and resolution guidance
#### ๐ **Adaptive Educational Content**
- **Progressive Physics Explanations**: Complexity adapts to user's demonstrated understanding level
- **Socratic Teaching Method**: Strategic questioning to build deep conceptual understanding
- **Engineering Guidance**: Context-aware design recommendations with academic justification
- **Industry Applications**: Real-world examples from automotive, aerospace, electronics, and marine sectors
- **Best Practices**: Intelligent mesh quality assessment, boundary condition validation, solver selection logic
#### ๐ **Comprehensive CFD Validation Framework**
- **Multi-Physics Domains**: Validation across pipe flow, external flow, heat transfer, and multiphase systems
- **Analytical Solutions**: Automatic comparison with classical solutions (Poiseuille, Blasius, Rayleigh-Bรฉnard)
- **Experimental Validation**: Database of experimental correlations and benchmark cases
- **Confidence Metrics**: Statistical validation with uncertainty quantification and error bounds
#### ๐ **Intelligent Visualization & Results**
- **ParaView Web Interface**: Real-time result visualization on port 8080 with educational annotations
- **Context-Aware Plots**: Automatically generated visualizations based on physics domain and user understanding
- **Interactive Learning**: Guided exploration of results with Socratic questioning about flow phenomena
- **Streamlines & Pathlines**: Flow visualization with educational explanations of particle tracking
- **Result Export**: VTK format for advanced post-processing with comprehensive metadata
## ๐ฅ Installation
### Prerequisites
#### System Requirements
- **OS**: Ubuntu 20.04+ or Debian 11+ (recommended)
- **Memory**: 8GB+ RAM (16GB+ recommended for large simulations)
- **Storage**: 10GB+ available disk space
- **CPU**: Multi-core processor (4+ cores recommended)
#### Required Dependencies
```bash
# Ubuntu/Debian - Install all dependencies
sudo apt-get update
sudo apt-get install -y \
cmake \
build-essential \
git \
nlohmann-json3-dev \
libboost-system-dev \
libboost-thread-dev \
sqlite3 \
libsqlite3-dev
```
#### OpenFOAM 12 Installation
```bash
# Ubuntu/Debian packages (recommended)
sudo apt-get update
sudo apt-get install openfoam12
# Alternative: OpenFOAM Foundation packages
wget -O - https://dl.openfoam.org/gpg.key | sudo apt-key add -
sudo add-apt-repository http://dl.openfoam.org/ubuntu
sudo apt-get update
sudo apt-get install openfoam12
```
#### Environment Setup & Verification
```bash
# Verify installation
export LD_LIBRARY_PATH=/opt/openfoam12/platforms/linux64GccDPInt32Opt/lib/dummy:/opt/openfoam12/platforms/linux64GccDPInt32Opt/lib:$LD_LIBRARY_PATH
export PATH=/opt/openfoam12/platforms/linux64GccDPInt32Opt/bin:$PATH
export WM_PROJECT_DIR=/opt/openfoam12
# Test core utilities
which blockMesh # โ
Mesh generation
which foamRun # โ
Modern solver framework
which icoFoam # โ
Laminar flow solver
# Note: OpenFOAM 12 uses foamRun instead of individual solver executables
```
### Build MCP Server
1. **Clone Repository**
```bash
git clone https://github.com/webworn/openfoam-mcp-server.git
cd openfoam-mcp-server
```
2. **Build with CMake**
```bash
mkdir build && cd build
cmake ..
make -j$(nproc)
```
3. **Test Installation**
```bash
# Test server builds successfully
./openfoam-mcp-server-test # Minimal test version
./openfoam-mcp-server # Full version (requires complete OpenFOAM setup)
# Verify MCP connectivity
python3 comprehensive_system_test.py
```
### Dependencies Auto-Detection
The build system automatically detects:
- โ
**OpenFOAM Libraries**: `/opt/openfoam12/platforms/linux64GccDPInt32Opt/lib`
- โ
**nlohmann/json**: JSON parsing for MCP protocol
- โ
**Boost**: System and threading libraries
- โ
**SQLite3**: Optional case database storage
## ๐ค Claude Code Integration
### MCP Configuration
Add the server to Claude Code using the CLI:
```bash
# Add OpenFOAM MCP server
claude mcp add-json openfoam-mcp-server '{
"command": "/workspaces/openfoam-mcp-server/build/openfoam-mcp-server-test",
"args": [],
"env": {
"LD_LIBRARY_PATH": "/opt/openfoam12/platforms/linux64GccDPInt32Opt/lib/dummy:/opt/openfoam12/platforms/linux64GccDPInt32Opt/lib",
"FOAM_INST_DIR": "/opt/openfoam12",
"WM_PROJECT_DIR": "/opt/openfoam12",
"FOAM_LIBBIN": "/opt/openfoam12/platforms/linux64GccDPInt32Opt/lib",
"FOAM_APPBIN": "/opt/openfoam12/platforms/linux64GccDPInt32Opt/bin",
"FOAM_ETC": "/opt/openfoam12/etc",
"PATH": "/opt/openfoam12/platforms/linux64GccDPInt32Opt/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
}
}'
# Verify server connection
claude mcp list
# Should show: openfoam-mcp-server - โ Connected
```
### Intelligent CFD Assistant Examples
#### Socratic Learning: Pipe Flow Analysis
```
๐งโ๐ป User: "Analyze water flow in a 0.1m diameter pipe at 2 m/s"
๐ค Claude: Before I run the analysis, let me understand your background better.
๐ CLARIFY: "What specifically interests you about this pipe flow - are you designing a hydraulic system, learning about pressure losses, or optimizing an existing installation?"
๐งโ๐ป User: "I'm learning about pressure losses for my fluid mechanics course"
๐ค Claude: Perfect! I'll guide you through the analysis step by step.
*Uses run_pipe_flow tool with educational context*
๐ Results with Learning:
โข Reynolds Number: 200,000
๐ก This indicates turbulent flow (Re > 4,000). What do you think this means for mixing?
โข Friction Factor: 0.0184 (Blasius correlation)
๐ EXPLORE: How would this change if we doubled the velocity?
โข Pressure Drop: 2.4 kPa per meter
โ
CONFIRM: So you're seeing that pressure drop increases significantly with velocity - can you explain why?
๐ฏ APPLY: "Now that you understand the relationship, how would you redesign this pipe to reduce pumping costs by 50%?"
```
#### Context-Aware Error Resolution
```
๐งโ๐ป User: "My heat transfer simulation isn't converging. The residuals keep oscillating."
๐ค Claude: I'll help you resolve this using systematic analysis.
*Applies 5 Whys methodology*
๐ Why #1: "Why are the residuals oscillating?"
Analysis: Likely numerical instability or inappropriate relaxation factors.
๐ Why #2: "Why might the relaxation factors be inappropriate?"
Your setup shows high temperature gradients that require more conservative factors.
๐ Why #3: "Why are the temperature gradients so high?"
The boundary conditions show a 500K temperature difference across a thin wall.
๐ Research-Backed Solution:
โข Reduce temperature relaxation from 0.7 to 0.3 (Versteeg & Malalasekera, 2007)
โข Implement under-relaxation for energy equation (Patankar, 1980)
โข Consider CFL number for transient effects
๐ฏ Prevention Strategy:
โข Always validate physical temperature ranges before simulation
โข Use dimensionless temperature analysis for better conditioning
โข Implement gradual temperature ramping for extreme conditions
```
#### Parameter Extraction from Natural Language
```
๐งโ๐ป User: "I have a large tank with water draining through a small hole at the bottom. The water level starts at about 2 meters and I want to know how long it takes to empty."
๐ค Claude: I can help with this dam break/draining analysis! Let me extract the CFD parameters from your description.
*Uses intelligent parameter extraction*
๐ Extracted Parameters (Confidence: 85%):
โข Physics Domain: Multiphase flow (free surface)
โข Initial water height: 2.0 m โ
โข Geometry: Tank with bottom orifice โ
โข Fluid: Water (ฯ=1000 kg/mยณ, ฮผ=1e-3 Paยทs) โ
โ Clarification Needed:
โข Tank dimensions (length, width)?
โข Orifice diameter?
โข Are we modeling turbulence effects?
๐ EXPLORE: "Based on Torricelli's law, what do you expect happens to the flow rate as the tank empties?"
*After clarification, runs multiphase flow analysis*
๐ Results with Physics Insight:
โข Analytical (Torricelli): ~89 seconds for complete drainage
โข CFD Simulation: ~94 seconds (includes viscous effects)
โข Flow regime: Initially turbulent (Re~50,000), transitions to laminar
โข Vortex formation near orifice affects drainage rate by ~5%
```
### Intelligent Workflow Integration
#### AI-Enhanced Engineering Design Process
1. **Conceptual Design**: Context-aware initial sizing with intelligent parameter extraction
2. **Physics Validation**: Socratic questioning to ensure understanding of assumptions
3. **Detailed Analysis**: Export OpenFOAM cases with AI-generated documentation
4. **Error Resolution**: 5 Whys methodology for systematic troubleshooting
5. **Optimization**: AI-guided design improvements with academic justification
6. **Validation**: Automatic comparison with analytical solutions and experimental data
#### Progressive CFD Education
1. **Adaptive Learning**: Complexity automatically adjusts to demonstrated user understanding
2. **Concept Mapping**: CFD knowledge graph guides learning path optimization
3. **Socratic Discovery**: Strategic questioning builds deep conceptual understanding
4. **Research Integration**: Academic papers and validated solutions support learning
5. **Industry Context**: Real-world applications connect theory to practice
6. **Error Prevention**: Learn from mistakes through systematic root cause analysis
## ๐ค Contributing
### Development Environment
**GitHub Codespaces** (Recommended):
1. Fork the repository
2. Open in Codespaces (auto-configures OpenFOAM 12)
3. VS Code Desktop integration with full IntelliSense
4. Cloud development with 4-32 core machines
**Local Development**:
```bash
# Install dependencies
sudo apt-get install cmake build-essential openfoam12 nlohmann-json3-dev
# Clone and build
git clone https://github.com/webworn/openfoam-mcp-server.git
cd openfoam-mcp-server
mkdir build && cd build
cmake .. && make -j$(nproc)
```
### Adding New Analysis Tools
#### 1. Create Analyzer Class
```cpp
// src/openfoam/your_analysis.hpp
class YourAnalyzer {
public:
struct Input { /* physics parameters */ };
struct Results { /* calculated outputs */ };
Results analyze(const Input& input);
bool validateInput(const Input& input);
json toJson(const Results& results);
};
```
#### 2. Create MCP Tool Wrapper
```cpp
// src/tools/your_analysis_tool.hpp
class YourAnalysisTool {
public:
static std::string getName() { return "your_analysis"; }
static std::string getDescription() { return "Physics description"; }
static json getInputSchema();
ToolResult execute(const json& arguments);
};
```
#### 3. Register Tool
```cpp
// src/main.cpp
#include "tools/your_analysis_tool.hpp"
int main() {
McpServer server;
registerYourAnalysisTool(server); // Add this line
server.start();
}
```
### Physics Implementation Guidelines
#### OpenFOAM Integration
- **Case Templates**: Use `src/openfoam/case_templates/` for solver setup
- **Boundary Conditions**: Implement physics-appropriate BC selection
- **Mesh Generation**: Add automatic meshing with quality checks
- **Solver Selection**: Choose appropriate OpenFOAM solver for physics
#### Validation Requirements
- **Analytical Comparison**: Compare with known solutions (Poiseuille, Blasius, etc.)
- **Experimental Data**: Validate against published correlations
- **Convergence Studies**: Ensure mesh-independent results
- **Physical Bounds**: Check for non-physical results
#### Educational Content
- **Physics Explanations**: Describe governing equations and assumptions
- **Dimensionless Numbers**: Calculate and explain significance
- **Engineering Context**: Provide industry-relevant guidance
- **Design Recommendations**: Suggest optimization strategies
### Code Standards
#### C++ Best Practices
- **C++20 Standard**: Use modern C++ features appropriately
- **OpenFOAM Style**: Follow OpenFOAM coding conventions
- **Memory Management**: Use smart pointers, RAII principles
- **Error Handling**: Comprehensive exception handling
#### MCP Protocol Compliance
- **JSON-RPC 2.0**: Strict protocol adherence
- **Schema Validation**: Complete input parameter validation
- **Error Messages**: User-friendly error reporting
- **Resource Management**: Proper cleanup and case management
## ๐๏ธ Technical Architecture
### System Overview
```
โโโโโโโโโโโโโโโโโโโ JSON-RPC 2.0 โโโโโโโโโโโโโโโโโโโโ
โ Claude Code โ โโโโโโโโโโโโโโโโโ โ MCP Server โ
โ AI Assistant โ โ (12 Tools) โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโ
โ Tool Router โ
โ (Registration) โ
โโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโฌโโโโโโโโดโโโโโโโโฌโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโ
โผ โผ โผ โผ โผ โผ
โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ
โCFD Assistantโ โ Mesh Qualityโ โSTL Analyzer โ โ RDE 2D Wave โ โRDE 3D Tools โ โ Pipe Flow โ
โ (5 tools) โ โ Tool โ โ Tool โ โ Tool โ โ (3 tools) โ โ Tool โ
โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ
โ โ โ โ โ โ
โผ โผ โผ โผ โผ โผ
โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ
โ Context โ โMeshQuality โ โ STLAnalyzer โ โRDE2DWave โ โRDE3DGeometryโ โ PipeFlow โ
โ Engine โ โ Analyzer โ โ Class โ โ Analyzer โ โ/Wave/Perf โ โ Analyzer โ
โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ
โ โ โ โ โ โ
โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโดโโโโโโโโฌโโโโโโโโดโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโ
โผ
โโโโโโโโโโโโโโโโโโโโ
โ Case Manager โ
โ (OpenFOAM) โ
โโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโ
โ OpenFOAM โ
โ Solvers โ
โ (Native C++) โ
โโโโโโโโโโโโโโโโโโโโ
```
### Data Flow
1. **User Request**: Natural language query to Claude Code
2. **AI Processing**: Claude interprets request and calls appropriate MCP tool
3. **Parameter Validation**: Input schema validation and physics bounds checking
4. **OpenFOAM Setup**: Automated case creation with boundary conditions
5. **CFD Simulation**: Native OpenFOAM solver execution
6. **Result Processing**: Physics calculations and educational content generation
7. **Response**: Formatted results with explanations and recommendations
### Performance Features
- **Parallel Execution**: Multi-threaded OpenFOAM solvers
- **Case Caching**: Intelligent reuse of similar simulations
- **Mesh Templates**: Pre-validated meshes for common geometries
- **Async Processing**: Non-blocking simulation execution (planned)
## ๐ References
- **OpenFOAM Foundation**: [https://openfoam.org/](https://openfoam.org/)
- **Model Context Protocol**: [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/)
- **CFD Theory**: "An Introduction to Computational Fluid Dynamics" by Versteeg & Malalasekera
- **Heat Transfer**: "Heat Transfer" by Cengel & Ghajar
- **Fluid Mechanics**: "Fluid Mechanics" by White
## ๐ License
Apache License 2.0 - see [LICENSE](LICENSE) for details.
## ๐ Acknowledgments
- **OpenFOAM Foundation** for the world-class CFD toolkit
- **Anthropic** for Claude Code and MCP protocol
- **CFD Community** for validation data and best practices
## ๐ง Current Development Status & Roadmap
*Join us in building an intelligent CFD-AI integration platform!*
### โ
**Completed Features**
#### **Core Infrastructure**
- โ
**MCP Server Framework**: JSON-RPC 2.0 protocol implementation
- โ
**OpenFOAM 12 Integration**: Basic solver connectivity with dummy Pstream
- โ
**Mesh Generation**: Working blockMesh integration for structured grids
- โ
**Educational AI**: Context engine, Socratic questioning, parameter extraction
- โ
**Pipe Flow Analysis**: Complete implementation with turbulence model setup
### ๐ง **In Active Development**
#### **OpenFOAM 12 Compatibility** (Priority: High)
- ๐ **Solver Migration**: Updating from legacy solver names to `foamRun` framework
- ๐ **Configuration Updates**: Modern OpenFOAM 12 solver dictionaries
- โ
**Turbulence Models**: k-ฮต and k-ฯ SST integration complete with `analyze_turbulent_flow` tool
- ๐ **JSON Response Fixes**: Resolving 2/5 tool output formatting issues
#### **Enhanced Physics Domains** (Priority: Medium)
- ๐ **External Flow**: Complete aerodynamics tool with turbulence models
- ๐ **Heat Transfer**: Basic conjugate heat transfer implementation
- ๐ **Multiphase Flow**: VOF method integration for free surface flows
### ๐ **Planned Industry Applications** (Future Development)
#### **Phase 2 Development** (6-12 months)
- **๐ Automotive**: Vehicle aerodynamics, underhood cooling, HVAC systems
- **โ๏ธ Aerospace**: Airfoil analysis, propulsion systems, hypersonic flows
- **โก Energy**: Wind turbines, solar collectors, gas turbines
- **๐ฅ Biomedical**: Blood flow simulation, drug delivery, medical devices
- **๐ Marine**: Ship resistance, offshore platforms, propeller analysis
*Note: These are planned extensions requiring additional solver integration and validation*
### ๐ง **AI-Enhanced Capabilities** (In Development)
#### **Current AI Features** (โ
Implemented)
- โ
**Context Engineering**: User modeling and adaptive explanations
- โ
**Socratic Questioning**: 4 strategic educational patterns (CLARIFY, EXPLORE, CONFIRM, APPLY)
- โ
**Intelligent Parameter Extraction**: Natural language to CFD parameter conversion
- โ
**5 Whys Error Resolution**: Systematic troubleshooting methodology
#### **Planned AI Enhancements** (๐ Future)
- ๐ **Auto-Mesh Generation**: AI-driven mesh adaptation based on physics
- ๐ **Convergence Prediction**: ML-based convergence behavior forecasting
- ๐ **Multi-Objective Optimization**: Pareto-optimal design exploration
- ๐ **Performance Prediction**: AI models trained on CFD databases
### ๐ง **Technical Architecture** (Current Implementation)
#### **Working Components**
- โ
**MCP Protocol**: JSON-RPC 2.0 with tool registration
- โ
**OpenFOAM Integration**: Basic solver connectivity
- โ
**Mesh Generation**: blockMesh with quality assessment
- โ
**Educational Framework**: Context-aware learning system
#### **Development Priorities**
- ๐ **Solver Modernization**: Update to OpenFOAM 12 foamRun framework
- ๐ **JSON Response Fixes**: Resolve tool output formatting issues
- ๐ **Validation Framework**: Automated testing against analytical solutions
- ๐ **Case Management**: Improved workflow automation
### ๐ **Current Tool & Solver Status Matrix**
| **Domain** | **Status** | **Implementation** | **Notes** |
|------------|------------|-------------------|-----------|
| **Mesh Quality** | โ
**Working** | `assess_mesh_quality` tool | Non-orthogonality, skewness, solver compatibility |
| **STL Analysis** | โ
**Working** | `analyze_stl_geometry` tool | Watertight check, feature extraction, snappyHexMesh prep |
| **RDE 2D Waves** | โ
**Working** | `analyze_rde_waves_2d` tool | Wave detection, collision analysis, performance metrics |
| **RDE 3D Suite** | โ
**Working** | 3 tools (geometry, waves, performance) | Complete 3D RDE analysis workflow |
| **Laminar Flow** | โ
**Working** | `icoFoam` integration | Pipe flow analysis complete |
| **Turbulent Flow** | โ
**Working** | `analyze_turbulent_flow` tool | k-ฮต, k-ฯ SST, Colebrook-White, y+ calculations |
| **External Flow** | โ ๏ธ **Framework** | Basic structure | Solver integration in progress |
| **Heat Transfer** | โ ๏ธ **Framework** | Tool skeleton | Requires solver implementation |
| **Multiphase** | โ ๏ธ **Framework** | Basic structure | VOF integration planned |
| **Compressible** | ๐ **Planned** | Not started | Future development |
| **Combustion** | ๐ **Planned** | Not started | Research phase |
### ๐ค **How to Contribute**
We welcome contributions across all domains! Here's how you can help:
#### **๐ฌ Physics Domain Experts**
- **Validate Physics Models**: Ensure accurate implementation of governing equations
- **Develop Test Cases**: Create validation cases against analytical/experimental data
- **Write Educational Content**: Explain physics concepts for educational tools
#### **๐ป Software Developers**
- **Implement New Tools**: Follow our architecture patterns for new analysis tools
- **Optimize Performance**: Improve computational efficiency and memory usage
- **Enhance UI/UX**: Develop better user interfaces and visualization tools
#### **๐ญ Industry Professionals**
- **Define Use Cases**: Specify real-world engineering problems and requirements
- **Provide Test Data**: Share (anonymized) validation cases and benchmarks
- **Review Results**: Validate tool outputs against industrial standards
#### **๐ Educators & Students**
- **Create Tutorials**: Develop educational content and learning materials
- **Test Tools**: Identify usability issues and suggest improvements
- **Documentation**: Improve documentation, examples, and guides
### ๐ฏ **Contribution Roadmap**
#### **Immediate Priorities** (Next 3 months)
1. **OpenFOAM 12 Compatibility**: Fix solver integration and configuration issues
2. **JSON Response Fixes**: Resolve 2/5 tool output formatting problems
3. **Validation Framework**: Implement automated testing against analytical solutions
4. **Documentation Updates**: Align documentation with actual implementation status
#### **Medium-term Development** (6-12 months)
1. **Advanced Physics**: Complete heat transfer and multiphase flow implementations
2. ~~**Turbulence Models**~~: โ
Completed - k-ฮต and k-ฯ SST with `analyze_turbulent_flow` tool
3. **Mesh Quality**: Implement intelligent mesh adaptation and quality assessment
4. **Industry Applications**: Basic automotive and aerospace analysis tools
#### **Long-term Vision** (1-2 years)
1. **Comprehensive Solver Coverage**: Integrate major OpenFOAM solver families
2. **Advanced AI Features**: Machine learning for optimization and prediction
3. **Real-world Validation**: Extensive validation against experimental data
4. **Production Deployment**: Stable, scalable system for engineering workflows
### ๐ฌ **Get Involved**
Ready to contribute? Here's how to start:
1. **Join Our Community**: Star the repository and join discussions
2. **Pick an Issue**: Check our [GitHub Issues](https://github.com/webworn/openfoam-mcp-server/issues) for beginner-friendly tasks
3. **Fork & Develop**: Use GitHub Codespaces for instant development environment
4. **Submit PR**: Follow our contribution guidelines and submit your improvements
**Together, we're building the future of AI-powered CFD analysis!** ๐๐คโก
---
*Transform your engineering workflow with AI-powered CFD analysis. Get started today!*