asic-mcp 0.1.0__tar.gz

asic_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,72 @@
+name: Bug report
+description: Something works wrong, returns wrong data, or crashes.
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing! Please give us enough to reproduce. The fastest path to a fix is a minimal reproducer + the version you're running.
+
+  - type: input
+    id: version
+    attributes:
+      label: asic-mcp version
+      description: Run `python -c "import asic_mcp; print(asic_mcp.__version__)"`
+      placeholder: 0.1.1
+    validations:
+      required: true
+
+  - type: dropdown
+    id: client
+    attributes:
+      label: MCP client
+      options:
+        - Claude Desktop
+        - Cursor
+        - Windsurf
+        - Cline
+        - Direct Python (no MCP client)
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproducer
+    attributes:
+      label: Reproducer
+      description: |
+        The exact tool call(s) that trigger the bug. Either the MCP request payload or the equivalent Python:
+        ```python
+        from asic_mcp import server
+        await server.latest("F1.1", series="cash_rate_target")
+        ```
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: What actually happened
+      description: Error message, wrong value, surprising response shape, etc.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: |
+        - Python version (`python --version`)
+        - OS (macOS / Linux / Windows + version)
+        - How you installed (`uvx asic-mcp`, `uv pip install -e .`, etc.)
+      placeholder: |
+        Python 3.12.3, macOS 15, installed via uvx

asic_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or how-to
+    url: https://github.com/Bigred97/asic-mcp/discussions/new?category=q-a
+    about: For "how do I" or "is it possible to" — start a Discussion instead of an issue.
+  - name: Show & tell — share what you built
+    url: https://github.com/Bigred97/asic-mcp/discussions/new?category=show-and-tell
+    about: Built something cool with asic-mcp? We'd love to see it.
+  - name: Security vulnerability
+    url: https://github.com/Bigred97/asic-mcp/security/advisories/new
+    about: Use the private security advisory flow — do NOT open a public issue.

asic_mcp-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,46 @@
+name: Feature request
+description: Suggest a new tool, F-table, or behaviour.
+title: "[feat] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion. Higher chance of merge if you frame it around a real use case ("I want to ask Claude X and currently I have to do Y").
+
+  - type: textarea
+    id: use_case
+    attributes:
+      label: What are you trying to do?
+      placeholder: I want to ask Claude about ATO government bond yields and currently asic-mcp doesn't curate F2.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: |
+        Concrete: which file would change, what would the new tool/curated YAML look like, what does the user-visible API become?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: e.g. "I could just pass raw ATO series IDs to get_data, but..."
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      options:
+        - Add a curated F-table YAML
+        - New MCP tool
+        - Change to existing tool's signature
+        - Change to default behaviour
+        - Documentation
+        - Other
+    validations:
+      required: true

asic_mcp-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## What & why
+
+<!-- One paragraph: what does this PR do, and what's the motivating use case or bug? -->
+
+## How
+
+<!-- Brief: which files changed and why? -->
+
+## Tests
+
+- [ ] All existing tests still pass (`uv run pytest -m "not live"`)
+- [ ] New behaviour has a test
+- [ ] If this touches the live-API surface, `uv run pytest -m live` is green
+
+## Compatibility
+
+- [ ] No breaking changes to the public MCP tool signatures
+- [ ] No breaking changes to the `DataResponse` / `TableDetail` JSON shape
+- [ ] CC-BY 4.0 attribution still surfaces in `DataResponse.attribution`
+- [ ] If any of the above is broken, this is justified in the PR body
+
+## Other
+
+- [ ] CHANGELOG.md updated
+- [ ] README updated if user-visible behaviour changed
+- [ ] No new dependencies (or new dep is justified above)

asic_mcp-0.1.0/.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

asic_mcp-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,40 @@
+name: codeql
+
+# GitHub's free SAST scanning. Runs on push to main, on PRs, and weekly.
+# Findings appear under the repo's Security tab.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "47 6 * * 1"   # Mondays 06:47 UTC — off-peak, offset 10min from rba-mcp
+
+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@v6
+
+      - name: Initialise CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          queries: security-extended
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"

asic_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: release
+
+# Push a tag like v0.3.0 → wheel is built and published to PyPI via
+# Trusted Publishing (OIDC, no API token in repo secrets). One-time setup:
+#   1. https://pypi.org/manage/account/publishing/
+#   2. Add a "pending publisher":
+#        PyPI project    = asic-mcp
+#        owner           = Bigred97
+#        repository      = asic-mcp
+#        workflow        = release.yml
+#        environment     = pypi
+#   3. Create a `pypi` environment in repo Settings → Environments
+#      (no secrets needed; the environment scopes the OIDC token).
+#      Optionally add a required-reviewers rule so a tag push waits for
+#      your manual approval before publishing.
+# 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/asic-mcp/
+    permissions:
+      id-token: write     # required for Trusted Publishing OIDC
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - 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/

