@oga-mcp/server 1.0.0

package/dist/tools/area-brief-format.js

@@ -0,0 +1,142 @@
+/**
+ * AR-369: Render an audience-shaped brief from a real AreaProfile +
+ * ScoreResponse (?explain=true). Server-side-narrative policy:
+ *
+ *   - The `summary`, `dimensions[].reasoning`, `dimensions[].confidence_reason`,
+ *     `recommendations[]`, and `data_sources[]` come straight from
+ *     /v1/score?explain=true (server-composed in AR-363).
+ *   - The per-signal `confidence_reason`, `value`, `unit`, `percentile`,
+ *     `source`, `observed_period` come straight from /v1/area (engine output).
+ *   - This module SELECTS which of those fields render in which section
+ *     based on the AudienceConfig. It does NOT invent prose.
+ */
+/* ── value/unit formatting (mirrors signals-format.ts) ──────────── */
+function formatValue(s) {
+    if (s.value === null)
+        return "—";
+    if (typeof s.value === "string")
+        return s.value;
+    const n = s.value;
+    if (s.unit === "GBP")
+        return `£${Math.round(n).toLocaleString("en-GB")}`;
+    if (s.unit === "pct")
+        return `${n.toFixed(1)}%`;
+    if (s.unit === "count" || s.unit === "rank" || s.unit === "decile")
+        return Math.round(n).toLocaleString("en-GB");
+    if (s.unit === "per_month")
+        return `${n.toFixed(1)} / mo`;
+    return n.toLocaleString("en-GB");
+}
+/* ── per-section renderers ──────────────────────────────────────── */
+function renderDimensionLine(d) {
+    const lines = [];
+    const conf = ` · confidence ${(d.confidence * 100).toFixed(0)}%`;
+    lines.push(`- **${d.label}**: ${d.score}/100 (weight ${d.weight}%${conf})`);
+    if (d.reasoning)
+        lines.push(`  ${d.reasoning}`);
+    if (d.confidence_reason)
+        lines.push(`  _${d.confidence_reason}_`);
+    return lines;
+}
+function renderSignalLine(s) {
+    const lines = [];
+    const unit = s.unit && !["GBP", "pct"].includes(s.unit) ? ` ${s.unit}` : "";
+    lines.push(`- **${s.label}**: ${formatValue(s)}${s.value !== null ? unit : ""}`);
+    if (typeof s.percentile === "number") {
+        lines.push(`  ${s.percentile}th percentile · direction: ${s.direction.replace(/_/g, " ")}`);
+    }
+    lines.push(`  Confidence ${(s.confidence * 100).toFixed(0)}% · ${s.confidence_reason}`);
+    lines.push(`  Source: ${s.source} · ${s.observed_period}`);
+    return lines;
+}
+/* ── section selector ───────────────────────────────────────────── */
+function pickDimensions(allDims, labels) {
+    /* Match by exact label (case-insensitive). The engine evolves dimension
+       names across versions; the audience config lists known aliases so we
+       don't drop a section just because "Safety" became "Safety & Crime". */
+    const wanted = new Set(labels.map((l) => l.toLowerCase()));
+    return allDims.filter((d) => wanted.has(d.label.toLowerCase()));
+}
+function pickSignals(allSignals, keys) {
+    const wanted = new Set(keys);
+    /* Preserve the audience-defined order, not the catalog order. */
+    const byKey = new Map(allSignals.map((s) => [s.key, s]));
+    const out = [];
+    for (const k of keys) {
+        const s = byKey.get(k);
+        if (s && wanted.has(k))
+            out.push(s);
+    }
+    return out;
+}
+function renderSection(section, score, profile) {
+    const dims = pickDimensions(score.dimensions, section.dimensions);
+    const signals = pickSignals(profile.signals, section.signals);
+    if (dims.length === 0 && signals.length === 0) {
+        /* Drop empty sections rather than render an empty header — the
+           audience config can over-specify and that's fine. */
+        return [];
+    }
+    const lines = [];
+    lines.push(`## ${section.title}`);
+    for (const d of dims)
+        for (const line of renderDimensionLine(d))
+            lines.push(line);
+    for (const s of signals)
+        for (const line of renderSignalLine(s))
+            lines.push(line);
+    lines.push("");
+    return lines;
+}
+/* ── brief assembly ─────────────────────────────────────────────── */
+export function formatAreaBriefAsText(audience, profile, score) {
+    const lines = [];
+    const geo = profile.geo;
+    /* Headline. */
+    const headlineLoc = geo.postcode && geo.postcode !== geo.query
+        ? `${geo.query} (${geo.postcode})`
+        : geo.query;
+    lines.push(`# ${audience.label} · ${headlineLoc}`);
+    lines.push(`${audience.framing}`);
+    lines.push("");
+    /* Geo summary line. */
+    const geoBits = [];
+    if (geo.admin_district)
+        geoBits.push(geo.admin_district);
+    if (geo.region)
+        geoBits.push(geo.region);
+    geoBits.push(geo.country);
+    geoBits.push(`${geo.area_type} area`);
+    if (geo.lsoa)
+        geoBits.push(`LSOA ${geo.lsoa}`);
+    lines.push(`**Area:** ${geoBits.join(" · ")}`);
+    lines.push(`**Engine version:** ${score.engine_version} · **Preset:** ${score.preset} · **Fetch mode:** ${profile.meta.fetch_mode}`);
+    lines.push("");
+    /* Overall verdict block — score + server-composed summary. */
+    lines.push(`## Overall verdict`);
+    lines.push(`**Score:** ${score.score}/100 · **Aggregate confidence:** ${(score.confidence * 100).toFixed(0)}%`);
+    if (score.summary) {
+        lines.push("");
+        lines.push(score.summary);
+    }
+    lines.push("");
+    /* Audience-shaped sections. Each pulls real fields per the config. */
+    for (const section of audience.sections) {
+        for (const line of renderSection(section, score, profile))
+            lines.push(line);
+    }
+    /* Recommendations (server-composed, AR-363). */
+    if (score.recommendations && score.recommendations.length > 0) {
+        lines.push(`## Notes & risks`);
+        for (const r of score.recommendations)
+            lines.push(`- ${r}`);
+        lines.push("");
+    }
+    /* Data sources (server-composed, AR-363). */
+    if (score.data_sources && score.data_sources.length > 0) {
+        lines.push(`## Data sources`);
+        lines.push(score.data_sources.join(" · "));
+    }
+    return lines.join("\n").trimEnd();
+}
+//# sourceMappingURL=area-brief-format.js.map

