webots-mcp-kit 0.8.0__tar.gz

webots_mcp_kit-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arda Karakaş
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

webots_mcp_kit-0.8.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: webots-mcp-kit
+Version: 0.8.0
+Summary: Windows-first Webots developer toolkit with CLI, MCP server, controller SDK, and bundled benchmarks.
+Author: Arda Karakas
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/RdaKA12/webots-mcp-kit
+Project-URL: Issues, https://github.com/RdaKA12/webots-mcp-kit/issues
+Project-URL: Documentation, https://github.com/RdaKA12/webots-mcp-kit/tree/main/docs
+Project-URL: Repository, https://github.com/RdaKA12/webots-mcp-kit
+Project-URL: Changelog, https://github.com/RdaKA12/webots-mcp-kit/blob/main/CHANGELOG.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.12.4
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: twine>=6.1.0; extra == "dev"
+Dynamic: license-file
+
+# webots-mcp-kit
+
+`webots-mcp-kit` is a Windows-first developer toolkit for connecting LLM agents to Webots.
+
+It combines:
+
+- a pip-installable CLI
+- an MCP server with Webots session tools
+- a controller-side SDK for structured telemetry and manual overrides
+- bundled example scenarios and benchmarks
+
+The bundled line follower is not the product itself. It is the first reference example.
+The toolkit is meant to be reusable across other Webots robots, controllers, and worlds.
+
+## Current release
+
+`v0.8.0`
+
+Current focus:
+
+- Windows-first local development
+- Webots `R2025a`
+- direct Webots integration without ROS2
+- stable controller-side integration through `ControllerAgent`
+- bundled scenarios plus registry-backed benchmark thresholds
+- hosted-safe CI with separate self-hosted runtime smoke
+- release pipeline for GitHub Release, TestPyPI, and PyPI
+
+## Bundled scenarios
+
+- `line-follower`
+  - camera-based line tracking
+  - example world: `examples/line-follower`
+- `obstacle-avoidance`
+  - proximity-sensor obstacle avoidance
+  - example world: `examples/obstacle-avoidance`
+- `waypoint-nav`
+  - fixed-waypoint navigation in an open arena
+  - example world: `examples/waypoint-nav`
+
+## Install
+
+Use an isolated virtual environment. The toolkit depends on `mcp`, which may pull shared web stack packages into your global Python install.
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -e .[dev]
+```
+
+Planned package install path:
+
+```powershell
+pip install webots-mcp-kit
+```
+
+Optional CI or slow-machine tuning:
+
+```powershell
+$env:WEBOTS_KIT_SESSION_START_TIMEOUT='90'
+```
+
+## Quick start
+
+```powershell
+webots-kit doctor
+webots-kit benchmark list
+webots-kit benchmark run line-follower --controller example --output .\report.json --duration-s 3
+webots-kit benchmark report .\report.json
+```
+
+For an interactive session:
+
+```powershell
+webots-kit session start --scenario line-follower --controller example --mode fast --render off
+webots-kit session inspect --session <session-id>
+webots-kit session logs --session <session-id>
+webots-kit session stop --session <session-id>
+```
+
+For a custom controller scaffold:
+
+```powershell
+webots-kit controller scaffold .\controllers\my_agent.py --scenario line-follower
+webots-kit controller validate .\controllers\my_agent.py --scenario line-follower --strict --json
+```
+
+To expose the toolkit as an MCP server:
+
+```powershell
+webots-kit mcp serve
+```
+
+## CLI surface
+
+- `webots-kit doctor [--json]`
+- `webots-kit session start --scenario <name> --world <path> --controller <path-or-id> [--robot-name <name>] [--robot-def <def>] [--mode fast|realtime|pause] [--render on|off]`
+- `webots-kit session inspect --session <id>`
+- `webots-kit session logs --session <id> [--name <file>] [--tail <n>]`
+- `webots-kit session stop --session <id>`
+- `webots-kit benchmark list`
+- `webots-kit benchmark run <scenario> --controller <path-or-id> --output <report.json> [--duration-s <seconds>]`
+- `webots-kit benchmark report <report.json>`
+- `webots-kit controller validate <path> [--scenario <name>] [--strict] [--json]`
+- `webots-kit controller scaffold <path> [--scenario <name>] [--force]`
+- `webots-kit mcp serve`
+
+## Controller integration
+
+There are two supported usage paths:
+
+- bundled example controllers under `examples/`
+- user-supplied Python controllers that integrate with `ControllerAgent`
+
+The public controller-side entrypoint is `ControllerAgent`.
+The stable public contract is:
+
+- `ControllerAgent.from_robot(...)`
+- `begin_step()`
+- `report_step(...)`
+
+Minimal integration shape:
+
+```python
+from controller import Robot
+from webots_mcp_kit.agent import ControllerAgent
+
+robot = Robot()
+agent = ControllerAgent.from_robot(robot, default_camera="camera")
+
+while robot.step(int(robot.getBasicTimeStep())) != -1:
+    override = agent.begin_step()
+    # apply your control logic, optionally overriding wheel commands
+    agent.report_step(
+        sensors={},
+        metrics={},
+        actuators={},
+        camera_frames=None,
+    )
+```
+
+Use `webots-kit controller validate <path>` to check whether a controller follows the expected integration pattern.
+Use `webots-kit controller scaffold` when you want a working starter file based on a bundled scenario.
+
+## MCP tools
+
+- `webots_session_start`
+- `webots_session_stop`
+- `webots_list_robots`
+- `webots_list_devices`
+- `webots_get_state`
+- `webots_get_sensors`
+- `webots_capture_camera`
+- `webots_set_motor_velocity`
+- `webots_step`
+- `webots_pause_resume`
+- `webots_reset`
+- `webots_run_benchmark`
+
+Stable payload shapes:
+
+- `webots_list_devices -> { robot, scenario, devices }`
+- `webots_get_sensors -> { robot, scenario, state, sensors, metrics, actuators, meta }`
+
+Reference docs:
+
+- [MCP contracts](./docs/mcp-contracts.md)
+- [Self-hosted runtime smoke](./docs/self-hosted-windows-runner.md)
+- [Custom controller integration](./docs/custom-controller-integration.md)
+- [Add a new scenario](./docs/new-scenario-guide.md)
+- [Failed runtime smoke triage](./docs/failed-runtime-smoke-triage.md)
+- [PyPI install and upgrade](./docs/pypi-install-and-upgrade.md)
+- [Release checklist](./docs/release-checklist.md)
+- [Runner maintenance](./docs/self-hosted-runner-maintenance.md)
+- [Packaging verification](./docs/packaging-verification-checklist.md)
+
+## Testing
+
+Unit tests:
+
+```powershell
+python -m pytest -q
+```
+
+Hosted-safe smoke tests:
+
+```powershell
+$env:WEBOTS_KIT_RUN_SMOKE='1'
+python -m pytest -q -k mcp_tool_list_smoke
+```
+
+Full runtime smoke tests with real Webots execution:
+
+```powershell
+$env:WEBOTS_KIT_RUN_RUNTIME_SMOKE='1'
+python -m pytest -q -k "session_start_inspect_stop_smoke or benchmark_smoke"
+```
+
+The self-hosted GitHub workflow for runtime smoke expects a Windows runner labeled `webots`.
+Packaging and release verification are handled by GitHub workflows:
+
+- `Packaging CI`
+- `Release`
+
+## Troubleshooting
+
+- If `doctor` fails, ensure `WEBOTS_HOME` is set or Webots is installed in `C:\Program Files\Webots`.
+- If MCP or session startup closes immediately, inspect `session logs` for the session artifacts.
+- If package installation changes global Python web dependencies, recreate a dedicated virtual environment and reinstall there.
+- GitHub-hosted `windows-latest` runners are only used for unit tests, `doctor`, and MCP handshake smoke. Real Webots runtime smoke is exposed as a separate manual workflow for self-hosted Windows runners with Webots installed.
+- `examples/` contains runnable demo assets; benchmark thresholds and pass/fail logic live in the benchmark registry inside the toolkit code.
+- Wheel installs use bundled package-local scenario assets; source checkouts continue to use repo-local `examples/`.

webots_mcp_kit-0.8.0/README.md

@@ -0,0 +1,212 @@
+# webots-mcp-kit
+
+`webots-mcp-kit` is a Windows-first developer toolkit for connecting LLM agents to Webots.
+
+It combines:
+
+- a pip-installable CLI
+- an MCP server with Webots session tools
+- a controller-side SDK for structured telemetry and manual overrides
+- bundled example scenarios and benchmarks
+
+The bundled line follower is not the product itself. It is the first reference example.
+The toolkit is meant to be reusable across other Webots robots, controllers, and worlds.
+
+## Current release
+
+`v0.8.0`
+
+Current focus:
+
+- Windows-first local development
+- Webots `R2025a`
+- direct Webots integration without ROS2
+- stable controller-side integration through `ControllerAgent`
+- bundled scenarios plus registry-backed benchmark thresholds
+- hosted-safe CI with separate self-hosted runtime smoke
+- release pipeline for GitHub Release, TestPyPI, and PyPI
+
+## Bundled scenarios
+
+- `line-follower`
+  - camera-based line tracking
+  - example world: `examples/line-follower`
+- `obstacle-avoidance`
+  - proximity-sensor obstacle avoidance
+  - example world: `examples/obstacle-avoidance`
+- `waypoint-nav`
+  - fixed-waypoint navigation in an open arena
+  - example world: `examples/waypoint-nav`
+
+## Install
+
+Use an isolated virtual environment. The toolkit depends on `mcp`, which may pull shared web stack packages into your global Python install.
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -e .[dev]
+```
+
+Planned package install path:
+
+```powershell
+pip install webots-mcp-kit
+```
+
+Optional CI or slow-machine tuning:
+
+```powershell
+$env:WEBOTS_KIT_SESSION_START_TIMEOUT='90'
+```
+
+## Quick start
+
+```powershell
+webots-kit doctor
+webots-kit benchmark list
+webots-kit benchmark run line-follower --controller example --output .\report.json --duration-s 3
+webots-kit benchmark report .\report.json
+```
+
+For an interactive session:
+
+```powershell
+webots-kit session start --scenario line-follower --controller example --mode fast --render off
+webots-kit session inspect --session <session-id>
+webots-kit session logs --session <session-id>
+webots-kit session stop --session <session-id>
+```
+
+For a custom controller scaffold:
+
+```powershell
+webots-kit controller scaffold .\controllers\my_agent.py --scenario line-follower
+webots-kit controller validate .\controllers\my_agent.py --scenario line-follower --strict --json
+```
+
+To expose the toolkit as an MCP server:
+
+```powershell
+webots-kit mcp serve
+```
+
+## CLI surface
+
+- `webots-kit doctor [--json]`
+- `webots-kit session start --scenario <name> --world <path> --controller <path-or-id> [--robot-name <name>] [--robot-def <def>] [--mode fast|realtime|pause] [--render on|off]`
+- `webots-kit session inspect --session <id>`
+- `webots-kit session logs --session <id> [--name <file>] [--tail <n>]`
+- `webots-kit session stop --session <id>`
+- `webots-kit benchmark list`
+- `webots-kit benchmark run <scenario> --controller <path-or-id> --output <report.json> [--duration-s <seconds>]`
+- `webots-kit benchmark report <report.json>`
+- `webots-kit controller validate <path> [--scenario <name>] [--strict] [--json]`
+- `webots-kit controller scaffold <path> [--scenario <name>] [--force]`
+- `webots-kit mcp serve`
+
+## Controller integration
+
+There are two supported usage paths:
+
+- bundled example controllers under `examples/`
+- user-supplied Python controllers that integrate with `ControllerAgent`
+
+The public controller-side entrypoint is `ControllerAgent`.
+The stable public contract is:
+
+- `ControllerAgent.from_robot(...)`
+- `begin_step()`
+- `report_step(...)`
+
+Minimal integration shape:
+
+```python
+from controller import Robot
+from webots_mcp_kit.agent import ControllerAgent
+
+robot = Robot()
+agent = ControllerAgent.from_robot(robot, default_camera="camera")
+
+while robot.step(int(robot.getBasicTimeStep())) != -1:
+    override = agent.begin_step()
+    # apply your control logic, optionally overriding wheel commands
+    agent.report_step(
+        sensors={},
+        metrics={},
+        actuators={},
+        camera_frames=None,
+    )
+```
+
+Use `webots-kit controller validate <path>` to check whether a controller follows the expected integration pattern.
+Use `webots-kit controller scaffold` when you want a working starter file based on a bundled scenario.
+
+## MCP tools
+
+- `webots_session_start`
+- `webots_session_stop`
+- `webots_list_robots`
+- `webots_list_devices`
+- `webots_get_state`
+- `webots_get_sensors`
+- `webots_capture_camera`
+- `webots_set_motor_velocity`
+- `webots_step`
+- `webots_pause_resume`
+- `webots_reset`
+- `webots_run_benchmark`
+
+Stable payload shapes:
+
+- `webots_list_devices -> { robot, scenario, devices }`
+- `webots_get_sensors -> { robot, scenario, state, sensors, metrics, actuators, meta }`
+
+Reference docs:
+
+- [MCP contracts](./docs/mcp-contracts.md)
+- [Self-hosted runtime smoke](./docs/self-hosted-windows-runner.md)
+- [Custom controller integration](./docs/custom-controller-integration.md)
+- [Add a new scenario](./docs/new-scenario-guide.md)
+- [Failed runtime smoke triage](./docs/failed-runtime-smoke-triage.md)
+- [PyPI install and upgrade](./docs/pypi-install-and-upgrade.md)
+- [Release checklist](./docs/release-checklist.md)
+- [Runner maintenance](./docs/self-hosted-runner-maintenance.md)
+- [Packaging verification](./docs/packaging-verification-checklist.md)
+
+## Testing
+
+Unit tests:
+
+```powershell
+python -m pytest -q
+```
+
+Hosted-safe smoke tests:
+
+```powershell
+$env:WEBOTS_KIT_RUN_SMOKE='1'
+python -m pytest -q -k mcp_tool_list_smoke
+```
+
+Full runtime smoke tests with real Webots execution:
+
+```powershell
+$env:WEBOTS_KIT_RUN_RUNTIME_SMOKE='1'
+python -m pytest -q -k "session_start_inspect_stop_smoke or benchmark_smoke"
+```
+
+The self-hosted GitHub workflow for runtime smoke expects a Windows runner labeled `webots`.
+Packaging and release verification are handled by GitHub workflows:
+
+- `Packaging CI`
+- `Release`
+
+## Troubleshooting
+
+- If `doctor` fails, ensure `WEBOTS_HOME` is set or Webots is installed in `C:\Program Files\Webots`.
+- If MCP or session startup closes immediately, inspect `session logs` for the session artifacts.
+- If package installation changes global Python web dependencies, recreate a dedicated virtual environment and reinstall there.
+- GitHub-hosted `windows-latest` runners are only used for unit tests, `doctor`, and MCP handshake smoke. Real Webots runtime smoke is exposed as a separate manual workflow for self-hosted Windows runners with Webots installed.
+- `examples/` contains runnable demo assets; benchmark thresholds and pass/fail logic live in the benchmark registry inside the toolkit code.
+- Wheel installs use bundled package-local scenario assets; source checkouts continue to use repo-local `examples/`.

webots_mcp_kit-0.8.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "webots-mcp-kit"
+version = "0.8.0"
+description = "Windows-first Webots developer toolkit with CLI, MCP server, controller SDK, and bundled benchmarks."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+  { name = "Arda Karakas" }
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: Microsoft :: Windows",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "mcp>=1.12.4,<2",
+]
+
+[project.urls]
+Homepage = "https://github.com/RdaKA12/webots-mcp-kit"
+Issues = "https://github.com/RdaKA12/webots-mcp-kit/issues"
+Documentation = "https://github.com/RdaKA12/webots-mcp-kit/tree/main/docs"
+Repository = "https://github.com/RdaKA12/webots-mcp-kit"
+Changelog = "https://github.com/RdaKA12/webots-mcp-kit/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "pytest>=8.0.0",
+  "twine>=6.1.0",
+]
+
+[project.scripts]
+webots-kit = "webots_mcp_kit.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+webots_mcp_kit = [
+  "examples/**/*.py",
+  "examples/**/*.wbt",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

webots_mcp_kit-0.8.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

webots_mcp_kit-0.8.0/src/webots_mcp_kit/__init__.py

@@ -0,0 +1,5 @@
+"""webots-mcp-kit package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.8.0"