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