package/dist/tools/area-brief-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"area-brief-format.js","sourceRoot":"","sources":["../../src/tools/area-brief-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,uEAAuE;AAEvE,SAAS,WAAW,CAAC,CAAa;IAChC,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,GAAG,CAAC;IACjC,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,KAAK,CAAC;IAChD,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;IAClB,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK;QAAE,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;IACzE,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK;QAAE,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IAChD,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IACjH,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IAC1D,OAAO,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,uEAAuE;AAEvE,SAAS,mBAAmB,CAAC,CAAqB;IAChD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,iBAAiB,CAAC,CAAC,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IACjE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,KAAK,gBAAgB,CAAC,CAAC,MAAM,IAAI,IAAI,GAAG,CAAC,CAAC;IAC5E,IAAI,CAAC,CAAC,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;IAChD,IAAI,CAAC,CAAC,iBAAiB;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,iBAAiB,GAAG,CAAC,CAAC;IAClE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,gBAAgB,CAAC,CAAa;IACrC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,OAAO,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACjF,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,8BAA8B,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9F,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACxF,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC;IAC3D,OAAO,KAAK,CAAC;AACf,CAAC;AAED,uEAAuE;AAEvE,SAAS,cAAc,CACrB,OAA6B,EAC7B,MAAgB;IAEhB;;6EAEyE;IACzE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAC3D,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,WAAW,CAAC,UAAwB,EAAE,IAAc;IAC3D,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,iEAAiE;IACjE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAU,CAAC,CAAC,CAAC;IAClE,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,aAAa,CACpB,OAAqB,EACrB,KAAwB,EACxB,OAAwB;IAExB,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAClE,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAE9D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9C;+DACuD;QACvD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,KAAK,MAAM,IAAI,IAAI,mBAAmB,CAAC,CAAC,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClF,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,KAAK,MAAM,IAAI,IAAI,gBAAgB,CAAC,CAAC,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,OAAO,KAAK,CAAC;AACf,CAAC;AAED,uEAAuE;AAEvE,MAAM,UAAU,qBAAqB,CACnC,QAAwB,EACxB,OAAwB,EACxB,KAAwB;IAExB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAExB,eAAe;IACf,MAAM,WAAW,GAAG,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,KAAK;QAC5D,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,KAAK,GAAG,CAAC,QAAQ,GAAG;QAClC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;IACd,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,KAAK,MAAM,WAAW,EAAE,CAAC,CAAC;IACnD,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAClC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,uBAAuB;IACvB,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,GAAG,CAAC,cAAc;QAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACzD,IAAI,GAAG,CAAC,MAAM;QAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACzC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1B,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,SAAS,OAAO,CAAC,CAAC;IACtC,IAAI,GAAG,CAAC,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/C,KAAK,CAAC,IAAI,CAAC,aAAa,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC/C,KAAK,CAAC,IAAI,CAAC,uBAAuB,KAAK,CAAC,cAAc,kBAAkB,KAAK,CAAC,MAAM,sBAAsB,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IACrI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,8DAA8D;IAC9D,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACjC,KAAK,CAAC,IAAI,CAAC,cAAc,KAAK,CAAC,KAAK,oCAAoC,CAAC,KAAK,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAChH,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,sEAAsE;IACtE,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACxC,KAAK,MAAM,IAAI,IAAI,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9E,CAAC;IAED,gDAAgD;IAChD,IAAI,KAAK,CAAC,eAAe,IAAI,KAAK,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9D,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,eAAe;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,6CAA6C;IAC7C,IAAI,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxD,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;AACpC,CAAC"}

