@integrity-labs/xero-broker 0.1.0
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.
- package/README.md +64 -0
- package/dist/index.js +21303 -0
- package/package.json +36 -0
package/README.md
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# @integrity-labs/xero-broker
|
|
2
|
+
|
|
3
|
+
Xero Broker — an MCP server that routes money- and ledger-touching **Xero
|
|
4
|
+
writes** through [`@augmented/approval-core`](../approval-core) so a human
|
|
5
|
+
approves them before they hit the books. Sibling to `cloud-broker` and
|
|
6
|
+
`channel-broker`.
|
|
7
|
+
|
|
8
|
+
## Why
|
|
9
|
+
|
|
10
|
+
Vendor MCP servers like `@integrity-labs/xero-mcp-server` run on the agent
|
|
11
|
+
host and talk to Claude Code over stdio. Their tool calls never transit the
|
|
12
|
+
central Augmented API, so the generic HITL resolver can't gate them
|
|
13
|
+
(ENG-6029). For read-only Xero that's fine; for writes that move money or
|
|
14
|
+
mutate the ledger it isn't.
|
|
15
|
+
|
|
16
|
+
This broker is the per-vendor mitigation. When an agent is provisioned with
|
|
17
|
+
the `xero-broker` integration, the provisioner launches the vendor Xero
|
|
18
|
+
server **read-only** (`XERO_WRITES_VIA_BROKER=true` strips its
|
|
19
|
+
Create/Update/Delete tools), making this broker the **only** path the agent
|
|
20
|
+
has to a Xero write — there is no ungated lane to the same operation.
|
|
21
|
+
|
|
22
|
+
## Gated verbs
|
|
23
|
+
|
|
24
|
+
| Verb | Risk tier | Why |
|
|
25
|
+
| -- | -- | -- |
|
|
26
|
+
| `xero.payment.create` | `write_high_risk` | Moves money out — irreversible at the bank layer |
|
|
27
|
+
| `xero.bill.create` | `write` | Creates a payable obligation |
|
|
28
|
+
| `xero.bill.approve` | `write_high_risk` | Draft → approved is the gate before payment |
|
|
29
|
+
| `xero.invoice.void` | `write_destructive` | Cannot be undone in Xero |
|
|
30
|
+
| `xero.contact.merge` | `write_destructive` | Irreversible |
|
|
31
|
+
| `xero.bank_transaction.delete` | `write_destructive` | Audit-trail loss |
|
|
32
|
+
|
|
33
|
+
## Tools
|
|
34
|
+
|
|
35
|
+
- `xero_preview_request({ verb, payload })` — dry-run: `auto_approve` /
|
|
36
|
+
`route_to_approver` / `hard_deny` plus the resolved `risk_tier`. No side
|
|
37
|
+
effects.
|
|
38
|
+
- `xero_request_approval({ verb, payload, reason, ttl_seconds?, source_context? })`
|
|
39
|
+
— submit. On approval the broker executes the Xero REST call server-side
|
|
40
|
+
and returns the result. `status` is `auto_approve` / `active` (done),
|
|
41
|
+
`pending` (human paged), or `denied`.
|
|
42
|
+
- `xero_poll_decision({ request_id })` — single-shot status check (escape
|
|
43
|
+
hatch; resolution is normally pushed via direct-chat).
|
|
44
|
+
- `xero_await_decision({ request_id, max_wait_seconds? })` — long-poll
|
|
45
|
+
fallback.
|
|
46
|
+
|
|
47
|
+
Always include `payload.tenant_id` (the Xero organisation the write lands in —
|
|
48
|
+
the `Xero-Tenant-Id` header value, **not** the Augmented team).
|
|
49
|
+
|
|
50
|
+
## Env contract
|
|
51
|
+
|
|
52
|
+
Spawned as a stdio child by the runtime adapter. Same env as the other
|
|
53
|
+
brokers:
|
|
54
|
+
|
|
55
|
+
| Var | Purpose |
|
|
56
|
+
| -- | -- |
|
|
57
|
+
| `AGT_HOST` | Augmented API base URL |
|
|
58
|
+
| `AGT_AGENT_ID` | Agent UUID (defaulted into `xero_request_approval`) |
|
|
59
|
+
| `AGT_RUN_ID` | Run UUID (defaulted into `xero_request_approval`) |
|
|
60
|
+
| `AGT_TOKEN` | Initial JWT (preferred) |
|
|
61
|
+
| `AGT_API_KEY` | `tlk_…` — refresh path when `AGT_TOKEN` expires |
|
|
62
|
+
|
|
63
|
+
All calls route under `/xero-broker` on the API; the team is derived
|
|
64
|
+
server-side from `agent_id`.
|