ADM1 MCP Server

Controla el modelado de digestión anaerobia (ADM1) usando lenguaje natural.

GitHub
2
Prueba este MCPPatrocinado

Documentación

Servidor MCP ADM1

Este servidor MCP permite el control en lenguaje natural del modelado de digestión anaerobia mediante el Modelo de Digestión Anaerobia No. 1 (ADM1), reconocido internacionalmente. Conecta a Claude u otros clientes LLM con la simulación profesional de tratamiento de aguas residuales para el diseño, optimización y análisis de procesos mediante indicaciones conversacionales.

Características Principales

Capacidades Centrales de Simulación

  • Implementación completa de ADM1 con más de 35 procesos bioquímicos y fisicoquímicos
  • Análisis de materia prima impulsado por IA usando Google Gemini para la conversión de lenguaje natural a parámetros
  • Soporte de simulación multi-reactor (hasta 3 configuraciones de reactor)
  • Cálculo dinámico de pH con modelado integral de inhibición
  • Generación de informes profesionales con visualizaciones de calidad de publicación

Herramientas Avanzadas de Análisis

  • Análisis de Corrientes: Análisis detallado de composición para corrientes de afluente, efluente y biogás
  • Evaluación de Salud del Proceso: Análisis integral de inhibición con recomendaciones de optimización
  • Métricas de Rendimiento: Eficiencia de eliminación de DQO, producción de metano y rendimientos de biomasa
  • Validación de Balance de Carga: Verificación de consistencia termodinámica para definiciones de materia prima
  • Visualizaciones Interactivas: Gráficos en tiempo real con datos reales de simulación

Informes Profesionales

  • Informes de Calidad de Publicación: Informes HTML/PDF profesionales con análisis integral
  • Paneles de KPI: Indicadores de rendimiento interactivos y métricas de proceso
  • Documentación Técnica: Secciones completas de metodología con referencias científicas
  • Exportación de Datos: Formato profesional sin artefactos de notación científica

Requisitos Previos

  • Python 3.8 o superior
  • Clave de API de Google (para análisis de materia prima impulsado por IA)
  • Claude Desktop u otra aplicación cliente MCP
  • QSDsan (se instala automáticamente con las dependencias)

Instrucciones de Configuración

1. Instalar Dependencias

git clone https://github.com/puran-water/adm1-mcp.git
cd adm1-mcp
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

2. Configurar el Entorno

cp .env.example .env
# Edit .env and add your Google API key:
# GOOGLE_API_KEY=your_google_api_key_here

Obtener Clave de API de Google:

  1. Visite Google AI Studio
  2. Cree una nueva clave de API
  3. Agréguela al archivo .env

3. Configurar Claude Desktop

Agregue a su claude_desktop_config.json:

{
  "mcpServers": {
    "adm1-mcp": {
      "command": "C:\\path\\to\\your\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\adm1-mcp\\server.py"],
      "env": {
        "MCP_TIMEOUT": "600000"
      }
    }
  }
}

Ubicaciones de Archivos de Configuración:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/claude/claude_desktop_config.json

4. Reiniciar Claude Desktop

Después de actualizar la configuración, reinicie Claude Desktop para cargar el servidor ADM1.

Herramientas Disponibles

Herramientas Centrales de Simulación

  • describe_feedstock: Convierte la descripción de materia prima en lenguaje natural a variables de estado de ADM1
  • describe_kinetics: Genera tanto variables de estado COMO parámetros cinéticos a partir de la descripción de materia prima
  • set_flow_parameters: Configura el caudal de afluente y los parámetros de tiempo de simulación
  • set_reactor_parameters: Establece parámetros específicos del reactor (temperatura, TRH, método de integración)
  • run_simulation_tool: Ejecuta la simulación ADM1 con los parámetros actuales

Herramientas de Análisis

  • get_stream_properties: Analiza propiedades detalladas de corrientes de afluente, efluente o biogás
  • get_inhibition_analysis: Evaluación de salud del proceso con factores de inhibición y recomendaciones
  • get_biomass_yields: Calcula métricas de rendimiento del proceso y eficiencia
  • validate_feedstock_charge_balance: Verifica la consistencia termodinámica de la definición de materia prima
  • check_nutrient_balance: Analiza las relaciones C:N:P para la optimización del proceso

Herramientas de Utilidad

  • get_parameter: Recupera los valores de parámetros actuales del estado de simulación
  • set_parameter: Modifica parámetros específicos de simulación
  • generate_report: Crea informes de simulación profesionales integrales
  • reset_simulation: Restablece todos los parámetros a los valores predeterminados

Indicación del Sistema para Integración con LLM

Al usar este servidor MCP con Claude u otros LLM, use esta indicación del sistema para un rendimiento óptimo:

**Available Tools**

You have access to the following ADM1 simulation tools:

1. describe_feedstock - Generate ADM1 state variables from a natural language description. Either this tool or describe_kinetics should be called prior to a simulation - there will never be a case where both tools need to be called.
 - Input: feedstock_description (string) - Detailed description of the feedstock
 - Use this to convert user descriptions of waste/feedstock into precise ADM1 parameters

