@ausvector/cli 1.0.0

package/LICENSE

@@ -0,0 +1,191 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link to, the interfaces of the Work and
+      Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including communication on
+      electronic mailing lists, source code control systems, and issue
+      tracking systems that are managed by, or on behalf of, the Licensor
+      for the purpose of discussing and improving the Work, but excluding
+      communication that is conspicuously marked or otherwise designated
+      in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity alleging that the
+      Work or a Contribution incorporated within the Work constitutes
+      direct or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You meet
+      the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works
+          a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works that
+          You distribute, all copyright, patent, trademark, and attribution
+          notices from the Source form of the Work, excluding those notices
+          that do not pertain to any part of the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License. You may
+          add Your own attribution notices within Derivative Works that You
+          distribute, alongside or as an addendum to the NOTICE text from
+          the Work, provided that such additional attribution notices cannot
+          be construed as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!) The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier identification
+      within third-party archives.
+
+      Copyright [yyyy] [name of copyright owner]
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.

package/README.md

@@ -0,0 +1,26 @@
+# @ausvector/cli
+
+The Ausvector command-line client connects to the Ausvector Streamable HTTP MCP service.
+
+## Install
+
+```bash
+npm install --global @ausvector/cli
+```
+
+Set an API key with the `align:address` scope before using remote commands:
+
+```bash
+set AUSVECTOR_API_KEY=your_api_key
+ausvector tools list
+ausvector suburb search "Sydney"
+ausvector suburb summary --suburb "Sydney" --state NSW --postcode 2000
+```
+
+Use `--format json` for machine-readable output. The CLI does not store credentials and does not accept API keys as command-line arguments.
+
+## License and data
+
+The CLI source is licensed under Apache-2.0. This license does not grant rights to Ausvector trademarks, the remote service, API credentials, or the data returned by the service. Service terms, data-provider terms, and the G-NAF Core licence continue to apply to API usage.
+
+Copyright 2026 Ausdata Science Pty Ltd.

