Text2Sim MCP Server

Um motor de simulação multi-paradigma para Eventos Discretos e Dinâmica de Sistemas, permitindo simulações baseadas em linguagem natural via MCP.

GitHub
25
Experimente este MCPPatrocinado

Documentação

Header Image

Text2Sim MCP Server

Mecanismo de Simulação Multiparadigma para Integração com LLM

Um servidor Model Context Protocol que fornece capacidades de simulação multiparadigma por meio de interfaces conversacionais. O servidor suporta Simulação de Eventos Discretos via SimPy e modelagem de Dinâmica de Sistemas via PySD e um esquema JSON compatível com PySD.

Visão Geral

O Text2Sim MCP Server permite que Modelos de Linguagem de Grande Porte criem, validem e executem modelos de simulação por meio de interfaces de linguagem natural. O servidor processa configurações de simulação estruturadas em JSON e retorna resultados de execução com análises abrangentes.

Paradigmas de Simulação Suportados

  • Simulação de Eventos Discretos (DES): Modelagem orientada a processos usando o mecanismo SimPy
  • Dinâmica de Sistemas (SD): Modelagem de estoque-e-fluxo usando PySD e esquema JSON compatível com PySD

Text2Sim MCP Server (demo)

Sobre

O Text2Sim MCP Server é um projeto de código aberto desenvolvido pela The Cato Bot Company Limited. Acreditamos em desenvolvimento de código aberto transparente e com suporte comercial que beneficia tanto usuários quanto contribuidores, ao mesmo tempo em que apoia o crescimento sustentável do projeto. Contribuições da comunidade são aceitas por meio de procedimentos padrão de pull request.

Instalação

Pré-requisitos

Instalar uv

No macOS e Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

No Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Saiba mais: astral-sh/uv

Início Rápido

Clonar o repositório

git clone https://github.com/IamCatoBot/text2sim-MCP-server.git
cd text2sim-MCP-server

Instalar dependências

uv sync

Integração com o Claude Desktop

  1. Abra:

Claude > Settings > Developer > Edit Config > claude_desktop_config.json

  1. Adicione o seguinte bloco:
{
  "mcpServers": {
    "Text2Sim MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "PATH_TO_TEXT2SIM_MCP_SERVER",
        "run",
        "python",
        "-m",
        "mcp_server"
      ],
      "env": {}
    }
  }
}

Nota: Substitua PATH_TO_TEXT2SIM_MCP_SERVER pelo caminho real do seu repositório clonado. Se o comando uv não for encontrado, execute which uv (Unix) ou Get-Command uv (PowerShell) e use o caminho completo no campo "command".

Recursos

Integração com LLM

  • Conversão de linguagem natural para modelo de simulação
  • Suporte a conversas de múltiplas rodadas para desenvolvimento iterativo de modelos
  • Validação JSON Schema 2020-12 para confiabilidade de configuração
  • Mensagens de erro contextuais com orientação corretiva
  • Persistência de modelos entre sessões de conversa

Capacidades de Simulação de Eventos Discretos

  • Múltiplos tipos de entidades com prioridades e atributos configuráveis
  • Gerenciamento de recursos com agendamento FIFO, por prioridade e preemptivo
  • Modelagem de comportamento de entidades incluindo balking e reneging
  • Simulação de falha de recursos e ciclo de reparo
  • Coleta e relatórios de métricas configuráveis

Capacidades de Dinâmica de Sistemas

  • Esquema JSON compatível com PySD
  • Modelagem de variáveis de estoque, fluxo e auxiliares
  • Suporte a expressões matemáticas por meio de estruturas de Árvore de Sintaxe Abstrata
  • Simulação de séries temporais com parâmetros configuráveis
  • Integração com o ecossistema da biblioteca Python PySD

Análises e Validação

  • Métricas de simulação incluindo tempos de espera, taxas de utilização e throughput
  • Análise estatística com períodos de aquecimento e intervalos de confiança
  • Validação em múltiplos modos com verificação parcial, estrita e estrutural
  • Relatórios de erro específicos do esquema e orientação de correção

Gerenciamento de Modelos

  • Armazenamento e recuperação de modelos com rastreamento de metadados
  • Funcionalidade de exportação JSON para compartilhamento e backup de modelos
  • Detecção automática de esquema para tipos de modelo DES e SD
  • Gerenciamento de versões com resolução de conflitos