package/dist/tools/area-brief.d.ts

@@ -0,0 +1,48 @@
+/**
+ * MCP tool: area_brief (AR-369) — the marquee composite.
+ *
+ * Given an area + audience, returns a fully-formatted audience-shaped
+ * brief on that area, composed from real engine state. Internally calls
+ * GET /v1/area (full signal catalog) and POST /v1/score?explain=true
+ * (audience's preset, with server-composed summary + recommendations +
+ * data sources), then renders an audience-specific markdown layout.
+ *
+ * Brief-shape policy: no client-side text synthesis. The MCP only
+ * SELECTS which real fields render in which section per the audience
+ * config. Every word of prose comes from the engine.
+ */
+import type { OogaApiClient } from "../api-client.js";
+import { type Audience } from "./area-brief-audiences.js";
+export declare const areaBriefToolName = "area_brief";
+export declare const areaBriefToolDef: {
+    readonly name: "area_brief";
+    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 audience: {
+                readonly type: "string";
+                readonly enum: Audience[];
+                readonly description: "Brief audience. One of: lender, insurer, retailer, investor.";
+            };
+        };
+        readonly required: readonly ["area", "audience"];
+        readonly additionalProperties: false;
+    };
+};
+export interface AreaBriefArgs {
+    area: string;
+    audience: Audience;
+}
+export declare function parseAreaBriefArgs(raw: unknown): AreaBriefArgs;
+export declare function executeAreaBrief(client: OogaApiClient, args: AreaBriefArgs): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tools/area-brief.js

