ADM1 MCP Server

Controle a modelagem de digestão anaeróbica (ADM1) usando linguagem natural.

GitHub
2

Documentação

Servidor ADM1 MCP

Este servidor MCP permite o controle em linguagem natural da modelagem de digestão anaeróbica por meio do internacionalmente reconhecido Anaerobic Digestion Model No. 1 (ADM1). Ele conecta o Claude ou outros clientes LLM à simulação profissional de tratamento de águas residuais para projeto de processos, otimização e análise por meio de prompts conversacionais.

Principais Recursos

Capacidades Centrais de Simulação

  • Implementação completa do ADM1 com mais de 35 processos bioquímicos e físico-químicos
  • Análise de substrato alimentar com IA usando Google Gemini para conversão de linguagem natural em parâmetros
  • Suporte a simulação multi-reator (até 3 configurações de reatores)
  • Cálculo dinâmico de pH com modelagem abrangente de inibição
  • Geração profissional de relatórios com visualizações com qualidade de publicação

Ferramentas Avançadas de Análise

  • Análise de Correntes: Análise detalhada de composição para correntes de afluente, efluente e biogás
  • Avaliação de Saúde do Processo: Análise abrangente de inibição com recomendações de otimização
  • Métricas de Desempenho: Eficiência de remoção de DQO, produção de metano e rendimentos de biomassa
  • Validação de Balanço de Carga: Verificação de consistência termodinâmica para definições de substrato
  • Visualizações Interativas: Gráficos em tempo real com dados reais de simulação

Relatórios Profissionais

  • Relatórios com Qualidade de Publicação: Relatórios profissionais em HTML/PDF com análise abrangente
  • Painéis de KPI: Indicadores de desempenho interativos e métricas de processo
  • Documentação Técnica: Seções completas de metodologia com referências científicas
  • Exportação de Dados: Formatação profissional sem artefatos de notação científica

Pré-requisitos

  • Python 3.8 ou superior
  • Chave de API do Google (para análise de substrato com IA)
  • Claude Desktop ou outro aplicativo cliente MCP
  • QSDsan (instalado automaticamente com as dependências)

Instruções de Configuração

1. Instalar Dependências

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 o Ambiente

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

Obter uma Chave de API do Google:

  1. Visite Google AI Studio
  2. Crie uma nova chave de API
  3. Adicione ao arquivo .env

3. Configurar o Claude Desktop

Adicione ao seu 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"
      }
    }
  }
}

Locais dos Arquivos de Configuração:

  • 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 o Claude Desktop

Após atualizar a configuração, reinicie o Claude Desktop para carregar o servidor ADM1.

Ferramentas Disponíveis

Ferramentas Centrais de Simulação

  • describe_feedstock: Converte descrição de substrato em linguagem natural para variáveis de estado do ADM1
  • describe_kinetics: Gera tanto variáveis de estado QUANTO parâmetros cinéticos a partir da descrição do substrato
  • set_flow_parameters: Configura a vazão do afluente e os parâmetros de tempo de simulação
  • set_reactor_parameters: Define parâmetros específicos do reator (temperatura, TRH, método de integração)
  • run_simulation_tool: Executa a simulação do ADM1 com os parâmetros atuais

Ferramentas de Análise

  • get_stream_properties: Analisa propriedades detalhadas das correntes de afluente, efluente ou biogás
  • get_inhibition_analysis: Avaliação de saúde do processo com fatores de inibição e recomendações
  • get_biomass_yields: Calcula métricas de desempenho e eficiência do processo
  • validate_feedstock_charge_balance: Verifica a consistência termodinâmica da definição do substrato
  • check_nutrient_balance: Analisa as proporções C:N:P para otimização do processo

Ferramentas Utilitárias

  • get_parameter: Recupera os valores atuais dos parâmetros do estado da simulação
  • set_parameter: Modifica parâmetros específicos da simulação
  • generate_report: Cria relatórios profissionais abrangentes de simulação
  • reset_simulation: Redefine todos os parâmetros para os valores padrão

Prompt de Sistema para Integração com LLM

Ao usar este servidor MCP com o Claude ou outros LLMs, use este prompt de sistema para obter desempenho ideal:

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

Exemplos de Uso

Fluxo de Trabalho Básico de Simulação

"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"

Otimização de Processo

"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álise Avançada

"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"

Fundamentação Científica

Implementação do Modelo ADM1