Sistema de Documentação

  • Documentação de esquema sensível ao contexto com exemplos
  • Múltiplos níveis de detalhe (resumido, padrão, detalhado)
  • Padrões de modelagem e fluxos de trabalho específicos de domínio
  • Sistema de ajuda integrado acessível por meio das ferramentas MCP

Segurança

  • Análise de distribuições baseada em regex sem execução de código
  • Validação de entrada contra esquemas JSON formais
  • Tratamento seguro de erros sem exposição de estado interno

Arquitetura

Design Modular

O Text2Sim MCP Server v2.6.0 apresenta uma arquitetura modular completamente refatorada que melhora a manutenibilidade, testabilidade e extensibilidade:

mcp_server/
├── __init__.py              # Package exports and version info
├── server.py                # Main server entry point
├── registry.py              # Centralized tool registration
├── shared/                  # Common utilities
│   ├── error_handlers.py    # Standardized error handling
│   ├── response_builders.py # Response formatting utilities
│   └── integration_layer.py # SD integration with fallbacks
└── tools/                   # Domain-specific tool modules
    ├── des_tools.py         # DES simulation tools
    ├── sd_tools.py          # SD simulation tools
    ├── model_mgmt_tools.py  # Model lifecycle management
    ├── validation_tools.py  # Validation and help tools
    └── template_tools.py    # Template management tools

Principais Melhorias

  • Separação de Preocupações: Cada domínio tem seu próprio módulo focado
  • Tratamento Padronizado de Erros: Respostas de erro consistentes com orientação acionável
  • Integração Aprimorada: Integração SD robusta com fallbacks graciosos
  • Padrões Profissionais: Documentação abrangente e dicas de tipo
  • Extensibilidade: Fácil adicionar novos paradigmas de simulação ou ferramentas

Referência da API

Visão Geral das Ferramentas MCP

O servidor expõe 16 ferramentas em 5 categorias por meio do Model Context Protocol:

Ferramentas Principais de Simulação

simulate_des - Executar modelos de Simulação de Eventos Discretos

  • Aceita configuração JSON com tipos de entidades, recursos e regras de processamento
  • Retorna resultados de simulação com métricas e análise estatística

simulate_sd - Executar modelos de Dinâmica de Sistemas

  • Aceita formato JSON abstractModel compatível com PySD
  • Retorna dados de séries temporais e metadados de execução do modelo

run_multiple_simulations - Executar múltiplas replicações de simulação

  • Executa múltiplas execuções de simulação independentes com análise estatística
  • Retorna intervalos de confiança, medidas de variabilidade e pontuação de confiabilidade
  • Suporta controle de números aleatórios baseado em semente para resultados reproduzíveis

Ferramentas de Validação e Ajuda

validate_model - Validar configurações de modelos de simulação

  • Suporta validação de modelos DES e SD com detecção automática
  • Fornece relatórios de erro detalhados com sugestões de correção
  • Múltiplos modos de validação: parcial, estrito e estrutural

help_validation - Obter orientação de validação

  • Mostra todas as ferramentas de validação disponíveis e quando usar cada uma
  • Fornece orientação de solução de problemas para erros de validação
  • Inclui detecção de tipo de esquema e explicações dos modos de validação

get_schema_help - Acessar documentação abrangente de esquema

  • Retorna documentação estruturada para seções do esquema com exemplos
  • Suporta caminhos de seção aninhados (ex.: "processing_rules.steps")
  • Múltiplos níveis de detalhe: resumido, padrão e detalhado
  • Exemplos específicos de domínio e orientação de fluxo de trabalho

Ferramentas de Gerenciamento de Modelos

save_model - Armazenar modelos com metadados

  • Nomeação automática com detecção de domínio
  • Rastreamento de metadados incluindo status de validação e tags
  • Gerenciamento de versões com resolução de conflitos

load_model - Recuperar modelos armazenados

  • Listar todos os modelos salvos com opções de filtragem
  • Carregar modelos específicos por nome ou identificador
  • Integração com rastreamento do último estado carregado

export_model - Exportar modelos para JSON

  • Múltiplos formatos de saída para diferentes casos de uso
  • Modelos prontos para conversa para compartilhamento de sessão
  • Estimativa de contagem de tokens para gerenciamento de contexto LLM

Ferramentas de Modelos e Descoberta