@@ -0,0 +1,82 @@
+/**
+ * MCP tool: area_brief (AR-369) — the marquee composite.
+ *
+ * Given an area + audience, returns a fully-formatted audience-shaped
+ * brief on that area, composed from real engine state. Internally calls
+ * GET /v1/area (full signal catalog) and POST /v1/score?explain=true
+ * (audience's preset, with server-composed summary + recommendations +
+ * data sources), then renders an audience-specific markdown layout.
+ *
+ * Brief-shape policy: no client-side text synthesis. The MCP only
+ * SELECTS which real fields render in which section per the audience
+ * config. Every word of prose comes from the engine.
+ */
+import { OogaApiError } from "../api-client.js";
+import { AUDIENCES, getAudienceConfig } from "./area-brief-audiences.js";
+import { formatAreaBriefAsText } from "./area-brief-format.js";
+export const areaBriefToolName = "area_brief";
+export const areaBriefToolDef = {
+    name: areaBriefToolName,
+    description: "Produce an audience-shaped brief on a UK area for one of four buyers: lender (residential mortgage origination), insurer (property risk underwriting), retailer (commercial site selection), investor (residential investment). " +
+        "Internally combines the full signals catalog with the audience's scoring preset (with explain mode) and renders an audience-specific markdown document: overall verdict, audience-relevant dimensions, audience-relevant signals with provenance, recommendations, and data sources. " +
+        "Every value is real engine output — no client-side prose synthesis. Costs two API calls per invocation (one /v1/area, one /v1/score?explain=true).",
+    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.",
+            },
+            audience: {
+                type: "string",
+                enum: AUDIENCES,
+                description: "Brief audience. One of: lender, insurer, retailer, investor.",
+            },
+        },
+        required: ["area", "audience"],
+        additionalProperties: false,
+    },
+};
+export function parseAreaBriefArgs(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("area_brief arguments must be an object");
+    }
+    const obj = raw;
+    const area = obj.area;
+    const audience = obj.audience;
+    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 audience !== "string" || !AUDIENCES.includes(audience)) {
+        throw new Error(`audience must be one of: ${AUDIENCES.join(", ")}`);
+    }
+    return { area: area.trim(), audience: audience };
+}
+export async function executeAreaBrief(client, args) {
+    const config = getAudienceConfig(args.audience);
+    try {
+        /* Two parallel calls — the brief needs both responses to render
+           and the network round-trip is the dominant cost. /v1/score is
+           called with explain=true (AR-363) so summary + recommendations
+           + data_sources come back server-composed. */
+        const [profile, score] = await Promise.all([
+            client.getAreaSignals(args.area),
+            client.scoreArea(args.area, config.preset),
+        ]);
+        return {
+            content: [{ type: "text", text: formatAreaBriefAsText(config, profile, score) }],
+        };
+    }
+    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=area-brief.js.map

package/dist/tools/area-brief.js.map

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

package/dist/tools/compare-postcodes.d.ts

@@ -0,0 +1,57 @@
+/**
+ * MCP tool: compare_postcodes
+ *
+ * Scores N areas (max 8) for a single preset in parallel and returns a
+ * comparison table sorted by overall score. Uses the existing scoreArea
+ * client method — Promise.allSettled in parallel, individual failures are
+ * captured inline rather than failing the whole call. Each per-area
+ * summary uses the server-composed `summary` from /v1/score?explain=true;
+ * no client-side narrative synthesis.
+ */
+import type { OogaApiClient, Preset, OogaScoreResponse } from "../api-client.js";
+export declare const comparePostcodesToolName = "compare_postcodes";
+export declare const comparePostcodesToolDef: {
+    readonly name: "compare_postcodes";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly areas: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly minItems: 2;
+                readonly maxItems: 8;
+                readonly description: "Array of UK postcodes or place names to compare. Between 2 and 8 entries.";
+            };
+            readonly preset: {
+                readonly type: "string";
+                readonly enum: readonly ["moving", "business", "investing", "research"];
+                readonly description: "Same preset applied to every area. Use 'moving' for origination, 'business' for site selection, 'investing' for yield, 'research' for neutral baseline.";
+            };
+        };
+        readonly required: readonly ["areas", "preset"];
+        readonly additionalProperties: false;
+    };
+};
+export interface ComparePostcodesArgs {
+    areas: string[];
+    preset: Preset;
+}
+export declare function parseComparePostcodesArgs(raw: unknown): ComparePostcodesArgs;
+interface ComparisonRow {
+    area: string;
+    score: number | null;
+    result: OogaScoreResponse | null;
+    error: string | null;
+}
+export declare function formatComparisonAsText(rows: ComparisonRow[], preset: Preset): string;
+export declare function executeComparePostcodes(client: OogaApiClient, args: ComparePostcodesArgs): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export {};

package/dist/tools/compare-postcodes.js

