Aerobic Design MCP Server

⚠️ DEVELOPMENT STATUS: This project is under active development and is not yet production-ready. APIs, interfaces, and functionality may change without notice. Use at your own risk for evaluation and testing purposes only. Not recommended for production deployments.

An intelligent MCP (Model Context Protocol) server for automated design of aerobic biological wastewater treatment systems with membrane bioreactor (MBR) technology.

---

Overview

The aerobic-design-mcp server enables AI-assisted wastewater treatment design through Claude AI. It implements sophisticated algorithms for flowsheet selection, reactor sizing, and mass balance calculations based on ASM2d (Activated Sludge Model 2d) kinetics.

Key Features

• Automated Flowsheet Selection: Chooses optimal process configuration (MLE, A2O, MLE+Post-Anoxic) based on effluent targets
• Rigorous Mass Balances: Temperature-corrected ASM2d kinetics with sludge, nitrogen, phosphorus, and oxygen balances
• MBR Integration: Membrane bioreactor sizing with flux constraints and fouling factors
• Deaeration Zone Sizing: Optional DO reduction before IR return to improve denitrification efficiency
• Dual MCP Architecture: FastMCP for design tools + Codex for ASM2d component fractionation
• State Persistence: JSON-based design state management for long workflows
• Report Generation: Markdown reports with Obsidian frontmatter, Mermaid diagrams, and LaTeX equations

Supported Flowsheet Types

Flowsheet	Description	Use Case
MLE	Modified Ludzack-Ettinger	Basic N removal
A2O	Anaerobic-Anoxic-Aerobic	EBPR + N removal
MLE_POST	MLE + Post-Anoxic	Enhanced N removal

---

Quick Start

Prerequisites

• Python 3.12+
• Claude Code (for MCP integration)
• Optional: QSDsan (for advanced simulations)

Installation

# Clone the repository
cd /path/to/mcp-servers/aerobic-design-mcp

# Install dependencies
pip install -r requirements.txt

# Optional: Install QSDsan
pip install qsdsan biosteam

MCP Configuration

Add to your Claude Code MCP configuration (.mcp.json):

{
  "mcpServers": {
    "aerobic-design": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/aerobic-design-mcp/server.py"],
      "env": {
        "MCP_TIMEOUT": "600000"
      }
    },
    "ASM2d-State-Variable-Estimator": {
      "type": "stdio",
      "command": "codex",
      "args": ["mcp"],
      "env": {
        "CODEX_HOME": "/path/to/aerobic-design-mcp/.codex"
      }
    }
  }
}

Basic Usage

Step 1: Collect Basis of Design

In Claude Code:

Please collect the basis of design for a wastewater treatment plant:
- Flow: 20,000 m3/d
- COD: 625 mg/L
- TKN: 62.5 mg/L
- TP: 9.37 mg/L
- TSS: 265 mg/L
- Temperature: 12-25°C
- Effluent targets: COD <50, TN <10, TP <1 mg/L

Step 2: Generate ASM2d State

Run the ASM2d state estimator to fractionate the wastewater components.

Step 3: Design the System

Design an aerobic MBR system for this wastewater.

Step 4: Generate Report

Generate a design report in Markdown format.

---

Design Workflow

1. collect_basis_of_design
   ├─ Flow rate, COD, nutrients, temperature
   └─ Effluent quality targets

2. ASM2d Estimator (Codex MCP)
   ├─ Component fractionation (25 mASM2d components)
   └─ Mass balance validation

3. validate_asm2d_state
   ├─ Load and enrich ASM2d state
   └─ Calculate rbCOD profile

4. design_aerobic_mbr
   ├─ Select optimal flowsheet
   ├─ Size reactor zones
   ├─ Calculate recycles
   └─ Validate compliance

5. generate_design_report
   └─ Markdown report (Obsidian-compatible)

---

MCP Tools

Core Tools