O servidor implementa o padrão completo da IWA ADM1, incluindo:

  1. Processos Bioquímicos:

    • Desintegração de partículas complexas
    • Hidrólise de carboidratos, proteínas e lipídios
    • Acidogênese e acetogênese
    • Metanogênese (acetotrófica e hidrogenotrófica)

  2. Processos Físico-Químicos:

    • Transferência líquido-gás (CH₄, CO₂, H₂)
    • Associação/dissociação de íons
    • Cálculo dinâmico de pH baseado no balanço de carga

  3. Mecanismos de Inibição:

    • Inibição por pH afetando todos os grupos microbianos
    • Inibição por amônia livre (particularmente metanogênicos acetoclásticos)
    • Inibição por hidrogênio afetando processos acetogênicos
    • Inibição por AGV devido ao acúmulo de ácidos orgânicos

Métodos de Integração

Suporta vários métodos de integração numérica:

  • BDF: Fórmula de Diferenciação Regressiva (recomendado para sistemas rígidos)
  • RK45: Método Runge-Kutta 4(5)
  • RK23: Método Runge-Kutta 2(3)
  • LSODA: Solucionador Livermore para EDOs com troca automática de método
  • Radau: Método Runge-Kutta implícito
  • DOP853: Método Dormand-Prince 8(5,3)

Recursos de Desempenho

Geração Profissional de Relatórios

  • Sem Notação Científica: Valores grandes são exibidos como "13.489 m³/d" em vez de "1.349e+04"
  • Extração de Dados Reais: Resultados reais de simulação em vez de valores de espaço reservado
  • Formatação Sensível ao Contexto: Precisão apropriada para diferentes tipos de medição
  • Apresentação Limpa: Sem artefatos de depuração ou mensagens de programação

Recursos de Otimização

  • Geração de Parâmetros com IA: Conversão de linguagem natural em parâmetros ADM1
  • Cenários Multi-Reator: Compare até 3 configurações diferentes simultaneamente
  • Validação Abrangente: Verificação de balanço de carga e proporção de nutrientes
  • Diagnóstico de Processo: Análise detalhada de inibição com orientação de otimização

Solução de Problemas

Problemas Comuns

1. Erros de Importação

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

2. Problemas com a Chave de API do Google

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

3. Problemas de Conexão com o Claude Desktop

  • Verifique se os caminhos de arquivo na configuração do MCP estão corretos
  • Garanta que o caminho do executável do Python esteja preciso
  • Reinicie o Claude Desktop após alterações de configuração
  • Verifique se MCP_TIMEOUT está definido como 600000 para simulações complexas

4. Problemas de Convergência da Simulação

  • Tente diferentes métodos de integração (BDF recomendado para a maioria dos casos)
  • Ajuste o passo de tempo (0,1 dia recomendado)
  • Verifique o balanço de carga do substrato antes da simulação
  • Verifique se as concentrações do substrato são realistas

Novidades Nesta Versão

Melhorias Mais Recentes

  • ✅ Formatação Profissional de Números: Notação científica eliminada nos relatórios
  • ✅ Extração de Dados Reais: Resultados reais de simulação substituem valores de espaço reservado
  • ✅ Integração Aprimorada com IA: Análise de substrato aprimorada com Google Gemini
  • ✅ Validação Abrangente: Verificação avançada de balanço de carga e nutrientes
  • ✅ Relatórios com Qualidade de Publicação: Visualizações e documentação profissionais
  • ✅ Otimização do Protocolo MCP: Desempenho e confiabilidade aprimorados
  • ✅ Aprimoramentos de Segurança: Proteção adequada de chaves de API e validação de entrada

Licença

Este projeto está licenciado sob a Licença MIT — consulte o arquivo LICENSE para obter detalhes.

Dependências e Agradecimentos

Este projeto se baseia no excelente framework QSDsan para projeto sustentável quantitativo de sistemas de saneamento e recuperação de recursos, licenciado sob a Licença de Código Aberto University of Illinois/NCSA. Agradecemos ao Quantitative Sustainable Design Group pelo trabalho fundamental em modelagem de digestão anaeróbica.

A implementação do ADM1 segue o padrão internacionalmente reconhecido desenvolvido pelo Grupo de Trabalho da International Water Association (IWA) para Modelagem Matemática de Processos de Digestão Anaeróbica.

Contribuindo

Contribuições são bem-vindas! Por favor:

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Teste com cenários de simulação básicos e avançados
  4. Envie um pull request com documentação clara

Suporte

  • Problemas: GitHub Issues
  • Documentação: Consulte os arquivos de documentação do repositório
  • Referências Científicas: Documentação da IWA ADM1 e framework QSDsan

Desenvolvido para a comunidade de engenharia de tratamento de água com capacidades de simulação de nível profissional.