Text2Sim MCP Server

A multi-paradigm simulation engine for Discrete-Event and System Dynamics, enabling natural language-based simulations via MCP.

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.

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.

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

The Text2Sim MCP Server is an open source project developed byThe 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.

- Python3.12or higher
- uvpackage manager

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

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

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

{ "mcpServers": { "Text2Sim MCP Server": { "command": "uv", "args": [ "--directory", "PATH_TO_TEXT2SIM_MCP_SERVER", "run", "python", "-m", "mcp_server" ], "env": {} } } }

Note:ReplacePATH_TO_TEXT2SIM_MCP_SERVERwith the actual path to your cloned repository. If theuvcommand is not found, runwhich uv(Unix) orGet-Command uv(PowerShell) and use the full path in the"command"field.

- 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

- 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

- 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

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

- 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

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

Text2Sim MCP Server v2.6.0 features a completely refactored modular architecture that improves maintainability, testability, and extensibility:

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

- Separation of Concerns: Each domain has its own focused module
- Standardized Error Handling: Consistent error responses with actionable guidance
- Enhanced Integration: Robust SD integration with graceful fallbacks
- Professional Standards: Comprehensive documentation and type hints
- Extensibility: Easy to add new simulation paradigms or tools

The server exposes16 toolsacross5 categoriesthrough the Model Context Protocol:

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

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

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

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

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

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

- Safe deletion with confirmation requirements
- Protects built-in templates from accidental removal
- Provides backup recommendations

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

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

- Remove saved models with confirmation requirements
- Provides model metadata before deletion
- Includes undo suggestions and safety features

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.

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.

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

- 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

- 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, seeschemas/DES/README.md.

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

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

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

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, seedocs/PYSD_JSON_SCHEMA_INTEGRATION.md,docs/PYSD_AST_STRUCTURES_GUIDE.md, andschemas/SD/README.md.

Text2Sim is structured into modular components:

- MCP Server– Handles natural language requests via MCP.
- Discrete-Event Simulation (DES) Module

- Simulation Model– CoreSimPyengine 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.

- PySD Integration– Executes models using PySD-compatible abstractModel JSON format.
- Schema Validation– Validates models against abstract_model_v2.json schema.
- Single-Schema Architecture– DirectPySDworkflow compatibility without format conversion.

This project is licensed under theMIT License. See theLICENSEfile for details.

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

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.