Text2sim MCP Server

Text2Sim MCP Server

LLM 統合のためのマルチパラダイムシミュレーションエンジン

会話型インターフェースを通じてマルチパラダイムのシミュレーション機能を提供する Model Context Protocol サーバーです。このサーバーは、SimPy による離散イベントシミュレーションと、PySD および PySD 互換の JSON スキーマによるシステムダイナミクスモデリングをサポートしています。

概要

Text2Sim MCP Server を使用すると、大規模言語モデルが自然言語インターフェースを通じてシミュレーションモデルを作成、検証、実行できます。このサーバーは、JSON 構造のシミュレーション設定を処理し、包括的な分析結果とともに実行結果を返します。

サポートされるシミュレーションパラダイム

• 離散イベントシミュレーション（DES）：SimPy エンジンを使用したプロセス指向のモデリング
• システムダイナミクス（SD）：PySD および PySD 互換の JSON スキーマを使用したストック・フローモデリング

---

概要

Text2Sim MCP Server は、The Cato Bot Company Limited が開発したオープンソースプロジェクトです。ユーザーとコントリビューターの双方にメリットをもたらし、プロジェクトの持続可能な成長を支える、透明性の高い商業的支援を受けたオープンソース開発を目指しています。標準的なプルリクエスト手順を通じて、コミュニティからの貢献を受け付けています。

---

インストール

前提条件

• 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 スキーマ
• ストック、フロー、補助変数のモデリング
• 抽象構文木構造による数式表現のサポート
• パラメーターを設定可能な時系列シミュレーション
• PySD Python ライブラリエコシステムとの統合

分析と検証

• 待ち時間、稼働率、スループットなどのシミュレーション指標
• ウォームアップ期間と信頼区間を含む統計分析
• 部分、厳密、構造チェックによる複数モードの検証
• スキーマ固有のエラーレポートと修正方法のガイダンス

モデル管理

• メタデータ追跡機能を備えたモデルの保存と取得
• モデルの共有とバックアップに対応した JSON エクスポート機能
• DES および SD モデルタイプの自動スキーマ検出
• 競合解決機能を備えたバージョン管理

ドキュメントシステム

• 例を含む、コンテキストに応じたスキーマドキュメント
• 複数の詳細レベル（簡潔、標準、詳細）
• ドメイン固有のモデリングパターンとワークフロー
• MCP ツールから利用できる統合ヘルプシステム

セキュリティ

• コードを実行しない正規表現ベースの分布解析
• 正式な JSON スキーマに基づく入力検証
• 内部状態を公開しない安全なエラー処理

---

アーキテクチャ

モジュール設計

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 の両方のモデル検証に対応し、自動判別します
• 修正の提案を含む詳細なエラーレポートを提供します
• 部分検証、厳密検証、構造検証の複数の検証モードを備えています

help_validation - 検証ガイダンスを取得します

• 利用可能なすべての検証ツールと、それぞれの使用場面を示します
• 検証エラーのトラブルシューティングガイダンスを提供します
• スキーマタイプの判別と検証モードの説明を含みます

get_schema_help - 包括的なスキーマドキュメントを参照します

• 例を含む、スキーマの各セクションの構造化されたドキュメントを返します
• ネストされたセクションパス（例："processing_rules.steps"）に対応します
• 簡潔、標準、詳細の複数の詳細レベルを備えています
• ドメイン固有の例とワークフローガイダンスを提供します

モデル管理ツール

save_model - メタデータとともにモデルを保存します

• ドメインを自動判別して名前を付けます
• 検証ステータスやタグを含むメタデータを追跡します
• 競合解決を伴うバージョン管理を行います

load_model - 保存済みモデルを取得します

• フィルタリングオプションを使って、保存済みのすべてのモデルを一覧表示します
• 名前または識別子を指定して、特定のモデルを読み込みます
• 最後に読み込んだ状態の追跡と統合されています

export_model - モデルを JSON にエクスポートします

• 用途に応じた複数の出力形式を備えています
• セッション共有に使える、会話向けのテンプレートを提供します
• LLM のコンテキスト管理用にトークン数を推定します

テンプレートおよび検出ツール

list_templates - 利用可能なモデルテンプレートを参照します

• DES と SD の両モデル向けに、事前構築されたテンプレートを一覧表示します
• スキーマタイプ、ドメイン、複雑さのレベルで絞り込めます
• テンプレートの説明と使用例を含みます

load_template - 特定のテンプレートを取得します

• 名前またはテンプレート ID を指定して、テンプレート設定を読み込みます
• すぐに使えるモデル設定を返します
• DES と SD の両方のテンプレート形式に対応します

save_template - モデルを再利用可能なテンプレートとして保存します

• 検証済みモデルを、今後使用するテンプレートとして保存します
• メタデータを含むテンプレート名を自動生成します
• テンプレートの共有と整理が可能です

delete_template - ユーザーテンプレートを削除します

• 確認を必須とする安全な削除機能を備えています
• 組み込みテンプレートを誤って削除しないよう保護します
• バックアップに関する推奨事項を提示します

