IamCatoBot/text2sim-MCP-server

Text2Sim MCP Server

Multi-paradigm Simulation Engine for LLM Integration

A Model Context Protocol server providing multi-paradigm simulation capabilities through conversational interfaces. The server supports Discrete-Event Simulation via SimPy and System Dynamics modeling via PySD and a PySD-compatible JSON schema.

Overview

Text2Sim MCP Server enables Large Language Models to create, validate, and execute simulation models through natural language interfaces. The server processes JSON-structured simulation configurations and returns execution results with comprehensive analytics.

Supported Simulation Paradigms

• Discrete-Event Simulation (DES): Process-oriented modeling using SimPy engine
• System Dynamics (SD): Stock-and-flow modeling using PySD and PySD-compatible JSON schema

About

The Text2Sim MCP Server is an open source project developed by The Cato Bot Company Limited. We believe in transparent, commercially-backed open source development that benefits both users and contributors while supporting sustainable project growth. Community contributions are accepted through standard pull request procedures.

Installation

Prerequisites

• Python 3.12 or higher
• uv package manager

Install uv

On macOS and Linux:

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

On Windows (PowerShell):

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

Learn more: astral-sh/uv

Usage

Clone the repository

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

Integration with Claude Desktop

1. Open:

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

2. Add the following block:

{
  "mcpServers": {
    "Text2Sim MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "PATH_TO_TEXT2SIM_MCP_SERVER", # Update it with yours
        "run",
        "mcp_server.py"
      ],
      "env": {}
    }
  }
}

Note: If the uv command is not found, run which uv (Unix) or Get-Command uv (PowerShell) and use the full path in the "command" field.

Features

LLM Integration

• Natural language to simulation model conversion
• Multi-round conversation support for iterative model development
• JSON Schema 2020-12 validation for configuration reliability
• Contextual error messages with corrective guidance
• Model persistence across conversation sessions

Discrete-Event Simulation Capabilities

• Multiple entity types with configurable priorities and attributes
• Resource management with FIFO, priority, and preemptive scheduling
• Entity behavior modeling including balking and reneging
• Resource failure and repair cycle simulation
• Configurable metrics collection and reporting

System Dynamics Capabilities

• PySD-compatible JSON schema
• Stock, flow, and auxiliary variable modeling
• Mathematical expression support via Abstract Syntax Tree structures
• Time-series simulation with configurable parameters
• Integration with PySD Python library ecosystem

Analytics and Validation

• Simulation metrics including wait times, utilization rates, and throughput
• Statistical analysis with warmup periods and confidence intervals
• Multi-mode validation with partial, strict, and structural checking
• Schema-specific error reporting and correction guidance

Model Management

• Model storage and retrieval with metadata tracking
• JSON export functionality for model sharing and backup
• Automatic schema detection for DES and SD model types
• Version management with conflict resolution

Documentation System

• Context-aware schema documentation with examples
• Multiple detail levels (brief, standard, detailed)
• Domain-specific modeling patterns and workflows
• Integrated help system accessible through MCP tools

Security

• Regex-based distribution parsing without code execution
• Input validation against formal JSON schemas
• Secure error handling without internal state exposure

API Reference

MCP Tools Overview

The server exposes the following tools through the Model Context Protocol:

Core Simulation Tools

simulate_des - Execute Discrete-Event Simulation models

• Accepts JSON configuration with entity types, resources, and processing rules
• Returns simulation results with metrics and statistical analysis

simulate_sd - Execute System Dynamics models

• Accepts PySD-compatible abstractModel JSON format
• Returns time-series data and model execution metadata

run_multiple_simulations - Execute multiple simulation replications

• Runs multiple independent simulation runs with statistical analysis
• Returns confidence intervals, variability measures, and reliability scoring
• Supports seed-based random number control for reproducible results

Validation and Help Tools

validate_model - Validate simulation model configurations

• Supports both DES and SD model validation with auto-detection
• Provides detailed error reports with correction suggestions
• Multiple validation modes: partial, strict, and structural

help_validation - Get validation guidance

• Shows all available validation tools and when to use each one
• Provides troubleshooting guidance for validation errors
• Includes schema type detection and validation mode explanations

get_schema_help - Access comprehensive schema documentation

• Returns structured documentation for schema sections with examples
• Supports nested section paths (e.g., "processing_rules.steps")
• Multiple detail levels: brief, standard, and detailed
• Domain-specific examples and workflow guidance

Model Management Tools

save_model - Store models with metadata

• Automatic naming with domain detection
• Metadata tracking including validation status and tags
• Version management with conflict resolution

load_model - Retrieve stored models

• List all saved models with filtering options
• Load specific models by name or identifier
• Integration with last-loaded state tracking

export_model - Export models to JSON

• Multiple output formats for different use cases
• Conversation-ready templates for session sharing
• Token count estimation for LLM context management

Template and Discovery Tools

list_templates - Browse available model templates

• Lists pre-built templates for both DES and SD models
• Filter by schema type, domain, or complexity level
• Includes template descriptions and use cases

load_template - Retrieve specific templates

• Load template configurations by name or template ID
• Returns ready-to-use model configurations
• Supports both DES and SD template formats

save_template - Save models as reusable templates

