businessapi-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,20 @@
1
+ # Python
2
+ __pycache__/
3
+ *.pyc
4
+ .venv/
5
+ venv/
6
+
7
+ # Local secrets / client config (keep the .example, never a real key)
8
+ .env
9
+ .mcp.json
10
+ *.local.json
11
+
12
+ # Local run logs
13
+ *.log
14
+
15
+ # Downloaded PDFs
16
+ downloads/
17
+
18
+ # Build output
19
+ dist/
20
+ *.egg-info/
@@ -0,0 +1,16 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 — 2026-11-18
4
+
5
+ First public release.
6
+
7
+ - MCP server (fastmcp 4) for businessapi.com.au: 46 tools, 12 documentation resources, request-schema resources.
8
+ - Typed, locally validated lodgements: company registration (Form 201), ABN application, business-name registration
9
+ and renewal, ASIC Forms 484 / 205A / 6010 / 361 / 362 / RA52; PPSR searches; entity monitoring; webhook management.
10
+ - Zero-configuration install: `uvx businessapi-mcp`, `businessapi-mcp setup` (key stored in the user config directory,
11
+ environment inferred from the key prefix), `businessapi-mcp install <client>`, `businessapi-mcp doctor`.
12
+ - Safety: sandbox by default, live writes blocked unless `BAPI_ALLOW_LIVE=true`, dry-run-first lodgement tools,
13
+ caller-supplied idempotency keys for monitoring orders.
14
+ - Context-size controls: lazy request schemas (`get_request_schema`) and `BAPI_TOOLSETS` splitting.
15
+ - Verified end-to-end against the vendor sandbox (company registration finished with a test ACN; ABN application
16
+ reached `validation ok`; business-name registration returned an ASIC payment link).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Joe Fu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,215 @@
1
+ Metadata-Version: 2.5
2
+ Name: businessapi-mcp
3
+ Version: 0.1.0
4
+ Summary: MCP server for businessapi.com.au — Australian ASIC / ATO / ABRS / PPSR registry API with dry-run-first lodgement tools
5
+ Project-URL: Homepage, https://github.com/JoeFu/businessapi-mcp
6
+ Project-URL: Issues, https://github.com/JoeFu/businessapi-mcp/issues
7
+ Project-URL: Changelog, https://github.com/JoeFu/businessapi-mcp/blob/main/CHANGELOG.md
8
+ Author: Joe Fu
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: abn,asic,ato,australia,businessapi,claude,mcp,model-context-protocol,ppsr
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Office/Business
19
+ Classifier: Topic :: Software Development :: Libraries
20
+ Requires-Python: >=3.11
21
+ Requires-Dist: fastmcp<5,>=4
22
+ Requires-Dist: pydantic>=2.7
23
+ Provides-Extra: openapi
24
+ Requires-Dist: pyyaml>=6; extra == 'openapi'
25
+ Description-Content-Type: text/markdown
26
+
27
+ # businessapi-mcp
28
+
29
+ [![CI](https://github.com/JoeFu/businessapi-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/JoeFu/businessapi-mcp/actions/workflows/ci.yml)
30
+ [![PyPI](https://img.shields.io/pypi/v/businessapi-mcp.svg)](https://pypi.org/project/businessapi-mcp/)
31
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
32
+
33
+ MCP server for [Business API](https://businessapi.com.au) — the Australian ASIC / ATO / ABRS / PPSR
34
+ digital-service-provider API. Give Claude Code, Claude Desktop, Cursor or any MCP client the ability to look up
35
+ ABNs and ACNs, check names, register companies, ABNs and business names, lodge ASIC agent forms, run PPSR searches,
36
+ and monitor entities — with the sandbox as the default environment and every lodgement dry-run first.
37
+
38
+ ```text
39
+ You: Register a company called ACME TRADING SANDBOX TEST PTY LTD in the sandbox
40
+ Claude: check_company_name_availability → Available
41
+ get_request_schema("company_registration") → asks you for officeholders, addresses, shares
42
+ lodge_company_registration(dry_run=true) → shows you the exact payload and fees
43
+ lodge_company_registration(dry_run=false) → requestId 37363
44
+ wait_for_request → finished · ACN 601510089 · document 0EACL6550
45
+ ```
46
+
47
+ ## Install in three steps
48
+
49
+ Requires [uv](https://docs.astral.sh/uv/) (it fetches and runs the package; nothing else to install).
50
+
51
+ 1. **Get a key.** Register at https://businessapi.com.au/register and create a key at
52
+ https://businessapi.com.au/user/api-keys. Sandbox keys start with `bapi_sk_test_`, are free and need no card.
53
+
54
+ 2. **Store it** (prompted, hidden; saved to your user config directory, verified against the API):
55
+
56
+ ```bash
57
+ uvx businessapi-mcp setup
58
+ ```
59
+
60
+ 3. **Register the server** with your client:
61
+
62
+ ```bash
63
+ uvx businessapi-mcp install claude-code # or: claude-desktop · cursor · vscode · mcp-json
64
+ ```
65
+
66
+ This is equivalent to `claude mcp add bapi -- uvx businessapi-mcp`; the key never appears in client configuration.
67
+ Not on PyPI yet, or want the latest commit? Add `--git` to run straight from GitHub
68
+ (`uvx --from git+https://github.com/JoeFu/businessapi-mcp businessapi-mcp`).
69
+
70
+ Then open a new session and ask: *"Which company has ABN 51 824 753 556?"* (it calls `lookup_abn`) or
71
+ *"Register a company in the sandbox"*. `uvx businessapi-mcp doctor` runs a self-test against the sandbox if anything
72
+ looks off, and `uvx businessapi-mcp status` shows which key and environment are active.
73
+
74
+ <details>
75
+ <summary>Manual client configuration</summary>
76
+
77
+ ```json
78
+ { "mcpServers": { "bapi": { "command": "uvx", "args": ["businessapi-mcp"] } } }
79
+ ```
80
+
81
+ Claude Desktop: `claude_desktop_config.json`. Cursor: `~/.cursor/mcp.json`. VS Code: `.vscode/mcp.json` with
82
+ `"servers": { "bapi": { "type": "stdio", "command": "uvx", "args": ["businessapi-mcp"] } }`. The key is read from
83
+ the user config file written by `setup`, from `./.env`, or from `BAPI_API_KEY`.
84
+ </details>
85
+
86
+ ## How the model knows what to do
87
+
88
+ The vendor publishes no OpenAPI specification, only HTML documentation. This project turns that documentation into
89
+ three things the model receives over MCP:
90
+
91
+ 1. **Server instructions** — environment, asynchronous lodgement flow, pricing, dry-run workflow, where to start.
92
+ 2. **Tools** — 46 of them, each with a description that says when to use it, what it costs and what to call next.
93
+ Lodgement bodies are validated by Pydantic models whose field names match the vendor docs one-to-one, with the
94
+ ASIC/ATO code tables as enums and the "Mandatory IF …" cross-field rules as validators.
95
+ 3. **Resources** — 12 guides under `bapi://docs/*` (endpoint catalogue, lifecycle, per-form guides, code tables) and
96
+ the request schema of every lodgement under `bapi://schemas/{form}`.
97
+
98
+ ### Tools
99
+
100
+ | Group | Tools | Notes |
101
+ |---|---|---|
102
+ | `lookup` | `lookup_abn` `lookup_acn` `check_company_name_availability` `check_business_name_availability` `search_business_industries` | free lookups |
103
+ | `registrations` | `lodge_company_registration` `lodge_abn_registration` `lodge_business_name_registration` `lodge_business_name_renewal` + status / payment-link tools, `get_abn_entitlement_questionnaire`, `get_request_schema` | Form 201, ABNREG, BNREG, BNRENEW |
104
+ | `agent_forms` | `lodge_asic_484_form` `lodge_company_name_change` `lodge_company_deregistration` `lodge_asic_361_form` `lodge_asic_362_form` `request_asic_account_transactions` + status tools | registered-agent forms 484 / 205A / 6010 / 361 / 362 / RA52 |
105
+ | `monitoring` | `start_entity_monitoring` `renew_entity_monitoring` `list_monitored_entities` `get_monitored_entity` `stop_entity_monitoring` `resume_entity_monitoring` `get_entity_snapshot` `list_monitoring_events` `get_monitoring_event` `simulate_monitoring_event` | $18 per entity per year live |
106
+ | `webhooks` | `list_webhooks` `create_webhook` `update_webhook` `delete_webhook` `rotate_webhook_secret` `verify_webhook_signature` | signature check runs locally |
107
+ | `ppsr` | `create_ppsr_search` `get_ppsr_search` | $6 per search live |
108
+ | `core` | `get_request_status` `wait_for_request` `get_account_status` `call_endpoint` | polling, account, escape hatch |
109
+
110
+ Every lodgement tool defaults to `dry_run=true`: it validates locally and returns the exact JSON that would be sent.
111
+ The model has to pass `dry_run=false` to lodge — the natural "show the user the payload and fees, then confirm" step.
112
+
113
+ ## Safety model
114
+
115
+ - **Sandbox by default.** The environment is inferred from the key prefix. `bapi_sk_test_…` only ever reaches
116
+ `https://businessapi.com.au/api/test/v2`, where nothing is billed and nothing reaches production registries.
117
+ - **Live writes are blocked** unless the server runs with `BAPI_ALLOW_LIVE=true`. With a live key every
118
+ POST / PATCH / DELETE is refused before any HTTP call. Turn it on only when you intend to lodge.
119
+ - `testTransmissionIndicator` is injected from the server environment and anything the model sends is ignored;
120
+ `simulate_monitoring_event` refuses to run against live; monitoring orders and renewals need a caller-supplied
121
+ idempotency key so retries never charge twice; TFNs are checksum-validated and never echoed; webhook secrets are
122
+ returned once.
123
+ - Tools carry MCP `annotations` (`readOnlyHint`, `destructiveHint`) and a toolset tag.
124
+
125
+ See [SECURITY.md](SECURITY.md).
126
+
127
+ ## Configuration
128
+
129
+ | Variable | Default | Effect |
130
+ |---|---|---|
131
+ | `BAPI_API_KEY` | — | the key; also read from `./.env` or the file written by `businessapi-mcp setup` |
132
+ | `BAPI_ENV` | inferred from the key | `test` / `live`; only a cross-check, a mismatch is reported |
133
+ | `BAPI_ALLOW_LIVE` | off | must be `true` before any live POST / PATCH / DELETE |
134
+ | `BAPI_INLINE_SCHEMAS` | off | `true` puts the full lodgement schemas into `tools/list` |
135
+ | `BAPI_TOOLSETS` | `all` | comma-separated groups to expose (see below) |
136
+
137
+ Lookup order: environment variables → `./.env` in the directory the server starts from → the user config file
138
+ (`%APPDATA%\businessapi-mcp\.env`, `~/Library/Application Support/businessapi-mcp/.env`, `~/.config/businessapi-mcp/.env`).
139
+
140
+ ### Context size: lazy schemas and toolsets
141
+
142
+ Inlining the full schemas of the lodgement tools into `tools/list` costs about 147k characters (~37k tokens) on every
143
+ connection. By default the `request` parameter of each `lodge_*` tool is a plain JSON object and the model fetches the
144
+ exact schema on demand with `get_request_schema(form)` or `bapi://schemas/{form}`; validation is unchanged and errors
145
+ come back as a list of field paths.
146
+
147
+ | Configuration | Tools | Chars | ≈Tokens |
148
+ |---|---|---|---|
149
+ | `BAPI_INLINE_SCHEMAS=true`, all toolsets | 46 | 146,619 | 36,654 |
150
+ | default (lazy), all toolsets | 46 | 52,432 | 13,108 |
151
+ | `BAPI_TOOLSETS=lookup,registrations,core` | 18 | 20,409 | 5,102 |
152
+ | `BAPI_TOOLSETS=agent_forms,core` | 15 | 17,893 | 4,473 |
153
+ | `BAPI_TOOLSETS=monitoring,webhooks` | 16 | 17,012 | 4,253 |
154
+ | `BAPI_TOOLSETS=lookup,ppsr` | 7 | 7,494 | 1,873 |
155
+
156
+ `BAPI_TOOLSETS` lets one package run as several small servers — see `.mcp.json.example`. Leaving `core` off a server
157
+ also removes the `call_endpoint` escape hatch. Re-measure with `uv run scripts/tools_list_size.py`.
158
+
159
+ ## Command line
160
+
161
+ ```text
162
+ businessapi-mcp run the MCP server on stdio (what clients launch)
163
+ businessapi-mcp run --transport http --port 8000
164
+ businessapi-mcp setup [--local] store the key (hidden prompt) and verify it
165
+ businessapi-mcp status where the key comes from, which environment is active
166
+ businessapi-mcp doctor [--lodge] sandbox self-test through the real tools; --lodge also lodges the examples
167
+ businessapi-mcp install <client> claude-code | claude-desktop | cursor | vscode | mcp-json (--dry-run, --dev REPO)
168
+ ```
169
+
170
+ `doctor` refuses live keys. Its read-only run covers account status, lookups, name checks, industry search, the ABN
171
+ entitlement questionnaire, a PPSR search polled to completion, a $0 monitoring order with a simulated event and
172
+ `list_webhooks`; `--lodge` additionally submits the example company, sole-trader ABN and business-name payloads to the
173
+ sandbox and polls them (observed: company `finished` with a test ACN, ABN `validation ok`, business name
174
+ `wating ASIC CC payment` with an ASIC UAT payment link).
175
+
176
+ ## What the vendor docs get wrong (verified in the sandbox)
177
+
178
+ - Two helpers need query parameters the docs omit: `/helpers/business-industries?searchTerm=` and
179
+ `/helpers/entitlement-questionnaire?entityType=&entitySubType=`.
180
+ - Every `officeHolders[]` entry in a company registration needs `addressOverriddenIndicator` (400 without it); the
181
+ model defaults it to `false`.
182
+ - Company registration POST answers `{requestId, status, billing}` at the top level, not `{response: {requestId}}`;
183
+ the finished status uses `registrationDate`, not `dateOfRegistration`; ASIC rejections arrive as
184
+ `errors[].details.text` (the full advice letter) with a snake_case `response`.
185
+ - ABN lookups return PascalCase keys (`EntityName`, `AbnStatus`, …).
186
+ - Share money fields: the rules say integers in cents, the vendor sample sends `100` for 100 × $1 shares, and the
187
+ sandbox accepts either — agree the convention with the vendor before a live lodgement.
188
+ - Several vendor samples carry the placeholder ACN `123456789`, which fails the checksum their own docs require.
189
+ - Endpoints without a public docs page (name reservations, extracts, `tax/registrations`, most RA forms, ASIC inbox)
190
+ are reachable only through `call_endpoint`.
191
+
192
+ ## Development
193
+
194
+ ```bash
195
+ git clone https://github.com/JoeFu/businessapi-mcp && cd businessapi-mcp
196
+ uv sync --group dev
197
+ uv run pytest # offline: vendor samples, rules, server modes, CLI
198
+ uv run businessapi-mcp install claude-code --dev . # point your client at this checkout
199
+ uv run businessapi-mcp doctor # needs a sandbox key in ./.env or via setup
200
+ uv run --group dev scripts/export_openapi.py # refresh openapi.yaml after editing models.py
201
+ ```
202
+
203
+ Layout: `src/businessapi_mcp/` (`server.py` tools and docs, `models.py` request models, `config.py` key discovery,
204
+ `cli.py`, `smoke.py` doctor, `examples/`), `tests/` with the vendor samples as fixtures, `scripts/` (OpenAPI export,
205
+ an OpenAPI-generated alternative server, tools/list size measurement), `openapi.yaml`.
206
+
207
+ Adding a lodgement: write the request model in `models.py`, a `_lodge_x(request, dry_run)` implementation in
208
+ `server.py`, and one row in the `LODGEMENTS` registry; lazy / inline mode, toolset filtering and `get_request_schema`
209
+ follow automatically. Other tools use `@tool("<group>", annotations=...)`.
210
+
211
+ Releases: push a `v*` tag; `publish.yml` builds and publishes to PyPI through trusted publishing.
212
+
213
+ ## License
214
+
215
+ MIT — see [LICENSE](LICENSE). Not affiliated with Business API Pty Ltd, ASIC or the ATO.
@@ -0,0 +1,189 @@
1
+ # businessapi-mcp
2
+
3
+ [![CI](https://github.com/JoeFu/businessapi-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/JoeFu/businessapi-mcp/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/businessapi-mcp.svg)](https://pypi.org/project/businessapi-mcp/)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
+
7
+ MCP server for [Business API](https://businessapi.com.au) — the Australian ASIC / ATO / ABRS / PPSR
8
+ digital-service-provider API. Give Claude Code, Claude Desktop, Cursor or any MCP client the ability to look up
9
+ ABNs and ACNs, check names, register companies, ABNs and business names, lodge ASIC agent forms, run PPSR searches,
10
+ and monitor entities — with the sandbox as the default environment and every lodgement dry-run first.
11
+
12
+ ```text
13
+ You: Register a company called ACME TRADING SANDBOX TEST PTY LTD in the sandbox
14
+ Claude: check_company_name_availability → Available
15
+ get_request_schema("company_registration") → asks you for officeholders, addresses, shares
16
+ lodge_company_registration(dry_run=true) → shows you the exact payload and fees
17
+ lodge_company_registration(dry_run=false) → requestId 37363
18
+ wait_for_request → finished · ACN 601510089 · document 0EACL6550
19
+ ```
20
+
21
+ ## Install in three steps
22
+
23
+ Requires [uv](https://docs.astral.sh/uv/) (it fetches and runs the package; nothing else to install).
24
+
25
+ 1. **Get a key.** Register at https://businessapi.com.au/register and create a key at
26
+ https://businessapi.com.au/user/api-keys. Sandbox keys start with `bapi_sk_test_`, are free and need no card.
27
+
28
+ 2. **Store it** (prompted, hidden; saved to your user config directory, verified against the API):
29
+
30
+ ```bash
31
+ uvx businessapi-mcp setup
32
+ ```
33
+
34
+ 3. **Register the server** with your client:
35
+
36
+ ```bash
37
+ uvx businessapi-mcp install claude-code # or: claude-desktop · cursor · vscode · mcp-json
38
+ ```
39
+
40
+ This is equivalent to `claude mcp add bapi -- uvx businessapi-mcp`; the key never appears in client configuration.
41
+ Not on PyPI yet, or want the latest commit? Add `--git` to run straight from GitHub
42
+ (`uvx --from git+https://github.com/JoeFu/businessapi-mcp businessapi-mcp`).
43
+
44
+ Then open a new session and ask: *"Which company has ABN 51 824 753 556?"* (it calls `lookup_abn`) or
45
+ *"Register a company in the sandbox"*. `uvx businessapi-mcp doctor` runs a self-test against the sandbox if anything
46
+ looks off, and `uvx businessapi-mcp status` shows which key and environment are active.
47
+
48
+ <details>
49
+ <summary>Manual client configuration</summary>
50
+
51
+ ```json
52
+ { "mcpServers": { "bapi": { "command": "uvx", "args": ["businessapi-mcp"] } } }
53
+ ```
54
+
55
+ Claude Desktop: `claude_desktop_config.json`. Cursor: `~/.cursor/mcp.json`. VS Code: `.vscode/mcp.json` with
56
+ `"servers": { "bapi": { "type": "stdio", "command": "uvx", "args": ["businessapi-mcp"] } }`. The key is read from
57
+ the user config file written by `setup`, from `./.env`, or from `BAPI_API_KEY`.
58
+ </details>
59
+
60
+ ## How the model knows what to do
61
+
62
+ The vendor publishes no OpenAPI specification, only HTML documentation. This project turns that documentation into
63
+ three things the model receives over MCP:
64
+
65
+ 1. **Server instructions** — environment, asynchronous lodgement flow, pricing, dry-run workflow, where to start.
66
+ 2. **Tools** — 46 of them, each with a description that says when to use it, what it costs and what to call next.
67
+ Lodgement bodies are validated by Pydantic models whose field names match the vendor docs one-to-one, with the
68
+ ASIC/ATO code tables as enums and the "Mandatory IF …" cross-field rules as validators.
69
+ 3. **Resources** — 12 guides under `bapi://docs/*` (endpoint catalogue, lifecycle, per-form guides, code tables) and
70
+ the request schema of every lodgement under `bapi://schemas/{form}`.
71
+
72
+ ### Tools
73
+
74
+ | Group | Tools | Notes |
75
+ |---|---|---|
76
+ | `lookup` | `lookup_abn` `lookup_acn` `check_company_name_availability` `check_business_name_availability` `search_business_industries` | free lookups |
77
+ | `registrations` | `lodge_company_registration` `lodge_abn_registration` `lodge_business_name_registration` `lodge_business_name_renewal` + status / payment-link tools, `get_abn_entitlement_questionnaire`, `get_request_schema` | Form 201, ABNREG, BNREG, BNRENEW |
78
+ | `agent_forms` | `lodge_asic_484_form` `lodge_company_name_change` `lodge_company_deregistration` `lodge_asic_361_form` `lodge_asic_362_form` `request_asic_account_transactions` + status tools | registered-agent forms 484 / 205A / 6010 / 361 / 362 / RA52 |
79
+ | `monitoring` | `start_entity_monitoring` `renew_entity_monitoring` `list_monitored_entities` `get_monitored_entity` `stop_entity_monitoring` `resume_entity_monitoring` `get_entity_snapshot` `list_monitoring_events` `get_monitoring_event` `simulate_monitoring_event` | $18 per entity per year live |
80
+ | `webhooks` | `list_webhooks` `create_webhook` `update_webhook` `delete_webhook` `rotate_webhook_secret` `verify_webhook_signature` | signature check runs locally |
81
+ | `ppsr` | `create_ppsr_search` `get_ppsr_search` | $6 per search live |
82
+ | `core` | `get_request_status` `wait_for_request` `get_account_status` `call_endpoint` | polling, account, escape hatch |
83
+
84
+ Every lodgement tool defaults to `dry_run=true`: it validates locally and returns the exact JSON that would be sent.
85
+ The model has to pass `dry_run=false` to lodge — the natural "show the user the payload and fees, then confirm" step.
86
+
87
+ ## Safety model
88
+
89
+ - **Sandbox by default.** The environment is inferred from the key prefix. `bapi_sk_test_…` only ever reaches
90
+ `https://businessapi.com.au/api/test/v2`, where nothing is billed and nothing reaches production registries.
91
+ - **Live writes are blocked** unless the server runs with `BAPI_ALLOW_LIVE=true`. With a live key every
92
+ POST / PATCH / DELETE is refused before any HTTP call. Turn it on only when you intend to lodge.
93
+ - `testTransmissionIndicator` is injected from the server environment and anything the model sends is ignored;
94
+ `simulate_monitoring_event` refuses to run against live; monitoring orders and renewals need a caller-supplied
95
+ idempotency key so retries never charge twice; TFNs are checksum-validated and never echoed; webhook secrets are
96
+ returned once.
97
+ - Tools carry MCP `annotations` (`readOnlyHint`, `destructiveHint`) and a toolset tag.
98
+
99
+ See [SECURITY.md](SECURITY.md).
100
+
101
+ ## Configuration
102
+
103
+ | Variable | Default | Effect |
104
+ |---|---|---|
105
+ | `BAPI_API_KEY` | — | the key; also read from `./.env` or the file written by `businessapi-mcp setup` |
106
+ | `BAPI_ENV` | inferred from the key | `test` / `live`; only a cross-check, a mismatch is reported |
107
+ | `BAPI_ALLOW_LIVE` | off | must be `true` before any live POST / PATCH / DELETE |
108
+ | `BAPI_INLINE_SCHEMAS` | off | `true` puts the full lodgement schemas into `tools/list` |
109
+ | `BAPI_TOOLSETS` | `all` | comma-separated groups to expose (see below) |
110
+
111
+ Lookup order: environment variables → `./.env` in the directory the server starts from → the user config file
112
+ (`%APPDATA%\businessapi-mcp\.env`, `~/Library/Application Support/businessapi-mcp/.env`, `~/.config/businessapi-mcp/.env`).
113
+
114
+ ### Context size: lazy schemas and toolsets
115
+
116
+ Inlining the full schemas of the lodgement tools into `tools/list` costs about 147k characters (~37k tokens) on every
117
+ connection. By default the `request` parameter of each `lodge_*` tool is a plain JSON object and the model fetches the
118
+ exact schema on demand with `get_request_schema(form)` or `bapi://schemas/{form}`; validation is unchanged and errors
119
+ come back as a list of field paths.
120
+
121
+ | Configuration | Tools | Chars | ≈Tokens |
122
+ |---|---|---|---|
123
+ | `BAPI_INLINE_SCHEMAS=true`, all toolsets | 46 | 146,619 | 36,654 |
124
+ | default (lazy), all toolsets | 46 | 52,432 | 13,108 |
125
+ | `BAPI_TOOLSETS=lookup,registrations,core` | 18 | 20,409 | 5,102 |
126
+ | `BAPI_TOOLSETS=agent_forms,core` | 15 | 17,893 | 4,473 |
127
+ | `BAPI_TOOLSETS=monitoring,webhooks` | 16 | 17,012 | 4,253 |
128
+ | `BAPI_TOOLSETS=lookup,ppsr` | 7 | 7,494 | 1,873 |
129
+
130
+ `BAPI_TOOLSETS` lets one package run as several small servers — see `.mcp.json.example`. Leaving `core` off a server
131
+ also removes the `call_endpoint` escape hatch. Re-measure with `uv run scripts/tools_list_size.py`.
132
+
133
+ ## Command line
134
+
135
+ ```text
136
+ businessapi-mcp run the MCP server on stdio (what clients launch)
137
+ businessapi-mcp run --transport http --port 8000
138
+ businessapi-mcp setup [--local] store the key (hidden prompt) and verify it
139
+ businessapi-mcp status where the key comes from, which environment is active
140
+ businessapi-mcp doctor [--lodge] sandbox self-test through the real tools; --lodge also lodges the examples
141
+ businessapi-mcp install <client> claude-code | claude-desktop | cursor | vscode | mcp-json (--dry-run, --dev REPO)
142
+ ```
143
+
144
+ `doctor` refuses live keys. Its read-only run covers account status, lookups, name checks, industry search, the ABN
145
+ entitlement questionnaire, a PPSR search polled to completion, a $0 monitoring order with a simulated event and
146
+ `list_webhooks`; `--lodge` additionally submits the example company, sole-trader ABN and business-name payloads to the
147
+ sandbox and polls them (observed: company `finished` with a test ACN, ABN `validation ok`, business name
148
+ `wating ASIC CC payment` with an ASIC UAT payment link).
149
+
150
+ ## What the vendor docs get wrong (verified in the sandbox)
151
+
152
+ - Two helpers need query parameters the docs omit: `/helpers/business-industries?searchTerm=` and
153
+ `/helpers/entitlement-questionnaire?entityType=&entitySubType=`.
154
+ - Every `officeHolders[]` entry in a company registration needs `addressOverriddenIndicator` (400 without it); the
155
+ model defaults it to `false`.
156
+ - Company registration POST answers `{requestId, status, billing}` at the top level, not `{response: {requestId}}`;
157
+ the finished status uses `registrationDate`, not `dateOfRegistration`; ASIC rejections arrive as
158
+ `errors[].details.text` (the full advice letter) with a snake_case `response`.
159
+ - ABN lookups return PascalCase keys (`EntityName`, `AbnStatus`, …).
160
+ - Share money fields: the rules say integers in cents, the vendor sample sends `100` for 100 × $1 shares, and the
161
+ sandbox accepts either — agree the convention with the vendor before a live lodgement.
162
+ - Several vendor samples carry the placeholder ACN `123456789`, which fails the checksum their own docs require.
163
+ - Endpoints without a public docs page (name reservations, extracts, `tax/registrations`, most RA forms, ASIC inbox)
164
+ are reachable only through `call_endpoint`.
165
+
166
+ ## Development
167
+
168
+ ```bash
169
+ git clone https://github.com/JoeFu/businessapi-mcp && cd businessapi-mcp
170
+ uv sync --group dev
171
+ uv run pytest # offline: vendor samples, rules, server modes, CLI
172
+ uv run businessapi-mcp install claude-code --dev . # point your client at this checkout
173
+ uv run businessapi-mcp doctor # needs a sandbox key in ./.env or via setup
174
+ uv run --group dev scripts/export_openapi.py # refresh openapi.yaml after editing models.py
175
+ ```
176
+
177
+ Layout: `src/businessapi_mcp/` (`server.py` tools and docs, `models.py` request models, `config.py` key discovery,
178
+ `cli.py`, `smoke.py` doctor, `examples/`), `tests/` with the vendor samples as fixtures, `scripts/` (OpenAPI export,
179
+ an OpenAPI-generated alternative server, tools/list size measurement), `openapi.yaml`.
180
+
181
+ Adding a lodgement: write the request model in `models.py`, a `_lodge_x(request, dry_run)` implementation in
182
+ `server.py`, and one row in the `LODGEMENTS` registry; lazy / inline mode, toolset filtering and `get_request_schema`
183
+ follow automatically. Other tools use `@tool("<group>", annotations=...)`.
184
+
185
+ Releases: push a `v*` tag; `publish.yml` builds and publishes to PyPI through trusted publishing.
186
+
187
+ ## License
188
+
189
+ MIT — see [LICENSE](LICENSE). Not affiliated with Business API Pty Ltd, ASIC or the ATO.
@@ -0,0 +1,32 @@
1
+ # Security
2
+
3
+ ## What this server can do
4
+
5
+ It lodges real forms with Australian regulators (ASIC, ATO, PPSR) on your Business API account and spends money when
6
+ run against the live environment. The design keeps that behind several explicit steps:
7
+
8
+ - **Sandbox by default.** The environment is inferred from the key prefix: `bapi_sk_test_…` keys only ever reach
9
+ `https://businessapi.com.au/api/test/v2`, where nothing is billed and nothing reaches production registries.
10
+ - **Live writes are blocked unless `BAPI_ALLOW_LIVE=true`.** With a live key, every POST / PATCH / DELETE is refused
11
+ before any HTTP request unless that variable is set for the server process. Keep it off until you intend to lodge.
12
+ - **Dry run first.** Every lodgement tool and the monitoring order / renewal tools default to `dry_run=true`: they
13
+ validate and return the exact payload without sending it. The model has to pass `dry_run=false` explicitly.
14
+ - **No hidden flags.** `testTransmissionIndicator` is injected from the server's environment; anything a model sends
15
+ is ignored. The sandbox-only `simulate_monitoring_event` tool refuses to run against live.
16
+ - **Idempotency.** Monitoring orders and renewals require a caller-supplied `Idempotency-Key`, so retries never
17
+ charge twice.
18
+
19
+ ## Secrets
20
+
21
+ - The API key lives in your user config file (`businessapi-mcp setup`), a project `.env`, or the `BAPI_API_KEY`
22
+ environment variable. Client configurations written by `businessapi-mcp install` never contain the key.
23
+ - `.env`, `.mcp.json`, downloads and run logs are git-ignored. Do not commit keys; rotate any key that leaks at
24
+ https://businessapi.com.au/user/api-keys.
25
+ - TFNs (tax file numbers) are checksum-validated locally and never logged; tool descriptions instruct the model not to
26
+ repeat them back. Webhook signing secrets are returned once by the API and should be stored immediately.
27
+
28
+ ## Reporting a vulnerability
29
+
30
+ Please open a private security advisory on GitHub (Security → Report a vulnerability) rather than a public issue.
31
+ Include the version (`businessapi-mcp --version`), the client you used, and steps to reproduce. Issues in Business API
32
+ itself should go to the vendor: https://businessapi.com.au/contact.