System Dynamics 専用ツール

get_sd_model_info - System Dynamics モデルを分析

• シミュレーションを実行せずに、SD モデルの構造を詳細に分析します
• 複雑度の指標と変数情報を返します
• abstractModel 形式を検証し、構造分析を報告します

convert_vensim_to_sd_json - Vensim モデルを PySD JSON に変換

• Vensim の .mdl ファイルを PySD 互換の abstractModel 形式に変換します
• モデルの変換と形式の検証を処理します
• PySD の Vensim 変換機能と連携します

拡張ツール（v2.6.0 で新登場）

delete_model - 安全なモデル削除

• 確認を必須として保存済みモデルを削除します
• 削除前にモデルのメタデータを提示します
• 元に戻すための提案と安全機能を備えています

JSON スキーマ

Text2Sim MCP Server は、シミュレーションモデルの正確性を確保し、構造化されたエラー報告を提供するために、正式な JSON Schema 検証（Draft 2020-12）を使用します。サーバーは、それぞれのシミュレーション方式に最適化された、2 種類の JSON 形式に対応しています。

離散イベントシミュレーション JSON 形式

サーバーは、離散イベントシミュレーションモデル向けに SimPy 互換の JSON スキーマを使用します。この形式は、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 を参照してください。

System Dynamics JSON 形式

サーバーは、System Dynamics シミュレーション向けに PySD 互換の JSON スキーマを使用します。この形式は、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 形式では、数式表現に次の 2 つの方法を使用できます。

• 単純な参照：文字列ベースの式（例："Birth_Rate - Death_Rate"）
• 算術構造：定義済みの演算子と引数を持つ明示的な数学的構造

PySD JSON 形式の詳細なドキュメントについては、docs/PYSD_JSON_SCHEMA_INTEGRATION.md、docs/PYSD_AST_STRUCTURES_GUIDE.md、schemas/SD/README.md を参照してください。

---

アーキテクチャ

Text2Sim は、モジュール化されたコンポーネントで構成されています。

• MCP Server – MCP 経由で自然言語のリクエストを処理します。
• 離散イベントシミュレーション（DES）モジュール
  • シミュレーションモデル – プロセスフローを実行するコアの SimPy エンジンです。
  • エンティティクラス – システム内を流れる単位を表します。
  • プロセスステップ – 各処理段階のロジックをカプセル化します。
  • メトリクスコレクター – 待ち時間やスループットなどの統計を収集します。
  • 安全な分布パーサー – 確率分布を安全に解析します。
• System Dynamics（SD）モジュール
  • PySD 統合 – PySD 互換の abstractModel JSON 形式を使用してモデルを実行します。
  • スキーマ検証 – abstract_model_v2.json スキーマに照らしてモデルを検証します。
  • 単一スキーマアーキテクチャ – 形式変換なしで、PySD ワークフローとの互換性を直接提供します。

ドキュメント

技術ドキュメントの詳細は、以下をご覧ください。

• docs/PYSD_JSON_SCHEMA_INTEGRATION.md - PySD JSON 形式の仕様
• docs/PYSD_AST_STRUCTURES_GUIDE.md - AST 構造のパターンとベストプラクティス
• schemas/SD/README.md - システムダイナミクスのスキーマに関するドキュメント
• schemas/DES/README.md - 離散事象シミュレーションのスキーマファイル
• SINGLE_SCHEMA_ARCHITECTURE.md - アーキテクチャの概要と設計上の判断

---

セキュリティに関する考慮事項

• eval() は使用しません
  正規表現ベースの解析により、任意のコード実行を防止します。

• 入力の検証
  分布タイプ、パラメーター、モデル設定を実行前に検証します。

• 堅牢なエラー処理
  内部状態を漏らすことなく、エラーを適切に報告します。

---

免責事項

Text2Sim MCP Server は現在開発中のプロジェクトです。正確性と安定性の向上に努めていますが、以下の点にご留意ください。

• 開発中のソフトウェアです： ソフトウェアは継続的に進化しています。機能が変更される場合があり、バグや未完成の機能に遭遇する可能性があります。改善に役立つバグ報告や貢献を歓迎します。
• LLM を活用するツールです： このサーバーは、大規模言語モデル（LLM）とともに使用することを想定しています。シミュレーションモデルの品質と結果の正確性は、LLM の性能に大きく左右されます。
• 結果を検証してください： シミュレーションモデルとその出力は、必ず批判的に確認し、検証してください。結果は参考として使用し、専門家による検証の代わりにしないでください。

Text2Sim をご利用いただけることをうれしく思います。皆様のお役に立てば幸いです。皆様からのフィードバックは、開発に欠かせません。

---

貢献

貢献は、標準的なフォークとプルリクエストの手順を通じて受け付けています。バグ報告や機能の提案は、プロジェクトのイシュートラッカーから送信できます。

大きな変更は、実装前に相談してください。プロジェクトは現在開発中であり、アーキテクチャ上の判断が変更される場合があります。

---

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は 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.

---