netlogo-mcp 1.0.0__tar.gz

netlogo_mcp-1.0.0/.env.example

@@ -0,0 +1,13 @@
+# Path to your NetLogo installation
+NETLOGO_HOME=C:/Program Files/NetLogo 7.0.3
+
+# Path to your Java JDK installation
+JAVA_HOME=C:/Program Files/Eclipse Adoptium/jdk-25.0.2.10-hotspot
+
+# (Optional) Directory where .nlogo model files are stored
+# Defaults to the current working directory's models/ folder
+# NETLOGO_MODELS_DIR=C:/Users/you/your-project/models
+
+# (Optional) NETLOGO_GUI controls whether a live NetLogo window opens.
+# Default is "true" (live GUI). Set to "false" for headless mode — faster, no window.
+# NETLOGO_GUI=false

netlogo_mcp-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,64 @@
+name: Bug report
+description: Something isn't working
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, and what happened instead?
+      placeholder: |
+        I asked Claude to "create a predator-prey model" and got...
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: How to reproduce
+      description: The prompt you gave your AI assistant, or the tool call that failed.
+      placeholder: |
+        1. Connect the server in Claude Code
+        2. Ask: "..."
+        3. Error: ...
+    validations:
+      required: true
+
+  - type: input
+    id: mcp-client
+    attributes:
+      label: MCP client
+      placeholder: e.g. Claude Code, Claude Desktop, Cursor, Cline
+    validations:
+      required: true
+
+  - type: input
+    id: netlogo-version
+    attributes:
+      label: NetLogo version
+      placeholder: e.g. 7.0.3
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: e.g. Windows 11, macOS 15, Ubuntu 24.04
+    validations:
+      required: true
+
+  - type: input
+    id: versions
+    attributes:
+      label: Python and Java versions
+      placeholder: e.g. Python 3.12, Temurin JDK 21
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Server output / logs
+      description: |
+        Run `netlogo-mcp` manually in a terminal to capture error output, or check
+        your MCP client's logs. Paste anything relevant here.
+      render: shell

netlogo_mcp-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question / setup help
+    url: https://github.com/Razee4315/NetLogo-MCP/discussions
+    about: Ask setup questions or share what you built — no bug report needed.

netlogo_mcp-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Suggest a new tool, resource, or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What are you trying to do?
+      description: Describe the modeling/analysis task you want your AI assistant to handle.
+      placeholder: |
+        I want to ask Claude to "..." but there's no tool for...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What should the server do? A new tool, a new parameter, a new resource?
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Workarounds you've tried
+      description: e.g. raw `command`/`report` calls, manual NetLogo steps

netlogo_mcp-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+# What does this PR do?
+
+<!-- One or two sentences. Link the issue if there is one: Fixes #123 -->
+
+## Checklist
+
+- [ ] Tests pass locally (`pytest tests/`)
+- [ ] Lint passes (`pre-commit run --all-files` and `mypy src/netlogo_mcp/`)
+- [ ] Added/updated tests for the change
+- [ ] Updated `CHANGELOG.md` under `[Unreleased]`
+- [ ] Updated docs (`docs/TOOLS.md`, `docs/CONFIGURATION.md`, README) if behavior changed

netlogo_mcp-1.0.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      python-deps:
+        patterns: ["*"]

netlogo_mcp-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main, gui]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Pre-commit hooks (Ruff lint + format)
+        run: pre-commit run --all-files --show-diff-on-failure
+
+      - name: Mypy type check
+        run: mypy src/netlogo_mcp/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: pytest tests/ -v --cov=netlogo_mcp --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false

netlogo_mcp-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,97 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches package version
+        run: |
+          PKG_VERSION=$(python -c "import re; print(re.search(r'__version__ = \"(.+?)\"', open('src/netlogo_mcp/__init__.py').read()).group(1))")
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match __version__ $PKG_VERSION"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: |
+          pip install build
+          python -m build
+
+      - name: Check distribution metadata
+        run: |
+          pip install twine
+          twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/netlogo-mcp
+    permissions:
+      id-token: write # OIDC trusted publishing — no API token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Extract changelog for this version
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          # Pull the section for this version out of CHANGELOG.md
+          awk -v ver="$VERSION" '
+            $0 ~ "^## \\[" ver "\\]" { found=1; next }
+            found && /^## \[/ { exit }
+            found { print }
+          ' CHANGELOG.md > release-notes.md
+          if [ ! -s release-notes.md ]; then
+            echo "No CHANGELOG section found for $VERSION — using auto-generated notes." > release-notes.md
+          fi
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file release-notes.md

