text2sim

Text2Sim MCP Server provides a multi-paradigm simulation environment that lets Large Language Models create, validate, and execute simulation models via natural language. It supports Discrete-Event Simulation (DES) using a SimPy-based engine and System Dynamics (SD) modeling using PySD with a PySD-compatible JSON schema. Through its 16 MCP tools across five categories, you can generate DES and SD configurations, validate models, run single or multiple simulations, and manage models with metadata and versioning. The server returns rich analytics, including metrics like wait times, utilization, throughput, time-series data, and validation feedback to guide model development.

To use it, start the UV-based server (as recommended in the installation guide) and interact with the MCP tools through your preferred orchestration layer or via the host application integrating MCP. Typical workflows involve: composing a JSON configuration for a DES or SD model, validating the configuration with the provided validation tools, executing simulations, and inspecting results and diagnostics. The architecture includes modular tools for DES/SD execution, validation, model management, and documentation support, enabling iterative refinement of models within a conversational or scripted interface.

Prerequisites:

• Python 3.12 or higher
• uv package manager (uv) for Python-based MCP server orchestration

1. Install the uv tool (if not already installed):

   • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
   • Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone the repository and navigate to the project directory: git clone https://github.com/IamCatoBot/text2sim-MCP-server.git cd text2sim-MCP-server

3. Synchronize dependencies with uv (installs Python dependencies and project bindings): uv sync

4. Run the MCP server via uv integration (as demonstrated in the Quick Start): uv --directory PATH_TO_TEXT2SIM_MCP_SERVER run python -m mcp_server

5. If integrating with Claude Desktop or other clients, configure the MCP server entry (as shown in the integration example) by editing the appropriate config and pointing to the local PATH_TO_TEXT2SIM_MCP_SERVER where the repository resides.

Tips and common issues:

• Ensure you are using Python 3.12+ and the uv tool as the primary launcher for the MCP server.
• When configuring external integrations (e.g., Claude Desktop), replace PATH_TO_TEXT2SIM_MCP_SERVER with the absolute path to your cloned repository to avoid path resolution errors.
• If uv is not found after installation, verify it with which uv (Unix) or Get-Command uv (PowerShell) and use the full path in the command field.
• The server supports DES and SD model types; the system automatically detects the model type and uses the appropriate toolchain.
• For validation and debugging, leverage the provided help and schema documentation tools to understand required fields and constraints (e.g., JSON schema validation levels and error messaging).
• Monitor environment-specific issues (e.g., Python path conflicts, virtual environments) by ensuring the active Python environment matches the uv invocation.
• For production deployments, consider containerization or orchestrated runtimes, and lock down environment variables and access controls as per your security policies.