2. describe_kinetics - Generate **both state variables AND kinetic parameters** from a natural language description. Either this tool or describe_feedstock should be called prior to a simulation - there will never be a case where both tools need to be called.
 - Input: feedstock_description (string) - Detailed description of the feedstock
 - Use this when users want customized kinetic parameters for their specific feedstock
 
3. set_flow_parameters - Set the influent flow rate and simulation timing parameters
 - Inputs: flow_rate (m³/d), simulation_time (days), time_step (days)
 - Use this to configure the basic hydraulic and simulation parameters
 
4. set_reactor_parameters - Set parameters for a specific reactor simulation
 - Inputs: reactor_index (1-3), temperature (K), hrt (days), integration_method (string)
 - Valid integration methods: "BDF", "RK45", "RK23", "DOP853", "Radau", "LSODA"
 - Use this to customize up to three different reactor configurations
 
5. run_simulation_tool - Run the ADM1 simulation with current parameters
 - No inputs required - uses previously set parameters
 - Call this after setting up feedstock and reactor parameters
                
6. get_stream_properties - Get detailed properties of a specified stream
 - Input: stream_type (string) - One of: "influent", "effluent1", "effluent2", "effluent3", "biogas1", "biogas2", "biogas3"
 - Use this to analyze composition and properties of input/output streams
 
7. get_inhibition_analysis - Get process health and inhibition analysis
 - Input: simulation_index (1-3) - Which simulation to analyze
 - Use this to diagnose process issues and get optimization recommendations
  
8. get_biomass_yields - Calculate biomass yields from a simulation
 - Input: simulation_index (1-3) - Which simulation to analyze
 - Use this to determine VSS and TSS yields and process efficiency
  
9. reset_simulation - Reset all simulation parameters to defaults
 - No inputs required
 - Use this to start fresh with default settings                    
         
10. Other tools (available for specific situations):
 - validate_feedstock_charge_balance: Check charge balance consistency after feedstock definition
 - get_parameter: Retrieve current parameter values
 - set_parameter: Modify specific parameters (invalidates previous simulation results)
 - generate_report: Create professional simulation reports

**Interaction Guidelines**

Anaerobic Digestion Simulation Support Protocol:

1. Guide the user through the following steps prior to running a simulation - asking for permission to proceed to the next step following the completion of each step. If the user asks for changes, perform the step again with the changes.

 - Step 1: Take the user's prompt and request clarifications on the feedstock characteristics (most importantly, COD concentration, TKN concentration, pH, and alkalinity) and flowrate. Further, request clarity on whether the user would like you to determine the feedstock state variables alone or both the feedstock state variables and kinetic parameters. This will determine whether you use the describe_feedstock or describe_kinetics function using the user's description of the feedstock.
                
 - Step 2: Call either the describe_feedstock or describe_kinetics tool based on the result of Step 1. Present the output of this tool call in a table that presents the variable name, the units of measurement, the variable value, and the reason/explanation for why this value was chosen (all of which are outputs of the tool call).
                
 - Step 3: Use the validate_feedstock_charge_balance tool to check the charge balance of the feedstock. If the charge balance is not valid based on the predicted concentration of H+ and OH- compared with the feedstock pH, present the user with your suggestion on how you can use the set_parameter tool to adjust the S_cat and/or S_an values to ensure that the charge balance is valid.
  
 - Step 4: After receiving user confirmation, proceed with setting the parameter to ensure the charge balance is valid.
                
 - Step 5: Request the user's permission to proceed with the simulation. Unless the user already specified the HRT, temperature, simulation time, and simulation time step, present your intention of running three simulations (Index 1 at a 20 d HRT reactor volume, Index 2 at a 30 d HRT reactor volume, and Index 3 at a 45 d HRT reactor volume) at a 38 deg C reactor temperature, 300 d simulation time, 0.1 d time step, and the BDF integration method.
 
 - Step 6: Run the simulation and present the results of the simulation as follows:
  - get_stream_properties and present a table **for all parameters that the tool returns** for the feedstock and the effluent
  - get_stream_properties and present a table **for all parameters that the tool returns** for the biogas flow and composition
  - get_biomass_yields and present a table **for all parameters that the tool returns** presenting excess sludge production
  - get_inhibition_analysis and present a table **for all parameters that the tool returns** for the health of the process

Ejemplos de Uso

Flujo de Trabajo Básico de Simulación

"I want to simulate anaerobic digestion of food waste containing 40% vegetables, 30% bread, 20% fruit, 10% meat with 85,000 mg/L COD"

"Set up a reactor at 35°C with 25-day HRT and 150 m³/d flow rate"

"Run the simulation and analyze the biogas production and process efficiency"

Optimización de Procesos

"What inhibition factors are limiting performance in reactor 2?"

"Compare methane production between different HRT scenarios"

"The pH is dropping in my reactor. What's causing this and how can I fix it?"

Análisis Avanzado

"Generate a comprehensive report for simulation 1 with all analysis and recommendations"

"Analyze the nutrient balance for my POME feedstock at pH 4.5"

