{"id":49418355,"url":"https://github.com/groupthink-dev/aussiebb-blade-mcp","last_synced_at":"2026-04-29T04:12:30.533Z","repository":{"id":352125387,"uuid":"1207803104","full_name":"Groupthink-dev/aussiebb-blade-mcp","owner":"Groupthink-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-18T00:41:01.000Z","size":144,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T02:39:14.296Z","etag":null,"topics":["aussie-broadband","isp","mcp","mcp-server","model-context-protocol","nbn","sidereal"],"latest_commit_sha":null,"homepage":"https://sidereal.cc","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Groupthink-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T12:28:45.000Z","updated_at":"2026-04-18T00:41:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Groupthink-dev/aussiebb-blade-mcp","commit_stats":null,"previous_names":["groupthink-dev/aussiebb-blade-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Groupthink-dev/aussiebb-blade-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Faussiebb-blade-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Faussiebb-blade-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Faussiebb-blade-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Faussiebb-blade-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Groupthink-dev","download_url":"https://codeload.github.com/Groupthink-dev/aussiebb-blade-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Faussiebb-blade-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32410083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T03:46:11.172Z","status":"ssl_error","status_checked_at":"2026-04-29T03:37:55.317Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aussie-broadband","isp","mcp","mcp-server","model-context-protocol","nbn","sidereal"],"created_at":"2026-04-29T04:12:23.244Z","updated_at":"2026-04-29T04:12:30.526Z","avatar_url":"https://github.com/Groupthink-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aussiebb-blade-mcp\n\nAn MCP server that gives AI agents structured access to Aussie Broadband accounts. Built for the [Model Context Protocol](https://modelcontextprotocol.io) with token efficiency and operational security as first-class design goals.\n\n## Why this exists\n\nAussie Broadband has no public API program. The MyAussie portal API is undocumented and session-authenticated — not designed for programmatic access. The community-maintained [pyaussiebb](https://github.com/yaleman/pyaussiebb) library (MIT, 6 years, powers the Home Assistant integration) has done the reverse-engineering work. This MCP wraps it with the guardrails that automated agents need:\n\n- **Token-efficient output** — compact pipe-delimited format. A full service listing in ~50 tokens per service. Usage summaries with human-readable units (GB, %) and billing period context.\n- **Credential isolation** — passwords and session cookies scrubbed from all error output. Bearer token auth for HTTP transport. No credential caching beyond the session.\n- **Diagnostic safety gate** — line tests (connection check, port reset, loopback) require explicit opt-in via `ABB_DIAGNOSTICS_ENABLED=true` *and* per-call `confirm=true`. Port resets and connection kicks briefly interrupt service.\n- **Multi-account** — manage home and business accounts from a single MCP instance. Each account authenticates independently.\n\n## How this differs from other ISP tools\n\n| | aussiebb-blade-mcp | Home Assistant integration | Raw pyaussiebb |\n|---|---|---|---|\n| **Interface** | MCP tools (any LLM agent) | HA entities + automations | Python library |\n| **Output** | Token-optimised text | Sensor values | Raw dicts |\n| **Multi-account** | Native (env var config) | One account per integration | Manual |\n| **Diagnostic safety** | Double-gated (env + confirm) | Exposed as buttons | No gate |\n| **Auth transport** | Bearer token + stdio | HA auth | None |\n| **Credential handling** | Scrubbed from all output | HA secrets | Caller's responsibility |\n\n## Quick start\n\n```bash\n# Install\nuv pip install -e .\n\n# Configure\nexport ABB_USERNAME=\"your.email@example.com\"\nexport ABB_PASSWORD=\"your-myaussie-password\"\n\n# Run\naussiebb-blade-mcp\n```\n\n## 12 tools, 5 categories\n\n### Account \u0026 Services (3 tools)\n\n| Tool | Purpose | Token cost |\n|------|---------|------------|\n| `abb_info` | Health check — accounts, connection status, service count, diagnostics gate | ~40 |\n| `abb_services` | List all services (broadband, VOIP, Fetch TV) with plan, tech, speed | ~50/svc |\n| `abb_service` | Full detail for one service — address, POI, technology type | ~120 |\n\n### Usage Monitoring (2 tools)\n\n| Tool | Purpose | Token cost |\n|------|---------|------------|\n| `abb_usage` | Broadband usage: download, upload, remaining, billing period, % used | ~80 |\n| `abb_telephony` | Telephony breakdown: national, mobile, international, SMS, voicemail | ~60 |\n\n### Network \u0026 Outages (1 tool)\n\n| Tool | Purpose | Token cost |\n|------|---------|------------|\n| `abb_outages` | Network events, ABB outages, NBN outages (current, scheduled, resolved) | ~40/outage |\n\n### Billing \u0026 Support (3 tools)\n\n| Tool | Purpose | Token cost |\n|------|---------|------------|\n| `abb_billing` | Transactions by month (configurable depth) | ~30/txn |\n| `abb_tickets` | Support tickets: ref, status, subject, date | ~30/ticket |\n| `abb_orders` | Pending orders: ID, status, type | ~30/order |\n\n### Diagnostics (3 tools, gated)\n\n| Tool | Purpose | Token cost |\n|------|---------|------------|\n| `abb_boltons` | Service add-ons (data blocks, extras) | ~25/bolton |\n| `abb_tests` | Available diagnostic tests + optional history | ~20/test |\n| `abb_run_test` | Execute a test (loopback, linestate, port reset, etc.) | ~80 |\n\n### Output format\n\n```\nid=12345 | NBN: Home Broadband | plan=250/25 Mbps | loc=Sydney | tech=FTTP | speed=TC4\nid=67890 | VOIP: Home Phone | plan=VOIP Basic\n```\n\n```\nDownloaded: 146.5GB\nUploaded: 24.4GB\nTotal used: 170.9GB\nAllowance: 976.6GB\nUsed: 17%\nRemaining: 805.7GB\nBilling period: 12/30 days remaining\n```\n\n## Multi-account support\n\nManage multiple ABB accounts (household + business, parent + child) from a single MCP instance:\n\n```bash\nexport ABB_ACCOUNTS=\"home,office\"\nexport ABB_HOME_USERNAME=\"home@example.com\"\nexport ABB_HOME_PASSWORD=\"home-password\"\nexport ABB_OFFICE_USERNAME=\"office@example.com\"\nexport ABB_OFFICE_PASSWORD=\"office-password\"\n```\n\nPass `account=\"office\"` to any tool to target a specific account. Omit for the first configured account.\n\nSingle-account mode (plain `ABB_USERNAME`/`ABB_PASSWORD`) remains fully supported.\n\n## Security model\n\n| Layer | Mechanism |\n|-------|-----------|\n| **Credential scrubbing** | Passwords, cookies, and tokens stripped from all error output |\n| **Diagnostics gate** | `ABB_DIAGNOSTICS_ENABLED=true` required for any line test |\n| **Test confirmation** | `abb_run_test` additionally requires `confirm=true` |\n| **Bearer auth** | Optional `ABB_MCP_API_TOKEN` for HTTP transport |\n| **Session isolation** | Each account authenticates independently; no credential sharing |\n| **No persistence** | Credentials read from env at startup, never written to disk |\n| **Rate limiting** | Automatic backoff on 429 responses from ABB API |\n| **MFA awareness** | Documents MFA requirement for plan changes; does not bypass |\n\n## Sidereal integration\n\nAdd to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"aussiebb\": {\n      \"type\": \"stdio\",\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"~/src/aussiebb-blade-mcp\", \"run\", \"aussiebb-blade-mcp\"],\n      \"env\": {\n        \"ABB_USERNAME\": \"...\",\n        \"ABB_PASSWORD\": \"...\",\n        \"ABB_DIAGNOSTICS_ENABLED\": \"false\"\n      }\n    }\n  }\n}\n```\n\n### Webhook trigger patterns\n\nThe outage and usage tools are designed for downstream automation:\n\n- **Outage monitoring** — `abb_outages` returns structured outage data suitable for Sidereal WatchPaths triggers or scheduled polling. Detect new outages, scheduled maintenance windows, and resolution events.\n- **Usage threshold alerts** — `abb_usage` returns percentage-used and days-remaining, enabling threshold-based alerting (e.g. \"notify at 80% usage with 10+ days remaining\").\n- **Service status changes** — `abb_services` returns service status, enabling detection of suspensions, activations, or plan changes.\n\n## Development\n\n```bash\nmake install-dev    # Install with dev + test dependencies\nmake test           # Unit tests (mocked API, no ABB account needed)\nmake check          # Lint + format + type-check\nmake run            # Start MCP server (stdio)\n```\n\n### Architecture\n\n```\nsrc/aussiebb_blade_mcp/\n├── server.py       — FastMCP 2.0 server, 12 @mcp.tool decorators\n├── client.py       — ABBClient with multi-account, credential scrubbing, session management\n├── formatters.py   — Token-efficient output (pipe-delimited, null omission, human units)\n├── models.py       — Account config, diagnostics gate, constants\n└── auth.py         — Bearer token middleware for HTTP transport\n```\n\nBuilt with [FastMCP 2.0](https://github.com/jlowin/fastmcp) and [pyaussiebb](https://github.com/yaleman/pyaussiebb).\n\n### Testing\n\n```bash\nmake test           # Unit tests (mocked)\nmake test-cov       # With coverage report\nmake test-e2e       # Live account tests (requires ABB_E2E=1 + real credentials)\n```\n\n## Acknowledgements\n\n- [yaleman/pyaussiebb](https://github.com/yaleman/pyaussiebb) — the reverse-engineering work that makes this possible\n- [Home Assistant aussie_broadband](https://www.home-assistant.io/integrations/aussie_broadband/) — production validation of the underlying API surface\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Faussiebb-blade-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroupthink-dev%2Faussiebb-blade-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Faussiebb-blade-mcp/lists"}