@oga-mcp/server 1.0.0

package/dist/tools/find-areas.js

@@ -0,0 +1,58 @@
+/**
+ * MCP tool: find_areas (AR-367)
+ *
+ * Natural-language interface to the OneGoodArea Intelligence query plane.
+ * The planner translates the question into a typed plan (one of 7 ops);
+ * the database executes it; the response carries plan + plan_source +
+ * results so every answer is reproducible.
+ *
+ * Wraps POST /v1/query with {question}.
+ */
+import { OogaApiError } from "../api-client.js";
+import { formatQueryResponseAsText } from "./intelligence-format.js";
+export const findAreasToolName = "find_areas";
+export const findAreasToolDef = {
+    name: findAreasToolName,
+    description: "Ask a natural-language question over UK area intelligence. The planner translates it into one of seven typed plan operations — rank_areas (filter + sort LSOAs by signals), get_area, score_area, compare_areas (2-5 side by side), find_peers (k-NN over normalized signals), find_insights (peer-relative anomalies), or find_forecast (linear-regression projection). " +
+        "Returns the emitted plan (for transparency) plus the op-specific results. Every answer is reproducible because the plan is the contract — replay the same plan, get the same result.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            question: {
+                type: "string",
+                description: "Free-form question about UK areas. Examples: 'areas under £250k median price and rising YoY in England', 'compare M1 1AE, SW4 0LG, EH1 1BB for site selection', 'LSOAs like E01034129 with similar crime + amenity profile', 'forecast median price in M1 1AE over the next 12 months'. Max 500 characters.",
+            },
+        },
+        required: ["question"],
+        additionalProperties: false,
+    },
+};
+export function parseFindAreasArgs(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("find_areas arguments must be an object");
+    }
+    const obj = raw;
+    const question = obj.question;
+    if (typeof question !== "string" || question.trim().length === 0) {
+        throw new Error("question must be a non-empty string");
+    }
+    if (question.length > 500) {
+        throw new Error("question must be 500 characters or fewer");
+    }
+    return { question: question.trim() };
+}
+export async function executeFindAreas(client, args) {
+    try {
+        const result = await client.findAreas(args.question);
+        return { content: [{ type: "text", text: formatQueryResponseAsText(result) }] };
+    }
+    catch (err) {
+        if (err instanceof OogaApiError) {
+            const msg = `OneGoodArea API error (HTTP ${err.status ?? "?"}): ${err.message}`;
+            return { content: [{ type: "text", text: msg }], isError: true };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Tool error: ${msg}` }], isError: true };
+    }
+}
+//# sourceMappingURL=find-areas.js.map

package/dist/tools/find-areas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-areas.js","sourceRoot":"","sources":["../../src/tools/find-areas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAErE,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAE9C,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT,2WAA2W;QAC3W,sLAAsL;IACxL,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,QAAQ,EAAE;gBACR,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,6SAA6S;aAChT;SACF;QACD,QAAQ,EAAE,CAAC,UAAU,CAAC;QACtB,oBAAoB,EAAE,KAAK;KAC5B;CACO,CAAC;AAMX,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;IAE9B,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;AACvC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAqB,EACrB,IAAmB;IAEnB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,yBAAyB,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;IAClF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,YAAY,EAAE,CAAC;YAChC,MAAM,GAAG,GAAG,+BAA+B,GAAG,CAAC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;YAChF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACnE,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACpF,CAAC;AACH,CAAC"}

package/dist/tools/find-peers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * MCP tool: find_peers (AR-367)
+ *
+ * k-nearest-neighbour peers for a UK area, by normalized signal values.
+ * Returns the target's geo_code + signals_used + a ranked peers[] list
+ * with distance and how many signal dimensions contributed.
+ *
+ * Wraps POST /v1/peers.
+ */
+import type { OogaApiClient } from "../api-client.js";
+export declare const findPeersToolName = "find_peers";
+export declare const findPeersToolDef: {
+    readonly name: "find_peers";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly area: {
+                readonly type: "string";
+                readonly description: "UK postcode (e.g. 'SW1A 1AA') or place name (e.g. 'Manchester city centre'). Max 100 characters.";
+            };
+            readonly k: {
+                readonly type: "number";
+                readonly description: "Number of peers to return. Default 20, max 200.";
+                readonly minimum: 1;
+                readonly maximum: 200;
+            };
+        };
+        readonly required: readonly ["area"];
+        readonly additionalProperties: false;
+    };
+};
+export interface FindPeersArgs {
+    area: string;
+    k?: number;
+}
+export declare function parseFindPeersArgs(raw: unknown): FindPeersArgs;
+export declare function executeFindPeers(client: OogaApiClient, args: FindPeersArgs): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tools/find-peers.js

@@ -0,0 +1,77 @@
+/**
+ * MCP tool: find_peers (AR-367)
+ *
+ * k-nearest-neighbour peers for a UK area, by normalized signal values.
+ * Returns the target's geo_code + signals_used + a ranked peers[] list
+ * with distance and how many signal dimensions contributed.
+ *
+ * Wraps POST /v1/peers.
+ */
+import { OogaApiError } from "../api-client.js";
+import { renderPeersBlock } from "./intelligence-format.js";
+export const findPeersToolName = "find_peers";
+export const findPeersToolDef = {
+    name: findPeersToolName,
+    description: "Find LSOAs similar to a UK area by k-nearest-neighbour over normalized signal values. " +
+        "Returns the target LSOA, the signal dimensions used in the comparison, and a ranked list of peers with distance (0 = identical, 1 = maximally distant in the normalized space) and n_dims_used. " +
+        "Use this when the LLM needs 'areas like this one' for a specific postcode or place name.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            area: {
+                type: "string",
+                description: "UK postcode (e.g. 'SW1A 1AA') or place name (e.g. 'Manchester city centre'). Max 100 characters.",
+            },
+            k: {
+                type: "number",
+                description: "Number of peers to return. Default 20, max 200.",
+                minimum: 1,
+                maximum: 200,
+            },
+        },
+        required: ["area"],
+        additionalProperties: false,
+    },
+};
+export function parseFindPeersArgs(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("find_peers arguments must be an object");
+    }
+    const obj = raw;
+    const area = obj.area;
+    const kRaw = obj.k;
+    if (typeof area !== "string" || area.trim().length === 0) {
+        throw new Error("area must be a non-empty string");
+    }
+    if (area.length > 100) {
+        throw new Error("area must be 100 characters or fewer");
+    }
+    let k;
+    if (kRaw !== undefined) {
+        if (typeof kRaw !== "number" || !Number.isInteger(kRaw) || kRaw < 1 || kRaw > 200) {
+            throw new Error("k must be an integer between 1 and 200");
+        }
+        k = kRaw;
+    }
+    return { area: area.trim(), k };
+}
+export async function executeFindPeers(client, args) {
+    try {
+        const result = await client.findPeers(args.area, args.k);
+        const lines = [];
+        lines.push(`# Peers · ${args.area}`);
+        lines.push(`Generated at: ${result.meta.generated_at}`);
+        lines.push("");
+        lines.push(renderPeersBlock(result));
+        return { content: [{ type: "text", text: lines.join("\n").trimEnd() }] };
+    }
+    catch (err) {
+        if (err instanceof OogaApiError) {
+            const msg = `OneGoodArea API error (HTTP ${err.status ?? "?"}): ${err.message}`;
+            return { content: [{ type: "text", text: msg }], isError: true };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Tool error: ${msg}` }], isError: true };
+    }
+}
+//# sourceMappingURL=find-peers.js.map

package/dist/tools/find-peers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-peers.js","sourceRoot":"","sources":["../../src/tools/find-peers.ts"],"names":[],"mappings":"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"}

package/dist/tools/get-area-signals.d.ts

@@ -0,0 +1,39 @@
+/**
+ * MCP tool: get_area_signals (AR-366)
+ *
+ * Returns the full Signals catalog for a UK area: every signal across all
+ * seven categories with raw value + unit, percentile when store-backed,
+ * per-signal confidence + engine-grounded reason, source attribution, and
+ * observation period. Wraps GET /v1/area.
+ *
+ * Use this when the LLM needs to inspect the underlying data — not a
+ * composite score, the actual signal values that would feed a score.
+ */
+import type { OogaApiClient } from "../api-client.js";
+export declare const getAreaSignalsToolName = "get_area_signals";
+export declare const getAreaSignalsToolDef: {
+    readonly name: "get_area_signals";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly area: {
+                readonly type: "string";
+                readonly description: "UK postcode (e.g. 'SW1A 1AA') or place name (e.g. 'Manchester city centre', 'Shoreditch'). Max 100 characters.";
+            };
+        };
+        readonly required: readonly ["area"];
+        readonly additionalProperties: false;
+    };
+};
+export interface GetAreaSignalsArgs {
+    area: string;
+}
+export declare function parseGetAreaSignalsArgs(raw: unknown): GetAreaSignalsArgs;
+export declare function executeGetAreaSignals(client: OogaApiClient, args: GetAreaSignalsArgs): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tools/get-area-signals.js

@@ -0,0 +1,60 @@
+/**
+ * MCP tool: get_area_signals (AR-366)
+ *
+ * Returns the full Signals catalog for a UK area: every signal across all
+ * seven categories with raw value + unit, percentile when store-backed,
+ * per-signal confidence + engine-grounded reason, source attribution, and
+ * observation period. Wraps GET /v1/area.
+ *
+ * Use this when the LLM needs to inspect the underlying data — not a
+ * composite score, the actual signal values that would feed a score.
+ */
+import { OogaApiError } from "../api-client.js";
+import { formatAreaProfileAsText } from "./signals-format.js";
+export const getAreaSignalsToolName = "get_area_signals";
+export const getAreaSignalsToolDef = {
+    name: getAreaSignalsToolName,
+    description: "Get the full OneGoodArea Signals catalog for a UK area (every signal across all seven categories: crime, deprivation, property, schools, amenities, transport, environment). " +
+        "Returns each signal's raw value with unit, percentile (when store-backed), confidence with engine-grounded reasoning, source attribution, and observation period. " +
+        "Use this to inspect underlying data rather than a composite score — the primitive that powers every other product.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            area: {
+                type: "string",
+                description: "UK postcode (e.g. 'SW1A 1AA') or place name (e.g. 'Manchester city centre', 'Shoreditch'). Max 100 characters.",
+            },
+        },
+        required: ["area"],
+        additionalProperties: false,
+    },
+};
+export function parseGetAreaSignalsArgs(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("get_area_signals arguments must be an object");
+    }
+    const obj = raw;
+    const area = obj.area;
+    if (typeof area !== "string" || area.trim().length === 0) {
+        throw new Error("area must be a non-empty string");
+    }
+    if (area.length > 100) {
+        throw new Error("area must be 100 characters or fewer");
+    }
+    return { area: area.trim() };
+}
+export async function executeGetAreaSignals(client, args) {
+    try {
+        const result = await client.getAreaSignals(args.area);
+        return { content: [{ type: "text", text: formatAreaProfileAsText(result) }] };
+    }
+    catch (err) {
+        if (err instanceof OogaApiError) {
+            const msg = `OneGoodArea API error (HTTP ${err.status ?? "?"}): ${err.message}`;
+            return { content: [{ type: "text", text: msg }], isError: true };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Tool error: ${msg}` }], isError: true };
+    }
+}
+//# sourceMappingURL=get-area-signals.js.map

