# Clone repository
git clone git@github.com:puran-water/corrosion-engineering-mcp.git
cd corrosion-engineering-mcp

# Activate virtual environment
source ../venv312/bin/activate  # Linux/Mac
# OR
..\venv312\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest tests/test_phase3_pitting_integration.py -v

{
  "mcpServers": {
    "corrosion-engineering": {
      "command": "python",
      "args": ["/path/to/corrosion-engineering-mcp/server.py"]
    }
  }
}

result = calculate_localized_corrosion(
    material="SS316",  # or 316L, 316, UNS S31600 (aliases supported)
    temperature_C=25.0,
    Cl_mg_L=19000.0,
    pH=8.0,
    dissolved_oxygen_mg_L=8.0,  # ← Enables Tier 2
)

# Tier 1 (PREN/CPT - always available)
print(result["pitting"]["susceptibility"])  # "critical" (T > CPT)
print(result["pitting"]["CPT_C"])            # 10.0°C
print(result["pitting"]["PREN"])             # 24.7

# Tier 2 (E_pit vs E_mix - requires DO)
print(result["pitting"]["electrochemical_risk"])  # "low" (E_mix << E_pit)
print(result["pitting"]["E_pit_VSCE"])            # 1.084 V_SCE
print(result["pitting"]["E_mix_VSCE"])            # 0.501 V_SCE

# Tier disagreement detection
print(result["tier_disagreement"]["detected"])    # True
print(result["tier_disagreement"]["explanation"]) # "Trust Tier 2 for accurate assessment..."

{
  "pitting": {
    "CPT_C": 10.0,
    "PREN": 24.7,
    "Cl_threshold_mg_L": 233,
    "susceptibility": "critical",
    "margin_C": -15.0,
    "interpretation": "CRITICAL: T = 25.0°C exceeds CPT...",
    "E_pit_VSCE": 1.084,
    "E_mix_VSCE": 0.501,
    "electrochemical_margin_V": -0.583,
    "electrochemical_risk": "low",
    "electrochemical_interpretation": "LOW RISK: E_mix (0.501 V) is 583 mV below E_pit..."
  },
  "tier_disagreement": {
    "detected": true,
    "tier1_assessment": "critical",
    "tier2_assessment": "low",
    "explanation": "⚠️ TIER DISAGREEMENT: Tier 1 (PREN/CPT empirical) says 'critical' but Tier 2 (E_pit vs E_mix mechanistic) says 'low'. Recommendation: Trust Tier 2..."
  },
  "overall_risk": "critical",
  "recommendations": [
    "⚠️ TIER DISAGREEMENT: Trust Tier 2 for accurate assessment...",
    "CRITICAL: Immediate risk of localized corrosion..."
  ]
}

corrosion-engineering-mcp/
├── server.py                           # FastMCP server
├── requirements.txt                    # Dependencies
├── .mcp.json                          # FastMCP configuration
├── README.md                           # This file
│
├── core/                               # Core architecture
│   ├── interfaces.py                   # Abstract base classes
│   ├── schemas.py                      # Pydantic models (CorrosionResult, etc.)
│   ├── state_container.py              # CorrosionContext caching
│   ├── phreeqc_adapter.py              # PHREEQC backend
│   └── localized_backend.py            # Tier 1+2 pitting backend (Phase 3)
│
├── tools/                              # MCP tool implementations
│   ├── handbook/                       # Tier 0: Semantic search
│   │   ├── material_screening.py       # ✅ screen_materials
│   │   ├── typical_rates.py            # ✅ query_typical_rates
│   │   └── mechanism_guidance.py       # ✅ identify_mechanism
│   ├── chemistry/                      # Tier 1: PHREEQC
│   │   ├── speciation.py               # ✅ run_phreeqc_speciation
│   │   └── calculate_pourbaix.py       # 🔄 calculate_pourbaix (stub)
│   └── mechanistic/                    # Tier 2: Physics models
│       ├── co2_h2s.py                  # ✅ predict_co2_h2s_corrosion
│       ├── aerated_chloride.py         # ✅ predict_aerated_chloride_corrosion
│       ├── predict_galvanic_corrosion.py # ✅ predict_galvanic_corrosion
│       └── localized_corrosion.py      # ✅ calculate_localized_corrosion (Phase 3)
│
├── utils/                              # Utility modules
│   ├── material_database.py            # Authoritative materials data
│   ├── nrl_materials.py                # NRL electrochemical database (Phase 3)
│   ├── nrl_constants.py                # Physical constants (Phase 3)
│   ├── nrl_electrochemical_reactions.py # ORR, HER, Fe oxidation (Phase 3)
│   ├── pitting_assessment.py           # E_pit calculator (Phase 3)
│   ├── redox_state.py                  # DO ↔ Eh conversion (Phase 3)
│   └── nacl_solution_chemistry.py      # NaCl solution properties (Phase 3)
│
├── external/                           # External data files
│   ├── nrl_coefficients/               # 23 CSV files (NRL Butler-Volmer)
│   └── nrl_matlab_reference/           # 12 MATLAB files (NRL validation)
│
├── tests/                              # Test suite
│   ├── test_phase3_pitting_integration.py  # ✅ 9/9 passing
│   ├── test_phase2_galvanic.py             # Phase 2 tests
│   └── test_redox_state.py                 # RedoxState module tests
│
└── docs/                               # Documentation
    ├── TIER1_VS_TIER2_PITTING_GUIDE.md     # User guide (600+ lines)
    ├── POURBAIX_PHREEQC_ROADMAP.md         # Pourbaix integration plan
    └── ...                                 # Additional documentation