netlogo_mcp-1.0.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+*.so
+
+# Virtual environments
+.env
+.venv/
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# NetLogo temp files
+*.nlogo~
+
+# OS files
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Testing
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Exports (keep folder structure, ignore actual exports)
+exports/views/*.png
+exports/worlds/*.csv
+exports/experiments/*.csv
+exports/experiments/*.xml
+
+# 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/

netlogo_mcp-1.0.0/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "netlogo": {
+      "command": "netlogo-mcp",
+      "args": [],
+      "env": {
+        "NETLOGO_HOME": "C:/Program Files/NetLogo 7.0.3",
+        "JAVA_HOME": "C:/Program Files/Eclipse Adoptium/jdk-25.0.2.10-hotspot"
+      }
+    }
+  }
+}

netlogo_mcp-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.1
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - types-setuptools
+        args: [--config-file=pyproject.toml, src/netlogo_mcp/]
+        pass_filenames: false

netlogo_mcp-1.0.0/CHANGELOG.md

@@ -0,0 +1,220 @@
+# Changelog
+
+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]
+
+## [1.0.0] - 2026-06-06
+
+First stable release. The server is feature-complete for conversational
+agent-based modeling: 25 tools covering model creation with declarative
+widgets, simulation and data collection, BehaviorSpace parameter sweeps,
+CoMSES Net library access, and view/world export — now published on PyPI
+as [`netlogo-mcp`](https://pypi.org/project/netlogo-mcp/).
+
+### Packaging
+
+- Published to PyPI: `pip install netlogo-mcp`.
+- Package renamed `NetLogo_MCP` → `netlogo-mcp` (PyPI-normalized name);
+  version is now single-sourced from `netlogo_mcp.__version__`.
+- Added release automation: pushing a `v*` tag builds, publishes to PyPI
+  via trusted publishing, and creates a GitHub Release with these notes.
+- Added `CITATION.cff`, issue/PR templates, and Dependabot config.
+
+### Changed — lazy JVM startup
+
+- The JVM (and the NetLogo GUI window) now starts **lazily** on the first
+  tool call that needs the workspace, instead of the moment an MCP client
+  connects. Connecting Claude/Cursor/etc. no longer pops a NetLogo window
+  you didn't ask for. Startup runs on a worker thread under the workspace
+  lock, so the event loop and MCP heartbeats stay responsive during the
+  30-60s boot. Set `NETLOGO_EAGER_START=true` to restore the old
+  boot-at-launch behavior.
+- `server_info` now reports `jvm_started` so clients can check workspace
+  state without triggering a boot.
+
+### Fixed — JVM startup deadlock on Windows
+
+- The stdio transport keeps a pending blocking read on the stdin pipe from
+  a worker thread; Windows serializes operations on a synchronous pipe's
+  file object, so the JVM's std-handle probes during `CreateJavaVM` blocked
+  behind that read — JVM startup hung until the client happened to send
+  another byte. The server now hands the transport a private duplicate of
+  stdin and points fd 0 (and the Win32 `STD_INPUT_HANDLE`) at devnull, so
+  the JVM never touches the protocol pipe. This was the real reason an
+  earlier lazy-startup attempt was abandoned for eager startup.
+
+### Fixed — protocol corruption on NetLogo errors
+
+- pynetlogo `print()`s Java stack traces to stdout whenever a NetLogo
+  command/reporter/load fails — and stdout is the MCP JSON-RPC channel.
+  One compile error in generated model code could corrupt the protocol
+  stream and leave the session flaky. The server now duplicates fd 1 for
+  the transport's private use, points fd 1 at stderr (covering the JVM's
+  direct `System.out` writes, which bypass Python entirely), and parks
+  Python's `sys.stdout` on stderr for the whole serving phase.
+
+### Fixed — widget generation
+
+- `create_model` / `save_model` no longer emit Setup/Go buttons for
+  procedures that don't exist in the code — a button pointing at a missing
+  procedure made the whole model fail to load.
+- `to setup-patches` no longer falsely counts as defining `setup`.
+
+### Changed — multi-column widget layout
+
+- Declarative widgets now wrap into additional columns when they'd
+  overflow the column height, and the world view shifts right to sit
+  beside the last column — widget-heavy models no longer pile into one
+  endless strip that runs off the bottom of the window.
+
+### Added — GUI polish
+
+- The NetLogo window is retitled to the model name and brought to the
+  front whenever a model is loaded (`create_model` / `open_model` /
+  `update_model` / `open_comses_model`). Best-effort via the Swing event
+  thread; silent no-op in headless mode.
+- New `watch_simulation(ticks, delay_ms)` tool — runs `go` step-by-step
+  with a pause between steps so a human can actually watch the dynamics
+  unfold in the GUI. Capped at 120s per call; `run_simulation` remains the
+  full-speed data-collection path.
+
+### Added — plot widgets
+
+- The `widgets` schema now supports `{"type": "plot", "pens": [...]}` —
+  live population-dynamics plots in the NetLogo window, the main reason to
+  watch a GUI run. Pens take NetLogo plot code, palette color names (or raw
+  AWT ints), line/bar/point modes, and intervals; axes auto-scale.
+  Verified live: NetLogo 7.0.3 loads the generated XML and pens plot every
+  tick.
+
+### Added — update_model
+
+- New `update_model(code, widgets?)` tool: rewrites the currently loaded
+  `.nlogox` in place and reloads it. Existing widgets are preserved when
+  `widgets` is omitted, so iterating on procedures keeps the interface the
+  user already has. Ends the one-`_created_*.nlogox`-file-per-iteration
+  clutter in the models directory.
+
+### Added — declarative interface widgets
+
+- `create_model` and `save_model` accept an optional `widgets` list:
+  sliders, switches, buttons, and monitors with validated names, escaped
+  code, and automatic column layout (NetLogo 7 `.nlogox` widget schema).
+  Slider/switch widgets define their variable, so generated models can use
+  interface globals exactly like hand-built ones — and `set_parameter`
+  works against them out of the box.
+
+### Docs
+
+- README slimmed to the essentials; full tool reference moved to
+  `docs/TOOLS.md`, environment variables and GUI/headless guidance to
+  `docs/CONFIGURATION.md`, and the security model to `docs/SECURITY.md`.
+- `docs/DEVELOPMENT.md` architecture notes rewritten to match the lazy
+  startup and fd-level stdout discipline (the old notes contradicted the
+  code on threading).
+
+### Security & validation
+
+- `set_parameter` now validates the `name` argument against a NetLogo
+  identifier regex before interpolating it into a `set <name> <value>`
+  command. Closes a command-injection vector where a name like
+  `"x setup -- "` would have appended an arbitrary NetLogo command past
+  the `set`. Legitimate kebab-case + predicate names (`show-energy?`,
+  `initial-number-sheep`) are unaffected.
+- `run_simulation` rejects empty / non-string entries in `reporters`,
+  and `get_patch_data` rejects blank `attribute`s — these formerly
+  produced confusing NetLogo compile errors deep in the call.
+- 25 new tests cover the validation surface (injection-shape names,
+  blank reporters, blank attributes).
+
+### Added — workspace control & introspection
+
+- New `close_model` tool — issues `clear-all` and forgets the current
+  model path so AI clients can drop pending state without bouncing the
+  JVM (which costs 30-60s on the next startup).
+- New `server_info` tool — pure config / filesystem inspection that
+  returns server version, GUI mode, configured paths, and whether the
+  BehaviorSpace headless launcher is reachable. Useful as a pre-flight
+  check before launching long sweeps; does not require the JVM to be
+  warm.
+
+### Removed
+
+- Dead `get_or_create_netlogo` lazy-init helper in `server.py` — the
+  eager `lifespan()` startup is the only path now, and the duplicated
+  init was an attractive nuisance for future contributors.
+
+### Added — BehaviorSpace integration & NetLogo 7 transition guide
+
+- 3 new tools for running NetLogo BehaviorSpace experiments:
+  `list_experiments` (read saved experiments from `.nlogox`),
+  `preview_experiment` (show run plan without executing),
+  `run_experiment` (drive the headless launcher in a separate JVM and
+  return parsed table-CSV results).
+- Drives BehaviorSpace via the canonical `NetLogo_Console` /
+  `netlogo-headless` launcher — no dependency on the unbundled `bspace`
+  extension, works with NetLogo 6.x and 7.x.
+- Hard run cap (`max_total_runs`, default 200) and wall-clock timeout
+  (`timeout_seconds`, default 600). Partial table CSV is preserved on
+  timeout; the runner reports `timed_out` separately from `failed`.
+- New prompt: `behaviorspace_experiment` — enforces preview-before-run.
+- New resource: `netlogo://docs/transition` — focused 6→7 porting guide
+  for AI clients hitting old CoMSES models. Covers `.nlogo` →
+  `.nlogox` auto-conversion, `ifelse-value` precedence shift, `task` →
+  anonymous procedures, movie-prim → `vid` extension, bundled vs
+  non-bundled extensions in 7.0.3.
+- Tracks `current_model_path` in the lifespan context so BehaviorSpace
+  can target the model the AI most recently loaded without an extra arg.
+
+### Changed — token efficiency
+
+- `run_simulation` accepts `summary_only=True` (returns
+  min/mean/max/std/final per reporter as one row each) and `max_rows=N`
+  (evenly-spaced decimation that always keeps the final tick).
+- `get_patch_data` accepts `summary_only=True` (returns shape + numeric
+  stats + unique-count instead of the full 2D grid).
+- Defaults are unchanged; existing prompts keep working.
+
+### 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
+
+- Initial release of NetLogo MCP Server
+- 12 tools: `open_model`, `command`, `report`, `run_simulation`, `set_parameter`, `get_world_state`, `get_patch_data`, `export_view`, `create_model`, `list_models`, `save_model`, `export_world`
+- 3 resources: `netlogo://docs/primitives`, `netlogo://docs/programming`, `netlogo://models/{name}`
+- 3 prompts: `analyze_model`, `create_abm`, `parameter_sweep`
+- Headless and GUI mode support
+- Built-in NetLogo primitives reference and programming guide
+- Path traversal protection on all file operations
+- XML escaping for `.nlogox` model creation
+- Stdout protection to prevent JVM corruption of MCP stdio transport
+- Mock-based test suite (no Java/NetLogo needed to run tests)
+- Cross-platform JVM detection (Windows, Linux, macOS)

netlogo_mcp-1.0.0/CITATION.cff

@@ -0,0 +1,24 @@
+cff-version: 1.2.0
+message: "If you use NetLogo MCP in your research, please cite it as below."
+type: software
+title: "NetLogo MCP: A Model Context Protocol server for NetLogo agent-based modeling"
+abstract: >-
+  The first MCP (Model Context Protocol) server for NetLogo, enabling AI
+  assistants to create, run, and analyze agent-based models through natural
+  conversation — including declarative interface widgets, BehaviorSpace
+  parameter sweeps, and safe access to the CoMSES Net model library.
+authors:
+  - family-names: Abbas
+    given-names: Saqlain
+    email: saqlainrazee@gmail.com
+repository-code: "https://github.com/Razee4315/NetLogo-MCP"
+license: MIT
+version: 1.0.0
+date-released: 2026-06-06
+keywords:
+  - NetLogo
+  - agent-based modeling
+  - Model Context Protocol
+  - MCP
+  - simulation
+  - AI assistants

netlogo_mcp-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to NetLogo MCP
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/Razee4315/NetLogo-MCP.git
+cd NetLogo-MCP
+pip install -e ".[dev]"
+pre-commit install
+```
+
+You'll need Java JDK 11+ and NetLogo 7.0+ installed for integration testing. Unit tests use mocks and don't require either.
+
+## Running Tests
+
+```bash
+# Run tests
+pytest tests/ -v
+
+# Run tests with coverage report
+pytest tests/ -v --cov=netlogo_mcp --cov-report=term-missing
+```
+
+## Code Quality
+
+This project uses [Ruff](https://github.com/astral-sh/ruff) for linting/formatting and [mypy](https://mypy-lang.org/) for type checking. Pre-commit hooks run these automatically, or run them manually:
+
+```bash
+# Lint
+ruff check src/ tests/
+
+# Format
+ruff format src/ tests/
+
+# Type check
+mypy src/netlogo_mcp/
+```
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes
+4. Run tests and linting to make sure nothing breaks
+5. Commit with a clear message
+6. Push to your fork and open a Pull Request
+
+## Reporting Issues
+
+Open an issue on GitHub with:
+- What you expected to happen
+- What actually happened
+- Your Python, Java, and NetLogo versions
+- Any error messages or logs
+
+## Code Style
+
+- Follow existing patterns in the codebase
+- Keep functions focused and well-named
+- Add type hints to new functions
+- Add tests for new tools or resources
+- Run `ruff format` before committing