• Store validated models as templates for future use
• Automatic template naming with metadata
• Template sharing and organization capabilities

System Dynamics Specific Tools

get_sd_model_info - Analyze System Dynamics models

• Provides detailed analysis of SD model structure without simulation
• Returns complexity metrics and variable information
• Validates abstractModel format and reports structure analysis

convert_vensim_to_sd_json - Convert Vensim models to PySD JSON (TO-DO) (Note: Current implementation returns a basic structure. Full Vensim conversion requires additional implementation)

• Converts Vensim .mdl files to PySD-compatible abstractModel format
• Handles model translation and format validation
• Integration with PySD's Vensim translation capabilities

JSON Schemas

Text2Sim MCP Server uses formal JSON Schema validation (Draft 2020-12) to ensure simulation model correctness and provide structured error reporting. The server supports two distinct JSON formats optimized for their respective simulation paradigms.

Discrete-Event Simulation JSON Format

The server uses a SimPy-compatible JSON schema for Discrete-Event Simulation models. This format provides declarative configuration that maps directly to SimPy's native capabilities.

Basic Structure

{
  "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)"
    }
  }
}

Key Components

• Entity Types: Define different classes of entities with probabilities, values, priorities, and custom attributes
• Resources: Specify system resources with capacity limits and queuing disciplines (FIFO, priority, preemptive)
• Processing Rules: Configure sequential processing steps with service time distributions and conditional routing
• Behavioral Rules: Support for balking, reneging, resource failures, and complex routing logic

Resource Types

• FIFO: First-in-first-out queuing (SimPy Resource)
• Priority: Priority-based queuing (SimPy PriorityResource)
• Preemptive: Preemptive priority queuing (SimPy PreemptiveResource)

For detailed documentation of the DES JSON format, see schemas/DES/README.md.

System Dynamics JSON Format

The server uses a PySD-compatible JSON schema for System Dynamics simulations. This format provides direct compatibility with the PySD Python library ecosystem.

Basic Structure

{
  "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"
        }
      ]
    }]
  }
}

Component Types

• Stock: Accumulation variables that integrate flows over time
• Flow: Rate variables that change stock values
• Auxiliary: Calculated variables derived from other variables

Abstract Syntax Tree (AST) Structures

The PySD format supports two approaches for mathematical expressions:

• Simple References: String-based expressions (e.g., "Birth_Rate - Death_Rate")
• Arithmetic Structures: Explicit mathematical structures with defined operators and arguments

For detailed documentation of the PySD JSON format, see docs/PYSD_JSON_SCHEMA_INTEGRATION.md, docs/PYSD_AST_STRUCTURES_GUIDE.md, and schemas/SD/README.md.

Architecture

Text2Sim is structured into modular components:

• MCP Server – Handles natural language requests via MCP.
• Discrete-Event Simulation (DES) Module
  • Simulation Model – Core SimPy engine that executes process flows.
  • Entity Class – Represents units flowing through the system.
  • Process Steps – Encapsulate logic for each process stage.
  • Metrics Collector – Gathers statistics like wait times and throughput.
  • Secure Distribution Parser – Parses probability distributions safely.
• System Dynamics (SD) Module
  • PySD Integration – Executes models using PySD-compatible abstractModel JSON format.
  • Schema Validation – Validates models against abstract_model_v2.json schema.
  • Single-Schema Architecture – Direct PySD workflow compatibility without format conversion.

Documentation

Additional technical documentation is available:

• docs/PYSD_JSON_SCHEMA_INTEGRATION.md - PySD JSON format specification
• docs/PYSD_AST_STRUCTURES_GUIDE.md - AST structure patterns and best practices
• schemas/SD/README.md - System Dynamics schema documentation
• schemas/DES/README.md - Discrete-Event Simulation schema files
• SINGLE_SCHEMA_ARCHITECTURE.md - Architecture overview and design decisions

Security Considerations

• No eval() usage
  Regex-based parsing prevents arbitrary code execution.

• Input Validation
  Distribution types, parameters, and model configurations are validated before execution.

• Robust Error Handling
  Errors are reported cleanly without leaking internal state.

Disclaimer

Text2Sim MCP Server is a project under active development. While we strive for accuracy and stability, please be aware of the following:

• Work in Progress: The software is continuously evolving. Features may change, and you may encounter bugs or incomplete functionality. We welcome bug reports and contributions to help us improve!
• LLM-Powered Tool: This server is designed to be used with Large Language Models (LLMs). The quality of the simulation models and the accuracy of the results depend heavily on the LLM's capabilities.
• Verify Your Results: Always critically review and validate any simulation models and their outputs. The results should be used as a guide and not as a substitute for professional validation.

We are excited for you to use Text2Sim and hope you find it valuable. Your feedback is crucial to its development.

Contributing

Contributions are accepted through standard fork-and-pull-request procedures. Bug reports and feature suggestions can be submitted via the project issue tracker.

Major changes should be discussed before implementation. The project is under active development and architectural decisions may change.

License

This project is licensed under the MIT License. See the file for details.

Citation

For academic use, cite as:

Maniatis, N. (2025). Text2Sim MCP Server (v2.5.3). https://github.com/IamCatoBot/text2sim-MCP-server Copyright The Cato Bot Company Limited and contributors. Licensed under MIT.