abs-spend-mcp 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# abs-spend-mcp
+
+An [MCP](https://modelcontextprotocol.io/) server that exposes **Australian household
+spending** data — so Claude (Claude Code, Claude Desktop, or any MCP client) can answer
+questions like *"how did Victorian transport spending move year-on-year?"* directly in
+conversation.
+
+Data comes live from the [ABS Data API](https://data.api.abs.gov.au) (SDMX), plus a bundled
+static extract of National Accounts sub-category detail. It runs server-side over stdio, so
+there's no CORS proxy and nothing to configure — just point your client at it.
+
+## Tools
+
+| Tool | Answers |
+|---|---|
+| `get_spending_trend` | Monthly time series for any category/state — `$` level or year-on-year `%`, Original / Seasonally adjusted / Trend series |
+| `get_latest_summary` | Latest month: total spend, nominal **and** real (CPI-deflated) YoY growth, top category, discretionary share |
+| `get_category_breakdown` | All 9 COICOP categories for a month/geography, with shares of total |
+| `get_l2_composition` | Level-2 sub-category split (e.g. Transport → vehicle purchase / operation / services) with YoY |
+| `get_cost_of_living` | Living Cost Indexes by household type (YoY or index) — includes mortgage interest, unlike CPI |
+
+Categories, states, and series types take friendly names (`transport`, `VIC`,
+`seasonally_adjusted`) — see each tool's schema for the full set.
+
+## Use with Claude Code
+
+```bash
+claude mcp add --scope user abs-spend -- npx -y abs-spend-mcp
+```
+
+Then start any `claude` session and ask a spending question, or headless:
+
+```bash
+claude -p "Use the abs-spend tools: what's the latest Australian household spending summary?"
+```
+
+## Use with Claude Desktop
+
+Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`):
+
+```json
+{
+  "mcpServers": {
+    "abs-spend": { "command": "npx", "args": ["-y", "abs-spend-mcp"] }
+  }
+}
+```
+
+Restart Claude Desktop; the tools appear under the 🔌 connectors menu.
+
+## Run locally
+
+```bash
+npm install
+npm test        # end-to-end smoke test against the live ABS API
+npm start       # run the server on stdio
+```
+
+Requires **Node 18+** (uses the built-in `fetch`).
+
+## Data sources & caveats
+
+- **Live:** Monthly Household Spending Indicator (`HSI_M`), Monthly CPI Indicator (`CPI_M`),
+  Selected Living Cost Indexes (`LCI`). Responses are cached in-process for 10 minutes.
+- **Static:** Level-2 detail is from National Accounts 5206.0 Table 8 (HFCE) — quarterly,
+  national, current-price. Bundled as `hfce.json`; refresh it in sync with the parent repo's
+  `src/data/hfce.json` (see the app's `scripts/extract_hfce.py`).
+- Dollar values are `$` millions, current prices (nominal). Real YoY deflates by the
+  all-groups CPI (8-capital-city average).
+- The ABS API does **not** guarantee chronological observation order; the server sorts
+  periods defensively before any YoY / deflation math.
+- No sub-state (regional) spend is published — the finest geography is state/territory.
+
+Part of the [Australian Household Spending Analytics](https://github.com/skannan02/australian-household-spending)
+project.

package/hfce.json

@@ -0,0 +1 @@
+{"source": "ABS National Accounts 5206.0 Table 8 (HFCE)", "release": "March 2026", "unit": "$ millions, current prices", "seriesType": "Original", "frequency": "Quarterly", "periods": ["2015-Q3", "2015-Q4", "2016-Q1", "2016-Q2", "2016-Q3", "2016-Q4", "2017-Q1", "2017-Q2", "2017-Q3", "2017-Q4", "2018-Q1", "2018-Q2", "2018-Q3", "2018-Q4", "2019-Q1", "2019-Q2", "2019-Q3", "2019-Q4", "2020-Q1", "2020-Q2", "2020-Q3", "2020-Q4", "2021-Q1", "2021-Q2", "2021-Q3", "2021-Q4", "2022-Q1", "2022-Q2", "2022-Q3", "2022-Q4", "2023-Q1", "2023-Q2", "2023-Q3", "2023-Q4", "2024-Q1", "2024-Q2", "2024-Q3", "2024-Q4", "2025-Q1", "2025-Q2", "2025-Q3", "2025-Q4", "2026-Q1"], "series": {"A3605689A": [10947, 14323, 10785, 11105, 11082, 14440, 10781, 11328, 11359, 14886, 11538, 11837, 11910, 15413, 11481, 11960, 12120, 15907, 12221, 14153, 14616, 18508, 13705, 14079, 13848, 19746, 15438, 16014, 16417, 20510, 15504, 15936, 15801, 20323, 14970, 15791, 16139, 20600, 15456, 16504, 17096, 21665, 16366], "A3605688X": [26263, 25738, 24396, 25651, 25730, 26097, 25545, 26537, 26604, 27144, 26538, 27992, 28163, 28052, 26802, 28620, 28750, 28567, 25315, 14677, 16842, 20421, 20761, 23006, 19759, 23157, 26070, 30241, 33083, 35019, 34147, 36577, 38709, 38510, 37162, 38636, 38421, 38595, 36660, 39117, 39607, 39717, 37713], "A2302247X": [8140, 7625, 6903, 7643, 8162, 8063, 7059, 7860, 8241, 8145, 7424, 8418, 9053, 8748, 7813, 8940, 9572, 9046, 6900, 1113, 1535, 2024, 2019, 2746, 1885, 3114, 4478, 7543, 9630, 10933, 10028, 11403, 12340, 12160, 11129, 12160, 12857, 12998, 11270, 12871, 13472, 13739, 11805], "A2302240J": [7928, 10414, 7498, 8673, 8313, 10856, 7546, 8720, 8327, 10911, 7741, 9045, 8623, 11381, 7984, 9333, 8941, 11825, 7655, 7030, 8181, 12342, 8605, 9947, 6985, 13412, 9775, 11972, 11614, 15435, 10662, 12388, 11891, 14864, 10722, 12193, 11862, 15526, 11124, 12944, 12532, 16411, 11720], "A2302239X": [4609, 5070, 4653, 4746, 4905, 5294, 4710, 4895, 4963, 5523, 4907, 5119, 5296, 5675, 5066, 5197, 5283, 5778, 5380, 6169, 6263, 6796, 5854, 5891, 6466, 6964, 6083, 6417, 6582, 7326, 6464, 6748, 6848, 7634, 6409, 6491, 6548, 7416, 6274, 6577, 6689, 7531, 6407], "A2302244T": [15443, 15094, 14651, 15898, 15979, 15876, 15887, 16623, 16801, 16810, 16656, 17640, 17754, 17849, 17704, 18420, 18791, 18750, 17982, 14733, 18551, 19452, 19196, 19994, 19010, 20404, 19881, 21358, 22185, 22325, 22246, 23186, 24006, 24174, 23924, 25376, 25732, 26168, 25945, 26973, 27865, 28287, 27834], "A3605684R": [2101, 2623, 2080, 2153, 2154, 2700, 2159, 2254, 2211, 2746, 2161, 2257, 2221, 2800, 2186, 2263, 2248, 2814, 2272, 2706, 2743, 3392, 2672, 2743, 2667, 3630, 2913, 3030, 3053, 3657, 2848, 2945, 2934, 3673, 2849, 2973, 2944, 3911, 2963, 3057, 3163, 3972, 3039], "A2302238W": [4050, 4313, 4150, 4097, 4090, 4495, 4429, 4400, 4552, 5217, 5065, 4990, 5041, 5645, 5409, 5324, 5337, 5740, 5532, 5387, 5529, 5987, 5743, 5606, 5583, 5676, 5424, 5152, 5086, 5242, 4926, 4537, 4320, 4264, 3910, 3840, 3817, 3919, 3631, 3238, 3206, 3092, 2863], "A3605694V": [12681, 13384, 12737, 12986, 13521, 13867, 12951, 13514, 13905, 14884, 13786, 14403, 15028, 15472, 14292, 14783, 15233, 15939, 13403, 6792, 10627, 13044, 13521, 14109, 11672, 15276, 14838, 16996, 18887, 20325, 18946, 19827, 20931, 21199, 19982, 20421, 20985, 22252, 20524, 21701, 22269, 23467, 21363], "A2302237V": [22179, 23960, 22609, 22223, 22920, 24834, 23170, 23314, 23618, 25508, 24020, 24059, 24572, 26547, 25169, 25080, 25446, 27460, 27743, 26880, 28076, 29299, 26979, 27051, 29171, 30496, 29012, 29023, 30360, 33523, 31827, 32111, 32604, 35099, 32878, 32527, 33484, 36303, 34255, 33988, 34892, 37933, 35707], "A2302251R": [17821, 18117, 16817, 17938, 19097, 18891, 17411, 18446, 19488, 20474, 18658, 19662, 20761, 21144, 19249, 20413, 21269, 22002, 17994, 8952, 13715, 16394, 17075, 18449, 15240, 19533, 19372, 22601, 25709, 27905, 26247, 28497, 30437, 30658, 28077, 29105, 30665, 31756, 28878, 31099, 32688, 34470, 30986], "A3605685T": [1553, 1813, 1527, 1530, 1636, 1927, 1519, 1537, 1597, 1843, 1526, 1536, 1622, 1896, 1593, 1594, 1681, 1937, 1705, 2112, 2087, 2384, 1948, 1916, 2012, 2456, 2081, 2101, 2198, 2510, 2077, 2034, 2285, 2562, 2190, 2131, 2182, 2626, 2197, 2224, 2301, 2757, 2278], "A3605696X": [33304, 34962, 33266, 34940, 34741, 36834, 34959, 36905, 36401, 38147, 36028, 37684, 37170, 39095, 36914, 38736, 37802, 39480, 36698, 33103, 34383, 38051, 37027, 39080, 38016, 41115, 39619, 40685, 42295, 44929, 43204, 44626, 44344, 46376, 45110, 46158, 47656, 49696, 47975, 49618, 51171, 53720, 51854], "A3605697A": [5433, 6542, 5224, 5563, 5635, 6889, 5369, 5719, 5787, 7038, 5481, 5888, 6013, 7238, 5688, 6052, 6059, 7335, 5999, 5184, 5733, 7306, 6109, 6407, 6255, 8526, 7048, 7558, 7916, 9568, 7446, 7942, 7959, 9228, 7369, 7748, 7939, 9512, 7610, 8109, 8381, 10158, 8066], "A3605816F": [8658, 9383, 8803, 8843, 8995, 9790, 9139, 9295, 9514, 10740, 9972, 10109, 10337, 11320, 10475, 10520, 10620, 11518, 10912, 11556, 11792, 12783, 11597, 11497, 12049, 12640, 11507, 11569, 11668, 12569, 11390, 11285, 11168, 11898, 10319, 10331, 10365, 11336, 9904, 9814, 9894, 10622, 9270], "A2302243R": [10715, 12867, 10526, 10695, 11109, 13329, 10513, 10933, 11111, 13279, 10786, 11152, 11374, 13592, 10847, 11142, 11400, 13677, 11341, 12844, 13292, 16012, 12905, 13134, 13001, 16900, 13967, 14473, 14838, 17920, 13904, 13993, 14509, 17376, 13795, 14333, 14559, 18140, 14114, 14624, 15025, 18615, 14633], "A3605683L": [7061, 8432, 6919, 7011, 7319, 8702, 6835, 7142, 7303, 8690, 7099, 7359, 7530, 8895, 7069, 7286, 7471, 8926, 7364, 8027, 8462, 10235, 8285, 8475, 8322, 10815, 8974, 9342, 9587, 11753, 8979, 9013, 9290, 11141, 8756, 9229, 9434, 11602, 8954, 9342, 9562, 11886, 9315], "A3605687W": [11029, 10433, 10292, 11564, 11528, 11462, 11388, 11812, 12053, 12031, 11753, 12632, 12525, 12521, 12390, 12978, 13202, 13150, 12066, 9664, 13009, 13708, 13213, 14005, 12943, 13998, 13502, 14848, 15685, 15725, 15916, 16577, 17393, 17281, 17291, 18494, 18691, 18685, 18985, 19707, 20355, 20163, 20291], "A2302249C": [24281, 28013, 23554, 24128, 24651, 28123, 23653, 24476, 25248, 29358, 24719, 25701, 26340, 30024, 24868, 25897, 26400, 30426, 24952, 21735, 25129, 31449, 27219, 28038, 25461, 34208, 30475, 33076, 33972, 39066, 32857, 33646, 34666, 39291, 33419, 34343, 35674, 40611, 34585, 36361, 37625, 42824, 36676], "A3605686V": [4414, 4661, 4359, 4334, 4451, 4414, 4499, 4810, 4748, 4779, 4903, 5008, 5229, 5328, 5314, 5442, 5589, 5601, 5916, 5069, 5542, 5744, 5983, 5989, 6066, 6406, 6379, 6511, 6500, 6600, 6330, 6609, 6613, 6892, 6633, 6882, 7041, 7483, 6960, 7266, 7510, 8123, 7543], "A2302245V": [5615, 5718, 5760, 6318, 5642, 5697, 5898, 6300, 5699, 5727, 5947, 6135, 5501, 5452, 5778, 6007, 5406, 5252, 5256, 4599, 5017, 6707, 6764, 7872, 6654, 6613, 7741, 7974, 8097, 8336, 8537, 9470, 9959, 9590, 9623, 9974, 9075, 8841, 9137, 10071, 9700, 9071, 9047], "A2302252T": [18986, 19462, 18997, 20242, 19852, 20653, 20238, 21750, 21070, 21501, 20798, 21880, 21202, 21774, 21094, 22551, 21652, 22022, 20997, 21810, 21116, 21927, 21518, 22974, 22729, 23290, 22929, 22867, 23835, 24652, 24772, 25432, 25464, 26020, 26371, 26830, 27793, 28134, 28178, 29132, 30061, 30662, 30766], "A3606485T": [8885, 8958, 9045, 9135, 9253, 9292, 9352, 9437, 9544, 9608, 9750, 9915, 9955, 10083, 10133, 10133, 10090, 10123, 9702, 6110, 7535, 8818, 9399, 9700, 9032, 9299, 9642, 10260, 10544, 10710, 10986, 11253, 10921, 11128, 11370, 11580, 11925, 12050, 12187, 12377, 12729, 12900, 13022], "A3605690K": [11310, 11286, 10764, 11091, 11584, 11343, 10913, 11229, 11917, 12183, 11295, 11980, 12492, 12372, 11547, 12109, 12421, 12396, 11040, 5997, 8883, 10837, 11795, 12210, 10020, 12310, 13252, 15307, 15786, 16340, 15578, 15959, 17079, 16851, 16758, 16822, 17755, 17836, 17413, 18084, 18728, 18962, 18560], "A2302246W": [12508, 12395, 11733, 11690, 11926, 12338, 12589, 12377, 12663, 13273, 13167, 13439, 13609, 13852, 13212, 13674, 13772, 14269, 13159, 8964, 10289, 11690, 11978, 12388, 11220, 13430, 13852, 14723, 15355, 15750, 15582, 15704, 16411, 16760, 16409, 16502, 16489, 16756, 16253, 16175, 16435, 16906, 16861], "A3605695W": [5140, 4733, 4080, 4951, 5576, 5024, 4460, 4932, 5583, 5590, 4872, 5259, 5733, 5672, 4957, 5630, 6035, 6063, 4591, 2161, 3088, 3350, 3554, 4340, 3569, 4257, 4534, 5605, 6822, 7581, 7300, 8670, 9506, 9459, 8095, 8684, 9680, 9504, 8354, 9399, 10420, 11002, 9623]}}

package/index.js

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+// MCP server for the Australian household spending analytics app.
+// Exposes the same ABS data the web app shows — Monthly Household Spending
+// Indicator (HSI), CPI, Living Cost Indexes (LCI), and the static National
+// Accounts HFCE L2 bundle — as tools Claude can query directly.
+//
+// Runs server-side, so it calls https://data.api.abs.gov.au directly:
+// no CORS proxy needed (unlike the browser app, see ../vite.config.js).
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+import { CATEGORIES, ANALYTICAL, STATES } from './meta.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const API = 'https://data.api.abs.gov.au/rest/data'
+const HSI = 'ABS,HSI_M,1.6.0'
+const CPI = 'ABS,CPI_M,1.2.0'
+const LCI = 'ABS,LCI,1.0.0'
+
+// Static L2 bundle (quarterly HFCE, National Accounts). Refresh in sync with
+// the web app's ../src/data/hfce.json — see README.
+const hfce = JSON.parse(readFileSync(join(__dirname, 'hfce.json'), 'utf8'))
+
+// ---- friendly-name maps -----------------------------------------------------
+
+const CATEGORY_KEYS = {
+  total: ANALYTICAL.TOTAL,
+  discretionary: ANALYTICAL.DISCRETIONARY,
+  non_discretionary: ANALYTICAL.NON_DISCRETIONARY,
+  food: '10',
+  alcohol_tobacco: '15',
+  clothing: '20',
+  furnishings: '30',
+  health: '35',
+  transport: '40',
+  recreation: '50',
+  hotels_cafes: '60',
+  miscellaneous: '65',
+}
+const CATEGORY_ENUM = Object.keys(CATEGORY_KEYS)
+const LABEL_BY_CODE = Object.fromEntries(CATEGORIES.map((c) => [c.code, c.label]))
+LABEL_BY_CODE[ANALYTICAL.TOTAL] = 'Total household spending'
+LABEL_BY_CODE[ANALYTICAL.DISCRETIONARY] = 'Discretionary'
+LABEL_BY_CODE[ANALYTICAL.NON_DISCRETIONARY] = 'Non-discretionary'
+
+const STATE_ENUM = STATES.map((s) => s.abbr)
+const stateCode = (abbr) => STATES.find((s) => s.abbr === abbr).code
+
+const SERIES_TYPES = { original: '10', seasonally_adjusted: '20', trend: '30' }
+
+// L1 category -> National Accounts parent + L2 children (mirrors src/lib/hfce.js,
+// which can't be imported here because it uses a Vite-only JSON import).
+const HFCE_MAP = {
+  10: { parent: 'A2302237V', children: [] },
+  15: { parent: 'A3605816F', children: [
+    ['Alcoholic beverages', 'A2302239X'], ['Cigarettes & tobacco', 'A2302238W'],
+  ] },
+  20: { parent: 'A2302240J', children: [] },
+  30: { parent: 'A2302243R', children: [
+    ['Furniture, floor coverings & goods', 'A3605683L'], ['Household appliances', 'A3605684R'], ['Household tools', 'A3605685T'],
+  ] },
+  35: { parent: 'A2302244T', children: [
+    ['Medicines, aids & appliances', 'A3605686V'], ['Total health services', 'A3605687W'],
+  ] },
+  40: { parent: 'A3605688X', children: [
+    ['Purchase of vehicles', 'A2302245V'], ['Operation of vehicles', 'A2302246W'], ['Transport services', 'A2302247X'],
+  ] },
+  50: { parent: 'A2302249C', children: [
+    ['Goods for recreation & culture', 'A3605689A'], ['Recreational & cultural services', 'A3605690K'],
+  ] },
+  60: { parent: 'A2302251R', children: [
+    ['Catering services', 'A3605694V'], ['Accommodation services', 'A3605695W'],
+  ] },
+  65: { parent: 'A3605696X', children: [
+    ['Other goods', 'A3605697A'], ['Insurance & financial services', 'A2302252T'], ['Other services', 'A3606485T'],
+  ] },
+}
+
+const LCI_TYPES = {
+  employee: { code: 'P1', label: 'Employee households' },
+  age_pensioner: { code: 'P2', label: 'Age pensioner households' },
+  other_government_transfer: { code: 'P3', label: 'Other government transfer recipient households' },
+  self_funded_retiree: { code: 'P4', label: 'Self-funded retiree households' },
+  pensioner_beneficiary: { code: 'PBLCI', label: 'Pensioner & beneficiary households (aggregate)' },
+}
+
+// ---- SDMX client ------------------------------------------------------------
+
+// 10-minute cache: ABS data changes monthly/quarterly, and Claude may call
+// several tools in one conversation that hit the same underlying request.
+const cache = new Map()
+const CACHE_MS = 10 * 60 * 1000
+
+async function sdmx(dataflow, key, startPeriod) {
+  const url = `${API}/${dataflow}/${key}?startPeriod=${startPeriod}&format=jsondata`
+  const hit = cache.get(url)
+  if (hit && Date.now() - hit.at < CACHE_MS) return hit.json
+  const res = await fetch(url, { headers: { Accept: 'application/vnd.sdmx.data+json' } })
+  if (!res.ok) throw new Error(`ABS API ${res.status} ${res.statusText} for ${dataflow}/${key}`)
+  const json = await res.json()
+  cache.set(url, { at: Date.now(), json })
+  return json
+}
+
+// Parse SDMX-JSON into { periods, series } where series is keyed by the values
+// of the requested dimensions, joined with "|".
+// The ABS API does NOT guarantee chronological observation order (single-series
+// requests have been observed shuffled), and the YoY math depends on order —
+// so sort periods and remap every observation index.
+function parse(json, dimIds) {
+  const struct = json.data.structures[0]
+  const seriesDims = struct.dimensions.series
+  const positions = dimIds.map((id) => seriesDims.findIndex((d) => d.id === id))
+  const rawPeriods = struct.dimensions.observation[0].values.map((v) => v.id)
+  const order = rawPeriods.map((p, i) => [p, i]).sort((a, b) => (a[0] < b[0] ? -1 : 1))
+  const periods = order.map(([p]) => p)
+  const newIndex = new Array(order.length)
+  order.forEach(([, oldI], newI) => { newIndex[oldI] = newI })
+  const series = {}
+  for (const [key, body] of Object.entries(json.data.dataSets[0].series)) {
+    const parts = key.split(':').map(Number)
+    const seriesKey = positions.map((pos) => seriesDims[pos].values[parts[pos]].id).join('|')
+    const arr = new Array(periods.length).fill(null)
+    for (const [obsIdx, val] of Object.entries(body.observations)) {
+      arr[newIndex[Number(obsIdx)]] = val[0] == null ? null : Number(val[0])
+    }
+    series[seriesKey] = arr
+  }
+  return { periods, series }
+}
+
+const toYoY = (arr, lag) =>
+  arr.map((v, i) =>
+    i < lag || v == null || arr[i - lag] == null || arr[i - lag] === 0
+      ? null
+      : Number((((v - arr[i - lag]) / arr[i - lag]) * 100).toFixed(2)),
+  )
+
+const lastValid = (arr) => {
+  for (let i = arr.length - 1; i >= 0; i--) if (arr[i] != null) return i
+  return -1
+}
+
+async function fetchHsi(catCodes, state, tsest, startPeriod = '2019-01') {
+  const key = ['7', catCodes.join('+'), 'CUR', tsest, state, 'M'].join('.')
+  return parse(await sdmx(HSI, key, startPeriod), ['CATEGORY', 'STATE'])
+}
+
+const text = (obj) => ({ content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }] })
+const errText = (e) => ({ content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true })
+
+// ---- server & tools ---------------------------------------------------------
+
+const server = new McpServer({ name: 'abs-household-spending', version: '0.1.0' })
+
+server.registerTool(
+  'get_spending_trend',
+  {
+    title: 'Australian household spending trend',
+    description:
+      'Monthly Australian household spending from the ABS Monthly Household Spending Indicator (live). ' +
+      'Returns a monthly time series in $ millions (current prices) or year-on-year % change. ' +
+      'Covers 9 COICOP categories plus total/discretionary/non-discretionary, national or by state.',
+    inputSchema: {
+      category: z.enum(CATEGORY_ENUM).default('total').describe('Spending category'),
+      state: z.enum(STATE_ENUM).default('AUS').describe('Geography (AUS = national)'),
+      series_type: z.enum(['original', 'seasonally_adjusted', 'trend']).default('original')
+        .describe('ABS time-series estimate type. Trend is suspended by ABS during volatile periods (gaps are real).'),
+      measure: z.enum(['level', 'yoy']).default('level').describe('level = $ millions/month, yoy = % change vs same month last year'),
+      start_period: z.string().regex(/^\d{4}-\d{2}$/).default('2019-01').describe('First month, YYYY-MM'),
+    },
+  },
+  async ({ category, state, series_type, measure, start_period }) => {
+    try {
+      const code = CATEGORY_KEYS[category]
+      const st = stateCode(state)
+      // YoY needs 12 months of run-up before the requested start.
+      const fetchStart = measure === 'yoy' ? `${Number(start_period.slice(0, 4)) - 1}-${start_period.slice(5)}` : start_period
+      let { periods, series } = await fetchHsi([code], st, SERIES_TYPES[series_type], fetchStart)
+      let values = series[`${code}|${st}`] || []
+      if (measure === 'yoy') {
+        values = toYoY(values, 12)
+        const from = periods.findIndex((p) => p >= start_period)
+        periods = periods.slice(from)
+        values = values.slice(from)
+      }
+      return text({
+        source: 'ABS Monthly Household Spending Indicator (live SDMX API)',
+        category: LABEL_BY_CODE[code],
+        state,
+        series_type,
+        unit: measure === 'yoy' ? '% change year-on-year' : '$ millions per month, current prices (nominal)',
+        latest_period: periods[lastValid(values)] ?? null,
+        data: Object.fromEntries(periods.map((p, i) => [p, values[i]]).filter(([, v]) => v != null)),
+      })
+    } catch (e) { return errText(e) }
+  },
+)
+
+server.registerTool(
+  'get_latest_summary',
+  {
+    title: 'Latest household spending summary',
+    description:
+      'Headline summary of the latest month of Australian household spending: total spend, nominal and ' +
+      'real (CPI-adjusted) year-on-year growth, largest category, and discretionary share. Live ABS data.',
+    inputSchema: {
+      state: z.enum(STATE_ENUM).default('AUS').describe('Geography (AUS = national)'),
+    },
+  },
+  async ({ state }) => {
+    try {
+      const st = stateCode(state)
+      const allCodes = [ANALYTICAL.TOTAL, ...CATEGORIES.map((c) => c.code), ANALYTICAL.DISCRETIONARY]
+      const [{ periods, series }, cpiJson] = await Promise.all([
+        fetchHsi(allCodes, st, '10'),
+        sdmx(CPI, '1.10001.10.50.M', '2019-01'),
+      ])
+      const total = series[`${ANALYTICAL.TOTAL}|${st}`] || []
+      const idx = lastValid(total)
+      if (idx < 0) throw new Error('no data returned')
+      const nominalYoy = idx >= 12 && total[idx - 12] ? ((total[idx] - total[idx - 12]) / total[idx - 12]) * 100 : null
+
+      // Real YoY: deflate by All groups CPI (8-capital-city avg). CPI publishes
+      // a month or two behind HSI, so carry the last known index forward.
+      const cpi = parse(cpiJson, ['INDEX'])
+      const cpiByPeriod = Object.fromEntries(cpi.periods.map((p, i) => [p, cpi.series['10001']?.[i] ?? null]))
+      let last = null
+      const aligned = periods.map((p) => { const v = cpiByPeriod[p]; if (v != null) last = v; return last })
+      const realYoy =
+        idx >= 12 && aligned[idx] && aligned[idx - 12] && total[idx - 12]
+          ? (((total[idx] / aligned[idx]) - (total[idx - 12] / aligned[idx - 12])) / (total[idx - 12] / aligned[idx - 12])) * 100
+          : null
+
+      const cats = CATEGORIES
+        .map((c) => ({ category: c.label, value_millions: series[`${c.code}|${st}`]?.[idx] ?? null, discretionary: c.discretionary }))
+        .filter((c) => c.value_millions != null)
+        .sort((a, b) => b.value_millions - a.value_millions)
+      const disc = series[`${ANALYTICAL.DISCRETIONARY}|${st}`]?.[idx] ?? null
+
+      return text({
+        source: 'ABS Monthly Household Spending Indicator + Monthly CPI Indicator (live)',
+        state,
+        period: periods[idx],
+        total_spend_millions: total[idx],
+        yoy_nominal_pct: nominalYoy == null ? null : Number(nominalYoy.toFixed(2)),
+        yoy_real_pct: realYoy == null ? null : Number(realYoy.toFixed(2)),
+        top_category: cats[0] ?? null,
+        discretionary_share_pct: disc != null && total[idx] ? Number(((disc / total[idx]) * 100).toFixed(1)) : null,
+        categories_ranked: cats,
+        notes: 'Original series, current prices. Real YoY deflated by All-groups CPI (8-capital-city average).',
+      })
+    } catch (e) { return errText(e) }
+  },
+)
+
+server.registerTool(
+  'get_category_breakdown',
+  {
+    title: 'Spending by category',
+    description:
+      'All 9 COICOP spending categories for one month and geography, with $ values, shares of total, ' +
+      'and discretionary flags. Live ABS Monthly Household Spending Indicator data.',
+    inputSchema: {
+      state: z.enum(STATE_ENUM).default('AUS').describe('Geography (AUS = national)'),
+      period: z.string().regex(/^\d{4}-\d{2}$/).optional().describe('Month YYYY-MM; omit for latest'),
+    },
+  },
+  async ({ state, period }) => {
+    try {
+      const st = stateCode(state)
+      const allCodes = [ANALYTICAL.TOTAL, ...CATEGORIES.map((c) => c.code)]
+      const { periods, series } = await fetchHsi(allCodes, st, '10')
+      const total = series[`${ANALYTICAL.TOTAL}|${st}`] || []
+      const idx = period ? periods.indexOf(period) : lastValid(total)
+      if (idx < 0) throw new Error(`period ${period} not available (range ${periods[0]}..${periods[periods.length - 1]})`)
+      const rows = CATEGORIES
+        .map((c) => {
+          const v = series[`${c.code}|${st}`]?.[idx] ?? null
+          return v == null ? null : {
+            category: c.label,
+            value_millions: v,
+            share_of_total_pct: total[idx] ? Number(((v / total[idx]) * 100).toFixed(1)) : null,
+            discretionary: c.discretionary,
+          }
+        })
+        .filter(Boolean)
+        .sort((a, b) => b.value_millions - a.value_millions)
+      return text({
+        source: 'ABS Monthly Household Spending Indicator (live)',
+        state, period: periods[idx],
+        total_spend_millions: total[idx] ?? null,
+        unit: '$ millions, current prices, Original series',
+        categories: rows,
+      })
+    } catch (e) { return errText(e) }
+  },
+)
+
+server.registerTool(
+  'get_l2_composition',
+  {
+    title: 'Sub-category (L2) composition',
+    description:
+      'Level-2 sub-category detail for one spending category — e.g. Transport splits into Purchase of vehicles / ' +
+      'Operation of vehicles / Transport services. From ABS National Accounts HFCE (quarterly, national, ' +
+      `current prices) — a static bundle, ${hfce.release} release, not the live API. ` +
+      'Categories food and clothing have no published L2 split.',
+    inputSchema: {
+      category: z.enum(['food', 'alcohol_tobacco', 'clothing', 'furnishings', 'health', 'transport', 'recreation', 'hotels_cafes', 'miscellaneous'])
+        .describe('L1 category to drill into'),
+      quarter: z.string().regex(/^\d{4}-Q[1-4]$/).optional().describe('Quarter like 2026-Q1; omit for latest'),
+    },
+  },
+  async ({ category, quarter }) => {
+    try {
+      const code = CATEGORY_KEYS[category]
+      const m = HFCE_MAP[code]
+      const q = quarter ?? hfce.periods[hfce.periods.length - 1]
+      const qi = hfce.periods.indexOf(q)
+      if (qi < 0) throw new Error(`quarter ${q} not in bundle (range ${hfce.periods[0]}..${hfce.periods[hfce.periods.length - 1]})`)
+      const at = (id, i) => hfce.series[id]?.[i] ?? null
+      const parent = at(m.parent, qi)
+      const yqi = hfce.periods.indexOf(`${Number(q.split('-')[0]) - 1}-${q.split('-')[1]}`)
+      const children = m.children.map(([label, id]) => {
+        const v = at(id, qi)
+        const prev = yqi >= 0 ? at(id, yqi) : null
+        return v == null ? null : {
+          sub_category: label,
+          value_millions: v,
+          share_of_parent_pct: parent ? Number(((v / parent) * 100).toFixed(1)) : null,
+          yoy_pct: prev ? Number((((v - prev) / prev) * 100).toFixed(2)) : null,
+        }
+      }).filter(Boolean).sort((a, b) => b.value_millions - a.value_millions)
+      return text({
+        source: `${hfce.source}, ${hfce.release} release (static bundle — quarterly, national, current prices)`,
+        category: LABEL_BY_CODE[code],
+        quarter: q,
+        parent_total_millions: parent,
+        sub_categories: children,
+        notes: children.length ? 'yoy_pct compares the same quarter one year earlier.' : 'ABS does not publish an L2 split for this category.',
+      })
+    } catch (e) { return errText(e) }
+  },
+)
+
+server.registerTool(
+  'get_cost_of_living',
+  {
+    title: 'Cost of living by household type',
+    description:
+      'ABS Selected Living Cost Indexes (live): quarterly cost-of-living change by household type. ' +
+      'Unlike CPI, LCI includes mortgage interest and consumer credit charges, so employee households ' +
+      'diverge from pensioners when interest rates move. Weighted average of the 8 capital cities.',
+    inputSchema: {
+      household_type: z.enum([...Object.keys(LCI_TYPES), 'all']).default('all').describe('Household type, or all'),
+      measure: z.enum(['yoy', 'index']).default('yoy').describe('yoy = % change vs same quarter last year; index = raw index numbers'),
+      start_period: z.string().regex(/^\d{4}-Q[1-4]$/).default('2019-Q1').describe('First quarter, YYYY-Qn'),
+    },
+  },
+  async ({ household_type, measure, start_period }) => {
+    try {
+      const types = household_type === 'all' ? Object.entries(LCI_TYPES) : [[household_type, LCI_TYPES[household_type]]]
+      const key = ['1', '10001', types.map(([, t]) => t.code).join('+'), '50', 'Q'].join('.')
+      // YoY needs 4 quarters of run-up before the requested start.
+      const fetchStart = measure === 'yoy' ? `${Number(start_period.split('-')[0]) - 1}-${start_period.split('-')[1]}` : start_period
+      const { periods, series } = parse(await sdmx(LCI, key, fetchStart), ['HOUSHOLD_TYPE'])
+      const startIdx = Math.max(0, periods.indexOf(start_period))
+      const out = {}
+      for (const [name, t] of types) {
+        let vals = series[t.code] || []
+        if (measure === 'yoy') vals = toYoY(vals, 4)
+        out[t.label] = Object.fromEntries(
+          periods.map((p, i) => [p, vals[i]]).slice(startIdx).filter(([, v]) => v != null),
+        )
+      }
+      return text({
+        source: 'ABS Selected Living Cost Indexes (live SDMX API)',
+        unit: measure === 'yoy' ? '% change year-on-year' : 'index (all groups)',
+        region: 'Weighted average of 8 capital cities',
+        series: out,
+        notes: 'LCI includes mortgage interest & consumer credit charges (CPI does not).',
+      })
+    } catch (e) { return errText(e) }
+  },
+)
+
+// ---- start ------------------------------------------------------------------
+
+const transport = new StdioServerTransport()
+await server.connect(transport)
+console.error('abs-household-spending MCP server running on stdio')

package/meta.js

@@ -0,0 +1,36 @@
+// Self-contained copy of the ABS category/state codes the server needs.
+// Mirrors the fields used from ../src/lib/meta.js in the web app; kept here so
+// the npm package has no dependencies outside its own folder.
+
+// The 9 COICOP "Level 1" divisions the ABS publishes for the HSI.
+export const CATEGORIES = [
+  { code: '10', label: 'Food', discretionary: false },
+  { code: '15', label: 'Alcoholic beverages & tobacco', discretionary: true },
+  { code: '20', label: 'Clothing & footwear', discretionary: true },
+  { code: '30', label: 'Furnishings & household equipment', discretionary: true },
+  { code: '35', label: 'Health', discretionary: false },
+  { code: '40', label: 'Transport', discretionary: false },
+  { code: '50', label: 'Recreation & culture', discretionary: true },
+  { code: '60', label: 'Hotels, cafes & restaurants', discretionary: true },
+  { code: '65', label: 'Miscellaneous goods & services', discretionary: false },
+]
+
+// Analytical aggregates (discretionary vs non-discretionary view).
+export const ANALYTICAL = {
+  TOTAL: 'TOT',
+  DISCRETIONARY: '3',
+  NON_DISCRETIONARY: '4',
+}
+
+// STATE codelist. `abbr` is the friendly input; `code` is the ABS dimension value.
+export const STATES = [
+  { code: 'AUS', abbr: 'AUS', label: 'Australia' },
+  { code: '1', abbr: 'NSW', label: 'New South Wales' },
+  { code: '2', abbr: 'VIC', label: 'Victoria' },
+  { code: '3', abbr: 'QLD', label: 'Queensland' },
+  { code: '4', abbr: 'SA', label: 'South Australia' },
+  { code: '5', abbr: 'WA', label: 'Western Australia' },
+  { code: '6', abbr: 'TAS', label: 'Tasmania' },
+  { code: '7', abbr: 'NT', label: 'Northern Territory' },
+  { code: '8', abbr: 'ACT', label: 'Australian Capital Territory' },
+]

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "abs-spend-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Australian household spending data — ABS Monthly Household Spending Indicator, CPI, Living Cost Indexes, and National Accounts sub-category detail.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "abs",
+    "australia",
+    "household-spending",
+    "economics",
+    "sdmx"
+  ],
+  "license": "MIT",
+  "author": "Sathish Kannan",
+  "type": "module",
+  "bin": {
+    "abs-spend-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "meta.js",
+    "hfce.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skannan02/australian-household-spending.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://github.com/skannan02/australian-household-spending/tree/main/mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/skannan02/australian-household-spending/issues"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  }
+}