list_templates - Navegar pelos modelos disponíveis

  • Lista modelos pré-construídos para modelos DES e SD
  • Filtrar por tipo de esquema, domínio ou nível de complexidade
  • Inclui descrições de modelos e casos de uso

load_template - Recuperar modelos específicos

  • Carregar configurações de modelo por nome ou ID do modelo
  • Retorna configurações de modelo prontas para uso
  • Suporta formatos de modelo DES e SD

save_template - Salvar modelos como modelos reutilizáveis

  • Armazenar modelos validados como modelos para uso futuro
  • Nomeação automática de modelos com metadados
  • Capacidades de compartilhamento e organização de modelos

delete_template - Remover modelos de usuário

  • Exclusão segura com requisitos de confirmação
  • Protege modelos integrados contra remoção acidental
  • Fornece recomendações de backup

Ferramentas Específicas de Dinâmica de Sistemas

get_sd_model_info - Analisar modelos de Dinâmica de Sistemas

  • Fornece análise detalhada da estrutura do modelo SD sem simulação
  • Retorna métricas de complexidade e informações de variáveis
  • Valida o formato abstractModel e relata análise de estrutura

convert_vensim_to_sd_json - Converter modelos Vensim para PySD JSON

  • Converte arquivos Vensim .mdl para o formato abstractModel compatível com PySD
  • Lida com tradução de modelos e validação de formato
  • Integração com as capacidades de tradução Vensim do PySD

Ferramentas Aprimoradas (Novas na v2.6.0)

delete_model - Exclusão segura de modelos

  • Remove modelos salvos com requisitos de confirmação
  • Fornece metadados do modelo antes da exclusão
  • Inclui sugestões de desfazer e recursos de segurança

Esquemas JSON

O Text2Sim MCP Server usa validação formal de JSON Schema (Draft 2020-12) para garantir a correção dos modelos de simulação e fornecer relatórios de erro estruturados. O servidor suporta dois formatos JSON distintos, otimizados para seus respectivos paradigmas de simulação.

Formato JSON de Simulação de Eventos Discretos

O servidor usa um esquema JSON compatível com SimPy para modelos de Simulação de Eventos Discretos. Este formato fornece configuração declarativa que mapeia diretamente para as capacidades nativas do SimPy.

Estrutura Básica

{
  "run_time": 480,
  "entity_types": {
    "customer": {
      "probability": 1.0,
      "value": {"min": 10, "max": 50},
      "priority": 5
    }
  },
  "resources": {
    "server": {
      "capacity": 2,
      "resource_type": "fifo"
    }
  },
  "processing_rules": {
    "steps": ["server"],
    "server": {
      "distribution": "uniform(5, 10)"
    }
  }
}

Componentes Principais

  • Tipos de Entidades: Definem diferentes classes de entidades com probabilidades, valores, prioridades e atributos personalizados
  • Recursos: Especificam recursos do sistema com limites de capacidade e disciplinas de fila (FIFO, prioridade, preemptivo)
  • Regras de Processamento: Configuram etapas sequenciais de processamento com distribuições de tempo de serviço e roteamento condicional
  • Regras Comportamentais: Suporte para balking, reneging, falhas de recursos e lógica de roteamento complexa

Tipos de Recursos

  • FIFO: Fila primeiro-a-entrar-primeiro-a-sair (Recurso SimPy)
  • Prioridade: Fila baseada em prioridade (PriorityResource SimPy)
  • Preemptivo: Fila de prioridade preemptiva (PreemptiveResource SimPy)

Para documentação detalhada do formato JSON DES, consulte schemas/DES/README.md.

Formato JSON de Dinâmica de Sistemas

O servidor usa um esquema JSON compatível com PySD para simulações de Dinâmica de Sistemas. Este formato fornece compatibilidade direta com o ecossistema da biblioteca Python PySD.

Estrutura Básica

{
  "abstractModel": {
    "originalPath": "model_name.json",
    "sections": [{
      "name": "__main__",
      "type": "main",
      "elements": [
        {
          "name": "Stock_Name",
          "components": [{
            "type": "Stock",
            "ast": {
              "syntaxType": "IntegStructure",
              "flow": {"syntaxType": "ReferenceStructure", "reference": "Flow_Name"},
              "initial": {"syntaxType": "ReferenceStructure", "reference": "1000"}
            }
          }],
          "units": "items"
        }
      ]
    }]
  }
}