@@ -0,0 +1,148 @@
+/**
+ * MCP tool: compare_postcodes
+ *
+ * Scores N areas (max 8) for a single preset in parallel and returns a
+ * comparison table sorted by overall score. Uses the existing scoreArea
+ * client method — Promise.allSettled in parallel, individual failures are
+ * captured inline rather than failing the whole call. Each per-area
+ * summary uses the server-composed `summary` from /v1/score?explain=true;
+ * no client-side narrative synthesis.
+ */
+import { OogaApiError } from "../api-client.js";
+const MAX_AREAS = 8;
+export const comparePostcodesToolName = "compare_postcodes";
+export const comparePostcodesToolDef = {
+    name: comparePostcodesToolName,
+    description: "Compare multiple UK postcodes (max 8) side-by-side for the same decision preset. " +
+        "Returns a sorted table showing each area's overall score, area type, top dimension, and the server-composed per-area summary. " +
+        "Each request hits POST /v1/score?explain=true independently — partial failures are inline, not fatal.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            areas: {
+                type: "array",
+                items: { type: "string" },
+                minItems: 2,
+                maxItems: MAX_AREAS,
+                description: `Array of UK postcodes or place names to compare. Between 2 and ${MAX_AREAS} entries.`,
+            },
+            preset: {
+                type: "string",
+                enum: ["moving", "business", "investing", "research"],
+                description: "Same preset applied to every area. Use 'moving' for origination, 'business' for site selection, 'investing' for yield, 'research' for neutral baseline.",
+            },
+        },
+        required: ["areas", "preset"],
+        additionalProperties: false,
+    },
+};
+export function parseComparePostcodesArgs(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("compare_postcodes arguments must be an object");
+    }
+    const obj = raw;
+    const areas = obj.areas;
+    const preset = obj.preset;
+    if (!Array.isArray(areas)) {
+        throw new Error("areas must be an array");
+    }
+    if (areas.length < 2) {
+        throw new Error("areas must contain at least 2 entries");
+    }
+    if (areas.length > MAX_AREAS) {
+        throw new Error(`areas must contain at most ${MAX_AREAS} entries`);
+    }
+    const cleaned = [];
+    for (const a of areas) {
+        if (typeof a !== "string" || a.trim().length === 0) {
+            throw new Error("every area must be a non-empty string");
+        }
+        if (a.length > 100) {
+            throw new Error("each area must be 100 characters or fewer");
+        }
+        cleaned.push(a.trim());
+    }
+    const presets = ["moving", "business", "investing", "research"];
+    if (typeof preset !== "string" || !presets.includes(preset)) {
+        throw new Error(`preset must be one of: ${presets.join(", ")}`);
+    }
+    return { areas: cleaned, preset: preset };
+}
+export function formatComparisonAsText(rows, preset) {
+    // Sort: successful results by descending score, errors at the bottom
+    const sorted = [...rows].sort((a, b) => {
+        if (a.score === null && b.score === null)
+            return 0;
+        if (a.score === null)
+            return 1;
+        if (b.score === null)
+            return -1;
+        return b.score - a.score;
+    });
+    const lines = [];
+    lines.push(`# Comparison · ${rows.length} areas · preset: ${preset}`);
+    lines.push("");
+    // Headline table — score + area type per area
+    lines.push("| Rank | Area | Score | Area type | Top dimension |");
+    lines.push("|---|---|---|---|---|");
+    let rank = 1;
+    for (const r of sorted) {
+        if (r.score === null) {
+            lines.push(`| — | ${r.area} | ERROR | — | ${r.error ?? "Unknown"} |`);
+            continue;
+        }
+        const top = r.result?.dimensions?.length
+            ? r.result.dimensions.reduce((a, b) => (a.score > b.score ? a : b))
+            : null;
+        const topStr = top ? `${top.label} (${top.score}/100)` : "—";
+        const areaType = r.result?.area_type ?? "—";
+        lines.push(`| ${rank} | ${r.area} | ${r.score}/100 | ${areaType} | ${topStr} |`);
+        rank++;
+    }
+    lines.push("");
+    // Per-area summary
+    lines.push("## Summaries");
+    for (const r of sorted) {
+        if (r.score === null) {
+            lines.push(`- **${r.area}**: error — ${r.error ?? "unknown failure"}`);
+            continue;
+        }
+        /* Summary is server-composed from explain=true. Falls back to a
+           minimal score line only if explain mode somehow returned without it. */
+        const summary = r.result?.summary ?? `${r.score}/100`;
+        lines.push(`- **${r.area}**: ${summary}`);
+    }
+    // Footer with engine version if available
+    const firstSuccess = sorted.find((r) => r.result !== null)?.result;
+    if (firstSuccess?.engine_version) {
+        lines.push("");
+        lines.push(`Engine version: ${firstSuccess.engine_version}`);
+    }
+    return lines.join("\n");
+}
+export async function executeComparePostcodes(client, args) {
+    const settled = await Promise.allSettled(args.areas.map((a) => client.scoreArea(a, args.preset)));
+    const rows = settled.map((s, i) => {
+        if (s.status === "fulfilled") {
+            return {
+                area: args.areas[i],
+                score: s.value.score,
+                result: s.value,
+                error: null,
+            };
+        }
+        const reason = s.reason instanceof OogaApiError
+            ? `HTTP ${s.reason.status ?? "?"}: ${s.reason.message}`
+            : s.reason instanceof Error
+                ? s.reason.message
+                : String(s.reason);
+        return { area: args.areas[i], score: null, result: null, error: reason };
+    });
+    // If EVERY call failed, surface that as isError so the LLM can act
+    const allFailed = rows.every((r) => r.error !== null);
+    return {
+        content: [{ type: "text", text: formatComparisonAsText(rows, args.preset) }],
+        ...(allFailed ? { isError: true } : {}),
+    };
+}
+//# sourceMappingURL=compare-postcodes.js.map

