{
  "markdown": "<div align=\"center\">\n\n# AgentSUMO\n\n**An Agentic Framework for Interactive Simulation Scenario Generation in SUMO via Large Language Models**\n\n[![PyPI](https://img.shields.io/pypi/v/agentsumo-mcp.svg)](https://pypi.org/project/agentsumo-mcp/)\n[![tests](https://github.com/mw-jeong/AgentSUMO/actions/workflows/tests.yml/badge.svg)](https://github.com/mw-jeong/AgentSUMO/actions/workflows/tests.yml)\n[![arXiv](https://img.shields.io/badge/arXiv-2511.06804-b31b1b.svg)](https://arxiv.org/abs/2511.06804)\n[![Docs](https://readthedocs.org/projects/agentsumo/badge/?version=latest)](https://agentsumo.readthedocs.io/en/latest/?badge=latest)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-agentsumo--mcp-purple.svg)](https://registry.modelcontextprotocol.io/v0/servers?search=agentsumo)\n\n<img src=\"assets/hero_overview.png\" alt=\"AgentSUMO overview\" width=\"850\"/>\n\n**[Documentation](https://agentsumo.readthedocs.io)** ·\n[Installation](#installation) ·\n[Tools](https://agentsumo.readthedocs.io/en/latest/mcp_servers/agentsumo/index.html) ·\n[Schema](https://agentsumo.readthedocs.io/en/latest/database/index.html) ·\n[Tutorials](https://agentsumo.readthedocs.io/en/latest/tutorials/index.html)\n\n</div>\n\n---\n\n## Overview\n\n**AgentSUMO** lets non-expert stakeholders design, execute, and analyze [SUMO](https://eclipse.dev/sumo/) traffic simulations through natural-language interaction. The Planner Agent translates abstract policy questions into executable simulation plans, drives them via the Model Context Protocol (MCP), and surfaces results through a web dashboard.\n\n- **Conversational scenario design** — describe a policy question, get a runnable simulation\n- **Policy experiments** — road closures, lane reductions, signal optimization, demand changes\n- **Cross-scenario analysis** — SQL-based comparison across runs, with auto-generated HTML reports\n- **Web dashboard** — geospatial visualization, time-series charts, and trip replay\n\n## Demo\n\n<div align=\"center\">\n\n<img src=\"assets/demo_web_interface.png\" alt=\"Web interface\" width=\"800\"/>\n\n*Web interface: conversational planning panel, scenario list, and live simulation status.*\n\n<br/><br/>\n\n<img src=\"assets/demo_geospatial.png\" alt=\"Geospatial visualization\" width=\"800\"/>\n\n*Geospatial visualization: per-edge metrics, congestion overlays, and trip replay on the 2.5D basemap.*\n\n</div>\n\n## Architecture\n\n```\nUser (natural language)\n    |\n    v\nPlanner Agent (Claude LLM, Interactive Planning Protocol)\n    |\n    +--> AgentSUMO MCP Client --> AgentSUMO MCP Server (PyPI: agentsumo-mcp) --> SUMO\n    |\n    +--> SQLite MCP Client    --> SQLite MCP Server (Anthropic, open source)  --> simulations.db\n    |\n    +--> Filesystem MCP Client --> Filesystem MCP Server (Anthropic, open source) --> additional XML files\n```\n\nThe reasoning layer (Planner Agent) lives in this repository. The execution layer (`agentsumo-mcp`) is published to PyPI and installed automatically as a dependency.\n\n## Tool Layer\n\nThe AgentSUMO MCP Server exposes **26 tools** grouped into five capability categories that follow the simulation workflow. Full reference at [agentsumo.readthedocs.io/.../tools](https://agentsumo.readthedocs.io/en/latest/mcp_servers/agentsumo/index.html).\n\n| Category | Purpose | Representative tools |\n|---|---|---|\n| **Scenario Generation** | Build a baseline SUMO simulation: OSM → network → trips → routes → run | `osm_extract`, `net_convert`, `trip_generate`, `route_generate`, `sumo_runner` |\n| **Policy Experimentation** | Apply infrastructure, demand, and signal-control interventions | `edge_edit_tool`, `reduce_lanes_tool`, `vehicle_generation_tool`, `flow_generation_tool`, `tls_offset_tool`, `tls_adaptation_tool` |\n| **Result Analysis** | Convert SUMO XML output to SQLite and render HTML reports | `xml_to_sqlite_tool`, `simulation_report_tool` |\n| **Visualization** | Render networks, highlighted edges, and per-edge metric heatmaps | `visualize_net_tool`, `visualize_edge_tool`, `visualize_policy_target_tool`, `visualize_edgedata_tool` |\n| **Utility Functions** | Network statistics, routing, road-name ↔ edge-id resolution, OD-coordinate validation, web-search grounding | `network_summary_tool`, `route_analysis_tool`, `validate_od_coordinates_tool`, `web_search_tool` |\n\n## Installation\n\n### Requirements\n\n- Python 3.10 or later\n- [SUMO](https://eclipse.dev/sumo/) 1.24 or later (locally installed, with `SUMO_HOME` set)\n- Anthropic Claude API key (bring-your-own-key)\n- Mapbox access token (used by the web map renderer)\n\n### 1. Install SUMO\n\n**macOS**\n```bash\nbrew install sumo\n```\nOr download the installer from the [Eclipse SUMO downloads page](https://sumo.dlr.de/docs/Downloads.php).\n\n**Windows** — Download the installer from the [Eclipse SUMO downloads page](https://sumo.dlr.de/docs/Downloads.php).\n\n**Linux (Ubuntu/Debian)**\n```bash\nsudo add-apt-repository ppa:sumo/stable\nsudo apt-get update\nsudo apt-get install sumo sumo-tools sumo-doc\n```\n\n### 2. Set up the Python environment\n\nInstall [`uv`](https://docs.astral.sh/uv/):\n```bash\n# macOS / Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Windows (PowerShell)\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\nClone the repository, create a virtual environment, and install AgentSUMO:\n```bash\ngit clone https://github.com/mw-jeong/AgentSUMO\ncd AgentSUMO\n\n# Create a Python 3.12 venv\nuv venv --python 3.12\n\n# Activate the venv\nsource .venv/bin/activate              # macOS / Linux\n# .venv\\Scripts\\activate               # Windows\n\n# Install AgentSUMO and all dependencies\n# (this also pulls agentsumo-mcp from PyPI as a dependency)\nuv pip install -e .\n```\n\n### 3. Configure environment variables\n\nAgentSUMO reads API keys and the SUMO path from environment variables. The easiest way is a `.env` file at the project root:\n```bash\ncp .env.example .env\n```\n\nOpen `.env` in your editor and fill in:\n\n**`ANTHROPIC_API_KEY`** (required) — Claude API key that drives the Planner Agent. Get one at the [Anthropic Console](https://console.anthropic.com/settings/keys).\n```\nANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n```\n\n**`MAPBOX_TOKEN`** (required for the web UI) — used to render the basemap. Get one at the [Mapbox access tokens page](https://account.mapbox.com/access-tokens/).\n```\nMAPBOX_TOKEN=pk.eyJ1Ijoixxxxxxxxxxxxxxxxxx\n```\n\n**`SUMO_HOME`** (required) — absolute path to your local SUMO installation. The directory must contain `bin/sumo` (or `bin/sumo.exe` on Windows).\n```\n# macOS (Homebrew)\nSUMO_HOME=/opt/homebrew/share/sumo\n\n# macOS (Eclipse SUMO installer)\nSUMO_HOME=/Library/Frameworks/EclipseSUMO.framework/Versions/<version>/EclipseSUMO  # e.g. 1.24.0; use the directory name installed under Versions/\n\n# Windows\nSUMO_HOME=C:\\Program Files (x86)\\Eclipse\\Sumo\n\n# Linux\nSUMO_HOME=/usr/share/sumo\n```\n\n**`AGENTSUMO_MCP_OUTPUT_BASE`** (optional) — override the base directory where the MCP server writes simulation outputs (networks, trips, results). Defaults to the current working directory.\n```\nAGENTSUMO_MCP_OUTPUT_BASE=/path/to/your/output/dir\n```\n\n### 4. Run\n\n```bash\n# Web interface (opens at http://localhost:8000)\npython web.py\n\n# CLI mode\npython chat.py\n\n# Clean up simulation outputs\npython clean.py\n```\n\n## Project Structure\n\n```\nAgentSUMO/\n├── agentsumo/\n│   ├── agent/        # Planner Agent (Claude orchestrator + prompts)\n│   ├── client/       # MCP clients (AgentSUMO, SQLite, Filesystem)\n│   └── core/         # Configuration\n├── agentsumo_mcp/    # AgentSUMO MCP Server source (also published to PyPI)\n│   └── defaults/     # Packaged fixtures (e.g., vehicle_types.add.xml)\n├── packaging/mcp/    # PyPI build configuration for agentsumo-mcp\n├── web/              # Web interface (FastAPI + Jinja2 templates)\n├── docs/             # Sphinx documentation source\n├── tests/            # Unit tests\n├── assets/           # README images\n├── output/           # Runtime artifacts (auto-populated; 8 categories tracked\n│                     #   via .gitkeep — simulations/, networks/, trips/,\n│                     #   analysis/, reports/, uploads/, visualizations/, additional/)\n├── chat.py           # CLI entry point\n├── web.py            # Web server entry point\n└── .env.example      # Environment variable template\n```\n\n## Use the MCP Server Standalone\n\nThe AgentSUMO MCP Server can be used independently from this framework with any MCP-compatible LLM client (Claude Desktop, OpenAI tool clients, Gemini, local LLMs):\n\n```bash\npip install agentsumo-mcp\n```\n\nOr via [`uvx`](https://docs.astral.sh/uv/guides/tools/) without installing:\n\n```bash\nuvx agentsumo-mcp\n```\n\nThe server is registered in the official [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=agentsumo) under `io.github.mw-jeong/agentsumo-mcp`.\n\n## Troubleshooting\n\n**SUMO path error** — Verify `SUMO_HOME` in your `.env`. The directory must contain `bin/sumo` (or `bin/sumo.exe` on Windows).\n\n**API key error** — Verify `ANTHROPIC_API_KEY` in your `.env` is set to a valid Claude API key. The Planner Agent will refuse to start without it.\n\n**Dependency error** — Re-resolve dependencies:\n```bash\nuv pip install -e . --upgrade\n```\n\n**Legacy token files (deprecated, scheduled for removal in 0.2.0)** — AgentSUMO still falls back to `claude_api.txt` and `mapbox_token.txt` at the project root when the corresponding environment variables are missing, but those code paths now emit a `DeprecationWarning` at import time. Use the `.env` workflow for new installations.\n\n## Documentation\n\nFull documentation lives at **[agentsumo.readthedocs.io](https://agentsumo.readthedocs.io)**.\n\n- [Installation](https://agentsumo.readthedocs.io/en/latest/installation.html) — SUMO, Python 3.10+, environment setup\n- [Tools](https://agentsumo.readthedocs.io/en/latest/mcp_servers/agentsumo/index.html) — reference for all MCP tools\n- [Schema](https://agentsumo.readthedocs.io/en/latest/database/index.html) — `simulations.db` ER diagram and column reference\n- [Tutorials](https://agentsumo.readthedocs.io/en/latest/tutorials/index.html) — walkthroughs of the paper case studies\n\n## Citation\n\nIf you use AgentSUMO in academic work, please cite:\n\n```bibtex\n@article{jeong2025agentsumo,\n  title         = {AgentSUMO: An Agentic Framework for Interactive Simulation Scenario Generation in SUMO via Large Language Models},\n  author        = {Jeong, Minwoo and Chang, Jeeyun and Yoon, Yoonjin},\n  journal       = {arXiv preprint arXiv:2511.06804},\n  year          = {2025},\n  url           = {https://arxiv.org/abs/2511.06804}\n}\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n---\n\n<div align=\"center\">\n\n<sub>Developed at</sub>\n\n<img src=\"assets/logo_kaist.png\" alt=\"KAIST\" height=\"55\"/> &nbsp;&nbsp;&nbsp;&nbsp;\n<img src=\"assets/logo_caus.png\" alt=\"CAUS\" height=\"55\"/> &nbsp;&nbsp;&nbsp;&nbsp;\n<img src=\"assets/logo_stil.png\" alt=\"Spatial Tech Innovation Lab\" height=\"55\"/>\n\n</div>\n",
  "bytes": 11053,
  "sha": "05d385d6069bf93d9159ad5e66a5eac04249b5498c9e18e6ba5ff9813138a9dd",
  "repo_slug": "mw-jeong/agentsumo",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mw_jeong_agentsumo_mcp_de1d6c9d/readme"
}