Tool	Purpose
collect_basis_of_design	Collect wastewater characteristics and targets
design_aerobic_mbr	Complete design (flowsheet + sizing)
validate_asm2d_state	Load and validate ASM2d state
generate_design_report	Generate Markdown design report

State Management

Tool	Purpose
get_current_design_state	Retrieve current design state
clear_current_design_state	Clear all design state
export_design_to_file	Export design to JSON
import_design_from_file	Import design from JSON

Validation

Tool	Purpose
validate_design_parameters	Validate input parameters

---

CLI Interface

For operations that may block the MCP server, use the CLI interface:

# Validate ASM2d state
python cli_runner.py validate --filepath asm2d_state.json

# Run complete design
python cli_runner.py design --params '{
  "auto_select": true,
  "auto_size": true,
  "save_to_state": true
}'

# Generate report
python cli_runner.py report --format markdown

---

Architecture

High-Level Architecture

┌─────────────┐
│  Claude AI  │
└──────┬──────┘
       │ MCP Protocol
       ├─────────────────┬──────────────┐
       ▼                 ▼              ▼
┌──────────────┐  ┌────────────┐  ┌─────────┐
│   FastMCP    │  │   Codex    │  │   KB    │
│ aerobic-     │  │  ASM2d-Est │  │ Server  │
│ design       │  └────────────┘  └─────────┘
└──────┬───────┘
       │
       ├─ UnifiedProcessDesigner
       ├─ MassBalanceEngine
       ├─ FlowsheetStrategies (MLE/A2O/MLE_POST)
       └─ State Management

Core Components

1. UnifiedProcessDesigner: Orchestrates flowsheet selection and reactor sizing
2. MassBalanceEngine: Single source of truth for all mass balance calculations
3. FlowsheetStrategies: Strategy pattern for different process configurations
4. DesignState: Singleton state management with JSON persistence

See ARCHITECTURE.md for complete architecture documentation.

---

Design Algorithms

Flowsheet Selection Logic

if phosphorus_target_not_met:
    select A2O (EBPR required)
    if still not met:
        recommend chemical P dosing
elif nitrogen_target_not_met_with_MLE:
    if can improve with post-anoxic:
        select MLE_POST
    else:
        recommend external carbon
else:
    select MLE (simplest option)

Temperature-Corrected Kinetics

All kinetic parameters are temperature-corrected:

μ_T = μ_20 × θ^(T - 20)    # Growth rates
b_T = b_20 × θ^(T - 20)    # Decay rates
Y_obs = Y / (1 + b_T × SRT) # Observed yield

Specific Denitrification Rate (SDNR)

Empirical correlation from Metcalf & Eddy:

SDNR = (b0 + b1 × ln(F/M)) × 1.09^(T - 20)

where b0, b1 are interpolated based on rbCOD availability.

Deaeration Zone Sizing

DO in internal recycle inhibits denitrification by competing with NO3 as an electron acceptor. The deaeration zone uses endogenous respiration to consume DO before IR returns to the pre-anoxic zone.

First Principles (ASM2d kinetics):

OUR_specific = 1.42 × (1 - f_d) × b_H_T × η_decay  [kg O2/kg VSS/d]
V_deaer = DO_load / (OUR_specific × MLVSS)

Where:

• b_H_T: Temperature-corrected heterotroph decay rate (0.4 d⁻¹ at 20°C)
• f_d: Debris fraction (0.1)
• η_decay: Anoxic reduction factor (0.5 for unaerated conditions)

DO Penalty on Denitrification:

Each g DO requires 2.86 g rbCOD (same stoichiometry as NO3-N), effectively adding an "equivalent NO3" load to the pre-anoxic zone:

DO_equivalent_NO3 = Q_IR × DO / 1e6  [kg N/d]

---

Data Models

Process Design Output