package/dist/tools/get-area-signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-area-signals.js","sourceRoot":"","sources":["../../src/tools/get-area-signals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,MAAM,CAAC,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAEzD,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,sBAAsB;IAC5B,WAAW,EACT,+KAA+K;QAC/K,oKAAoK;QACpK,oHAAoH;IACtH,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,gHAAgH;aACnH;SACF;QACD,QAAQ,EAAE,CAAC,MAAM,CAAC;QAClB,oBAAoB,EAAE,KAAK;KAC5B;CACO,CAAC;AAMX,MAAM,UAAU,uBAAuB,CAAC,GAAY;IAClD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IACD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IAEtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;AAC/B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAqB,EACrB,IAAwB;IAExB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;IAChF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,YAAY,EAAE,CAAC;YAChC,MAAM,GAAG,GAAG,+BAA+B,GAAG,CAAC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;YAChF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACnE,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACpF,CAAC;AACH,CAAC"}

package/dist/tools/get-portfolio-changes.d.ts

@@ -0,0 +1,58 @@
+/**
+ * MCP tool: get_portfolio_changes (AR-368)
+ *
+ * Check a Monitor portfolio for material signal changes between two
+ * time-series periods. Wraps POST /v1/portfolios/:id/changes (with
+ * emit:false — the MCP shouldn't fire webhooks on a probe call).
+ *
+ * Returns the change report rendered as markdown: scope (baseline,
+ * threshold, min_transactions), counts (areas_checked, material_count),
+ * and a per-area table of material signal moves.
+ */
+import type { OogaApiClient, OogaChangeReport } from "../api-client.js";
+export declare const getPortfolioChangesToolName = "get_portfolio_changes";
+export declare const getPortfolioChangesToolDef: {
+    readonly name: "get_portfolio_changes";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly portfolio_id: {
+                readonly type: "string";
+                readonly description: "ID returned by watch_portfolio (e.g. 'ptf_...').";
+            };
+            readonly threshold_pct: {
+                readonly type: "number";
+                readonly description: "Minimum |percent change| to flag a move as material. Default is the portfolio's configured threshold. Non-negative.";
+                readonly minimum: 0;
+            };
+            readonly baseline: {
+                readonly type: "string";
+                readonly enum: readonly ["previous", "first"];
+                readonly description: "Compare the latest period vs the previous period (default), or vs the first period in range.";
+            };
+            readonly min_transactions: {
+                readonly type: "number";
+                readonly description: "Sample-size gate for price moves (de-noise). Non-negative integer; default is the portfolio's configured value.";
+                readonly minimum: 0;
+            };
+        };
+        readonly required: readonly ["portfolio_id"];
+        readonly additionalProperties: false;
+    };
+};
+export interface GetPortfolioChangesArgs {
+    portfolio_id: string;
+    threshold_pct?: number;
+    baseline?: "previous" | "first";
+    min_transactions?: number;
+}
+export declare function parseGetPortfolioChangesArgs(raw: unknown): GetPortfolioChangesArgs;
+export declare function formatChangeReportAsText(report: OogaChangeReport): string;
+export declare function executeGetPortfolioChanges(client: OogaApiClient, args: GetPortfolioChangesArgs): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tools/get-portfolio-changes.js