package/dist/tools/compare-postcodes.js.map

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

package/dist/tools/engine-version.d.ts

@@ -0,0 +1,23 @@
+/**
+ * MCP tool: engine_version
+ *
+ * Returns the current OneGoodArea engine version + changelog. Useful for
+ * procurement / model-risk teams documenting which engine version is in
+ * production, and for confirming version pinning when that ships.
+ */
+export declare const engineVersionToolName = "engine_version";
+export declare const engineVersionToolDef: {
+    readonly name: "engine_version";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
+};
+export declare function executeEngineVersion(): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+};

package/dist/tools/engine-version.js

@@ -0,0 +1,35 @@
+/**
+ * MCP tool: engine_version
+ *
+ * Returns the current OneGoodArea engine version + changelog. Useful for
+ * procurement / model-risk teams documenting which engine version is in
+ * production, and for confirming version pinning when that ships.
+ */
+import { ENGINE } from "../methodology-data.js";
+export const engineVersionToolName = "engine_version";
+export const engineVersionToolDef = {
+    name: engineVersionToolName,
+    description: "Return the current OneGoodArea engine version (e.g. '2.0.0'), release date, and changelog. " +
+        "Use this when a customer asks 'what version are we on' or for procurement / model-risk documentation. " +
+        "The engine version is also stamped on every score_postcode response for audit trails.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+};
+export function executeEngineVersion() {
+    const lines = [];
+    lines.push(`# OneGoodArea engine ${ENGINE.version}`);
+    lines.push(`Released: ${ENGINE.released}`);
+    lines.push("");
+    lines.push(`## Changelog`);
+    for (const entry of ENGINE.changelog) {
+        lines.push(`### ${entry.version} — ${entry.date}`);
+        lines.push(entry.summary);
+        lines.push("");
+    }
+    lines.push(`Full methodology: https://www.onegoodarea.com/methodology`);
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+}
+//# sourceMappingURL=engine-version.js.map

package/dist/tools/engine-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-version.js","sourceRoot":"","sources":["../../src/tools/engine-version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAEhD,MAAM,CAAC,MAAM,qBAAqB,GAAG,gBAAgB,CAAC;AAEtD,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,qBAAqB;IAC3B,WAAW,EACT,6FAA6F;QAC7F,wGAAwG;QACxG,uFAAuF;IACzF,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE;QACd,oBAAoB,EAAE,KAAK;KAC5B;CACO,CAAC;AAEX,MAAM,UAAU,oBAAoB;IAGlC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,wBAAwB,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACrD,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC3C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,OAAO,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACnD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;IAExE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;AACjE,CAAC"}

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

@@ -0,0 +1,38 @@
+/**
+ * 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 type { OogaApiClient } from "../api-client.js";
+export declare const findAreasToolName = "find_areas";
+export declare const findAreasToolDef: {
+    readonly name: "find_areas";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly question: {
+                readonly type: "string";
+                readonly 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.";
+            };
+        };
+        readonly required: readonly ["question"];
+        readonly additionalProperties: false;
+    };
+};
+export interface FindAreasArgs {
+    question: string;
+}
+export declare function parseFindAreasArgs(raw: unknown): FindAreasArgs;
+export declare function executeFindAreas(client: OogaApiClient, args: FindAreasArgs): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;