aemo-mcp 0.1.2__tar.gz

aemo_mcp-0.1.2/.github/dependabot.yml

@@ -0,0 +1,39 @@
+version: 2
+
+updates:
+  # Python dependencies (pyproject.toml + uv.lock)
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+      time: "10:00"
+      timezone: Australia/Sydney
+    open-pull-requests-limit: 5
+    groups:
+      # Group all minor + patch updates into one PR per week.
+      python-runtime-minor-patch:
+        applies-to: version-updates
+        update-types: [minor, patch]
+    labels: [dependencies]
+    commit-message:
+      prefix: deps
+      include: scope
+
+  # GitHub Actions used in workflows
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+      time: "10:00"
+      timezone: Australia/Sydney
+    open-pull-requests-limit: 3
+    groups:
+      gha-minor-patch:
+        applies-to: version-updates
+        update-types: [minor, patch]
+    labels: [dependencies, github-actions]
+    commit-message:
+      prefix: ci
+      include: scope

aemo_mcp-0.1.2/.github/workflows/codeql.yml

@@ -0,0 +1,32 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "21 6 * * 1"
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ["python"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"

aemo_mcp-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: release
+
+# Push a tag like v0.1.0 → wheel is built and published to PyPI via
+# Trusted Publishing (no API token in repo secrets). One-time setup:
+#   1. https://pypi.org/manage/project/aemo-mcp/settings/publishing/
+#   2. Add a "pending publisher":
+#        owner = Bigred97
+#        repo  = aemo-mcp
+#        workflow = release.yml
+#        environment = pypi
+#   3. Create a `pypi` environment in repo Settings → Environments
+#      (no secrets needed; the environment scopes the OIDC token).
+# Then any `git push origin vX.Y.Z` triggers this job.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/aemo-mcp/
+    permissions:
+      id-token: write     # required for Trusted Publishing OIDC
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Sanity-check the tag matches pyproject.toml
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PYPROJECT_VERSION=$(uv run python -c "import tomllib,sys; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$PYPROJECT_VERSION" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match pyproject version $PYPROJECT_VERSION"
+            exit 1
+          fi
+          echo "Releasing version $PYPROJECT_VERSION"
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

aemo_mcp-0.1.2/.github/workflows/test.yml

@@ -0,0 +1,47 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Sync dependencies
+        run: uv sync --extra dev
+      - name: Install package
+        run: uv pip install -e .
+      - name: Run unit tests
+        run: uv run pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Build wheel + sdist
+        run: uv build
+      - name: Verify wheel installs cleanly
+        run: |
+          uv run --isolated --with ./dist/*.whl python -c \
+            "import aemo_mcp.server as s; n = len(s.list_curated()); assert n >= 7, f'expected >=7 curated, got {n}'; print(f'OK ({n} curated feeds)')"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

aemo_mcp-0.1.2/.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.Python
+.venv/
+venv/
+env/
+
+build/
+dist/
+*.egg-info/
+*.egg
+
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+.DS_Store
+.idea/
+.vscode/
+
+# Local cache database
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+
+# uv lockfile pinned in repo
+# uv.lock is committed deliberately

aemo_mcp-0.1.2/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+## 0.1.2 (2026-05-15)
+
+Portfolio parity — stale-cache fallback + error-message sweep + dependabot +
+CLAUDE.md. 297 unit tests (was 288) + 10 live tests, 3× zero-flake green.
+
+- **Add: stale-cache fallback (graceful degradation).** When NEMWEB returns
+  5xx or is unreachable (`httpx.RequestError`), `AEMOClient._fetch_cached`
+  now falls back to the most-recent cached payload (regardless of TTL) via
+  the new `Cache.get_stale()` and records the staleness on a `_stale_signal`
+  ContextVar. Server-side tool wrappers (`get_data`, `latest`) read the
+  signal after the fetch chain and surface it on the response via
+  `DataResponse.stale=True, stale_reason="AEMO/OpenNEM fetch returned X
+  for Y; serving cached payload from ~N minute(s) ago"`. Mirrors abs-mcp
+  0.2.13 / rba-mcp 0.1.10 patterns. Empty-cache fallback preserves the
+  original `AEMOAPIError` behaviour.
+- **Add: `DataResponse.stale_reason` and `truncated_at` fields.** Aligns the
+  envelope with the rest of the portfolio (abs / rba / ato / apra / aihw /
+  asic). `stale` retains its dual meaning: True when the latest NEM
+  observation is older than 2x cadence OR a cached fallback was served.
+- **Error-message sweep.** Every weak `ValueError` rewritten to suggest the
+  correction via stdlib `difflib.get_close_matches`. Unknown dataset IDs
+  now emit `Did you mean 'dispatch_price'?` for close typos; unknown filter
+  keys emit `Did you mean 'region'?`; unknown formats emit `Did you mean
+  'records'?`. Period errors now show a worked example
+  (`'2026-05-14' or '2026-05-14 09:00'`). `Unsupported aggregation
+  dimension` in duid_lookup now lists valid options. No new top-level
+  dependencies.
+- **Add: `CLAUDE.md`.** Repo-specific conventions auto-loaded by Claude
+  Code, mirroring the rest of the portfolio. Calls out the AEMO-specific
+  module set (`fetch.py`, `feeds.py`, `parsing.py`, `duid_lookup.py`),
+  the dual-meaning `stale` flag, the 5-min cadence cache-TTL ladder, and
+  the `/Reports/Current/` vs `/Reports/Archive/` pivot.
+- **Add: `.github/dependabot.yml`.** Weekly minor + patch update PRs for
+  pip + GitHub Actions, grouped, Mon 10:00 Sydney. Verbatim from the
+  sister repos.
+- **Tests: +4 stale-fallback regressions + 5 error-message-suggestion
+  regressions.** New tests cover: 5xx + stale cache → fallback + signal;
+  ConnectError + stale cache → same; 5xx + empty cache → still raises
+  `AEMOAPIError`; `Cache.get_stale()` round-trip + TTL bypass; "Did you
+  mean" hint for dataset / filter-key / format typos; period worked
+  example.
+
+## 0.1.1 (2026-05-15)
+
+Customer-simulation hardening pass. Hammered every dataset against the live
+NEMWEB feed; fixed every bug surfaced. 288 unit tests (was 225) + 10 live
+tests, 10× zero-flake green.
+
+- **Fix: `daily_summary` section name** — Daily_Reports publishes regional
+  data under `DREGION.` (with trailing dot — second cell of I-row is empty),
+  not `DISPATCH.PRICE`. YAML updated + 4 metrics (rrp, total_demand,
+  dispatchable_generation, net_interchange) now resolve correctly. The
+  parser already builds the empty-subname name; added a regression test.
+- **Fix: `predispatch_30min` section names** — the actual NEMWEB sections
+  are `PREDISPATCH.REGION_SOLUTION` (demand/generation) and
+  `PREDISPATCH.REGION_PRICES` (RRP); the YAML pointed at the non-existent
+  `PREDISPATCH.REGIONSUM`. Forward curves now return 135+ records per
+  region per run (instead of 1).
+- **Fix: `rooftop_pv` filename regex** — AEMO renamed the ACTUAL infix
+  from `MEASUREMENT` to `SATELLITE` and now also publishes some files
+  with no infix at all. Regex accepts all three forms.
+- **Fix: archive fallback** — added `/Reports/Archive/<feed>/` (one ZIP-of-
+  ZIPs per day) fetch for windows older than 4 hours. Daily archive zips
+  are unpacked recursively. Demo 3 ("did SA hit negative pricing in the
+  last 24h?") and Demo 4 ("weekly avg dispatch price for VIC, last 4
+  weeks") now succeed where they previously hit 403 on rolled-out
+  /Current/ files. Capped at 31 days per response.
+- **Fix: archive path** — the path constructor was including the literal
+  `Current` segment, producing `/Reports/Archive/Current/...` instead of
+  `/Reports/Archive/...`. Now strips correctly.
+- **Fix: 5-min feeds: skip rolled-out files instead of failing the whole
+  response** — NEMWEB rolls files in/out of /Current/ continuously; a
+  file present in the directory listing may have moved to /Archive/ by
+  the time we GET it. Individual 403/404s now skip silently; only a
+  fully-empty result surfaces an error.
+- **Fix: `latest()` on forecast feeds returns the full forward curve**,
+  not a single row collapsed to the furthest-out horizon. `rooftop_pv`
+  forecast and `predispatch_30min` now behave correctly.
+- **Fix: section filter at folder level** — `filters={"section": "actual"}`
+  now skips fetching the FORECAST folder entirely, cutting one HTTP round
+  trip + sidestepping flaky listings.
+- **Fix: section filter row-level skip** — the synthesised `section`
+  filter is no longer treated as a row column (which would reject every
+  row since rows have no SECTION cell).
+- **Fix: section dedup** — when AEMO emits the same section twice in one
+  file with different versions (e.g. `DREGION.` v2 + v3 in Daily_Reports),
+  we now combine and dedupe by (settlement_column, filter columns)
+  instead of taking only the first match.
+- **Fix: `Cache(db_path=DEFAULT_DB_PATH)` honors monkeypatches** — the
+  default value was captured at class-definition time, so test
+  monkeypatches of `DEFAULT_DB_PATH` had no effect. Now resolved at
+  construction time. Fixes flaky integration test where live NEMWEB data
+  bled through respx mocks.
+- **Fix: in-flight dedup future exception leaks** — failed fetches no
+  longer log "Future exception was never retrieved" warnings.
+- **Expand: DUID snapshot from 128 → 350 entries**, covering the majority
+  of active NEM units across all 5 regions and 7 fuel buckets. Generation-
+  by-fuel queries (QLD gas, NSW solar, SA battery, etc.) now return non-
+  empty results.
+- **Tests: +63 regressions + edge cases.** Tests now cover: every bug above
+  + unicode queries, very long queries, special-char queries, negative
+  TTL, concurrent 10x dedup, DOS line endings, truncated CSV, quoted
+  commas, ZIP-bomb defence, every-dataset describe sweep, fuzzy ranker
+  invariants, and DUID coverage thresholds per fuel/region.
+
+## 0.1.0 (2026-05-14)
+
+Initial release. MCP server wrapping AEMO NEMWEB feeds with 5 plain-English
+tools and 7 curated datasets.
+
+- **5 tools** mirroring abs-mcp / rba-mcp / ato-mcp: `search_datasets`,
+  `describe_dataset`, `get_data`, `latest`, `list_curated`.
+- **7 curated feeds** covering ~95% of typical NEM analytic queries:
+  - `dispatch_price` — 5-min regional spot price (RRP) per NEM region
+  - `dispatch_region` — 5-min total demand, scheduled + semi-scheduled generation, net interchange
+  - `interconnector_flows` — 5-min MW flow across the 6 NEM interconnectors
+  - `generation_scada` — 5-min DUID-level SCADA MW (every generating unit)
+  - `rooftop_pv` — 30-min regional rooftop solar (actual + forecast)
+  - `predispatch_30min` — 30-min half-hourly forecast, ~40h horizon
+  - `daily_summary` — daily rolled-up compendium of yesterday's price + demand + dispatch
+- **Trust contract** on every `DataResponse`: `source`, `attribution`,
+  `source_url`, `retrieved_at`, `interval_start`, `interval_end`, `stale`.
+- **Live-fetch only**, no pre-bundled NEMWEB archives in the wheel.
+- **Cache TTLs tuned per cadence**: 60s for 5-min feeds, 5min for 30-min
+  feeds, 1h forecasts, 24h daily, immutable for archived timestamped files.
+- **In-flight request deduplication** — concurrent callers share one HTTP
+  request per URL (critical at 5-min cadence with many users).
+- **AEMO Copyright Permissions** attribution string in every response.
+
+Licence: AEMO grants general permission to use AEMO Material for any purpose
+with attribution. See https://aemo.com.au/privacy-and-legal-notices/copyright-permissions.

aemo_mcp-0.1.2/CLAUDE.md

@@ -0,0 +1,182 @@
+# aemo-mcp
+
+Sister MCP in the Australian Public Data stack. See `../CLAUDE.md` for
+portfolio-wide conventions; this file captures repo-specific details
+plus the cross-sister discipline.
+
+## Source
+
+| | |
+|--|--|
+| Source agency | Australian Energy Market Operator (AEMO) |
+| Source URL | http://nemweb.com.au/Reports/Current/ |
+| Data format | Multi-section CSV (AEMO `C,/I,/D,` rows) packed in ZIP files, served from NEMWEB (IIS static file server). Directory listings are HTML. |
+| Licence | AEMO Copyright Permissions (general permission for any purpose with attribution; commercial use allowed) |
+| Licence URL | https://aemo.com.au/privacy-and-legal-notices/copyright-permissions |
+| Python module | `aemo_mcp` |
+| PyPI package | `aemo-mcp` |
+| GitHub | https://github.com/Bigred97/aemo-mcp |
+
+Note: AEMO's data is NOT CC-BY. Their Copyright Permissions policy is similar
+in effect (general permission with attribution) but the canonical attribution
+string differs — see `models._AEMO_ATTRIBUTION`.
+
+## Curated datasets (7)
+
+dispatch_price · dispatch_region · interconnector_flows · generation_scada ·
+rooftop_pv · predispatch_30min · daily_summary
+
+All cover the NEM (NSW1, QLD1, SA1, TAS1, VIC1). Western Australia (WEM) and
+the Northern Territory are not on the NEM and are out of scope.
+
+## Repo-specific module set
+
+Required (every sister): `server.py`, `models.py`, `curated.py`, `client.py`, `cache.py`, `shaping.py`, `data/curated/*.yaml`
+
+Repo-specific extras:
+- `fetch.py` — orchestration layer between server.py and the HTTP/parsing
+  stack. Resolves curated dataset → folder(s) → file selection (Current vs
+  Archive) → ZIP fetch → CSV parse → filter → shape. Sits where most
+  sisters' `server.py` would have inline orchestration logic — pulled out
+  because NEM file selection (5-min vs 30-min, Current vs Archive, latest
+  vs window, forecast vs actual) is non-trivial.
+- `feeds.py` — dataset search ranking + DatasetSummary projection. Replaces
+  rba-mcp's `tables.py` / abs-mcp's `catalog.py`.
+- `parsing.py` — AEMO multi-section CSV parser + ZIP unpacker. Each NEMWEB
+  ZIP holds one CSV with one or more `I,/D,` sections (DISPATCH.PRICE,
+  DISPATCH.REGIONSUM, DISPATCH.INTERCONNECTORRES, ...). Stdlib `csv` +
+  `zipfile` only; no pandas.
+- `duid_lookup.py` — DUID → region/fuel join table for `generation_scada`.
+  Static snapshot in `data/duid_snapshot.csv` (DUIDs change infrequently);
+  refreshed periodically. Used to translate `region`/`fuel` filters into a
+  DUID allow-set before filtering DISPATCH.UNIT_SCADA rows.
+
+## Repo-specific gotchas
+
+- **5-min cadence drives cache TTLs.** `live` = 60s, `half_hour` = 5min,
+  `forecast` = 1h, `daily` = 24h, `archive` = 7d, `listing` = 30s. Timestamped
+  NEMWEB files are immutable once written (filename embeds the interval), so
+  the file-body cache is effectively infinite. Only the directory listing
+  has freshness sensitivity.
+- **AEMO market time is UTC+10, no DST.** NEM is Brisbane-aligned year-round.
+  All NEMWEB timestamps in this code are tz-aware in NEM time (`NEM_TZ`).
+- **`/Reports/Current/` vs `/Reports/Archive/`.** Current holds ~24-48h of
+  5-min files; older intervals roll into daily ZIP-of-ZIPs compendia at
+  `/Reports/Archive/<feed>/PUBLIC_<feed>_YYYYMMDD.zip`. `fetch.py` auto-pivots
+  to Archive for windows older than `_CURRENT_WINDOW_HOURS` (4h). Archive
+  fallback unpacks two ZIP levels.
+- **In-flight request deduplication is mandatory.** At 5-min cadence with
+  many concurrent users, naive caching would hammer NEMWEB. `AEMOClient._in_flight`
+  shares one HTTP call across concurrent identical URLs.
+- **Latest-file detection is purely lexicographic.** AEMO embeds the interval
+  timestamp (`YYYYMMDDHHmm`) as the first 12-digit group in every filename,
+  so `max(filenames)` is the most recent. No HEAD requests needed.
+- **Forecast feeds use `latest()` differently.** For `rooftop_pv` forecast and
+  `predispatch_30min`, `latest()` returns the FULL forward curve from the
+  most-recent run, not a single collapsed row per dim. `_is_forecast_folder`
+  controls this.
+- **AEMO `C,/I,/D,` CSV format.** `C` = comment, `I` = schema row (opens a
+  new section), `D` = data row. Section name is `col1.col2` of the I-row;
+  data rows positionally map cells 4+ to the I-row's column names. One ZIP
+  can hold many sections, and one file can hold the same section twice in
+  two schema versions (`DREGION.` v2 + v3 in Daily_Reports) — `find_sections`
+  returns all; the caller dedupes.
+- **NEMWEB rolls files in/out continuously.** A filename present in the
+  directory listing may have moved to `/Archive/` between the listing GET
+  and the per-file GET. Individual 403/404 must NOT fail the whole response
+  — `_fetch_current_zips` skips and continues.
+- **`stale` field has dual meaning.** Set True if EITHER the latest observation
+  is older than 2× the feed cadence (NEM-side delay) OR a cached-fallback was
+  served because NEMWEB returned a non-2xx (graceful degradation). `stale_reason`
+  disambiguates.
+
+## Cache kinds (aemo-specific, not portable to other sisters)
+
+```
+live      60s   — 5-min dispatch feeds
+half_hour 5min  — 30-min feeds: rooftop PV actual, predispatch
+forecast  1h    — longer-horizon forecast bundles
+daily     24h   — daily rolled-up archives
+archive   7d    — immutable historical files (could be infinite)
+listing   30s   — NEMWEB directory HTML
+```
+
+---
+
+## The 5-tool surface (uniform across sisters — non-negotiable)
+
+1. `search_datasets(query, limit)` — fuzzy-search the 7 curated NEM feeds
+2. `describe_dataset(dataset_id)` — schema + filters + cadence + source URL
+3. `get_data(dataset_id, filters, start_period, end_period, format)` — query
+4. `latest(dataset_id, filters)` — most recent 5-min / 30-min / daily interval
+5. `list_curated()` — enumerate supported IDs
+
+Every parameter uses `Annotated[Type, Field(description=..., examples=[...])]`.
+This is the Glama Tool Definition Quality requirement — non-negotiable.
+
+## Trust contract (every DataResponse carries)
+
+```
+source             "Australian Energy Market Operator"
+source_url         the NEMWEB folder the data came from
+attribution        full AEMO Copyright Permissions attribution string
+retrieved_at       UTC timestamp
+server_version     importlib.metadata.version("aemo-mcp")
+interval_start     ISO-8601 in AEMO market time (UTC+10)
+interval_end       ISO-8601 in AEMO market time (UTC+10)
+stale              True when the feed is delayed OR cached fallback was served
+stale_reason       human-readable when stale=True (e.g. "AEMO/OpenNEM fetch returned 503 ...")
+truncated_at       int | None — set when latest() caps a large response
+```
+
+## The 5 quality dimensions (audit every release against these)
+
+1. **Semantic Clarity** — verb-noun tool names, Annotated[Field] with examples, rich docstrings (Examples + Returns blocks), `pattern=` constraints on dataset IDs and region codes
+2. **Data Pruning** — <10k tokens for typical responses, `latest()` returns the most-recent interval(s) for the filter dims rather than the whole file, no leaked AEMO row metadata in observations
+3. **Cross-Agency Joining** — AEMO market time uniformly UTC+10; region codes (NSW1/QLD1/SA1/TAS1/VIC1) match the canonical AEMO IDs that other sisters can join against; periods accept the shared YYYY / YYYY-MM / YYYY-MM-DD / YYYY-MM-DD HH:MM grammar
+4. **Reliability + Caching** — TTLs tuned per AEMO cadence (60s / 5min / 1h / 24h / 7d), self-heal on `sqlite3.DatabaseError`, **graceful degradation**: when NEMWEB returns 5xx or is unreachable, fall back to last cached payload via `Cache.get_stale()` and set `stale=True, stale_reason="..."` rather than raising
+5. **Deterministic Error Handling** — every `ValueError` carries a "Try X" / "Did you mean X?" / "Valid options: ..." hint that suggests the correction, not just describes the rejection
+
+## Test taxonomy
+
+Required: `test_cache.py`, `test_curated.py`, `test_server_validation.py`, `test_shaping.py`, `test_integration.py` (live, `@pytest.mark.live`)
+Recommended: `test_client.py`, `test_fetch.py`, `test_feeds.py`, `test_parsing.py`, `test_duid_lookup.py`, `test_mcp_protocol.py`, `test_regressions.py`, `test_edge_cases.py`, `test_live.py`
+
+Zero-flake bar: full unit suite must run 10× consecutively green before tagging a release.
+
+## Release workflow (Trusted Publishing via OIDC, no API tokens in CI)
+
+```
+1. Bump version in pyproject.toml (semver)
+2. Update CHANGELOG.md (latest entry at top, semver headings)
+3. uv run pytest × 10 — zero flakes
+4. git commit -am "X.Y.Z: <one-line reason>"
+5. git tag -a vX.Y.Z -m "X.Y.Z: <reason>"
+6. git push origin main vX.Y.Z
+7. release.yml fires → builds → OIDC publish → PyPI
+```
+
+PyPI new-project rate limit: 5/day per account; not an issue for existing
+projects (only counts NEW package names). `aemo-mcp` is already published.
+
+## Anti-patterns — DO NOT do these
+
+- Don't add a 6th tool; uniform 5-tool surface is the brand
+- Don't add new top-level dependencies beyond what other sisters use (httpx, pydantic, fastmcp, aiosqlite, rapidfuzz, pyyaml)
+- Don't introduce pandas at the parsing layer — stdlib `csv` + `zipfile` is enough
+- Don't bundle large NEMWEB archives in the wheel; cache at runtime
+- Don't ship without 10 consecutive zero-flake pytest runs
+- Don't echo PyPI tokens / PATs in tool output, commit messages, or CHANGELOG
+- Don't classify a slow source as a bug — NEMWEB cold fetches take 1-3s, only flag >10s or actual errors
+- Don't hammer NEMWEB — in-flight dedup + cache are mandatory at 5-min cadence
+- Don't widen scope mid-audit-loop; loops are fix-only
+
+## Common operations
+
+```bash
+cd .                                                       # in the repo
+uv sync --extra dev                                        # install deps
+uv run pytest                                              # unit tests
+uv run pytest -m live                                      # live tests too
+uvx --refresh --from aemo-mcp==<ver> python -c "..."        # smoke a published wheel
+```

aemo_mcp-0.1.2/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## Our Pledge
+
+We pledge to make participation in our project a harassment-free experience
+for everyone, regardless of age, body size, visible or invisible disability,
+ethnicity, sex characteristics, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance,
+race, caste, color, religion, or sexual identity and orientation.
+
+## Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward others
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility, apologizing, and learning from mistakes
+- Focusing on what is best for the overall community
+
+Unacceptable behavior includes:
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers via GitHub issues or a private channel.
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1. [homepage]: https://www.contributor-covenant.org

aemo_mcp-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to aemo-mcp
+
+Thanks for the interest. This MCP server is part of a family of Australian
+open-data wrappers ([abs-mcp](https://github.com/Bigred97/abs-mcp),
+[rba-mcp](https://github.com/Bigred97/rba-mcp),
+[ato-mcp](https://github.com/Bigred97/ato-mcp),
+[apra-mcp](https://github.com/Bigred97/apra-mcp),
+[aihw-mcp](https://github.com/Bigred97/aihw-mcp),
+[asic-mcp](https://github.com/Bigred97/asic-mcp),
+[au-weather-mcp](https://github.com/Bigred97/au-weather-mcp)) and follows the
+same architectural template.
+
+## Quick start
+
+```bash
+git clone https://github.com/Bigred97/aemo-mcp
+cd aemo-mcp
+uv sync --extra dev
+uv pip install -e .
+uv run pytest -q
+```
+
+## What we accept
+
+- **Bug fixes** with a regression test.
+- **New curated feeds** for high-value NEMWEB reports. Add a YAML in
+  `src/aemo_mcp/data/curated/`, extend `src/aemo_mcp/data/feeds.yaml`, and
+  add at least one unit test against a fixture in `tests/fixtures/`.
+- **Search-keyword expansions** to help LLMs route common queries — must be
+  paired with a routing regression test in `test_feeds.py`.
+- **Performance improvements** in parsing, caching, or in-flight dedup.
+
+## What we don't accept (by design)
+
+- **Tool count > 5.** We hold to the standard `search_datasets / describe_dataset / get_data / latest / list_curated` surface across all sibling MCPs.
+- **Pre-bundled NEMWEB archives in the wheel.** Live fetch only.
+- **Pandas at the tool surface.** Records must be plain `list[dict]` / `list[Observation]`. Pandas is fine internally for CSV parsing.
+- **Dependencies on `nemosis`, `nempy`, `openelectricity`.** Stay light.
+
+## Tests
+
+```bash
+# Unit tests (offline)
+uv run pytest -q
+
+# Live tests (hit NEMWEB)
+uv run pytest -q -m live
+
+# 10x zero-flake validation
+for i in $(seq 1 10); do uv run pytest -q || break; done
+```
+
+## Release
+
+Tag the commit:
+
+```bash
+git tag v0.1.x
+git push origin v0.1.x
+```
+
+GitHub Actions builds the wheel and publishes to PyPI via Trusted Publishing
+(OIDC, no token needed).
+
+## Attribution
+
+Every response carries the AEMO Copyright Permissions attribution string.
+Keep that contract intact across changes.

aemo_mcp-0.1.2/LICENSE

@@ -0,0 +1,33 @@
+MIT License
+
+Copyright (c) 2026 Harry Vass
+
+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.
+
+---
+
+Note on AEMO data: this software fetches data published by the Australian
+Energy Market Operator (AEMO) via NEMWEB. AEMO grants general permission to
+use AEMO Material for any purpose (commercial included) on the sole condition
+of accurate attribution of the relevant material and AEMO as its author. See
+https://aemo.com.au/privacy-and-legal-notices/copyright-permissions.
+
+End-users redistributing data fetched via this server must credit AEMO. The
+`DataResponse.attribution` field on every response carries the canonical
+attribution string.