asic_mcp-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,60 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Run ruff check
+        # `uvx` runs ruff in an isolated managed env; avoids PEP 668
+        # "externally-managed environment" failure on Ubuntu 23.04+ runners
+        # that the previous `uv pip install --system` hit.
+        run: uvx "ruff>=0.5" check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        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@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Build wheel + sdist
+        run: uv build
+      - name: Verify wheel installs cleanly
+        run: |
+          uv run --isolated --with ./dist/*.whl python -c \
+            "import asic_mcp.server as s; n = len(s.list_curated()); assert n >= 8, f'expected >=8 curated, got {n}'; print(f'OK ({n} curated datasets)')"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

asic_mcp-0.1.0/.gitignore

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

asic_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,79 @@
+# 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.0] — 2026-05-13
+
+Initial release. ASIC registers via data.gov.au, plain-English access.
+
+### Added
+
+- **Seven curated ASIC register datasets**, all served from CKAN-discovered
+  resource URLs on data.gov.au under CC BY 3.0 AU:
+  - `ASIC_FINANCIAL_ADVISERS` — Financial Advisers Register (~21,000 records, weekly).
+  - `ASIC_AFS_LICENSEE` — Australian Financial Services Licensees (~6,500 entities, weekly).
+  - `ASIC_AFS_AUTH_REP` — AFS Authorised Representatives (~50 MB CSV, weekly).
+  - `ASIC_CREDIT_LICENSEE` — Australian Credit Licensees (NCCP-regulated lenders/brokers, weekly).
+  - `ASIC_BANNED_PERSONS` — Banned and Disqualified Persons (weekly).
+  - `ASIC_BANNED_ORGS` — Banned and Disqualified Organisations (weekly).
+  - `ASIC_LIQUIDATOR` — Registered & Official Liquidators (~700 practitioners, weekly).
+- **Five MCP tools** matching the abs-mcp / rba-mcp / ato-mcp / apra-mcp envelope:
+  `search_datasets`, `describe_dataset`, `get_data`, `latest`, `list_curated`.
+- **Trust contract on every `DataResponse`**: `source`, `source_url`,
+  `attribution`, `retrieved_at`, `server_version`, `stale`. Attribution is
+  the exact CC BY 3.0 AU statement from data.gov.au, naming ASIC as the
+  source and pointing at the canonical CC licence URL.
+- **CKAN auto-discovery** — each YAML declares a `discovery:` block
+  (`package_id` + `resource_name`); the server resolves the freshest
+  resource URL at fetch time. Hard-coded YAML URLs are the safe fallback.
+- **CSV delimiter sniffing** — ASIC labels every file `.csv` on data.gov.au,
+  but the actual delimiter is tab for some datasets (Financial Advisers, AFS
+  Authorised Representative, Banned Orgs) and comma for others (AFS
+  Licensee, Credit Licensee, Banned Persons, Liquidator). `read_csv`
+  detects from the first line.
+- **Dimension-only register shaping** — register data has no measure
+  columns, so `shape_wide` emits one `Observation` per row carrying every
+  dimension on `Observation.dimensions` with `value`/`measure` left `None`.
+- **SQLite byte cache** with per-kind TTLs (24h for register data, 1h for
+  CKAN catalogue) and mid-session corruption recovery.
+- **Parsed-DataFrame in-process LRU cache** keyed by (URL, parse-spec,
+  body content hash) — warm hits avoid pandas re-parse.
+- **In-flight dedup** — a burst of identical `latest()` calls fans into
+  one HTTP request.
+- **State alias maps** on every register that exposes `state` — pass
+  `"nsw"`, `"NSW"`, or canonical `"NSW"`; all resolve identically.
+- **Status alias maps** on Credit Licensee, Liquidator, and Financial
+  Adviser registers — pass `"approved"` and asic-mcp resolves to ASIC's
+  `"APPR"` code.
+- **Polite User-Agent** on every outbound request. data.gov.au's CDN
+  blocks the default httpx UA (returns 302 to HTML); asic-mcp identifies
+  itself with `asic-mcp/0.1 (+https://github.com/Bigred97/asic-mcp)`.
+
+### Tests
+
+- **229 unit tests + 9 live tests = 238 total**, zero flake across the
+  10× gauntlet.
+- Live tests assert a known-stable AFSL number (234945 — Commonwealth
+  Bank of Australia) is present in the live snapshot.
+- Adversarial / fuzz inputs: ~80 parametrised cases probing Unicode, path
+  traversal, URL injection, type confusion, huge strings, and emoji on
+  every tool parameter.
+- Discovery tests cover happy paths, off-host URL rejection (defense-in-
+  depth), no-match raises `DiscoveryError`, malformed CKAN responses,
+  and the fallback-to-YAML invariant when the network is down.
+
+### Known limitations (deferred to v0.2+)
+
+- `ASIC_COMPANIES` (373 MB CSV) and `ASIC_BUSINESS_NAMES` (234 MB CSV)
+  are excluded from v0.1 — they need a streaming lookup-by-ACN/ABN tool
+  rather than bulk table reads.
+- Enforcement / insolvency statistics (Series 3.1 / 3.2 / 3.3 XLSX on
+  asic.gov.au) are not in v0.1 — they live outside data.gov.au and need
+  apra-style landing-page scraping.
+- Short-position daily CSVs are not in v0.1 — they have a different
+  cadence and shape (one CSV per reporting day).
+- The dimension-only register model gives `Observation.value = None` for
+  every row. Agents should read register data from `Observation.dimensions`.

asic_mcp-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# 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, 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, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behaviour 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 and apologising to those affected by mistakes, and learning from the experience
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behaviour:
+
+- The use of sexualised language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour 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.

asic_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing to asic-mcp
+
+Thanks for considering a contribution. This is an indie open-source project — every PR is read.
+
+## Quick start
+
+```bash
+git clone https://github.com/Bigred97/asic-mcp.git
+cd asic-mcp
+uv sync --extra dev
+uv pip install -e .
+
+# Unit tests (no network)
+uv run pytest
+
+# Live integration tests (hits data.gov.au)
+uv run pytest -m live
+```
+
+## What kind of contribution helps?
+
+| Most welcome | Be cautious |
+|---|---|
+| Bug fixes (with a regression test) | Adding new tools to the MCP surface |
+| New curated datasets (one YAML per dataset in `src/asic_mcp/data/curated/`) | Refactors that touch >3 modules |
+| Better error messages with actionable hints | Changes that break the public response shape |
+| Docs / README improvements | Pulling in new dependencies |
+| Performance fixes (with a benchmark) | Changes to the YAML schema |
+
+## Adding a curated dataset
+
+1. Find the dataset on [data.gov.au](https://data.gov.au/data/organization/australiantaxationoffice). Note the dataset slug (e.g. `taxation-statistics-2022-23`) and the specific resource (e.g. `Individuals - Table 6`).
+2. Fetch the resource metadata via CKAN: `curl https://data.gov.au/data/api/3/action/package_show?id={slug} | jq` and find the resource's `url` field.
+3. Download a copy and inspect headers:
+   ```python
+   import openpyxl
+   wb = openpyxl.load_workbook("file.xlsx", read_only=True, data_only=True)
+   for sn in wb.sheetnames:
+       ws = wb[sn]
+       for row in ws.iter_rows(max_row=5, values_only=True):
+           print(row)
+   ```
+   Identify the data sheet, the 1-indexed header row, and the canonical column names. Note: ATO column headers often have embedded newlines (`Individuals\nno.`) — `parsing._normalize_header` strips padding around the newline so canonical YAML form is `"Individuals\nno."`.
+4. Hand-write the YAML under `src/asic_mcp/data/curated/{ID}.yaml`. `CORP_TRANSPARENCY.yaml` is the simplest reference (header_row 1, flat tabular); `IND_POSTCODE.yaml` covers the multi-dimension case.
+5. Run the smoke test to confirm column mappings match:
+   ```bash
+   PYTHONPATH=src uv run python -c "
+   from pathlib import Path
+   from asic_mcp import curated, parsing, shaping
+   cd = curated.get('YOUR_ID')
+   df = parsing.read_xlsx(Path('/path/to/file.xlsx').read_bytes(), sheet=cd.sheet, header_row=cd.header_row)
+   missing = [c.source_column for c in cd.columns.values() if c.source_column not in df.columns]
+   print('missing:' if missing else 'all columns match', missing)
+   "
+   ```
+6. Add a test fixture in `tests/fixtures/` and write a test in `tests/test_shaping.py`.
+7. Run `uv run pytest -m live` and confirm green.
+
+## PR checklist
+
+- [ ] All tests pass (`uv run pytest -m "not live"` minimum; `uv run pytest -m live` if you touched curation or the network path)
+- [ ] New code has tests
+- [ ] No new dependencies (or they're justified in the PR body)
+- [ ] CHANGELOG.md updated under the Unreleased section
+- [ ] If you changed default behaviour, the README "Example queries" still produces the documented values
+- [ ] CC-BY 3.0 AU attribution still surfaces in `DataResponse.attribution`
+
+## Style
+
+- Python 3.11+, `from __future__ import annotations` at file top
+- Pydantic v2 models — use `Field(default_factory=...)` for mutable defaults
+- Docstrings in module-level summary; functions only when non-obvious
+- No comments restating the code; comments explain *why*
+
+## Filing bugs
+
+Use the bug-report issue template. Bugs filed via the template get triaged within a week; freeform issues may sit longer.
+
+## Discussions vs Issues
+
+- **Issue**: bug, feature request, security report
+- **Discussion**: question, idea you're not sure about, sharing how you're using the package
+
+## Code of conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). Be kind.

asic_mcp-0.1.0/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.