Merge pull request #2 from Razee4315/feat/comses

feat: CoMSES Net integration (5 tools + 1 prompt)

Author: Razee4315

.gitignore

@@ -43,3 +43,9 @@ exports/worlds/*.csv
 
 # Auto-created models (from create_model tool)
 models/_created_*.nlogox
+
+# Claude Code session scratch (worktrees, session state)
+.claude/
+
+# COMSES download cache — live data, not source
+models/comses/

CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added — CoMSES Net integration
+
+- 5 new tools for exploring the CoMSES Net computational model library:
+  `search_comses`, `get_comses_model`, `download_comses_model`,
+  `open_comses_model`, `read_comses_files`.
+- 1 new prompt: `explore_comses` — NetLogo-first, source-introspection,
+  never fabricates commands, stops-and-asks on runtime errors.
+- Safe download pipeline: HEAD screen + mid-stream byte cap
+  (`COMSES_MAX_DOWNLOAD_MB`, default 50), zip-member path-traversal
+  validation, zip-bomb guard, atomic temp-to-final extract with
+  `.comses_complete` marker, race reconciliation.
+- `"latest"` version resolution with snapshot semantics — resolved to
+  a concrete version before any cache path is computed; the resolved
+  version is returned so follow-up reads stay pinned.
+- `read_comses_files` returns a precise contract with per-file
+  `{content, full_size, returned_size, truncated}`, priority ordering
+  (ODD → NetLogo → other code → md/txt), byte cap with line-boundary
+  truncation, UTF-8 decoding with `errors="replace"`, zero-match case
+  handled explicitly.
+- `httpx>=0.27` dependency.
+- 44 new tests covering retry matrix, zip-slip, zip-bomb, marker,
+  race-orphan, NetLogo-file selection rule, ODD discovery, cache
+  reuse, latest resolution, truncation, extension filters, prompt rules.
+
 ## [0.1.0] - 2025-02-23
 
 ### Added

README.md

@@ -59,8 +59,27 @@ By default, a real NetLogo window opens so you can watch your simulations run li
 | `save_model(name, code)` | Save model to file |
 | `export_world()` | Export full world state to CSV |
 | `list_models()` | List model files in models directory |
+| `search_comses(query)` | Search the CoMSES Net model library |
+| `get_comses_model(uuid)` | Fetch metadata + citation text for one COMSES model |
+| `download_comses_model(uuid)` | Safely download + extract a COMSES archive |
+| `open_comses_model(uuid)` | Download (or reuse cache) and load NetLogo models |
+| `read_comses_files(uuid)` | Read ODD / source contents from a downloaded model |
 
-Plus 3 resources (primitives reference, programming guide, model source) and 3 prompts (`analyze_model`, `create_abm`, `parameter_sweep`).
+Plus 3 resources (primitives reference, programming guide, model source) and 4 prompts (`analyze_model`, `create_abm`, `parameter_sweep`, `explore_comses`).
+
+### CoMSES Net integration
+
+NetLogo MCP can search and safely fetch any model from the [CoMSES Net computational model library](https://www.comses.net/) — the largest peer-reviewed ABM repository. NetLogo models load automatically; Python / R / Julia models are identified and cached locally so you can inspect their source and ODD documentation from any MCP client, including clients with no filesystem tools.
+
+Try it with the `explore_comses` prompt or just ask: *"Find me a predator-prey ABM on COMSES and run a short baseline."*
+
+Safety properties (applied to every download):
+- Archives streamed with a hard byte cap (`COMSES_MAX_DOWNLOAD_MB`, default 50 MB) enforced mid-stream, not just via HEAD.
+- Every zip member is path-traversal-validated before extraction.
+- Zip-bomb refusal on uncompressed-size overflow.
+- Extraction is atomic: downloads land in a temp dir first, then move to the cache only on success.
+- Cache directories are trusted only when they carry the `.comses_complete` marker.
+- `"latest"` is resolved to a concrete version before any cache path is computed; the resolved version is returned to the AI so follow-up reads stay pinned to the same slot.
 
 ## Prerequisites
 
@@ -163,6 +182,7 @@ JAVA_HOME=C:/Program Files/Eclipse Adoptium/jdk-25.0.2.10-hotspot
 | `NETLOGO_MODELS_DIR` | No | Directory for model files (defaults to `./models`) |
 | `NETLOGO_GUI` | No | `"true"` (default) for live GUI window, `"false"` for headless |
 | `NETLOGO_EXPORTS_DIR` | No | Directory for exported views/worlds (defaults to `./exports`) |
+| `COMSES_MAX_DOWNLOAD_MB` | No | Max CoMSES archive size in MB (default 50). Enforced mid-stream. |
 
 ## Client Setup
 

docs/DEVELOPMENT.md

@@ -16,9 +16,10 @@ NetLogo_MCP/
 ├── src/
 │   └── netlogo_mcp/
 │       ├── server.py           # FastMCP app, stdout protection, lifespan
-│       ├── tools.py            # All 12 tools
+│       ├── tools.py            # All 17 tools (12 NetLogo + 5 CoMSES)
+│       ├── comses.py           # CoMSES Net API client + safe zip extract
 │       ├── resources.py        # 3 resources (docs + model source)
-│       ├── prompts.py          # 3 prompts (analyze, create, sweep)
+│       ├── prompts.py          # 4 prompts (analyze, create, sweep, explore_comses)
 │       ├── config.py           # Environment variable loading
 │       ├── py.typed            # PEP 561 type marker
 │       └── data/
@@ -30,7 +31,9 @@ NetLogo_MCP/
     ├── conftest.py             # Mock fixtures (no JVM needed)
     ├── test_server.py
     ├── test_tools.py
-    └── test_resources.py
+    ├── test_comses.py          # CoMSES integration: API, zip safety, tools, prompt
+    ├── test_resources.py
+    └── fixtures/comses/        # Captured JSON fixtures for CoMSES tests
 ```
 
 ## Tech Stack

pyproject.toml

@@ -16,6 +16,7 @@ dependencies = [
     "pandas",
     "numpy",
     "python-dotenv",
+    "httpx>=0.27",
 ]
 
 [project.optional-dependencies]