"Compare the performance of primary sludge vs food waste as feedstock"

Antecedentes Científicos

Implementación del Modelo ADM1

El servidor implementa el estándar completo de IWA ADM1, incluyendo:

  1. Procesos Bioquímicos:

    • Desintegración de partículas complejas
    • Hidrólisis de carbohidratos, proteínas y lípidos
    • Acidogénesis y acetogénesis
    • Metanogénesis (acetotrófica e hidrogenotrófica)

  2. Procesos Fisicoquímicos:

    • Transferencia líquido-gas (CH₄, CO₂, H₂)
    • Asociación/disociación de iones
    • Cálculo dinámico de pH basado en balance de carga

  3. Mecanismos de Inhibición:

    • Inhibición por pH que afecta a todos los grupos microbianos
    • Inhibición por amoníaco libre (particularmente metanógenos acetoclásticos)
    • Inhibición por hidrógeno que afecta los procesos acetogénicos
    • Inhibición por AGV por acumulación de ácidos orgánicos

Métodos de Integración

Soporta múltiples métodos de integración numérica:

  • BDF: Fórmula de diferenciación hacia atrás (recomendado para sistemas rígidos)
  • RK45: Método Runge-Kutta 4(5)
  • RK23: Método Runge-Kutta 2(3)
  • LSODA: Solver de Livermore para EDO con cambio automático de método
  • Radau: Método Runge-Kutta implícito
  • DOP853: Método Dormand-Prince 8(5,3)

Características de Rendimiento

Generación de Informes Profesionales

  • Sin Notación Científica: Los valores grandes se muestran como "13,489 m³/d" en lugar de "1.349e+04"
  • Extracción de Datos Reales: Resultados reales de simulación en lugar de valores de marcador de posición
  • Formato Contextual: Precisión apropiada para diferentes tipos de medición
  • Presentación Limpia: Sin artefactos de depuración ni mensajes de programación

Características de Optimización

  • Generación de Parámetros Impulsada por IA: Conversión de lenguaje natural a parámetros ADM1
  • Escenarios Multi-Reactor: Compare hasta 3 configuraciones diferentes simultáneamente
  • Validación Integral: Verificación de balance de carga y proporción de nutrientes
  • Diagnóstico de Procesos: Análisis detallado de inhibición con guía de optimización

Solución de Problemas

Problemas Comunes

1. Errores de Importación

# Ensure virtual environment is activated and dependencies installed
pip install -r requirements.txt --force-reinstall

2. Problemas con la Clave de API de Google

# Verify .env file format
cat .env
# Should show: GOOGLE_API_KEY=your_key_here

3. Problemas de Conexión con Claude Desktop

  • Verifique que las rutas de archivo en la configuración de MCP sean correctas
  • Asegúrese de que la ruta del ejecutable de Python sea precisa
  • Reinicie Claude Desktop después de los cambios de configuración
  • Verifique que MCP_TIMEOUT esté configurado en 600000 para simulaciones complejas

4. Problemas de Convergencia de Simulación

  • Pruebe diferentes métodos de integración (BDF recomendado para la mayoría de los casos)
  • Ajuste el paso de tiempo (0.1 días recomendado)
  • Verifique el balance de carga de la materia prima antes de la simulación
  • Confirme concentraciones realistas de materia prima

Novedades en Esta Versión

Mejoras Recientes

  • ✅ Formato de Números Profesional: Se eliminó la notación científica en los informes
  • ✅ Extracción de Datos Reales: Los resultados reales de simulación reemplazan los valores de marcador de posición
  • ✅ Integración de IA Mejorada: Análisis de materia prima mejorado con Google Gemini
  • ✅ Validación Integral: Verificación avanzada de balance de carga y nutrientes
  • ✅ Informes de Calidad de Publicación: Visualizaciones y documentación profesionales
  • ✅ Optimización del Protocolo MCP: Rendimiento y confiabilidad mejorados
  • ✅ Mejoras de Seguridad: Protección adecuada de claves de API y validación de entrada

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulte el archivo LICENCIA para más detalles.

Dependencias y Agradecimientos

Este proyecto se basa en el excelente marco QSDsan para el diseño sostenible cuantitativo de sistemas de saneamiento y recuperación de recursos, que está licenciado bajo la Licencia de Código Abierto de la Universidad de Illinois/NCSA. Agradecemos al Grupo de Diseño Sostenible Cuantitativo por su trabajo fundamental en el modelado de digestión anaerobia.

La implementación de ADM1 sigue el estándar reconocido internacionalmente desarrollado por el Grupo de Trabajo de la Asociación Internacional del Agua (IWA) para el Modelado Matemático de Procesos de Digestión Anaerobia.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Pruebe con escenarios de simulación básicos y avanzados
  4. Envíe una solicitud de extracción con documentación clara

Soporte

  • Problemas: Problemas de GitHub
  • Documentación: Consulte los archivos de documentación del repositorio
  • Referencias Científicas: Documentación de IWA ADM1 y marco QSDsan

Construido para la comunidad de ingeniería de tratamiento de agua con capacidades de simulación de grado profesional.