ProcessDesign {
    mass_balance: {
        sludge: SludgeProduction
        nitrogen: NitrogenBalance
        phosphorus: PhosphorusBalance
        oxygen: OxygenRequirements
        rbcod_profile: RbCODProfile
    },
    flowsheet: {
        flowsheet_type: "MLE" | "A2O" | "MLE_POST"
        zones: Dict[str, ReactorZone]
        internal_recycle_ratio: float
        ras_ratio: float
        total_volume_m3: float
        meets_tn_target: bool
        meets_tp_target: bool
    },
    warnings: List[str],
    recommendations: List[str]
}

Reactor Zone

ReactorZone {
    zone_type: str                  # anaerobic, pre_anoxic, aerobic, post_anoxic, mbr, deaeration
    volume_m3: float
    hrt_h: float
    mlss_mg_l: float
    membrane_area_m2: float         # MBR zone only
    flux_lmh: float                 # MBR zone only
    do_consumed_kg_d: float         # Deaeration zone only
    do_inlet_mg_l: float            # Deaeration zone only
    sour_mg_g_vss_h: float          # Deaeration zone only
}

Design Options

Optional parameters for advanced configurations:

Option	Type	Default	Description
enable_deaeration	bool	False	Enable deaeration zone before IR return
do_target_deaer	float	0.5	Target DO leaving deaeration (mg/L)
deaeration_placement	str	"ir_only"	"ir_only" or "inline" placement
ir_ratio	float	4.0	Internal recycle ratio
ras_ratio	float	4.0	Return activated sludge ratio
allow_carbon_supplement	bool	True	Allow external carbon dosing

---

Integration with Codex MCP

The Codex MCP server provides ASM2d component fractionation:

Input: basis_of_design.json

{
  "flow_m3d": 20000,
  "cod_mg_l": 625,
  "tkn_mg_l": 62.5,
  "tp_mg_l": 9.37,
  "wastewater_type": "municipal"
}

Output: asm2d_state.json

{
  "model_type": "mASM2d",
  "masm2d_components": {
    "S_F": 109.2,    // Fermentable
    "S_A": 46.8,     // Acetate
    "S_I": 62.5,     // Inert soluble
    "X_S": 256.5,    // Slowly biodegradable
    "X_H": 60.0,     // Heterotrophs
    "X_AUT": 10.0,   // Autotrophs
    // ... 19 more components
  },
  "validation": { ... },
  "rbCOD_mg_l": 171.39,
  "rbcod_fraction": 0.274
}

---

Output Files

Generated Files