# SS316 in aerated seawater
result = calculate_localized_corrosion(
    material="316L",  # Alias → SS316
    temperature_C=25.0,
    Cl_mg_L=19000.0,
    pH=8.0,
    dissolved_oxygen_mg_L=8.0,  # Enables Tier 2
)

# Tier 1: Conservative CPT screening
print(f"CPT: {result['pitting']['CPT_C']}°C")             # 10.0
print(f"Tier 1 Risk: {result['pitting']['susceptibility']}")  # "critical"

# Tier 2: Mechanistic electrochemical
print(f"E_pit: {result['pitting']['E_pit_VSCE']:.3f} V_SCE")  # 1.084
print(f"E_mix: {result['pitting']['E_mix_VSCE']:.3f} V_SCE")  # 0.501
print(f"ΔE: {result['pitting']['electrochemical_margin_V']*1000:.0f} mV")  # -583
print(f"Tier 2 Risk: {result['pitting']['electrochemical_risk']}")  # "low"

# Disagreement detection
if result['tier_disagreement']['detected']:
    print(result['tier_disagreement']['explanation'])
    # "Trust Tier 2 for accurate assessment - it accounts for actual
    #  electrochemical driving force and redox conditions..."

# Steel bolts in stainless flange
result = predict_galvanic_corrosion(
    anode_material="HY80",
    cathode_material="SS316",
    temperature_C=25.0,
    pH=7.5,
    chloride_mg_L=800.0,
    area_ratio_cathode_to_anode=50.0,  # Large flange, small bolts
)

print(f"Galvanic current density: {result['galvanic_current_density_A_cm2']:.2e} A/cm²")
print(f"Anode corrosion rate: {result['anode_corrosion_rate_mm_year']:.3f} mm/year")
if 'warnings' in result and result['warnings']:
    print(f"Warnings: {result['warnings']}")

result = screen_materials(
    environment="CO2-rich brine, 60°C, pCO2=0.5 bar, pH 6.8",
    candidates=["CS", "316L", "duplex_2205"],
    application="piping"
)

print(f"Material: {result.material}")
print(f"Compatibility: {result.compatibility}")
print(f"Typical rate range: {result.typical_rate_range} mm/y")

# MCP Framework
fastmcp>=0.1.0

# Core
numpy>=1.24.0
pandas>=2.0.0
scipy>=1.10.0
pydantic>=2.0.0

# Chemistry
phreeqpython>=1.5.5

# Testing
pytest>=7.0.0
pytest-cov>=4.0.0
pytest-asyncio>=0.21.0

@software{corrosion_mcp_2025,
  title={Corrosion Engineering MCP Server},
  author={Puran Water LLC},
  year={2025},
  url={https://github.com/puran-water/corrosion-engineering-mcp},
  version={0.3.0}
}