Text2sim MCP Server

Text2Sim MCP 服务

用于 LLM 集成的多范式仿真引擎

一个 Model Context Protocol 服务，通过对话式界面提供多范式仿真能力。该服务支持通过 SimPy 进行离散事件仿真，以及通过 PySD 和兼容 PySD 的 JSON schema 进行系统动力学建模。

概述

Text2Sim MCP 服务使大模型能够通过自然语言界面创建、验证和执行仿真模型。该服务处理 JSON 结构的仿真配置，并返回带有全面分析结果的执行结果。

支持的仿真范式

• 离散事件仿真（DES）：使用 SimPy 引擎的面向过程建模
• 系统动力学（SD）：使用 PySD 和兼容 PySD 的 JSON schema 进行存量-流量建模

---

关于

Text2Sim MCP 服务是由 The Cato Bot Company Limited 开发的开源项目。我们相信透明、有商业支持的开源开发，既能惠及用户和贡献者，又能支持项目的可持续增长。社区贡献通过标准 pull request 流程接受。

---

安装

前置条件

• Python 3.12 或更高版本
• uv 包管理器

安装 uv

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

了解更多：astral-sh/uv

---

快速开始

克隆仓库

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

安装依赖

uv sync

与 Claude Desktop 集成

1. 打开：

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

2. 添加以下块：

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

注意： 将 PATH_TO_TEXT2SIM_MCP_SERVER 替换为你克隆仓库的实际路径。如果找不到 uv 命令，请运行 which uv（Unix）或 Get-Command uv（PowerShell），并在 "command" 字段中使用完整路径。

---

功能

LLM 集成

• 自然语言到仿真模型的转换
• 支持多轮对话以进行迭代式模型开发
• 使用 JSON Schema 2020-12 验证以确保配置可靠性
• 带有纠正指导的上下文错误消息
• 跨对话会话的模型持久化

离散事件仿真能力

• 多种实体类型，可配置优先级和属性
• 资源管理，支持 FIFO、优先级和抢占式调度
• 实体行为建模，包括放弃和反悔
• 资源故障和修复周期仿真
• 可配置的指标收集和报告

系统动力学能力

• 兼容 PySD 的 JSON schema
• 存量、流量和辅助变量建模
• 通过抽象语法树结构支持数学表达式
• 具有可配置参数的时间序列仿真
• 与 PySD Python 库生态系统集成

分析和验证

• 仿真指标，包括等待时间、利用率和吞吐量
• 具有预热期和置信区间的统计分析
• 多模式验证，支持部分、严格和结构检查
• 针对 schema 的错误报告和纠正指导

模型管理

• 带元数据跟踪的模型存储和检索
• 用于模型共享和备份的 JSON 导出功能
• 针对 DES 和 SD 模型类型的自动 schema 检测
• 具有冲突解决的版本管理

文档系统

• 带示例的上下文感知 schema 文档
• 多个详细级别（简要、标准、详细）
• 领域特定的建模模式和工作流
• 可通过 MCP 工具访问的集成帮助系统

安全性

• 基于正则的分布解析，不执行代码
• 依据正式 JSON schema 进行输入验证
• 安全的错误处理，不暴露内部状态

---

架构

模块化设计

Text2Sim MCP Server v2.6.0 采用完全重构的模块化架构，提升了可维护性、可测试性和可扩展性：

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

关键改进

• 关注点分离：每个领域都有自己专注的模块
• 标准化错误处理：一致且可操作的错误响应与指导
• 增强集成：稳健的 SD 集成，支持优雅降级
• 专业标准：全面的文档和类型提示
• 可扩展性：轻松添加新的仿真范式或工具

---

API 参考

MCP 工具概览

该服务通过 Model Context Protocol 在 5 个类别中提供 16 个工具：

核心仿真工具

simulate_des - 执行离散事件仿真模型

• 接受包含实体类型、资源和处理规则的 JSON 配置
• 返回带有指标和统计分析的仿真结果

simulate_sd - 执行系统动力学模型

• 接受兼容 PySD 的 abstractModel JSON 格式
• 返回时间序列数据和模型执行元数据

run_multiple_simulations - 执行多次仿真重复

• 运行多个独立仿真并附带统计分析
• 返回置信区间、变异性度量和可靠性评分
• 支持基于种子的随机数控制以获得可复现结果

验证和帮助工具

validate_model - 验证仿真模型配置

• 支持 DES 和 SD 模型验证，并自动检测
• 提供带有更正建议的详细错误报告
• 多种验证模式：partial、strict 和 structural

help_validation - 获取验证指导

• 显示所有可用的验证工具以及各自的使用时机
• 提供针对验证错误的故障排除指导
• 包括 schema 类型检测和验证模式说明

get_schema_help - 访问全面的 schema 文档

• 返回带有示例的 schema 各节的结构化文档
• 支持嵌套节路径（例如 "processing_rules.steps"）
• 多种详细程度：brief、standard 和 detailed
• 针对特定领域的示例和工作流指导

模型管理工具

save_model - 存储带元数据的模型

• 自动命名并检测领域
• 元数据跟踪，包括验证状态和标签
• 带冲突解决的版本管理

load_model - 检索已存储的模型

• 列出所有已保存模型，并提供筛选选项
• 按名称或标识符加载特定模型
• 与最近加载状态跟踪集成

export_model - 将模型导出为 JSON

• 针对不同用例的多种输出格式
• 便于会话共享的对话就绪模板
• 用于大模型上下文管理的 token 数量估算

模板和发现工具

list_templates - 浏览可用的模型模板

• 列出 DES 和 SD 模型的预构建模板
• 按 schema 类型、领域或复杂度级别筛选
• 包含模板描述和用例