@@ -0,0 +1,121 @@
+/**
+ * MCP tool: get_portfolio_changes (AR-368)
+ *
+ * Check a Monitor portfolio for material signal changes between two
+ * time-series periods. Wraps POST /v1/portfolios/:id/changes (with
+ * emit:false — the MCP shouldn't fire webhooks on a probe call).
+ *
+ * Returns the change report rendered as markdown: scope (baseline,
+ * threshold, min_transactions), counts (areas_checked, material_count),
+ * and a per-area table of material signal moves.
+ */
+import { OogaApiError } from "../api-client.js";
+export const getPortfolioChangesToolName = "get_portfolio_changes";
+export const getPortfolioChangesToolDef = {
+    name: getPortfolioChangesToolName,
+    description: "Check a Monitor portfolio for material signal changes between two time-series periods. " +
+        "Returns the portfolio's baseline + threshold settings, counts of areas checked and material changes, and a per-area table of every material signal move (with direction, from/to values, delta, and percent change). " +
+        "Use this after watch_portfolio has set up tracking — typically with default threshold_pct, or tighter when you want only large moves.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            portfolio_id: {
+                type: "string",
+                description: "ID returned by watch_portfolio (e.g. 'ptf_...').",
+            },
+            threshold_pct: {
+                type: "number",
+                description: "Minimum |percent change| to flag a move as material. Default is the portfolio's configured threshold. Non-negative.",
+                minimum: 0,
+            },
+            baseline: {
+                type: "string",
+                enum: ["previous", "first"],
+                description: "Compare the latest period vs the previous period (default), or vs the first period in range.",
+            },
+            min_transactions: {
+                type: "number",
+                description: "Sample-size gate for price moves (de-noise). Non-negative integer; default is the portfolio's configured value.",
+                minimum: 0,
+            },
+        },
+        required: ["portfolio_id"],
+        additionalProperties: false,
+    },
+};
+export function parseGetPortfolioChangesArgs(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("get_portfolio_changes arguments must be an object");
+    }
+    const obj = raw;
+    const portfolio_id = obj.portfolio_id;
+    if (typeof portfolio_id !== "string" || portfolio_id.trim().length === 0) {
+        throw new Error("portfolio_id must be a non-empty string");
+    }
+    const out = { portfolio_id: portfolio_id.trim() };
+    if (obj.threshold_pct !== undefined) {
+        if (typeof obj.threshold_pct !== "number" || !Number.isFinite(obj.threshold_pct) || obj.threshold_pct < 0) {
+            throw new Error("threshold_pct must be a non-negative number");
+        }
+        out.threshold_pct = obj.threshold_pct;
+    }
+    if (obj.baseline !== undefined) {
+        if (obj.baseline !== "previous" && obj.baseline !== "first") {
+            throw new Error("baseline must be 'previous' or 'first'");
+        }
+        out.baseline = obj.baseline;
+    }
+    if (obj.min_transactions !== undefined) {
+        if (typeof obj.min_transactions !== "number" || !Number.isFinite(obj.min_transactions) || obj.min_transactions < 0) {
+            throw new Error("min_transactions must be a non-negative number");
+        }
+        out.min_transactions = obj.min_transactions;
+    }
+    return out;
+}
+function formatChange(c) {
+    const arrow = c.direction === "up" ? "↑" : c.direction === "down" ? "↓" : "→";
+    const pct = c.pct_change === null ? "—" : `${c.pct_change > 0 ? "+" : ""}${c.pct_change.toFixed(1)}%`;
+    const from = c.value_from === null ? "—" : c.value_from.toLocaleString("en-GB");
+    const to = c.value_to === null ? "—" : c.value_to.toLocaleString("en-GB");
+    const label = c.label ?? c.signal_key;
+    return `| ${c.area} (${c.geo_code}) | ${label} | ${c.period_from} → ${c.period_to} | ${from} ${arrow} ${to} | ${pct} |`;
+}
+export function formatChangeReportAsText(report) {
+    const lines = [];
+    lines.push(`# Portfolio changes · \`${report.portfolio_id}\``);
+    lines.push(`Generated at: ${report.generated_at}`);
+    lines.push("");
+    lines.push(`**Baseline:** ${report.baseline}`);
+    lines.push(`**Threshold:** ${report.threshold_pct}% · **Min transactions:** ${report.min_transactions}`);
+    lines.push(`**Areas checked:** ${report.areas_checked} · **Material changes:** ${report.material_count}`);
+    lines.push("");
+    if (report.changes.length === 0) {
+        lines.push("No material signal changes detected for this portfolio with the current threshold.");
+        return lines.join("\n").trimEnd();
+    }
+    lines.push("| Area | Signal | Period | Value | % change |");
+    lines.push("|---|---|---|---|---|");
+    for (const c of report.changes)
+        lines.push(formatChange(c));
+    return lines.join("\n").trimEnd();
+}
+export async function executeGetPortfolioChanges(client, args) {
+    try {
+        const report = await client.getPortfolioChanges(args.portfolio_id, {
+            baseline: args.baseline,
+            threshold_pct: args.threshold_pct,
+            min_transactions: args.min_transactions,
+        });
+        return { content: [{ type: "text", text: formatChangeReportAsText(report) }] };
+    }
+    catch (err) {
+        if (err instanceof OogaApiError) {
+            const msg = `OneGoodArea API error (HTTP ${err.status ?? "?"}): ${err.message}`;
+            return { content: [{ type: "text", text: msg }], isError: true };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Tool error: ${msg}` }], isError: true };
+    }
+}
+//# sourceMappingURL=get-portfolio-changes.js.map

package/dist/tools/get-portfolio-changes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-portfolio-changes.js","sourceRoot":"","sources":["../../src/tools/get-portfolio-changes.ts"],"names":[],"mappings":"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"}

package/dist/tools/get-signals-by-category.d.ts

@@ -0,0 +1,44 @@
+/**
+ * MCP tool: get_signals_by_category (AR-366)
+ *
+ * Returns the Signals for one category only (crime, deprivation, property,
+ * schools, amenities, transport, or environment). Use this when the LLM
+ * needs to focus on a single data domain — narrower than get_area_signals,
+ * same engine-grounded fields per signal.
+ *
+ * Wraps GET /v1/signals/:category.
+ */
+import type { OogaApiClient, SignalCategory } from "../api-client.js";
+export declare const getSignalsByCategoryToolName = "get_signals_by_category";
+export declare const getSignalsByCategoryToolDef: {
+    readonly name: "get_signals_by_category";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly area: {
+                readonly type: "string";
+                readonly description: "UK postcode (e.g. 'SW1A 1AA') or place name (e.g. 'Manchester city centre'). Max 100 characters.";
+            };
+            readonly category: {
+                readonly type: "string";
+                readonly enum: readonly ["crime", "deprivation", "property", "schools", "amenities", "transport", "environment"];
+                readonly description: "Signal category to return. One of: crime, deprivation, property, schools, amenities, transport, environment.";
+            };
+        };
+        readonly required: readonly ["area", "category"];
+        readonly additionalProperties: false;
+    };
+};
+export interface GetSignalsByCategoryArgs {
+    area: string;
+    category: SignalCategory;
+}
+export declare function parseGetSignalsByCategoryArgs(raw: unknown): GetSignalsByCategoryArgs;
+export declare function executeGetSignalsByCategory(client: OogaApiClient, args: GetSignalsByCategoryArgs): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tools/get-signals-by-category.js

@@ -0,0 +1,67 @@
+/**
+ * MCP tool: get_signals_by_category (AR-366)
+ *
+ * Returns the Signals for one category only (crime, deprivation, property,
+ * schools, amenities, transport, or environment). Use this when the LLM
+ * needs to focus on a single data domain — narrower than get_area_signals,
+ * same engine-grounded fields per signal.
+ *
+ * Wraps GET /v1/signals/:category.
+ */
+import { OogaApiError, SIGNAL_CATEGORIES } from "../api-client.js";
+import { formatAreaProfileAsText } from "./signals-format.js";
+export const getSignalsByCategoryToolName = "get_signals_by_category";
+export const getSignalsByCategoryToolDef = {
+    name: getSignalsByCategoryToolName,
+    description: "Get OneGoodArea Signals for a single category at a UK area. Categories: crime (police.uk), deprivation (IMD/WIMD/SIMD), property (HM Land Registry), schools (Ofsted/Estyn/Education Scotland), amenities (OpenStreetMap), transport (OpenStreetMap), environment (Environment Agency). " +
+        "Same per-signal shape as get_area_signals — value, unit, percentile (when store-backed), confidence with engine-grounded reason, source, observation period — narrowed to one category for focused analysis.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            area: {
+                type: "string",
+                description: "UK postcode (e.g. 'SW1A 1AA') or place name (e.g. 'Manchester city centre'). Max 100 characters.",
+            },
+            category: {
+                type: "string",
+                enum: SIGNAL_CATEGORIES,
+                description: "Signal category to return. One of: crime, deprivation, property, schools, amenities, transport, environment.",
+            },
+        },
+        required: ["area", "category"],
+        additionalProperties: false,
+    },
+};
+export function parseGetSignalsByCategoryArgs(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("get_signals_by_category arguments must be an object");
+    }
+    const obj = raw;
+    const area = obj.area;
+    const category = obj.category;
+    if (typeof area !== "string" || area.trim().length === 0) {
+        throw new Error("area must be a non-empty string");
+    }
+    if (area.length > 100) {
+        throw new Error("area must be 100 characters or fewer");
+    }
+    if (typeof category !== "string" || !SIGNAL_CATEGORIES.includes(category)) {
+        throw new Error(`category must be one of: ${SIGNAL_CATEGORIES.join(", ")}`);
+    }
+    return { area: area.trim(), category: category };
+}
+export async function executeGetSignalsByCategory(client, args) {
+    try {
+        const result = await client.getSignalsByCategory(args.area, args.category);
+        return { content: [{ type: "text", text: formatAreaProfileAsText(result, args.category) }] };
+    }
+    catch (err) {
+        if (err instanceof OogaApiError) {
+            const msg = `OneGoodArea API error (HTTP ${err.status ?? "?"}): ${err.message}`;
+            return { content: [{ type: "text", text: msg }], isError: true };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Tool error: ${msg}` }], isError: true };
+    }
+}
+//# sourceMappingURL=get-signals-by-category.js.map

package/dist/tools/get-signals-by-category.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-signals-by-category.js","sourceRoot":"","sources":["../../src/tools/get-signals-by-category.ts"],"names":[],"mappings":"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"}

package/dist/tools/intelligence-format.d.ts

@@ -0,0 +1,28 @@
+/**
+ * AR-367: Format /v1/query responses for the find_areas MCP tool.
+ *
+ * The query plane returns a discriminated union over 7 plan ops. This
+ * module renders each op's results as markdown the LLM can pass to its
+ * user. Every value rendered is a real field from the response — no
+ * client-side text synthesis.
+ *
+ * Rendering bias: surface the emitted PLAN front-and-center (the
+ * "what did the planner decide to run" transparency play that makes
+ * the query plane defensible), then the op-specific results.
+ */
+import type { OogaQueryResponse } from "../api-client.js";
+export declare function renderPeersBlock(r: {
+    target: {
+        geo_code: string;
+        signals_used: string[];
+    };
+    peers: Array<{
+        geo_code: string;
+        distance: number;
+        n_dims_used: number;
+    }>;
+    meta: {
+        scope: string;
+    };
+}): string;
+export declare function formatQueryResponseAsText(res: OogaQueryResponse): string;