Tipos de Componentes

  • Estoque: Variáveis de acumulação que integram fluxos ao longo do tempo
  • Fluxo: Variáveis de taxa que alteram valores de estoque
  • Auxiliar: Variáveis calculadas derivadas de outras variáveis

Estruturas de Árvore de Sintaxe Abstrata (AST)

O formato PySD suporta duas abordagens para expressões matemáticas:

  • Referências Simples: Expressões baseadas em strings (ex.: "Birth_Rate - Death_Rate")
  • Estruturas Aritméticas: Estruturas matemáticas explícitas com operadores e argumentos definidos

Para documentação detalhada do formato JSON PySD, consulte docs/PYSD_JSON_SCHEMA_INTEGRATION.md, docs/PYSD_AST_STRUCTURES_GUIDE.md e schemas/SD/README.md.

Arquitetura

O Text2Sim é estruturado em componentes modulares:

  • Servidor MCP – Lida com solicitações de linguagem natural via MCP.
  • Módulo de Simulação de Eventos Discretos (DES)
    • Modelo de Simulação – Mecanismo central SimPy que executa fluxos de processo.
    • Classe de Entidade – Representa unidades que fluem pelo sistema.
    • Etapas de Processo – Encapsulam a lógica de cada estágio do processo.
    • Coletor de Métricas – Coleta estatísticas como tempos de espera e throughput.
    • Analisador Seguro de Distribuições – Analisa distribuições de probabilidade com segurança.
  • Módulo de Dinâmica de Sistemas (SD)
    • Integração PySD – Executa modelos usando o formato JSON abstractModel compatível com PySD.
    • Validação de Esquema – Valida modelos contra o esquema abstract_model_v2.json.
    • Arquitetura de Esquema Único – Compatibilidade direta com o fluxo de trabalho PySD sem conversão de formato.

Documentação

Documentação técnica adicional está disponível:

  • docs/PYSD_JSON_SCHEMA_INTEGRATION.md - Especificação do formato JSON PySD
  • docs/PYSD_AST_STRUCTURES_GUIDE.md - Padrões de estrutura AST e melhores práticas
  • schemas/SD/README.md - Documentação do esquema de Dinâmica de Sistemas
  • schemas/DES/README.md - Arquivos de esquema de Simulação de Eventos Discretos
  • SINGLE_SCHEMA_ARCHITECTURE.md - Visão geral da arquitetura e decisões de design

Considerações de Segurança

  • Sem uso de eval()
    A análise baseada em regex impede a execução de código arbitrário.

  • Validação de Entrada
    Tipos de distribuição, parâmetros e configurações de modelo são validados antes da execução.

  • Tratamento Robusto de Erros
    Erros são reportados de forma limpa, sem vazar estado interno.

Aviso Legal

Text2Sim MCP Server é um projeto em desenvolvimento ativo. Embora nos esforcemos para garantir precisão e estabilidade, esteja ciente do seguinte:

  • Trabalho em Andamento: O software está em constante evolução. Os recursos podem mudar, e você pode encontrar bugs ou funcionalidades incompletas. Agradecemos relatórios de bugs e contribuições para nos ajudar a melhorar!
  • Ferramenta Baseada em LLM: Este servidor foi projetado para ser usado com Modelos de Linguagem de Grande Porte (LLMs). A qualidade dos modelos de simulação e a precisão dos resultados dependem fortemente das capacidades do LLM.
  • Verifique Seus Resultados: Sempre revise e valide criticamente quaisquer modelos de simulação e suas saídas. Os resultados devem ser usados como um guia e não como substituto para validação profissional.

Estamos animados para que você use o Text2Sim e esperamos que o considere valioso. Seu feedback é crucial para o seu desenvolvimento.

Contribuindo

Contribuições são aceitas por meio dos procedimentos padrão de fork e pull request. Relatórios de bugs e sugestões de recursos podem ser enviados pelo rastreador de problemas do projeto.

Mudanças importantes devem ser discutidas antes da implementação. O projeto está em desenvolvimento ativo e as decisões arquiteturais podem mudar.

Licença

Este projeto é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.

Citação

Para uso acadêmico, cite como:

Maniatis, N. (2025). Text2Sim MCP Server (v2.6.0). https://github.com/IamCatoBot/text2sim-MCP-server Copyright The Cato Bot Company Limited e colaboradores. Licenciado sob MIT.