Simulation AI Agent

A plugin-based discrete event simulation server with MCP (Model Context Protocol) integration, enabling AI assistants to run and analyze simulations.

Features

• Plugin-based Simulation Engine: Extensible architecture supporting multiple simulation types
• Built-in Simulations: Queueing, Manufacturing, Inventory, and Logistics
• MCP Integration: Expose simulations as tools for Claude and other AI assistants
• JWT Authentication: Secure API access with user/tenant management
• Multi-tenant Support: Row-level security for data isolation
• Real-time WebSocket Updates: Stream simulation events as they happen
• Analytics & Reporting: Aggregate statistics and trend analysis
• ML Predictions: PyTorch neural networks for outcome prediction
• Prometheus Metrics: Monitor API performance and simulation runs

Quick Start

Installation

# Clone and install
git clone https://github.com/bulentsoykan/Simulation-AI-Agent.git
cd Simulation-AI-Agent
pip install -r requirements.txt

Running the Servers

# Terminal 1: Start FastAPI server (port 8000)
python server.py

# Terminal 2: Start MCP server (port 8001)
python mcp_server.py

The API will be available at http://localhost:8000 with interactive docs at http://localhost:8000/docs

Simulation Types

Queueing (M/M/c Queue)

Models customer arrivals, waiting, and service with multiple servers.

curl -X POST http://localhost:8000/simulations/queueing/run \
  -H "Content-Type: application/json" \
  -d '{"params": {"n_servers": 3, "arrival_rate": 10, "service_time": 2, "sim_time": 480}}'

Parameters:

• n_servers: Number of parallel service stations (default: 1)
• arrival_rate: Customer arrival rate per time unit (default: 5.0)
• service_time: Average service time per customer (default: 3.0)
• sim_time: Total simulation time (default: 1440)

Metrics:

• total_customers, avg_wait_time, avg_system_time, max_wait_time, server_utilization

Manufacturing (Production Line)

Models work flowing through production stations with buffers.

curl -X POST http://localhost:8000/simulations/manufacturing/run \
  -H "Content-Type: application/json" \
  -d '{"params": {"stations": ["Cutting", "Assembly", "QC"], "processing_times": [2.0, 5.0, 1.5], "arrival_rate": 0.3}}'

Parameters:

• stations: Names of production stations in order
• processing_times: Processing time at each station
• buffer_sizes: Buffer capacity before each station
• arrival_rate: Raw material arrival rate

Metrics:

• throughput, avg_cycle_time, wip, station_utilization, bottleneck_station

Inventory ((s,S) Policy)

Models inventory with reorder points and lead times.

curl -X POST http://localhost:8000/simulations/inventory/run \
  -H "Content-Type: application/json" \
  -d '{"params": {"reorder_point": 20, "order_up_to": 100, "demand_rate": 5.0, "lead_time": 5.0}}'

Parameters:

• reorder_point: Inventory level that triggers reorder (s)
• order_up_to: Target inventory level when ordering (S)
• demand_rate: Average demand per time unit
• lead_time: Time between order and delivery

Metrics:

• total_demand, total_fulfilled, fill_rate, avg_inventory, stockout_count, total_cost

Logistics (Vehicle Routing)

Models capacitated vehicle routing for deliveries.

curl -X POST http://localhost:8000/simulations/logistics/run \
  -H "Content-Type: application/json" \
  -d '{"params": {"num_vehicles": 3, "vehicle_capacity": 100, "num_customers": 20}}'

Parameters:

• num_vehicles: Number of delivery vehicles
• vehicle_capacity: Capacity per vehicle
• num_customers: Number of customer locations
• service_time: Time to serve each customer

Metrics:

• customers_served, customers_unserved, total_distance, vehicle_utilization, demand_fulfilled

API Endpoints

Simulations

Endpoint	Method	Description
/simulations	GET	List all available simulation types
/simulations/{type}/schema	GET	Get parameter schema for a simulation
/simulations/{type}/run	POST	Run a simulation
/simulate	POST	Run queueing simulation (legacy)

Authentication

Endpoint	Method	Description
/auth/register	POST	Register new user
/auth/login	POST	Login and get tokens
/auth/refresh	POST	Refresh access token
/auth/me	GET	Get current user info

Analytics

Endpoint	Method	Description
/analytics/simulation-summary	GET	Get simulation run statistics
/analytics/trends	GET	Get metric trends over time

ML Predictions

Endpoint	Method	Description
/predict/{sim_type}	GET	Predict simulation outcomes
/ml/train	POST	Train prediction model (admin)
/ml/model-info	GET	Get model information

Health & Monitoring

Endpoint	Method	Description
/health	GET	Health check
/health/ready	GET	Readiness check (DB)
/metrics	GET	Prometheus metrics

MCP Tools

When connected via MCP, the following tools are available:

• list_simulations: List all available simulation types
• run_simulation(simulation_type, params): Run any simulation type
• simulate(...): Run queueing simulation (convenience wrapper)
• get_workorder_details(workorder_number): Get workorder tracking info
• get_workorder_configuration(workorder_number): Get workorder config

Claude Desktop Integration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "simulation": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8001/mcp"]
    }
  }
}

Adding Custom Simulations

Create a new simulation by extending BaseSimulation:

from simulations.base import BaseSimulation
from simulations.registry import SimulationRegistry

@SimulationRegistry.register
class MySimulation(BaseSimulation):
    name = "my_simulation"
    description = "My custom simulation"

    def get_parameter_schema(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "my_param": {"type": "number", "default": 1.0}
            }
        }

    def get_metrics_schema(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "my_metric": {"type": "number"}
            }
        }

    def run(self, params: dict, callback=None) -> dict:
        validated = self.validate_params(params)
        # Run your simulation logic
        return {"my_metric": 42.0}