File	Description
design_state.json	Complete design state (basis, ASM2d, design, sizing)
asm2d_state.json	ASM2d component fractionation
asm2d_justifications.json	Detailed justifications for fractionation
basis_of_design.json	Input parameters for Codex estimator
reports/output/*_YYYYMMDD_HHMMSS.md	Markdown design report

Design State Structure

{
  "basis_of_design": { ... },
  "asm2d_state": { ... },
  "unified_design": {
    "flowsheet_type": "A2O",
    "mass_balance": { ... },
    "reactor_zones": {
      "anaerobic": { "volume_m3": 250, "hrt_h": 0.3 },
      "pre_anoxic": { "volume_m3": 1000, "hrt_h": 1.2 },
      "aerobic": { "volume_m3": 4000, "hrt_h": 4.8 },
      "mbr": { "volume_m3": 500, "membrane_area_m2": 25000 }
    },
    "performance": { ... }
  }
}

---

Design Validation

Multi-Level Validation

1. Input Validation

   • Parameter range checking
   • Consistency checks (TKN/COD, VSS/TSS ratios)
   • Temperature range validation

2. Mass Balance Validation

   • COD balance: ± 5%
   • Nitrogen balance: ± 5%
   • Phosphorus balance: ± 5%

3. Design Feasibility Checks

   • HRT > 2 hours (minimum)
   • SRT > minimum for nitrification
   • MLSS < 12,000 mg/L (oxygen transfer limit)
   • Compliance with effluent targets

Design Warnings

The system generates warnings for:

• Low temperature (requires higher SRT)
• Low alkalinity (recommend caustic/lime)
• Carbon limitation (recommend external carbon)
• High MLSS (oxygen transfer issues)
• TP targets not met (recommend EBPR or chemical P)
• TN targets not met (recommend post-anoxic or methanol)

---

Examples

Example 1: Municipal Wastewater

# Basis
Flow: 20,000 m3/d
COD: 625 mg/L
TKN: 62.5 mg/L
TP: 9.37 mg/L
Temperature: 12-25°C

# Targets
COD < 50 mg/L
TN < 10 mg/L
TP < 1 mg/L

# Result
Flowsheet: A2O
Total Volume: 10,500 m3
Anaerobic: 500 m3
Pre-Anoxic: 2,000 m3
Aerobic: 6,500 m3
MBR: 1,500 m3
Membrane Area: 37,000 m2

Example 2: Industrial Dairy Wastewater

# Basis
Flow: 500 m3/d
COD: 1,500 mg/L
TKN: 118 mg/L
TP: 24 mg/L
Temperature: 15-25°C
Type: Dairy - post DAF

# Targets
COD < 50 mg/L
TN < 10 mg/L
TP < 1 mg/L

# Result
Flowsheet: A2O + Chemical P
Total Volume: 375 m3
High rbCOD (75%) enables excellent denitrification
EBPR insufficient → Chemical P dosing required

---

Development Status

Version: 2.0.0 Status: Active Development (70-75% complete)

Completed ✅

• Core design functionality (flowsheet selection + sizing)
• Unified mass balance engine
• Temperature-corrected kinetics
• MBR membrane sizing
• Deaeration zone sizing (DO penalty on denitrification)
• State persistence
• Report generation
• CLI bypass for long operations
• Codex MCP integration

In Progress 🚧

• Comprehensive test suite
• QSDsan simulator integration
• Advanced data visualization and interactive dashboards

Planned 📋

• Dynamic simulation capability
• Multi-objective optimization
• Additional flowsheet types
• Sensitivity analysis

See IMPLEMENTATION_PLAN.md for detailed roadmap.

---

Dependencies

Core

• fastmcp >= 0.1.0 - MCP framework
• pydantic >= 2.0.0 - Data validation
• numpy >= 1.24.0 - Numerical computing
• pandas >= 2.0.0 - Data manipulation
• requests >= 2.28.0 - HTTP requests
• cachetools >= 5.3.0 - Response caching

Optional

• qsdsan >= 1.3.0 - Wastewater treatment modeling
• biosteam >= 2.37.0 - Mass/energy balance

---

Troubleshooting

MCP Server Not Starting

Check Python version and dependencies:

python --version  # Should be 3.12+
pip list | grep fastmcp

Design Tools Blocking

Use CLI bypass:

python cli_runner.py design --params '{...}'

ASM2d State Not Found

Ensure Codex MCP is running and asm2d_state.json exists:

ls -la asm2d_state.json

QSDsan Import Errors

QSDsan is optional. System will use manual fallback calculations.

---

Contributing

This is a research/production tool. For issues or feature requests, please document in the project's issue tracker.

Running Tests

pytest tests/ -v --cov=core --cov=tools

---

References

Technical References

1. Metcalf & Eddy (2014) - "Wastewater Engineering: Treatment and Resource Recovery" 5th Edition
2. Henze et al. (2000) - "Activated Sludge Models ASM1, ASM2, ASM2d and ASM3"
3. Tchobanoglous et al. (2014) - "Wastewater Engineering: Treatment and Reuse"

Software References

• QSDsan: https://github.com/QSD-Group/QSDsan
• FastMCP: https://github.com/jlowin/fastmcp
• Codex: https://github.com/anthropics/codex

---

License

[To be determined]

---

Contact

For questions or support, please refer to the project documentation or issue tracker.

---

Built with Claude Code and MCP 🤖