Skip to content
Back to search

openfoam-mcp-server

LLM-powered OpenFOAM MCP server for intelligent CFD education with Socratic questioning and expert error resolution

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/webworn--openfoam-mcp-server/badge.svg)](/listings/webworn--openfoam-mcp-server)

HTML

<a href="/listings/webworn--openfoam-mcp-server"><img src="/api/listings/webworn--openfoam-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

# 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

# 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

# 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**

git clone https://github.com/webworn/openfoam-mcp-server.git
cd openfoam-mcp-server

2. **Build with CMake**

mkdir build && cd build
cmake ..
make -j$(nproc)

3. **Test Installation**

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 753 lines · 7 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OpenFOAM MCP Server
  2. 🚀 **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.
  3. [![OpenFOAM](https://img.shields.io/badge/OpenFOAM-12-blue)](https://openfoam.org/)
  4. [![C++](https://img.shields.io/badge/C++-20-green)](https://isocpp.org/)
  5. [![MCP](https://img.shields.io/badge/MCP-1.0-purple)](https://modelcontextprotocol.io/)
  6. [![License](https://img.shields.io/badge/License-Apache%202.0-red)](LICENSE)
  7. ## 📊 **Current Status**
  8. | Component | Status | Details |
  9. |-----------|--------|---------|
  10. | **MCP Server** | ✅ **Working** | JSON-RPC 2.0, 12 registered tools, Claude Code integration |
  11. | **OpenFOAM Integration** | ⚠️ **Partial** | Basic connectivity, solver migration needed for OF12 |
  12. | **Educational AI** | ✅ **Working** | Context engine, Socratic questioning, adaptive learning |
  13. | **Mesh & Geometry Tools** | ✅ **Complete** | Mesh quality assessment, STL analysis with snappyHexMesh guidance |
  14. | **RDE Analysis Suite** | ✅ **Complete** | 2D/3D wave analysis, geometry generation, performance calculation |
  15. | **Pipe Flow Analysis** | ✅ **Complete** | Full implementation with mesh generation and validation |
  16. | **Advanced Physics** | ⚠️ **In Development** | Heat transfer, multiphase frameworks exist, need implementation |
  17. **Overall System Status: 75% Functional** - Core educational, mesh quality, and RDE analysis capabilities working.
  18. ## 🎯 Why This MCP? The CFD-AI Educational Revolution
  19. ### The Problem: CFD Expertise Barrier
  20. - **Complex Setup**: OpenFOAM requires deep expertise in mesh generation, boundary conditions, and solver selection
  21. - **Physics Knowledge**: CFD analysis demands understanding of fluid dynamics, heat transfer, and numerical methods
  22. - **Time-Intensive**: Manual setup and analysis can take hours to days for complex cases
  23. - **Error-Prone**: Incorrect boundary conditions or solver settings lead to non-physical results
  24. - **Learning Curve**: Traditional CFD tools lack educational guidance and progressive learning support
  25. ### The Solution: Intelligent CFD Education System
  26. This revolutionary MCP transforms CFD learning and problem-solving through:
  27. - **Context Engineering**: Advanced user modeling that tracks CFD concept understanding and adapts complexity
  28. - **Socratic Questioning**: Strategic questioning engine with 4 proven patterns (Clarify, Explore, Confirm, Apply)
  29. - **Intelligent Parameter Extraction**: Natural language to CFD parameter translation with confidence scoring
  30. - **Advanced Error Resolution**: 5 Whys methodology with research-backed solutions and academic references
  31. - **CFD Knowledge Graph**: Concept relationship mapping for guided learning paths
  32. - **Dual-Terminal Architecture**: Seamless OpenFOAM execution with intelligent conversation flow
  33. ### Market Impact
  34. - **Revolutionizes CFD Education**: First AI-driven system that teaches CFD through guided discovery
  35. - **Democratizes CFD**: Makes professional fluid dynamics analysis accessible through natural language
  36. - **Accelerates Learning**: Progressive complexity adaptation based on user understanding level
  37. - **Enhances Problem-Solving**: 5 Whys error resolution with research-backed solutions
  38. - **Professional Integration**: Maintains full OpenFOAM compatibility with intelligent guidance overlay
  39. ## 🛠️ Intelligent CFD Capabilities
  40. ### 🧠 Advanced AI Features
  41. #### **Context Engineering System**
  42. - **Enhanced User Modeling**: Tracks CFD concept understanding, experience level, and learning progress
  43. - **Confidence Scoring**: Monitors user comprehension across fluid dynamics, heat transfer, and numerical methods
  44. - **Adaptive Complexity**: Automatically adjusts explanations and guidance based on user expertise
  45. - **Learning Path Optimization**: Suggests optimal concept progression for effective CFD mastery
  46. #### **Socratic Questioning Engine**
  47. - **Strategic Question Patterns**: 4 proven educational strategies for progressive learning
  48. - 🔍 **CLARIFY**: "What specifically do you mean by turbulent flow in this context?"
  49. - 🌊 **EXPLORE**: "What would happen if we increased the Reynolds number to 500,000?"
  50. - ✅ **CONFIRM**: "So you're saying that pressure drop increases quadratically with velocity?"
  51. - 🎯 **APPLY**: "How would you use the Moody diagram for this pipe flow problem?"
  52. - **Context-Aware Questions**: Generated based on user's current understanding and conversation history
  53. - **Progressive Difficulty**: Questions adapt complexity to build understanding systematically
  54. #### **Intelligent Parameter Extraction**
  55. - **Natural Language Processing**: Converts conversational descriptions to precise CFD parameters
  56. - **Physics Validation**: Ensures extracted parameters are physically reasonable and consistent
  57. - **Confidence Scoring**: Provides certainty levels for parameter extraction accuracy
  58. - **Interactive Clarification**: Asks intelligent follow-up questions when parameters are ambiguous
  59. #### **Advanced Error Resolution**
  60. - **5 Whys Methodology**: Systematic root cause analysis for CFD simulation failures
  61. - **Research Integration**: Academic paper database with evidence-based solutions
  62. - **Diagnostic Guidance**: Step-by-step troubleshooting with educational explanations
  63. - **Prevention Strategies**: Teaches users to avoid similar issues through understanding
  64. #### **CFD Knowledge Graph**
  65. - **Concept Relationships**: Maps connections between fluid mechanics, heat transfer, and numerical methods
  66. - **Learning Dependencies**: Identifies prerequisite concepts for advanced topics
  67. - **Skill Assessment**: Evaluates user knowledge gaps and suggests focused learning areas
  68. - **Academic References**: Links concepts to authoritative sources and research papers
  69. ### 📋 Available MCP Tools
  70. The server provides **12 registered tools** across different CFD domains:
  71. | Tool | Description | Status |
  72. |------|-------------|--------|
  73. | `start_cfd_assistance` | Start an intelligent CFD conversation with context engineering | ✅ Working |
  74. | `continue_cfd_conversation` | Continue CFD discussion with adaptive Socratic questioning | ✅ Working |
  75. | `execute_openfoam_operation` | Execute OpenFOAM operations (mesh, solve, post-process) | ✅ Working |
  76. | `analyze_cfd_results` | Analyze CFD results with educational explanations | ✅ Working |
  77. | `get_cfd_learning_guidance` | Get personalized CFD learning recommendations | ✅ Working |
  78. | `assess_mesh_quality` | Mesh quality analysis with solver compatibility assessment | ✅ Working |
  79. | `analyze_stl_geometry` | STL preprocessing and snappyHexMesh readiness analysis | ✅ Working |
  80. | `analyze_turbulent_flow` | Comprehensive turbulent flow analysis with model recommendations | ✅ Working |
  81. | `analyze_rde_waves_2d` | 2D RDE wave detection and performance metrics | ✅ Working |
  82. | `generate_rde_3d_geometry` | 3D RDE annular geometry generation with blockMesh | ✅ Working |
  83. | `analyze_rde_waves_3d` | 3D RDE wave propagation and interaction analysis | ✅ Working |
  84. | `calculate_rde_3d_performance` | 3D RDE thrust, Isp, and efficiency calculations | ✅ Working |
  85. ### Core Analysis Tools
  86. #### 1. 🔬 **Pipe Flow Analysis** (`run_pipe_flow`)
  87. **Physics**: Internal flow in circular pipes with laminar flow analysis
  88. - **Calculates**: Reynolds number, friction factor, pressure drop, wall shear stress
  89. - **Applications**: Hydraulic systems, pipeline design, HVAC analysis
  90. - **Solvers**: `icoFoam` (laminar), `foamRun -solver incompressibleFluid` (in development)
  91. - **Status**: ✅ **Working** - Complete implementation with mesh generation
  92. - **Current Limitations**: For advanced turbulent analysis, use `analyze_turbulent_flow`
  93. #### 1b. 🌀 **Turbulent Flow Analysis** (`analyze_turbulent_flow`)
  94. **Physics**: Comprehensive turbulent flow analysis for pipes, channels, and external flows
  95. - **Turbulence Models**: Automatic selection between k-epsilon and k-omega SST with justification
  96. - **Friction Factors**: Smooth pipes (Blasius) and rough pipes (Colebrook-White/Swamee-Jain)
  97. - **Pipe Roughness**: Built-in database with 13 standard materials (steel, cast iron, PVC, etc.)
  98. - **Calculates**:
  99. - Reynolds number and flow regime classification
  100. - Friction factor (smooth and rough pipes)
  101. - Pressure drop and head loss (Darcy-Weisbach)
  102. - Wall shear stress and friction velocity
  103. - y+ estimation and first cell height recommendations
  104. - Turbulent inlet conditions (k, ε, ω, νt)
  105. - **Mesh Guidance**: y+ validation for wall functions, first cell height calculator
  106. - **Educational Content**: Socratic questions, physics explanations, model comparisons
  107. - **Status**: ✅ **Working** - Complete implementation with validation
  108. #### 2. ✈️ **External Flow Analysis** (`analyze_external_flow`)
  109. **Physics**: Basic aerodynamics analysis (simplified implementation)
  110. - **Calculates**: Basic flow patterns and pressure distributions
  111. - **Applications**: Preliminary aerodynamic assessments
  112. - **Solvers**: `foamRun -solver incompressibleFluid` (basic configuration)
  113. - **Status**: ⚠️ **Partial** - Framework exists, needs solver integration fixes
  114. - **Current Limitations**: Advanced turbulence models not fully integrated
  115. #### 3. 🌡️ **Heat Transfer Analysis** (`analyze_heat_transfer`)
  116. **Physics**: Basic heat transfer analysis (limited implementation)
  117. - **Calculates**: Temperature distributions (simplified cases)
  118. - **Applications**: Basic thermal analysis
  119. - **Solvers**: Heat transfer solvers integration in progress
  120. - **Status**: ⚠️ **In Development** - Basic framework, solver integration needed
  121. - **Current Limitations**: Conjugate heat transfer not yet implemented
  122. #### 4. 🌊 **Multiphase Flow Analysis** (`analyze_multiphase_flow`)
  123. **Physics**: Multiphase flow framework (early development)
  124. - **Applications**: Basic free surface flow analysis
  125. - **Solvers**: Multiphase solver integration planned
  126. - **Status**: ⚠️ **Framework Only** - Tool structure exists, solver integration needed
  127. - **Current Limitations**: VOF methods and advanced multiphase physics not implemented
  128. ### Mesh & Geometry Tools
  129. #### 5. 📐 **Mesh Quality Assessment** (`assess_mesh_quality`)
  130. **Purpose**: Comprehensive mesh quality analysis for OpenFOAM cases
  131. - **Metrics**: Non-orthogonality, skewness, aspect ratio, cell volume distribution
  132. - **Features**: Solver compatibility assessment, quality grading (A-F), improvement recommendations
  133. - **Educational**: Explains mesh quality impact on solver convergence and accuracy
  134. - **Status**: ✅ **Working** - Complete implementation with educational content
  135. #### 6. 🔺 **STL Geometry Analyzer** (`analyze_stl_geometry`)
  136. **Purpose**: STL file quality analysis for snappyHexMesh preprocessing
  137. - **Checks**: Watertightness, manifold edges, normal consistency, triangle quality
  138. - **Features**: Feature edge extraction, refinement region suggestions, complexity assessment
  139. - **Expert Insight**: "90% of snappyHexMesh failures start with bad geometry"
  140. - **Status**: ✅ **Working** - Complete implementation with repair guidance
  141. ### RDE (Rotating Detonation Engine) Analysis Suite
  142. #### 7. 🔥 **2D RDE Wave Analysis** (`analyze_rde_waves_2d`)
  143. **Physics**: 2D rotating detonation wave detection and performance analysis
  144. - **Detects**: Wave fronts, multi-wave interactions, collision events
  145. - **Calculates**: Thrust (validated: 11,519 N), Isp (1,629 s), combustion efficiency (85%)
  146. - **Features**: Wave tracking, collision analysis, stability assessment
  147. - **Status**: ✅ **Working** - Validated against analytical solutions
  148. #### 8. 🏗️ **3D RDE Geometry Generator** (`generate_rde_3d_geometry`)
  149. **Purpose**: Generate complete 3D annular RDE geometry for OpenFOAM
  150. - **Components**: Inlet section, annular combustor, nozzle with expansion
  151. - **Outputs**: blockMeshDict, boundary patches, injection port locations
  152. - **Features**: Mesh quality prediction, computational requirement estimation
  153. - **Status**: ✅ **Working** - Full geometry generation with validation
  154. #### 9. 🌀 **3D RDE Wave Analysis** (`analyze_rde_waves_3d`)
  155. **Physics**: 3D detonation wave propagation and interaction analysis
  156. - **Tracks**: 3D wave fronts, axial propagation, wave-wave interactions
  157. - **Calculates**: 3D thrust components, radial losses, wave collision enhancement
  158. - **Educational**: Explains 3D vs 2D wave physics differences
  159. - **Status**: ✅ **Working** - Enhanced from validated 2D baseline
  160. #### 10. 📊 **3D RDE Performance Calculator** (`calculate_rde_3d_performance`)
  161. **Purpose**: Comprehensive 3D RDE performance metrics calculation
  162. - **Thrust Analysis**: Combustor + nozzle breakdown, axial/radial components
  163. - **Efficiency**: Combustion efficiency, nozzle performance, mixing analysis
  164. - **Validation**: Compares against 2D baseline (11,519 N, 1,629 s, 85%)
  165. - **Status**: ✅ **Working** - Complete with optimization guidance
  166. ### 🎯 Intelligent CFD Education Features
  167. #### 🧮 **Physics-Based Calculations with AI Guidance**
  168. - **Dimensionless Numbers**: Reynolds, Prandtl, Nusselt, Rayleigh, Grashof with educational context
  169. - **Material Properties**: Thermal conductivity, density, specific heat, viscosity with database references
  170. - **Validation**: Analytical comparisons against Hagen-Poiseuille, Blasius, and experimental correlations
  171. - **Error Detection**: Non-physical results detection with 5 Whys analysis and resolution guidance
  172. #### 🎓 **Adaptive Educational Content**
  173. - **Progressive Physics Explanations**: Complexity adapts to user's demonstrated understanding level
  174. - **Socratic Teaching Method**: Strategic questioning to build deep conceptual understanding
  175. - **Engineering Guidance**: Context-aware design recommendations with academic justification
  176. - **Industry Applications**: Real-world examples from automotive, aerospace, electronics, and marine sectors
  177. - **Best Practices**: Intelligent mesh quality assessment, boundary condition validation, solver selection logic
  178. #### 🔍 **Comprehensive CFD Validation Framework**
  179. - **Multi-Physics Domains**: Validation across pipe flow, external flow, heat transfer, and multiphase systems
  180. - **Analytical Solutions**: Automatic comparison with classical solutions (Poiseuille, Blasius, Rayleigh-Bénard)
  181. - **Experimental Validation**: Database of experimental correlations and benchmark cases
  182. - **Confidence Metrics**: Statistical validation with uncertainty quantification and error bounds
  183. #### 📊 **Intelligent Visualization & Results**
  184. - **ParaView Web Interface**: Real-time result visualization on port 8080 with educational annotations
  185. - **Context-Aware Plots**: Automatically generated visualizations based on physics domain and user understanding
  186. - **Interactive Learning**: Guided exploration of results with Socratic questioning about flow phenomena
  187. - **Streamlines & Pathlines**: Flow visualization with educational explanations of particle tracking
  188. - **Result Export**: VTK format for advanced post-processing with comprehensive metadata
  189. ## 📥 Installation
  190. ### Prerequisites
  191. #### System Requirements
  192. - **OS**: Ubuntu 20.04+ or Debian 11+ (recommended)
  193. - **Memory**: 8GB+ RAM (16GB+ recommended for large simulations)
  194. - **Storage**: 10GB+ available disk space
  195. - **CPU**: Multi-core processor (4+ cores recommended)
  196. #### Required Dependencies
  197. ```bash
  198. # Ubuntu/Debian - Install all dependencies
  199. sudo apt-get update
  200. sudo apt-get install -y \
  201. cmake \
  202. build-essential \
  203. git \
  204. nlohmann-json3-dev \
  205. libboost-system-dev \
  206. libboost-thread-dev \
  207. sqlite3 \
  208. libsqlite3-dev
  209. ```
  210. #### OpenFOAM 12 Installation
  211. ```bash
  212. # Ubuntu/Debian packages (recommended)
  213. sudo apt-get update
  214. sudo apt-get install openfoam12
  215. # Alternative: OpenFOAM Foundation packages
  216. wget -O - https://dl.openfoam.org/gpg.key | sudo apt-key add -
  217. sudo add-apt-repository http://dl.openfoam.org/ubuntu
  218. sudo apt-get update
  219. sudo apt-get install openfoam12
  220. ```
  221. #### Environment Setup & Verification
  222. ```bash
  223. # Verify installation
  224. export LD_LIBRARY_PATH=/opt/openfoam12/platforms/linux64GccDPInt32Opt/lib/dummy:/opt/openfoam12/platforms/linux64GccDPInt32Opt/lib:$LD_LIBRARY_PATH
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 269 on GitHub
  225. export PATH=/opt/openfoam12/platforms/linux64GccDPInt32Opt/bin:$PATH
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 270 on GitHub
  226. export WM_PROJECT_DIR=/opt/openfoam12
  227. # Test core utilities
  228. which blockMesh # ✅ Mesh generation
  229. which foamRun # ✅ Modern solver framework
  230. which icoFoam # ✅ Laminar flow solver
  231. # Note: OpenFOAM 12 uses foamRun instead of individual solver executables
  232. ```
  233. ### Build MCP Server
  234. 1. **Clone Repository**
  235. ```bash
  236. git clone https://github.com/webworn/openfoam-mcp-server.git
  237. cd openfoam-mcp-server
  238. ```
  239. 2. **Build with CMake**
  240. ```bash
  241. mkdir build && cd build
  242. cmake ..
  243. make -j$(nproc)
  244. ```
  245. 3. **Test Installation**
  246. ```bash
  247. # Test server builds successfully
  248. ./openfoam-mcp-server-test # Minimal test version
  249. ./openfoam-mcp-server # Full version (requires complete OpenFOAM setup)
  250. # Verify MCP connectivity
  251. python3 comprehensive_system_test.py
  252. ```
  253. ### Dependencies Auto-Detection
  254. The build system automatically detects:
  255. - ✅ **OpenFOAM Libraries**: `/opt/openfoam12/platforms/linux64GccDPInt32Opt/lib`
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 308 on GitHub
  256. - ✅ **nlohmann/json**: JSON parsing for MCP protocol
  257. - ✅ **Boost**: System and threading libraries
  258. - ✅ **SQLite3**: Optional case database storage
  259. ## 🤖 Claude Code Integration
  260. ### MCP Configuration
  261. Add the server to Claude Code using the CLI:
  262. ```bash
  263. # Add OpenFOAM MCP server
  264. claude mcp add-json openfoam-mcp-server '{
  265. "command": "/workspaces/openfoam-mcp-server/build/openfoam-mcp-server-test",
  266. "args": [],
  267. "env": {
  268. "LD_LIBRARY_PATH": "/opt/openfoam12/platforms/linux64GccDPInt32Opt/lib/dummy:/opt/openfoam12/platforms/linux64GccDPInt32Opt/lib",
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 325 on GitHub
  269. "FOAM_INST_DIR": "/opt/openfoam12",
  270. "WM_PROJECT_DIR": "/opt/openfoam12",
  271. "FOAM_LIBBIN": "/opt/openfoam12/platforms/linux64GccDPInt32Opt/lib",
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 328 on GitHub
  272. "FOAM_APPBIN": "/opt/openfoam12/platforms/linux64GccDPInt32Opt/bin",
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 329 on GitHub
  273. "FOAM_ETC": "/opt/openfoam12/etc",
  274. "PATH": "/opt/openfoam12/platforms/linux64GccDPInt32Opt/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 331 on GitHub
  275. }
  276. }'
  277. # Verify server connection
  278. claude mcp list
  279. # Should show: openfoam-mcp-server - ✓ Connected
  280. ```
  281. ### Intelligent CFD Assistant Examples
  282. #### Socratic Learning: Pipe Flow Analysis
  283. ```
  284. 🧑‍💻 User: "Analyze water flow in a 0.1m diameter pipe at 2 m/s"
  285. 🤖 Claude: Before I run the analysis, let me understand your background better.
  286. 🔍 CLARIFY: "What specifically interests you about this pipe flow - are you designing a hydraulic system, learning about pressure losses, or optimizing an existing installation?"
  287. 🧑‍💻 User: "I'm learning about pressure losses for my fluid mechanics course"
  288. 🤖 Claude: Perfect! I'll guide you through the analysis step by step.
  289. *Uses run_pipe_flow tool with educational context*
  290. 📊 Results with Learning:
  291. • Reynolds Number: 200,000
  292. 💡 This indicates turbulent flow (Re > 4,000). What do you think this means for mixing?
  293. • Friction Factor: 0.0184 (Blasius correlation)
  294. 🌊 EXPLORE: How would this change if we doubled the velocity?
  295. • Pressure Drop: 2.4 kPa per meter
  296. ✅ CONFIRM: So you're seeing that pressure drop increases significantly with velocity - can you explain why?
  297. 🎯 APPLY: "Now that you understand the relationship, how would you redesign this pipe to reduce pumping costs by 50%?"
  298. ```
  299. #### Context-Aware Error Resolution
  300. ```
  301. 🧑‍💻 User: "My heat transfer simulation isn't converging. The residuals keep oscillating."
  302. 🤖 Claude: I'll help you resolve this using systematic analysis.
  303. *Applies 5 Whys methodology*
  304. 🔍 Why #1: "Why are the residuals oscillating?"
  305. Analysis: Likely numerical instability or inappropriate relaxation factors.
  306. 🔍 Why #2: "Why might the relaxation factors be inappropriate?"
  307. Your setup shows high temperature gradients that require more conservative factors.
  308. 🔍 Why #3: "Why are the temperature gradients so high?"
  309. The boundary conditions show a 500K temperature difference across a thin wall.
  310. 📚 Research-Backed Solution:
  311. • Reduce temperature relaxation from 0.7 to 0.3 (Versteeg & Malalasekera, 2007)
  312. • Implement under-relaxation for energy equation (Patankar, 1980)
  313. • Consider CFL number for transient effects
  314. 🎯 Prevention Strategy:
  315. • Always validate physical temperature ranges before simulation
  316. • Use dimensionless temperature analysis for better conditioning
  317. • Implement gradual temperature ramping for extreme conditions
  318. ```
  319. #### Parameter Extraction from Natural Language
  320. ```
  321. 🧑‍💻 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."
  322. 🤖 Claude: I can help with this dam break/draining analysis! Let me extract the CFD parameters from your description.
  323. *Uses intelligent parameter extraction*
  324. 📋 Extracted Parameters (Confidence: 85%):
  325. • Physics Domain: Multiphase flow (free surface)
  326. • Initial water height: 2.0 m ✓
  327. • Geometry: Tank with bottom orifice ✓
  328. • Fluid: Water (ρ=1000 kg/m³, μ=1e-3 Pa·s) ✓
  329. ❓ Clarification Needed:
  330. • Tank dimensions (length, width)?
  331. • Orifice diameter?
  332. • Are we modeling turbulence effects?
  333. 🔍 EXPLORE: "Based on Torricelli's law, what do you expect happens to the flow rate as the tank empties?"
  334. *After clarification, runs multiphase flow analysis*
  335. 📊 Results with Physics Insight:
  336. • Analytical (Torricelli): ~89 seconds for complete drainage
  337. • CFD Simulation: ~94 seconds (includes viscous effects)
  338. • Flow regime: Initially turbulent (Re~50,000), transitions to laminar
  339. • Vortex formation near orifice affects drainage rate by ~5%
  340. ```
  341. ### Intelligent Workflow Integration
  342. #### AI-Enhanced Engineering Design Process
  343. 1. **Conceptual Design**: Context-aware initial sizing with intelligent parameter extraction
  344. 2. **Physics Validation**: Socratic questioning to ensure understanding of assumptions
  345. 3. **Detailed Analysis**: Export OpenFOAM cases with AI-generated documentation
  346. 4. **Error Resolution**: 5 Whys methodology for systematic troubleshooting
  347. 5. **Optimization**: AI-guided design improvements with academic justification
  348. 6. **Validation**: Automatic comparison with analytical solutions and experimental data
  349. #### Progressive CFD Education
  350. 1. **Adaptive Learning**: Complexity automatically adjusts to demonstrated user understanding
  351. 2. **Concept Mapping**: CFD knowledge graph guides learning path optimization
  352. 3. **Socratic Discovery**: Strategic questioning builds deep conceptual understanding
  353. 4. **Research Integration**: Academic papers and validated solutions support learning
  354. 5. **Industry Context**: Real-world applications connect theory to practice
  355. 6. **Error Prevention**: Learn from mistakes through systematic root cause analysis
  356. ## 🤝 Contributing
  357. ### Development Environment
  358. **GitHub Codespaces** (Recommended):
  359. 1. Fork the repository
  360. 2. Open in Codespaces (auto-configures OpenFOAM 12)
  361. 3. VS Code Desktop integration with full IntelliSense
  362. 4. Cloud development with 4-32 core machines
  363. **Local Development**:
  364. ```bash
  365. # Install dependencies
  366. sudo apt-get install cmake build-essential openfoam12 nlohmann-json3-dev
  367. # Clone and build
  368. git clone https://github.com/webworn/openfoam-mcp-server.git
  369. cd openfoam-mcp-server
  370. mkdir build && cd build
  371. cmake .. && make -j$(nproc)
  372. ```
  373. ### Adding New Analysis Tools
  374. #### 1. Create Analyzer Class
  375. ```cpp
  376. // src/openfoam/your_analysis.hpp
  377. class YourAnalyzer {
  378. public:
  379. struct Input { /* physics parameters */ };
  380. struct Results { /* calculated outputs */ };
  381. Results analyze(const Input& input);
  382. bool validateInput(const Input& input);
  383. json toJson(const Results& results);
  384. };
  385. ```
  386. #### 2. Create MCP Tool Wrapper
  387. ```cpp
  388. // src/tools/your_analysis_tool.hpp
  389. class YourAnalysisTool {
  390. public:
  391. static std::string getName() { return "your_analysis"; }
  392. static std::string getDescription() { return "Physics description"; }
  393. static json getInputSchema();
  394. ToolResult execute(const json& arguments);
  395. };
  396. ```
  397. #### 3. Register Tool
  398. ```cpp
  399. // src/main.cpp
  400. #include "tools/your_analysis_tool.hpp"
  401. int main() {
  402. McpServer server;
  403. registerYourAnalysisTool(server); // Add this line
  404. server.start();
  405. }
  406. ```
  407. ### Physics Implementation Guidelines
  408. #### OpenFOAM Integration
  409. - **Case Templates**: Use `src/openfoam/case_templates/` for solver setup
  410. - **Boundary Conditions**: Implement physics-appropriate BC selection
  411. - **Mesh Generation**: Add automatic meshing with quality checks
  412. - **Solver Selection**: Choose appropriate OpenFOAM solver for physics
  413. #### Validation Requirements
  414. - **Analytical Comparison**: Compare with known solutions (Poiseuille, Blasius, etc.)
  415. - **Experimental Data**: Validate against published correlations
  416. - **Convergence Studies**: Ensure mesh-independent results
  417. - **Physical Bounds**: Check for non-physical results
  418. #### Educational Content
  419. - **Physics Explanations**: Describe governing equations and assumptions
  420. - **Dimensionless Numbers**: Calculate and explain significance
  421. - **Engineering Context**: Provide industry-relevant guidance
  422. - **Design Recommendations**: Suggest optimization strategies
  423. ### Code Standards
  424. #### C++ Best Practices
  425. - **C++20 Standard**: Use modern C++ features appropriately
  426. - **OpenFOAM Style**: Follow OpenFOAM coding conventions
  427. - **Memory Management**: Use smart pointers, RAII principles
  428. - **Error Handling**: Comprehensive exception handling
  429. #### MCP Protocol Compliance
  430. - **JSON-RPC 2.0**: Strict protocol adherence
  431. - **Schema Validation**: Complete input parameter validation
  432. - **Error Messages**: User-friendly error reporting
  433. - **Resource Management**: Proper cleanup and case management
  434. ## 🏗️ Technical Architecture
  435. ### System Overview
  436. ```
  437. ┌─────────────────┐ JSON-RPC 2.0 ┌──────────────────┐
  438. │ Claude Code │ ◄──────────────── │ MCP Server │
  439. │ AI Assistant │ │ (12 Tools) │
  440. └─────────────────┘ └──────────────────┘
  441. │
  442. ▼
  443. ┌──────────────────┐
  444. │ Tool Router │
  445. │ (Registration) │
  446. └──────────────────┘
  447. │
  448. ┌──────────────┬──────────────┬───────┴───────┬──────────────┬──────────────┐
  449. ▼ ▼ ▼ ▼ ▼ ▼
  450. ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
  451. │CFD Assistant│ │ Mesh Quality│ │STL Analyzer │ │ RDE 2D Wave │ │RDE 3D Tools │ │ Pipe Flow │
  452. │ (5 tools) │ │ Tool │ │ Tool │ │ Tool │ │ (3 tools) │ │ Tool │
  453. └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
  454. │ │ │ │ │ │
  455. ▼ ▼ ▼ ▼ ▼ ▼
  456. ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
  457. │ Context │ │MeshQuality │ │ STLAnalyzer │ │RDE2DWave │ │RDE3DGeometry│ │ PipeFlow │
  458. │ Engine │ │ Analyzer │ │ Class │ │ Analyzer │ │/Wave/Perf │ │ Analyzer │
  459. └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
  460. │ │ │ │ │ │
  461. └──────────────┴──────────────┴───────┬───────┴──────────────┴──────────────┘
  462. ▼
  463. ┌──────────────────┐
  464. │ Case Manager │
  465. │ (OpenFOAM) │
  466. └──────────────────┘
  467. │
  468. ▼
  469. ┌──────────────────┐
  470. │ OpenFOAM │
  471. │ Solvers │
  472. │ (Native C++) │
  473. └──────────────────┘
  474. ```
  475. ### Data Flow
  476. 1. **User Request**: Natural language query to Claude Code
  477. 2. **AI Processing**: Claude interprets request and calls appropriate MCP tool
  478. 3. **Parameter Validation**: Input schema validation and physics bounds checking
  479. 4. **OpenFOAM Setup**: Automated case creation with boundary conditions
  480. 5. **CFD Simulation**: Native OpenFOAM solver execution
  481. 6. **Result Processing**: Physics calculations and educational content generation
  482. 7. **Response**: Formatted results with explanations and recommendations
  483. ### Performance Features
  484. - **Parallel Execution**: Multi-threaded OpenFOAM solvers
  485. - **Case Caching**: Intelligent reuse of similar simulations
  486. - **Mesh Templates**: Pre-validated meshes for common geometries
  487. - **Async Processing**: Non-blocking simulation execution (planned)
  488. ## 📚 References
  489. - **OpenFOAM Foundation**: [https://openfoam.org/](https://openfoam.org/)
  490. - **Model Context Protocol**: [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/)
  491. - **CFD Theory**: "An Introduction to Computational Fluid Dynamics" by Versteeg & Malalasekera
  492. - **Heat Transfer**: "Heat Transfer" by Cengel & Ghajar
  493. - **Fluid Mechanics**: "Fluid Mechanics" by White
  494. ## 📄 License
  495. Apache License 2.0 - see [LICENSE](LICENSE) for details.
  496. ## 🙏 Acknowledgments
  497. - **OpenFOAM Foundation** for the world-class CFD toolkit
  498. - **Anthropic** for Claude Code and MCP protocol
  499. - **CFD Community** for validation data and best practices
  500. ## 🚧 Current Development Status & Roadmap
  501. *Join us in building an intelligent CFD-AI integration platform!*
  502. ### ✅ **Completed Features**
  503. #### **Core Infrastructure**
  504. - ✅ **MCP Server Framework**: JSON-RPC 2.0 protocol implementation
  505. - ✅ **OpenFOAM 12 Integration**: Basic solver connectivity with dummy Pstream
  506. - ✅ **Mesh Generation**: Working blockMesh integration for structured grids
  507. - ✅ **Educational AI**: Context engine, Socratic questioning, parameter extraction
  508. - ✅ **Pipe Flow Analysis**: Complete implementation with turbulence model setup
  509. ### 🔧 **In Active Development**
  510. #### **OpenFOAM 12 Compatibility** (Priority: High)
  511. - 🔄 **Solver Migration**: Updating from legacy solver names to `foamRun` framework
  512. - 🔄 **Configuration Updates**: Modern OpenFOAM 12 solver dictionaries
  513. - ✅ **Turbulence Models**: k-ε and k-ω SST integration complete with `analyze_turbulent_flow` tool
  514. - 🔄 **JSON Response Fixes**: Resolving 2/5 tool output formatting issues
  515. #### **Enhanced Physics Domains** (Priority: Medium)
  516. - 🔄 **External Flow**: Complete aerodynamics tool with turbulence models
  517. - 🔄 **Heat Transfer**: Basic conjugate heat transfer implementation
  518. - 🔄 **Multiphase Flow**: VOF method integration for free surface flows
  519. ### 📋 **Planned Industry Applications** (Future Development)
  520. #### **Phase 2 Development** (6-12 months)
  521. - **🚗 Automotive**: Vehicle aerodynamics, underhood cooling, HVAC systems
  522. - **✈️ Aerospace**: Airfoil analysis, propulsion systems, hypersonic flows
  523. - **⚡ Energy**: Wind turbines, solar collectors, gas turbines
  524. - **🏥 Biomedical**: Blood flow simulation, drug delivery, medical devices
  525. - **🌊 Marine**: Ship resistance, offshore platforms, propeller analysis
  526. *Note: These are planned extensions requiring additional solver integration and validation*
  527. ### 🧠 **AI-Enhanced Capabilities** (In Development)
  528. #### **Current AI Features** (✅ Implemented)
  529. - ✅ **Context Engineering**: User modeling and adaptive explanations
  530. - ✅ **Socratic Questioning**: 4 strategic educational patterns (CLARIFY, EXPLORE, CONFIRM, APPLY)
  531. - ✅ **Intelligent Parameter Extraction**: Natural language to CFD parameter conversion
  532. - ✅ **5 Whys Error Resolution**: Systematic troubleshooting methodology
  533. #### **Planned AI Enhancements** (🔄 Future)
  534. - 🔄 **Auto-Mesh Generation**: AI-driven mesh adaptation based on physics
  535. - 🔄 **Convergence Prediction**: ML-based convergence behavior forecasting
  536. - 🔄 **Multi-Objective Optimization**: Pareto-optimal design exploration
  537. - 🔄 **Performance Prediction**: AI models trained on CFD databases
  538. ### 🔧 **Technical Architecture** (Current Implementation)
  539. #### **Working Components**
  540. - ✅ **MCP Protocol**: JSON-RPC 2.0 with tool registration
  541. - ✅ **OpenFOAM Integration**: Basic solver connectivity
  542. - ✅ **Mesh Generation**: blockMesh with quality assessment
  543. - ✅ **Educational Framework**: Context-aware learning system
  544. #### **Development Priorities**
  545. - 🔄 **Solver Modernization**: Update to OpenFOAM 12 foamRun framework
  546. - 🔄 **JSON Response Fixes**: Resolve tool output formatting issues
  547. - 🔄 **Validation Framework**: Automated testing against analytical solutions
  548. - 🔄 **Case Management**: Improved workflow automation
  549. ### 📊 **Current Tool & Solver Status Matrix**
  550. | **Domain** | **Status** | **Implementation** | **Notes** |
  551. |------------|------------|-------------------|-----------|
  552. | **Mesh Quality** | ✅ **Working** | `assess_mesh_quality` tool | Non-orthogonality, skewness, solver compatibility |
  553. | **STL Analysis** | ✅ **Working** | `analyze_stl_geometry` tool | Watertight check, feature extraction, snappyHexMesh prep |
  554. | **RDE 2D Waves** | ✅ **Working** | `analyze_rde_waves_2d` tool | Wave detection, collision analysis, performance metrics |
  555. | **RDE 3D Suite** | ✅ **Working** | 3 tools (geometry, waves, performance) | Complete 3D RDE analysis workflow |
  556. | **Laminar Flow** | ✅ **Working** | `icoFoam` integration | Pipe flow analysis complete |
  557. | **Turbulent Flow** | ✅ **Working** | `analyze_turbulent_flow` tool | k-ε, k-ω SST, Colebrook-White, y+ calculations |
  558. | **External Flow** | ⚠️ **Framework** | Basic structure | Solver integration in progress |
  559. | **Heat Transfer** | ⚠️ **Framework** | Tool skeleton | Requires solver implementation |
  560. | **Multiphase** | ⚠️ **Framework** | Basic structure | VOF integration planned |
  561. | **Compressible** | 📋 **Planned** | Not started | Future development |
  562. | **Combustion** | 📋 **Planned** | Not started | Research phase |
  563. ### 🤝 **How to Contribute**
  564. We welcome contributions across all domains! Here's how you can help:
  565. #### **🔬 Physics Domain Experts**
  566. - **Validate Physics Models**: Ensure accurate implementation of governing equations
  567. - **Develop Test Cases**: Create validation cases against analytical/experimental data
  568. - **Write Educational Content**: Explain physics concepts for educational tools
  569. #### **💻 Software Developers**
  570. - **Implement New Tools**: Follow our architecture patterns for new analysis tools
  571. - **Optimize Performance**: Improve computational efficiency and memory usage
  572. - **Enhance UI/UX**: Develop better user interfaces and visualization tools
  573. #### **🏭 Industry Professionals**
  574. - **Define Use Cases**: Specify real-world engineering problems and requirements
  575. - **Provide Test Data**: Share (anonymized) validation cases and benchmarks
  576. - **Review Results**: Validate tool outputs against industrial standards
  577. #### **📚 Educators & Students**
  578. - **Create Tutorials**: Develop educational content and learning materials
  579. - **Test Tools**: Identify usability issues and suggest improvements
  580. - **Documentation**: Improve documentation, examples, and guides
  581. ### 🎯 **Contribution Roadmap**
  582. #### **Immediate Priorities** (Next 3 months)
  583. 1. **OpenFOAM 12 Compatibility**: Fix solver integration and configuration issues
  584. 2. **JSON Response Fixes**: Resolve 2/5 tool output formatting problems
  585. 3. **Validation Framework**: Implement automated testing against analytical solutions
  586. 4. **Documentation Updates**: Align documentation with actual implementation status
  587. #### **Medium-term Development** (6-12 months)
  588. 1. **Advanced Physics**: Complete heat transfer and multiphase flow implementations
  589. 2. ~~**Turbulence Models**~~: ✅ Completed - k-ε and k-ω SST with `analyze_turbulent_flow` tool
  590. 3. **Mesh Quality**: Implement intelligent mesh adaptation and quality assessment
  591. 4. **Industry Applications**: Basic automotive and aerospace analysis tools
  592. #### **Long-term Vision** (1-2 years)
  593. 1. **Comprehensive Solver Coverage**: Integrate major OpenFOAM solver families
  594. 2. **Advanced AI Features**: Machine learning for optimization and prediction
  595. 3. **Real-world Validation**: Extensive validation against experimental data
  596. 4. **Production Deployment**: Stable, scalable system for engineering workflows
  597. ### 📬 **Get Involved**
  598. Ready to contribute? Here's how to start:
  599. 1. **Join Our Community**: Star the repository and join discussions
  600. 2. **Pick an Issue**: Check our [GitHub Issues](https://github.com/webworn/openfoam-mcp-server/issues) for beginner-friendly tasks
  601. 3. **Fork & Develop**: Use GitHub Codespaces for instant development environment
  602. 4. **Submit PR**: Follow our contribution guidelines and submit your improvements
  603. **Together, we're building the future of AI-powered CFD analysis!** 🌊🤖⚡
  604. ---
  605. *Transform your engineering workflow with AI-powered CFD analysis. Get started today!*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.