Configuration

Environment variables (or .env file):

Variable	Default	Description
DATABASE_URL	sqlite:///./simulation.db	Database connection string
JWT_SECRET_KEY	(generated)	Secret for JWT signing
API_PORT	8000	FastAPI server port
MCP_PORT	8001	MCP server port
DEBUG	false	Enable debug mode

Project Structure

simulation-ai-agent/
├── server.py              # FastAPI application
├── mcp_server.py          # MCP server
├── config.py              # Configuration settings
├── simulations/           # Simulation plugins
│   ├── base.py            # BaseSimulation class
│   ├── registry.py        # Plugin registry
│   ├── queueing.py        # M/M/c queue
│   ├── manufacturing.py   # Production line
│   ├── inventory.py       # Inventory management
│   └── logistics.py       # Vehicle routing
├── database/              # SQLAlchemy models
│   ├── connection.py      # DB session management
│   └── models.py          # ORM models
├── auth/                  # JWT authentication
│   ├── jwt_handler.py     # Token creation/validation
│   ├── dependencies.py    # FastAPI dependencies
│   └── schemas.py         # Pydantic schemas
├── analytics/             # Reporting
│   ├── aggregations.py    # Query aggregations
│   └── reports.py         # Report generation
├── ml/                    # Machine learning
│   ├── predictor.py       # PyTorch inference
│   └── trainer.py         # Model training
├── websocket/             # Real-time updates
│   └── manager.py         # Connection manager
└── monitoring/            # Prometheus metrics
    └── metrics.py         # Metric collectors

Author

Bulent Soykan

• GitHub: @bulentsoykan
• Email: soykanb@gmail.com

License

MIT

Project Overview

A plugin-based MCP server exposing discrete event simulations to AI assistants. Features:

• Plugin-based simulation engine (queueing, manufacturing, inventory, logistics)
• JWT authentication with multi-tenant support
• Real-time WebSocket updates
• Analytics and ML-based prediction
• Prometheus monitoring

Architecture

┌─────────────────┐    WS/HTTP   ┌─────────────────┐
│  MCP Clients    │ ◄──────────► │  mcp_server.py  │
└─────────────────┘    :8001     └────────┬────────┘
                                          │
┌─────────────────┐    WS/HTTP   ┌────────▼────────┐    ┌─────────────────┐
│  Web Clients    │ ◄──────────► │   server.py     │◄──►│  SQLite DB      │
└─────────────────┘    :8000     │   (FastAPI)     │    │  (SQLAlchemy)   │
                                 └────────┬────────┘    └─────────────────┘
                                          │
              ┌───────────────────────────┼───────────────────────────┐
              ▼                           ▼                           ▼
    ┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
    │ simulations/    │         │  ml/            │         │  analytics/     │
    │  base.py        │         │  predictor.py   │         │  reports.py     │
    │  registry.py    │         │   (PyTorch)     │         │  aggregations.py│
    │  queueing.py    │         └─────────────────┘         └─────────────────┘
    │  manufacturing.py│
    │  inventory.py   │
    │  logistics.py   │
    └─────────────────┘

Running the Project

# Install dependencies
pip install -r requirements.txt

# Terminal 1: FastAPI server (port 8000)
python server.py

# Terminal 2: MCP server (port 8001)
python mcp_server.py

Key Components

Simulation Plugin System (simulations/)

• base.py: BaseSimulation abstract class with run(), get_parameter_schema(), get_metrics_schema()
• registry.py: SimulationRegistry for plugin discovery and instantiation
• Built-in types: queueing, manufacturing, inventory, logistics

Authentication (auth/)

• JWT-based with access/refresh tokens
• Multi-tenant via tenant_id on all models
• Dependencies: get_current_user, get_current_tenant, require_role()

Database (database/)

• SQLAlchemy ORM with SQLite (configurable to PostgreSQL)
• Models: Tenant, User, SimulationRun, Workorder

ML Prediction (ml/)

• PyTorch neural networks trained on historical simulation data
• SimulationPredictor for inference, SimulationTrainer for training

API Endpoints

Category	Endpoint	Description
Simulations	GET /simulations	List simulation types
	GET /simulations/{type}/schema	Get parameter schema
	POST /simulations/{type}/run	Run simulation
Auth	POST /auth/register	Register user
	POST /auth/login	Get tokens
	GET /auth/me	Current user
Health	GET /health	Health check
	GET /metrics	Prometheus metrics

MCP Tools

• list_simulations(): List available simulation types
• run_simulation(simulation_type, params): Run any simulation
• simulate(...): Run queueing simulation (legacy)
• get_workorder_details(workorder_number): Get workorder info
• get_workorder_configuration(workorder_number): Get workorder config

Adding a New Simulation

from simulations.base import BaseSimulation
from simulations.registry import SimulationRegistry

@SimulationRegistry.register
class MySimulation(BaseSimulation):
    name = "my_simulation"
    description = "Description here"

    def get_parameter_schema(self) -> dict:
        return {"type": "object", "properties": {...}}

    def get_metrics_schema(self) -> dict:
        return {"type": "object", "properties": {...}}

    def run(self, params: dict, callback=None) -> dict:
        validated = self.validate_params(params)
        # Simulation logic here
        return {"metric": value}

Configuration

Settings loaded from environment or .env:

• DATABASE_URL: Database connection (default: sqlite:///./simulation.db)
• JWT_SECRET_KEY: JWT signing secret
• API_PORT / MCP_PORT: Server ports (8000/8001)
• DEBUG: Enable debug mode