load_template - 检索特定模板

• 按名称或模板 ID 加载模板配置
• 返回可直接使用的模型配置
• 支持 DES 和 SD 模板格式

save_template - 将模型保存为可复用模板

• 将已验证的模型存储为模板以供将来使用
• 自动模板命名并附带元数据
• 模板共享和组织能力

delete_template - 删除用户模板

• 需要确认的安全删除
• 保护内置模板免遭意外删除
• 提供备份建议

系统动力学专用工具

get_sd_model_info - 分析系统动力学模型

• 在不进行仿真的情况下，对 SD 模型结构进行详细分析
• 返回复杂度指标和变量信息
• 验证 abstractModel 格式并报告结构分析结果

convert_vensim_to_sd_json - 将 Vensim 模型转换为 PySD JSON

• 将 Vensim .mdl 文件转换为 PySD 兼容的 abstractModel 格式
• 处理模型转换和格式验证
• 与 PySD 的 Vensim 转换能力集成

增强工具（v2.6.0 新增）

delete_model - 安全删除模型

• 在需要确认的情况下删除已保存的模型
• 在删除前提供模型元数据
• 包含撤销建议和安全功能

JSON Schema

Text2Sim MCP 服务使用正式的 JSON Schema 验证（Draft 2020-12），以确保仿真模型的正确性，并提供结构化的错误报告。该服务支持两种不同的 JSON 格式，分别针对各自的仿真范式进行了优化。

离散事件仿真 JSON 格式

该服务为离散事件仿真模型使用 SimPy 兼容的 JSON schema。该格式提供声明式配置，可直接映射到 SimPy 的原生能力。

基本结构

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

关键组件

• 实体类型：定义不同类别的实体，包含概率、值、优先级和自定义属性
• 资源：指定具有容量限制和排队规则（FIFO、优先级、抢占）的系统资源
• 处理规则：配置带有服务时间分布和条件路由的顺序处理步骤
• 行为规则：支持放弃排队、中途退出、资源故障和复杂路由逻辑

资源类型

• FIFO：先进先出排队（SimPy Resource）
• Priority：基于优先级的排队（SimPy PriorityResource）
• Preemptive：抢占式优先级排队（SimPy PreemptiveResource）

有关 DES JSON 格式的详细文档，请参见 schemas/DES/README.md。

系统动力学 JSON 格式

该服务为系统动力学仿真使用 PySD 兼容的 JSON schema。该格式可直接兼容 PySD Python 库生态系统。

基本结构

{
  "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）：随时间累积流量的累积变量
• 流量（Flow）：改变存量值的速率变量
• 辅助变量（Auxiliary）：由其他变量推导出的计算变量

抽象语法树（AST）结构

PySD 格式支持两种数学表达式方法：

• 简单引用：基于字符串的表达式（例如 "Birth_Rate - Death_Rate"）
• 算术结构：具有已定义运算符和参数的显式数学结构

有关 PySD JSON 格式的详细文档，请参见 docs/PYSD_JSON_SCHEMA_INTEGRATION.md、docs/PYSD_AST_STRUCTURES_GUIDE.md 和 schemas/SD/README.md。

---

架构

Text2Sim 由模块化组件构成：

• MCP 服务 – 通过 MCP 处理自然语言请求。
• 离散事件仿真（DES）模块
  • 仿真模型 – 执行流程流转的核心 SimPy 引擎。
  • 实体类 – 表示在系统中流动的单元。
  • 流程步骤 – 封装每个流程阶段的逻辑。
  • 指标收集器 – 收集等待时间和吞吐量等统计数据。
  • 安全分布解析器 – 安全地解析概率分布。
• 系统动力学（SD）模块
  • PySD 集成 – 使用 PySD 兼容的 abstractModel JSON 格式执行模型。
  • Schema 验证 – 根据 abstract_model_v2.json schema 验证模型。
  • 单 Schema 架构 – 直接兼容 PySD 工作流，无需格式转换。

文档

还提供其他技术文档：

• docs/PYSD_JSON_SCHEMA_INTEGRATION.md - PySD JSON 格式规范
• docs/PYSD_AST_STRUCTURES_GUIDE.md - AST 结构模式与最佳实践
• schemas/SD/README.md - 系统动力学 schema 文档
• schemas/DES/README.md - 离散事件仿真 schema 文件
• SINGLE_SCHEMA_ARCHITECTURE.md - 架构概览与设计决策

---

安全注意事项

• 不使用 eval()
  基于正则表达式的解析可防止任意代码执行。

• 输入验证
  分布类型、参数和模型配置在执行前都会经过验证。

• 健壮的错误处理
  错误会被清晰报告，不会泄露内部状态。

---

免责声明

Text2Sim MCP 服务是一个正在积极开发中的项目。虽然我们力求准确与稳定，但请注意以下事项：

• 开发中的工作： 该软件在持续演进。功能可能会发生变化，你可能会遇到 bug 或不完整的功能。我们欢迎 bug 报告和贡献，以帮助我们改进！
• 由大模型驱动的工具： 该服务设计用于配合大模型（LLM）使用。仿真模型的质量和结果的准确性在很大程度上取决于大模型的能力。
• 验证你的结果： 请始终批判性地审查并验证任何仿真模型及其输出。结果应作为参考，而不能替代专业验证。

我们很高兴你能使用 Text2Sim，并希望你觉得它有价值。你的反馈对其开发至关重要。

---

贡献

贡献通过标准的 fork-and-pull-request 流程接受。Bug 报告和功能建议可通过项目 issue 跟踪器提交。

重大变更应在实施前进行讨论。该项目正在积极开发中，架构决策可能会发生变化。

---

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

---

引用

用于学术用途时，请引用：

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

---