package/dist/bin.mjs

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+import { defineCommand, runCommand } from "citty";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+
+//#region ../../src/config/version.ts
+/** MCP server release version. Increment independently from the HTTP API. */
+const MCP_SERVER_VERSION = "1.2.0";
+const SERVICE_VERSION = MCP_SERVER_VERSION;
+/**
+* The SDK's LATEST_PROTOCOL_VERSION identifies its legacy wire revision.
+* createMcpHandler serves this explicit modern revision instead.
+*/
+const MCP_PROTOCOL_VERSION = "2026-07-28";
+const VERSION = `Ausdata MCP Server v${SERVICE_VERSION}`;
+
+//#endregion
+//#region ../../src/cli/mcp-client.ts
+const DEFAULT_MCP_ENDPOINT = "https://mcp.ausvector.ai/mcp";
+function parseEndpoint(value) {
+	const endpoint = value?.trim() || DEFAULT_MCP_ENDPOINT;
+	const url = new URL(endpoint);
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname))) throw new Error("MCP endpoint must use HTTPS, except for localhost development endpoints.");
+	return url;
+}
+function getApiKey(env = process.env) {
+	const apiKey = env.AUSVECTOR_API_KEY?.trim();
+	if (!apiKey) throw new Error("AUSVECTOR_API_KEY is required. Set it in the environment before running this command.");
+	return apiKey;
+}
+async function createMcpClient(options) {
+	const apiKey = options.apiKey.trim();
+	if (!apiKey) throw new Error("AUSVECTOR_API_KEY must not be empty.");
+	const client = new Client({
+		name: "ausvector-cli",
+		version: "1.0.0"
+	}, { versionNegotiation: { mode: { pin: MCP_PROTOCOL_VERSION } } });
+	const transport = new StreamableHTTPClientTransport(parseEndpoint(options.endpoint), { authProvider: { token: async () => apiKey } });
+	await client.connect(transport, { timeout: options.timeoutMs ?? 1e4 });
+	return {
+		async listTools() {
+			return (await client.listTools(void 0, { timeout: options.timeoutMs ?? 1e4 })).tools.map((tool) => ({
+				name: tool.name,
+				title: tool.title,
+				description: tool.description,
+				inputSchema: tool.inputSchema
+			}));
+		},
+		async callTool(name, args) {
+			const result = await client.callTool({
+				name,
+				arguments: args
+			}, { timeout: options.timeoutMs ?? 1e4 });
+			return {
+				content: result.content,
+				structuredContent: result.structuredContent,
+				isError: result.isError
+			};
+		},
+		close() {
+			return client.close();
+		}
+	};
+}
+
+//#endregion
+//#region ../../src/cli/commands.ts
+const connectionArgs = {
+	endpoint: {
+		type: "string",
+		description: "MCP endpoint URL."
+	},
+	timeout: {
+		type: "string",
+		description: "Request timeout in milliseconds.",
+		default: "10000"
+	},
+	format: {
+		type: "string",
+		description: "Output format: table or json.",
+		default: "table"
+	}
+};
+function parseFormat(value) {
+	if (value === "json" || value === "table") return value;
+	throw new Error("--format must be either table or json.");
+}
+function parseTimeout(value) {
+	const timeout = Number.parseInt(value, 10);
+	if (!Number.isSafeInteger(timeout) || timeout < 250 || timeout > 12e4) throw new Error("--timeout must be an integer between 250 and 120000 milliseconds.");
+	return timeout;
+}
+function parseLimit(value) {
+	const limit = Number.parseInt(value, 10);
+	if (!Number.isSafeInteger(limit) || limit < 1 || limit > 20) throw new Error("--limit must be an integer between 1 and 20.");
+	return limit;
+}
+function resolveEndpoint(value, env) {
+	return value?.trim() || env.AUSVECTOR_MCP_ENDPOINT?.trim() || DEFAULT_MCP_ENDPOINT;
+}
+function cell(value) {
+	if (value === null || value === void 0 || value === "") return "-";
+	return String(value).replace(/[\r\n]+/g, " ");
+}
+function table(headers, rows) {
+	const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => cell(row[index]).length)));
+	const formatRow = (row) => row.map((value, index) => cell(value).padEnd(widths[index])).join("  ");
+	return [
+		formatRow(headers),
+		widths.map((width) => "-".repeat(width)).join("  "),
+		...rows.map(formatRow)
+	].join("\n");
+}
+function emit(runtimeValue, format, value, headers, rows) {
+	if (format === "json" || !headers || !rows) {
+		runtimeValue.stdout(JSON.stringify(value, null, 2));
+		return;
+	}
+	runtimeValue.stdout(table(headers, rows));
+}
+function record(value) {
+	return typeof value === "object" && value !== null ? value : {};
+}
+function resultData(result) {
+	if (result.isError) {
+		const text = Array.isArray(result.content) ? result.content.map((item) => record(item).text).filter((value) => typeof value === "string").join(" ") : "";
+		throw new Error(text || "The MCP tool reported an error.");
+	}
+	return result.structuredContent ?? result.content ?? null;
+}
+function redactError(error) {
+	return (error instanceof Error ? error.message : "CLI command failed.").replace(/Bearer\s+[^\s"']+/gi, "Bearer [REDACTED]").replace(/am_sk_[A-Za-z0-9+/=_-]+/g, "[REDACTED]");
+}
+async function withClient(runtimeValue, context, action) {
+	const args = context.args;
+	const client = await runtimeValue.createClient({
+		apiKey: getApiKey(runtimeValue.env),
+		endpoint: resolveEndpoint(args.endpoint, runtimeValue.env),
+		timeoutMs: parseTimeout(args.timeout)
+	});
+	try {
+		await action(client, parseFormat(args.format));
+	} finally {
+		await client.close();
+	}
+}
+function toolRows(tools) {
+	return tools.map((tool) => [
+		tool.name,
+		tool.title,
+		tool.description
+	]);
+}
+function createRootCommand(runtimeValue) {
+	return defineCommand({
+		meta: {
+			name: "ausvector",
+			version: "1.0.0",
+			description: "Ausvector MCP command-line client."
+		},
+		subCommands: {
+			auth: defineCommand({
+				meta: {
+					name: "auth",
+					description: "Inspect API key availability."
+				},
+				subCommands: { status: defineCommand({
+					meta: {
+						name: "status",
+						description: "Report whether AUSVECTOR_API_KEY is configured."
+					},
+					args: {
+						format: connectionArgs.format,
+						endpoint: connectionArgs.endpoint
+					},
+					run(context) {
+						const args = context.args;
+						const configured = Boolean(runtimeValue.env.AUSVECTOR_API_KEY?.trim());
+						const value = {
+							configured,
+							credentialSource: configured ? "AUSVECTOR_API_KEY" : null,
+							endpoint: resolveEndpoint(args.endpoint, runtimeValue.env)
+						};
+						emit(runtimeValue, parseFormat(args.format), value, [
+							"CONFIGURED",
+							"SOURCE",
+							"ENDPOINT"
+						], [[
+							configured ? "yes" : "no",
+							value.credentialSource,
+							value.endpoint
+						]]);
+					}
+				}) }
+			}),
+			tools: defineCommand({
+				meta: {
+					name: "tools",
+					description: "Discover remote MCP tools."
+				},
+				subCommands: { list: defineCommand({
+					meta: {
+						name: "list",
+						description: "List available remote MCP tools."
+					},
+					args: connectionArgs,
+					run(context) {
+						return withClient(runtimeValue, context, async (client, format) => {
+							const tools = await client.listTools();
+							emit(runtimeValue, format, { tools }, [
+								"NAME",
+								"TITLE",
+								"DESCRIPTION"
+							], toolRows(tools));
+						});
+					}
+				}) }
+			}),
+			call: defineCommand({
+				meta: {
+					name: "call",
+					description: "Call an MCP tool with a JSON object."
+				},
+				args: {
+					name: {
+						type: "positional",
+						required: true,
+						description: "Tool name."
+					},
+					args: {
+						type: "string",
+						required: true,
+						description: "JSON object passed as tool arguments."
+					},
+					...connectionArgs
+				},
+				run(context) {
+					return withClient(runtimeValue, context, async (client, format) => {
+						const args = context.args;
+						let toolArgs;
+						try {
+							toolArgs = JSON.parse(args.args);
+						} catch {
+							throw new Error("--args must be valid JSON.");
+						}
+						if (!toolArgs || typeof toolArgs !== "object" || Array.isArray(toolArgs)) throw new Error("--args must be a JSON object.");
+						emit(runtimeValue, format, resultData(await client.callTool(args.name, toolArgs)));
+					});
+				}
+			}),
+			address: defineCommand({
+				meta: {
+					name: "address",
+					description: "Address search commands."
+				},
+				subCommands: { search: defineCommand({
+					meta: {
+						name: "search",
+						description: "Search Australian addresses."
+					},
+					args: {
+						query: {
+							type: "positional",
+							required: true,
+							description: "Address query."
+						},
+						limit: {
+							type: "string",
+							default: "5",
+							description: "Maximum candidate count."
+						},
+						suburb: {
+							type: "string",
+							description: "Optional suburb filter."
+						},
+						state: {
+							type: "string",
+							description: "Optional state filter."
+						},
+						postcode: {
+							type: "string",
+							description: "Optional postcode filter."
+						},
+						...connectionArgs
+					},
+					run(context) {
+						return withClient(runtimeValue, context, async (client, format) => {
+							const args = context.args;
+							const result = record(resultData(await client.callTool("search_address", {
+								query: args.query,
+								limit: parseLimit(args.limit),
+								...args.suburb ? { suburb: args.suburb } : {},
+								...args.state ? { state: args.state } : {},
+								...args.postcode ? { postcode: args.postcode } : {}
+							})));
+							emit(runtimeValue, format, result, [
+								"ID",
+								"ADDRESS",
+								"UNIT"
+							], (Array.isArray(result.candidates) ? result.candidates.map(record) : []).map((candidate) => [
+								candidate.id,
+								candidate.label,
+								candidate.unit
+							]));
+						});
+					}
+				}) }
+			}),
+			suburb: defineCommand({
+				meta: {
+					name: "suburb",
+					description: "Suburb discovery commands."
+				},
+				subCommands: {
+					search: defineCommand({
+						meta: {
+							name: "search",
+							description: "Search Australian suburbs."
+						},
+						args: {
+							query: {
+								type: "positional",
+								required: true,
+								description: "Suburb query."
+							},
+							state: {
+								type: "string",
+								description: "Optional state filter."
+							},
+							limit: {
+								type: "string",
+								default: "8",
+								description: "Maximum suburb count."
+							},
+							...connectionArgs
+						},
+						run(context) {
+							return withClient(runtimeValue, context, async (client, format) => {
+								const args = context.args;
+								const result = record(resultData(await client.callTool("search_suburb", {
+									query: args.query,
+									limit: parseLimit(args.limit),
+									...args.state ? { state: args.state } : {}
+								})));
+								emit(runtimeValue, format, result, [
+									"SUBURB",
+									"STATE",
+									"POSTCODE",
+									"LOCALITY PID"
+								], (Array.isArray(result.suburbs) ? result.suburbs.map(record) : []).map((suburb) => [
+									suburb.suburb,
+									suburb.state,
+									suburb.postcode,
+									suburb.localityPid
+								]));
+							});
+						}
+					}),
+					summary: defineCommand({
+						meta: {
+							name: "summary",
+							description: "Get summary statistics for an exact suburb."
+						},
+						args: {
+							suburb: {
+								type: "string",
+								required: true,
+								description: "Exact suburb name."
+							},
+							state: {
+								type: "string",
+								required: true,
+								description: "State abbreviation."
+							},
+							postcode: {
+								type: "string",
+								required: true,
+								description: "Four-digit postcode."
+							},
+							...connectionArgs
+						},
+						run(context) {
+							return withClient(runtimeValue, context, async (client, format) => {
+								const args = context.args;
+								const result = record(resultData(await client.callTool("get_suburb_summary", {
+									suburb: args.suburb,
+									state: args.state,
+									postcode: args.postcode
+								})));
+								const statistics = record(result.statistics);
+								emit(runtimeValue, format, result, [
+									"SUBURB",
+									"STATE",
+									"POSTCODE",
+									"ADDRESSES",
+									"STREETS"
+								], [[
+									result.suburb,
+									result.state,
+									result.postcode,
+									statistics.addressCount,
+									statistics.streetCount
+								]]);
+							});
+						}
+					})
+				}
+			})
+		}
+	});
+}
+async function runCli(rawArgs, options = {}) {
+	const runtimeValue = {
+		env: options.env ?? process.env,
+		stdout: options.stdout ?? ((message) => console.log(message)),
+		stderr: options.stderr ?? ((message) => console.error(message)),
+		createClient: options.createClient ?? createMcpClient
+	};
+	try {
+		await runCommand(createRootCommand(runtimeValue), { rawArgs });
+		return 0;
+	} catch (error) {
+		runtimeValue.stderr(`Error: ${redactError(error)}`);
+		return 1;
+	}
+}
+
+//#endregion
+//#region ../../src/cli/bin.ts
+runCli(process.argv.slice(2)).then((exitCode) => {
+	process.exitCode = exitCode;
+});
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ausvector/cli",
+  "version": "1.0.0",
+  "description": "Command-line client for the Ausvector Streamable HTTP MCP service.",
+  "license": "Apache-2.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "ausvector": "./dist/bin.mjs"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsdown",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
+    "citty": "^0.1.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsdown": "^0.18.4",
+    "typescript": "^5"
+  },
+  "publishConfig": { "access": "public" }
+}