apra-mcp 0.1.2__tar.gz

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

@@ -0,0 +1,37 @@
+name: codeql
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "57 6 * * 1"   # Mondays 06:57 UTC, offset from sister MCPs
+
+jobs:
+  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: Initialise CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          queries: security-extended
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"

apra_mcp-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: publish
+
+# Publishes the wheel + sdist to PyPI on every published Release.
+# Uses PyPI Trusted Publishing (OIDC) — no token in repo secrets.
+#
+# Setup (one-time, done once on PyPI):
+#   pypi.org → Your projects → apra-mcp → Publishing
+#   (or for the first release: pypi.org → "Pending publishers" → Add)
+#   Owner=Bigred97, Repository=apra-mcp, Workflow=publish.yml, Environment=pypi
+#
+# Trigger: create a GitHub Release. The release's tag (e.g. v0.1.3) drives
+# the version that gets uploaded. Make sure pyproject.toml's `version`
+# matches before tagging.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Build wheel + sdist
+        run: uv build
+      - name: Verify wheel installs cleanly
+        run: |
+          uv run --isolated --with ./dist/*.whl python -c \
+            "import apra_mcp.server as s; n = len(s.list_curated()); assert n >= 7, f'expected >=7 curated, got {n}'; print(f'OK ({n} curated datasets)')"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/apra-mcp
+    permissions:
+      id-token: write   # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI via OIDC
+        uses: pypa/gh-action-pypi-publish@release/v1

apra_mcp-0.1.2/.github/workflows/refresh-urls.yml

@@ -0,0 +1,56 @@
+name: refresh-seed-urls
+
+# Daily scrape of every APRA landing page in apra-mcp's curated set.
+# - When the scraped URLs differ from data/seed_urls.json, opens a PR.
+# - When any URL returns non-2xx, opens a GitHub issue.
+# Effect: even users on a months-old pip install stay current for weeks
+# because new wheels carry the refreshed seed.
+
+on:
+  schedule:
+    - cron: "30 13 * * *"   # 13:30 UTC daily (post-APRA-publication window)
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Sync dependencies
+        run: uv sync --extra dev && uv pip install -e .
+
+      - name: Run scraper for every curated dataset
+        id: scrape
+        run: |
+          uv run python scripts/refresh_seed.py > seed_diff.txt 2>&1 || echo "scrape_failed=true" >> $GITHUB_OUTPUT
+          cat seed_diff.txt
+
+      - name: Open PR if URLs changed
+        if: steps.scrape.outputs.scrape_failed != 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: "chore(seed): refresh URLs from APRA landing pages"
+          title: "chore(seed): refresh URLs from APRA landing pages"
+          body: |
+            Automated PR from `.github/workflows/refresh-urls.yml`.
+
+            ```
+            ${{ steps.scrape.outputs.diff }}
+            ```
+          branch: refresh-seed-urls
+          delete-branch: true
+          add-paths: src/apra_mcp/data/seed_urls.json

apra_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 apra_mcp.server as s; n = len(s.list_curated()); assert n >= 7, f'expected >=7 curated, got {n}'; print(f'OK ({n} curated datasets)')"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

apra_mcp-0.1.2/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+dist/
+build/
+.coverage
+.coverage.*
+htmlcov/
+.DS_Store
+*.swp
+*.swo
+.idea/
+.vscode/
+.apra-mcp-cache/

apra_mcp-0.1.2/CHANGELOG.md

@@ -0,0 +1,172 @@
+# 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).
+
+## [0.1.2] — 2026-05-13
+
+### Bug fixes (real customer impact)
+
+- **`latest()` was returning a single record for long-format datasets**
+  (`INSURANCE_GENERAL`, `INSURANCE_GENERAL_HISTORICAL`, `LIFE_INSURANCE`,
+  `LIFE_INSURANCE_HISTORICAL`). Root cause: `last_n=1` was implemented as
+  "keep 1 per measure", but long-format datasets carry a single `value`
+  measure with the semantic metric in the `data_item` dimension —
+  collapsing to 1 record per measure threw away the whole table. Fix:
+  detect long-format mode (one measure + period_column declared) and
+  switch to "keep all records at the most recent period(s)". `latest()`
+  on insurance datasets now returns hundreds of records (the latest
+  quarter's worth) instead of one.
+- **Period filters with quarter shorthand (`2025-Q4`) and bare years
+  (`2024`) silently returned zero rows.** The source `period_column`
+  stores ISO dates (`2025-12-31`) and string-comparing them against
+  `"2025-Q4"` excluded everything (`Q` > `1` in ASCII). Fix: a new
+  `_expand_period_input` normaliser converts user-supplied periods to
+  ISO `YYYY-MM-DD` bounds before comparison. Supports `YYYY`, `YYYY-MM`,
+  `YYYY-Qx` (and lowercase `q`), and ISO dates.
+
+### UX
+
+- **"Did you mean?" suggestions on unknown filter values.** Closest
+  RapidFuzz match (WRatio ≥ 70) is offered in the error message:
+  `Unknown value 'major' for filter 'sector'. Did you mean 'major_banks'?`
+  Permissive dimensions (fund_name, data_item) still pass unknowns
+  through unchanged.
+
+### Documentation honesty fix
+
+- Corrected `period_coverage` metadata on three snapshot datasets
+  (`ADI_KEY_STATS`, `ADI_RISK_WEIGHTED_ASSETS`, `SUPER_FUND_LEVEL`).
+  The APRA "centralised publication" XLSX is a SNAPSHOT of the latest
+  reporting quarter, not the multi-year history the filename suggests.
+  The YAML descriptions and `period_coverage` strings now say so
+  explicitly. The insurance long-format datasets remain true time
+  series (Sep 2023 → Dec 2025 for current; back to 2002/2008 for
+  historical).
+
+### Tests
+
+- 263 unit tests (up from 229 — 34 new covering the fixes)
+- 16 live integration tests
+- Zero-flake across 10 sequential runs
+
+## [0.1.1] — 2026-05-12
+
+### Attribution correction
+
+- **Attribution string switched from CC-BY 4.0 International to CC-BY 3.0
+  Australia** to align with APRA's actual licence terms. Both the
+  `attribution` field on every `DataResponse` and the README/llms.txt/docs
+  now read "Creative Commons Attribution 3.0 Australia" with the
+  https://creativecommons.org/licenses/by/3.0/au/ URL. No code-shape
+  changes — only the licence text + URL.
+- This brings apra-mcp in line with the sister packages (abs-mcp, ato-mcp,
+  rba-mcp), which all carry CC-BY 3.0 AU attribution.
+- Tests updated; 229 unit + 16 live remain green.
+
+### Dataset scope — what shipped and what's deferred
+
+The v0.1.0 spec listed six curated datasets including `ADI_PROPERTY_EXPOSURES`
+and `SUPER_AGGREGATE`. After inspecting the actual APRA XLSX layouts, the
+final v0.1.x cut substitutes:
+
+- **Shipped** (7 datasets, all long-format / wide layout — cleaner to parse,
+  easier to filter):
+  - `ADI_KEY_STATS` — per-bank capital + key ratios (Table 1 from the ADI
+    centralised publication; entity-level, the more valuable cut)
+  - `ADI_RISK_WEIGHTED_ASSETS` — per-bank RWA breakdown (Table 2 from the
+    same file; a free bonus that emerged from the inspection pass)
+  - `SUPER_FUND_LEVEL` — fund-by-fund detail
+  - `INSURANCE_GENERAL` + `INSURANCE_GENERAL_HISTORICAL`
+  - `LIFE_INSURANCE` + `LIFE_INSURANCE_HISTORICAL`
+
+- **Deferred to v0.2** (both are transposed multi-tab industry-aggregate
+  files that need a transposed-layout parser before they can ship cleanly):
+  - `ADI_PROPERTY_EXPOSURES` — industry-aggregate commercial property
+    exposures + residential mortgage approvals from the ADI property file
+  - `SUPER_AGGREGATE` — quarterly superannuation performance industry totals
+    (the multi-tab presentational file, distinct from `SUPER_FUND_LEVEL`)
+
+Net coverage is broader than the original spec (entity-level RWA is a clear
+value-add for any agent that asks "which banks carry the most credit risk").
+
+## [0.1.0] — 2026-05-12
+
+### Initial release
+
+apra-mcp v0.1.0 ships seven curated APRA datasets across banking,
+superannuation, and insurance, exposed through a six-tool MCP surface that
+mirrors abs-mcp / rba-mcp / ato-mcp.
+
+### Tools (6)
+
+- `search_datasets(query, limit=10)` — fuzzy search the curated catalog
+- `describe_dataset(dataset_id)` — list dimensions, measures, framework info
+- `get_data(dataset_id, filters, measures, start_period, end_period, format)`
+- `latest(dataset_id, filters, measures)` — shortcut to last observation per measure
+- `top_n(dataset_id, measure, n, filters, direction)` — server-side ranking
+- `list_curated()` — enumerate curated IDs
+
+### Curated datasets (7)
+
+- **`ADI_KEY_STATS`** — per-bank CET1 / Tier 1 / total capital + RWA + ratios,
+  every quarter since March 2013. Plain-English `institution: cba` aliases
+  for the Big 4 + Macquarie + 70 other ADIs, sector enum, mutual flag.
+- **`ADI_RISK_WEIGHTED_ASSETS`** — per-bank RWA broken down by credit /
+  operational / market risk, plus IRRBB and traded-market-risk sub-components.
+- **`SUPER_FUND_LEVEL`** — fund-by-fund member counts, benefits, median age,
+  active/inactive splits. Plain-English aliases for AustralianSuper, Aware,
+  HOSTPLUS, REST, UniSuper, HESTA, Cbus etc.
+- **`INSURANCE_GENERAL`** — long-format quarterly general insurance database
+  (post-AASB17). 14 dimensions × 1 value column × ~24k rows.
+- **`INSURANCE_GENERAL_HISTORICAL`** — pre-AASB17 GI archive (Dec 2002 → Jun 2023).
+- **`LIFE_INSURANCE`** — long-format quarterly life insurance database
+  (post-AASB17). 9 dimensions × 1 value column × ~10.6k rows.
+- **`LIFE_INSURANCE_HISTORICAL`** — pre-AASB17 LI archive (Jun 2008 → Jun 2023).
+
+### Reliability engineering
+
+- **3-tier URL discovery** — apra.gov.au publishes XLSX at date-versioned
+  paths that change every quarter. The discovery layer scrapes the canonical
+  landing page (with ETag-based conditional GET — 304s cost zero bytes), and
+  falls back to a CI-refreshed seed manifest, and finally to the YAML default.
+- **Schema-fingerprint warning surface** — `_apply_aliases` raises an
+  actionable `ValueError` if any expected column disappears from the source
+  XLSX, with the first 6 columns it actually saw embedded in the message.
+- **Cache self-heal** — corrupt `~/.apra-mcp/cache.db` is detected on init
+  and silently rebuilt.
+- **In-flight request dedup** — 50 parallel callers asking for the same XLSX
+  fan in to exactly one HTTP request.
+- **Host pinning** — `fetch_resource` refuses any URL outside `apra.gov.au`,
+  defense-in-depth against scraper or seed-manifest corruption.
+
+### Trust contract
+
+Every response includes:
+
+- `source = "Australian Prudential Regulation Authority"`
+- `source_url` — canonical APRA landing page
+- `download_url` — the actual XLSX URL used (post-discovery)
+- `attribution` — CC-BY 3.0 Australia string + license link
+- `retrieved_at` — ISO UTC timestamp
+- `server_version` — apra-mcp wheel version
+- `stale` + `stale_reason` — true when the live scrape failed and we served
+  from the bundled seed
+- `framework` — basis (post-AASB17 / pre-AASB17), break date, cross-reference
+  to the paired historical dataset (insurance datasets only)
+
+### Permissive filters + wildcards
+
+Dimensions flagged `permissive: true` accept any string value and support
+substring matching: `{"institution": "macquarie*"}` substring-matches every
+Macquarie entity. Useful for entity-name and data-item dimensions where
+exhaustively enumerating ~100 long names in the YAML isn't realistic.
+
+### Quality bar
+
+- 229 unit tests, 16 live integration tests against apra.gov.au
+- Zero-flake: full unit suite passes 10/10 sequential runs
+- Schema fingerprint guards catch column renames
+- Defensive validation guards on every MCP tool with "Try X" hints

apra_mcp-0.1.2/CODE_OF_CONDUCT.md

@@ -0,0 +1,37 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility for our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting 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 in a
+  professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer at hvass97@gmail.com. All complaints will
+be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1,
+available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

apra_mcp-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing
+
+Pull requests welcome. The goal: keep apra-mcp's surface uniform with its
+sister packages (abs-mcp, rba-mcp, ato-mcp) so an agent that uses all four
+gets a consistent shape.
+
+## Setup
+
+```bash
+git clone https://github.com/Bigred97/apra-mcp.git
+cd apra-mcp
+uv venv
+uv pip install -e ".[dev]"
+pytest                  # 229 unit tests, ~12s
+pytest -m live          # 16 live integration tests against apra.gov.au, ~20s
+```
+
+## Adding a curated dataset
+
+Drop one YAML file into `src/apra_mcp/data/curated/`. The schema:
+
+```yaml
+id: NEW_DATASET                    # SCREAMING_SNAKE_CASE
+name: Human-readable title
+description: |
+  Paragraph describing the dataset, including period coverage and any
+  caveats. Surfaces in describe_dataset() and search results.
+period_coverage: "September 2023 → latest quarter"
+update_frequency: quarterly
+source_url: https://www.apra.gov.au/...      # the landing page
+download_url: https://www.apra.gov.au/...    # initial XLSX URL (fallback)
+format: xlsx
+sheet: Database
+header_row: 1
+layout: wide
+cache_kind: data
+period_column: Reporting Period              # the source-column name
+search_keywords:
+  - keyword
+  - other keyword
+discovery:                                   # required for live URL resolution
+  landing_url: https://www.apra.gov.au/...
+  filename_pattern: '(?i)pattern\s+to\s+match'
+  prefer_database: true                      # optional
+  exclude_patterns:                          # optional
+    - '(?i)historical'
+    - '(?i)specifications'
+framework:                                   # optional, insurance-only
+  current_basis: post-AASB17
+  break_date: "2023-09-30"
+  break_reason: ...
+  historical_dataset: PAIRED_HISTORICAL_KEY
+columns:
+  alias:
+    source_column: "Exact source header"
+    description: User-facing column documentation.
+    role: dimension                          # dimension | measure | id
+    dtype: string                            # int | float | string | date
+    permissive: true                         # optional, allows wildcard match
+dimension_values:                            # optional, alias maps
+  alias:
+    user_alias: "Canonical Value In Source"
+```
+
+Then:
+1. Add a fixture (head-only 80–200 row XLSX) to `tests/fixtures/`
+2. Add the dataset's URL to `src/apra_mcp/data/seed_urls.json`
+3. Add tests in the existing test files (test_curated.py confirms loading;
+   test_customer_flows.py runs an end-to-end flow)
+4. Run `pytest` 10 times for zero-flake confirmation
+
+## Discovery filename_pattern
+
+The discovery layer scrapes the landing page HTML and regex-matches the
+decoded filename of every `<a href="...xlsx">`. Test with:
+
+```python
+from apra_mcp.discovery import resolve_via_scrape, DiscoverySpec
+from apra_mcp.client import APRAClient
+spec = DiscoverySpec(landing_url="https://...", filename_pattern=r"...")
+async with APRAClient() as c:
+    url = await resolve_via_scrape(c, spec)
+```
+
+When multiple files match, the one with the latest-dated filename wins.
+Use `exclude_patterns` to skip historical or specifications variants.
+
+## Style
+
+- Mirror the patterns in existing files. Consistency across the four MCPs
+  matters more than micro-optimisations.
+- Every MCP tool parameter must use `Annotated[Type, Field(description=...,
+  examples=[...])]`. This is what gives the package its Glama
+  tool-definition-quality score.
+- No new dependencies beyond `fastmcp`, `httpx`, `pydantic`, `rapidfuzz`,
+  `pandas`, `openpyxl`, `aiosqlite`, `PyYAML`.
+- No defensive code for impossible scenarios — trust internal types.
+- Default to no comments. Add one only when the *why* is non-obvious.
+
+## Reporting bugs
+
+Open an issue: https://github.com/Bigred97/apra-mcp/issues
+
+Especially helpful:
+
+- "APRA changed the shape of dataset X" — paste the error message from
+  `_apply_aliases`; the schema fingerprint guard prints the first 6
+  columns it actually saw.
+- "Live scrape returned the wrong file" — paste the resolved URL and the
+  filename_pattern it used.

apra_mcp-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+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.